<< All versions

Skill v1.0.0

currentAutomated scan100/100
golemcloud/golem/golem-annotate-agent-ts
──Details
PublishedOctober 22, 2026 at 07:22 PM
Content Hashsha256:92bbb5033967b11a...
Git SHAe14fbcde9145
──Files
Files (1 file, 3.3 KB)
SKILL.md3.3 KBactive
SKILL.md · 80 lines · 3.3 KB

version: "1.0.0" name: golem-annotate-agent-ts description: "Adding prompt and description annotations to TypeScript agents and their methods. Use when the user asks to add descriptions, prompts, or documentation metadata to agent classes or methods for AI/LLM discovery."

Annotating Agents and Methods (TypeScript)

Overview

Golem agents can annotate the agent and its methods with human-readable metadata. This metadata drives AI/LLM tool discovery — agents with annotations can be used as tools by LLM-based systems. In the TypeScript SDK the annotations are plain fields on the defineAgent(...) spec and on each method(...).

Annotations

  • `promptHint` — a short instruction telling an LLM when to call this method
  • `description` — a longer explanation of what the agent or method does, its parameters, and return value

Agent-Level Annotations

To describe the agent itself (its overall purpose), set description (and optionally promptHint) as top-level fields on the defineAgent(...) spec:

typescript
import { z } from 'zod';
import { defineAgent, method, http } from '@golemcloud/golem-ts-sdk';
export const ProfileAgent = defineAgent({
    name: 'ProfileAgent',
    description: 'Handles user profile management and preferences',
    id: { userId: z.string() },
    http: http.mount('/api/v1/profiles/{userId}'),
    methods: { /* ... */ },
});

Method-Level Annotations

Set description and promptHint inside the method({...}) call for each method:

typescript
import { z } from 'zod';
import { defineAgent, method, http } from '@golemcloud/golem-ts-sdk';
export const InventoryAgent = defineAgent({
    name: 'InventoryAgent',
    description: 'Manages product inventory for a warehouse',
    id: { warehouseId: z.string() },
    http: http.mount('/warehouses/{warehouseId}'),
    methods: {
        checkStock: method({
            input: { sku: z.string() },
            returns: z.number(),
            promptHint: 'Look up the current stock level for a product',
            description:
                'Returns the number of units in stock for the given product SKU. Returns 0 if the product is not found.',
        }),
        restock: method({
            input: { sku: z.string(), quantity: z.number() },
            returns: z.number(),
            promptHint: 'Add units of a product to inventory',
            description:
                'Increases the stock count for the given SKU by the specified amount. Returns the new total.',
        }),
        pick: method({
            input: { sku: z.string(), quantity: z.number() },
            returns: z.number(),
            promptHint: 'Remove units of a product from inventory',
            description: 'Decreases the stock count for the given SKU. Throws if insufficient stock.',
        }),
    },
});

Guidelines

  • description on the agent spec describes the agent's overall purpose for LLM discovery
  • promptHint on a method should be a natural-language instruction an LLM can match against a user request
  • description on a method should document behavior, edge cases, and expected inputs/outputs
  • All of these fields are optional — omit them for internal methods not intended for LLM discovery
  • Annotations have no effect on runtime behavior; they are purely metadata
All versions