Skip to main content

Agent Skill

Modular capability packages that extend AI agent behavior. Teach agent how to do things.

Key Insights​

  • Triggered manually via /skill-name or automatically when agent detects relevance.
  • Descriptions always load (~100 tokens each), full content loads progressively.
  • Descriptions share a ~15k-char discovery budget, going over silently truncates.
  • All loaded skills share a ~25k-token budget. Older skills may be dropped after auto-compaction.
  • Updated skills apply to existing sessions.
  • Claude Desktop and Claude Code do not share skills.
  • Technique-teaching skills rot as models improve, preference skills stay durable.

DOs​

  • Use skill-creator skill.
  • Keep ~5–8 active skills per project.
  • Audit recurringly. Most value is in relocating and merging, not deleting.
  • Retire skills re-derivable with a one-liner or absorbed by newer models.

DON'Ts​

  • Don't keep skills "just in case"; disable after two weeks unused.
  • Don't keep a larger procedure's steps as separate skills — merge.
  • Don't write evals with only clean prompts — real users have typos and abbreviations.
  • Don't use multi-line YAML descriptions — they fail silently.

Hierarchy​

~/.claude/skills/
└── my-awesome-global-skill/

my-awesome-project/
├── my-awesome-project-skill/
└── packages/
    └── api/
        └── my-awesome-project-override-skill/

my-awesome-skill/
├── SKILL.md           → Required, the main skill definition
├── assets/            → Optional, static files used in output (templates, icons, fonts)
├── references/        → Optional, detailed context loaded on demand
├── scripts/           → Optional, executable code for deterministic/repetitive tasks
└── some-other-dir/    → Optional, explain what it's for in SKILL.md

References​