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.