Skip to content

Agent Skills

Notes and examples for Agent Skills — folders of instructions (and optional scripts / resources) that an AI agent loads on demand to do a specific kind of task well.

How a skill gets used

flowchart LR
    Prompt["user request"] --> Agent["agent"]
    Skills[("every installed skill's\nname + description")] -->|scanned first| Agent
    Agent -->|one description matches| Skill["that skill's SKILL.md\n+ bundled files/scripts"]
    Skill -->|loaded into context| Agent
    Agent -->|follows the instructions,\nmaybe runs a bundled script| Result["result"]

Only names and descriptions are scanned up front — cheap, so having many installed skills costs little. A skill's full body (and any bundled script) loads only once the agent decides it's actually relevant, which is why the description field is what authoring a skill is really about getting right (see 02-authoring-skills.md).

Play it: Skill Issue is a short game where you author a SKILL.md and see whether a simulated agent would trigger it, within a limited context window, using the same lint rules as scripts/check_skill.py.

Contents

  • notes/01-what-are-agent-skills.md — the concept and when to reach for one.
  • notes/02-authoring-skills.md — the SKILL.md format, frontmatter, and bundled files.
  • notes/03-skills-in-claude-code.md — how Claude Code discovers, gates, and invokes skills.
  • examples/pdf-summary/ — a minimal skill (instructions only).
  • examples/release-notes/ — a skill that bundles a helper script. Not just a hypothetical example — this repo's own CHANGELOG.md was generated by actually running it against this repo's merged PR history.

New here? Start with notes/01-what-are-agent-skills.md, then read examples/pdf-summary/SKILL.md — it's short enough to read in one pass.

Quickstart

python scripts/check_skill.py topics/skills/examples/pdf-summary/SKILL.md
# ok   topics/skills/examples/pdf-summary/SKILL.md

That's the same check CI runs on every SKILL.md — a useful sanity check to run on any new skill you author, before installing it anywhere.

Validation

  • markdownlint covers the notes.
  • scripts/check_skill.py validates every examples/**/SKILL.md: frontmatter present, name is kebab-case ≤ 64 chars and matches the folder, description present ≤ 1024 chars, and a non-empty body.
python scripts/check_skill.py topics/skills/examples/*/SKILL.md