Skip to content

Authoring a skill

A good skill is trigger-first, concrete, and verifiable. Agents decide whether to invoke your skill based almost entirely on the description, so the single most important rule is:

Write the description as when to use the skill, not what it does.

Anatomy of a great skill

  1. description — starts with "Use when …" and names the situation. Use when reviewing code for common vulnerabilities (SQLi, XSS, leaked secrets, unsafe eval) and proposing fixes.
  2. ## When to use — reinforces the trigger and scope.
  3. ## Steps — a small, ordered, actionable procedure. Prefer steps an agent can actually execute over vague advice.
  4. ## Examples — real trigger prompts from examples: in frontmatter.
  5. ## References — link to references/ files the agent reads on demand (keeps the main body focused).

Checklist

  • [ ] name is kebab-case and unique.
  • [ ] description is 20–300 chars and says when.
  • [ ] Body has a ## heading and is ≥200 chars.
  • [ ] At least one examples: entry exists.
  • [ ] forge validate --links is clean.
  • [ ] forge test is green.

Scaffold

forge init my-skill --template advanced \
  --description "when the user needs to X" \
  --example "do X for me"
forge validate my-skill --links
forge test my-skill