Create Skill

Adding a Reusable Skill

Reference: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

Agent Skills are modular capabilities that extend an AI agent's functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates) that the agent uses automatically when relevant.

Core principles (keep SKILL.md lean)

• Be concise: SKILL.md is loaded into context; every token competes with the user's request.
• Assume the agent is smart: only add context it wouldn't already know.
• Use progressive disclosure: keep detailed explanations and examples in references/*.md.

Naming + metadata

• name must be lowercase, numbers, hyphens only; prefer a clear action or domain name.
• description must be third-person, specific, and include "when to use".

Invocation and arguments

• Skills run in many harnesses: never assume an invocation syntax ("supplied after /command") or $ARGUMENTS substitution in the body. Where a harness injects arguments, its own configuration does it (e.g. an OpenCode command wrapper), not the skill.
• Read the scope from the user's request, and define a default for when none is given.
• Frontmatter beyond the portable core (name, description, and disable-model-invocation for user-invoked skills) is allowed only when inert elsewhere: harness-specific extras such as Claude Code's argument-hint are ignored by harnesses that don't support them, and the body must never depend on them.

Structure

• skills/<skill-name>/SKILL.md contains quick start, workflow, rules, and pointers to references.
• skills/<skill-name>/references/*.md holds extended explanations and examples.
• Keep references one level deep from SKILL.md (no nested references).
• Add a table of contents for reference files longer than ~100 lines.
• Cross-skill references are allowed, but must include install instructions (e.g., npx skills add https://github.com/alexandru/skills --skill <skill-name>).

Guidance quality

• Prefer the smallest needed typeclass/constraint or API surface.
• Avoid time-sensitive guidance; move outdated info to an "old patterns" section if needed.
• Use consistent terminology across the skill.
• Provide concrete examples only when they materially improve correctness.
• Provide original sources (web links) in references; keep sources high-quality.

Versioning (skills.json)

• Version uses semantic versioning (e.g., 1.0.0).
• Increment patch for minor fixes (typos, code sample mistakes).
• Increment minor when adding a new skill.
• Increment major for more substantial skill changes.

Workflow for adding a skill

1. Create skills/<skill-name>/SKILL.md with YAML frontmatter and concise instructions.
2. Add reference docs under skills/<skill-name>/references/ as needed.
3. Register the skill in skills.json (name, path, description, tags).
4. Update README.md so the skill list and structure stay current.
5. Test with representative prompts and refine.

Checklist

• Name/description meet format rules and are specific.
• SKILL.md is concise and directs to references.
• Examples are in references, not SKILL.md.
• No nested references; one level deep from SKILL.md.
• skills.json version updated per semantic versioning rules.
• skills.json updated with tags.
• README.md updated.
• Tested with at least a few real requests.