Claude Skill Authoring

Teach and apply the official Claude Code rules for authoring a SKILL.md. Keep the active file short, make activation explicit via the description, and push detail to referenced files. This skill explains how to author correctly; for bulk repair/hardening use toolkit-hardener, for plugin packaging use plugin-builder.

Frontmatter Contract

The toolkit requires name and description. Its shared validator accepts the current Claude Code fields when_to_use, argument-hint, arguments, invocation controls, allowed-tools, disallowed-tools, model, effort, context, agent, hooks, paths, and shell, plus toolkit metadata fields. Unknown legacy keys such as author or owner belong under metadata:. [DOC][CÓDIGO]

• name — kebab-case, ≤64 chars, must match the skill directory name. [DOC]
• description — states WHAT it does AND WHEN to load it (triggers live here, not in the body); ≤1024 chars; no </>. [DOC]
• allowed-tools — pre-approves (auto-approves) listed tools; it does not shrink the total tool pool. To limit or block tools use disallowed-tools or permissions.deny. [DOC]
• argument-hint — documents expected invocation arguments. [DOC]
• user-invocable: false — background knowledge that should not surface as a command. [DOC]
• disable-model-invocation: true — user-only invocation for controlled workflows. [DOC]
• context: fork + optional agent — execute in a forked subagent context. [DOC]
• hooks, paths, shell, model, and effort — scoped runtime controls; use only when the workflow needs them. [DOC]

Authoring Workflow

1. Classify the target: personal (~/.claude/skills/), project (.claude/skills/), plugin skill (/plugin:skill), or plugin-root skill. The command name comes from the directory (or plugin namespace), not a display name. [DOC]
2. Write a triggering description. Lead with concrete user phrasings ("when the user asks to …"). A vague description means Claude never loads the skill. [DOC]
3. Keep SKILL.md lean (<500 lines): overview, triggers, process, resource map. Move matrices, checklists, templates to references/, assets/, examples/. [DOC]
4. Set tool controls deliberately. Least-privilege allowed-tools; context: fork only when the skill should run as an isolated subagent task. When converting a command into a skill, carry its allowed-tools/argument-hint over to the frontmatter and add context: fork only if the command was a long isolated job, not a quick inline reply. [DOC]
5. Add evals in schema v2: explicit semantic_status: not_executed, an allowlisted static_contract.oracles set, and cases with typed activation, expected behavior/checks, and resolved static_oracle_ids. Include positive and adversarial/routing coverage. [CONFIG]
6. Validate: python3 "${CLAUDE_PLUGIN_ROOT}/scripts/lib/validate_frontmatter.py" <SKILL.md> followed by python3 "${CLAUDE_PLUGIN_ROOT}/scripts/validate_skill_contracts.py". ${CLAUDE_PLUGIN_ROOT}/scripts/scaffold_skill.py emits a schema-v2 candidate that remains red until independent review metadata is recorded. [CÓDIGO]

Quality Gate

• Frontmatter only uses allowed keys; extras folded into metadata.
• Description carries real triggers; name matches directory.
• Progressive disclosure instead of giant in-file matrices.
• Evals are non-generic and include a false-positive case.
• coverage_gap recorded when official docs/validators can't be checked.

Anti-Patterns

• Putting triggers in the body instead of the description.
• Non-standard frontmatter keys at top level (author/owner) — they fail validation.
• Duplicating toolkit-hardener (repair/harden) or plugin-builder (packaging) here.
• One skill per documentation URL.

Related

• toolkit-hardener — audit/repair/harden lifecycle over the packet and its gates.
• plugin-builder — packaging skills into a shareable plugin.
• claude-command-authoring — slash-command vs skill decision and authoring.
• custom-tooling-extension — extension decision tree and tool whitelisting.

Sources

• references/source-map.md — official skill-authoring provenance and refresh boundary. [CONFIG]

Contract

• Aceptación: SKILL.md con description 3ª persona/trigger fuerte, cuerpo lean, progressive disclosure a references/. [EXPLICIT]
• Límites: autoría de la skill; empaquetar como plugin → plugin-builder. [EXPLICIT]
• Casos borde: cuerpo pesado → mover detalle a references/ (presupuesto de tokens). [EXPLICIT]
• Supuestos: contrato de frontmatter del validador vendorizado. [SUPUESTO]
• Trade-off: cuerpo rico vs lean — descubribilidad vs costo de activación. [EXPLICIT]

Packet

Capas del packet, cargables bajo demanda (disciplina ICM: una capa por vez, nunca todas juntas): references/ guías de profundidad (cargar UNA por etapa).