skill-authoring

How to author skills correctly

A set of rules based on the Agent Skills specification + practice. Verified against real skills.

1. Frontmatter (required fields)

---
name: my-skill
description: Use when [triggers/symptoms/contexts]. [what it does + when to apply]
---

Field	Rule
name	REQUIRED. 1–64 characters, a-z0-9 + hyphens; must not start or end with a hyphen, no consecutive hyphens. Must match the skill's folder name
description	REQUIRED. 1–1024 characters. «What it does + when to use»; include the keywords the agent searches by. NOT a workflow summary
metadata	optional, str → str map (kit convention: version); keep values plain strings
license	optional
compatibility	1–500 characters, only if there are environment requirements

2. Directory structure

skill-name/
├── SKILL.md            # required
├── scripts/            # optional: executable scripts
├── references/         # optional: details, «read when X»
├── assets/             # optional
└── any other files/folders — allowed

• Reference files one level deep from the skill root; avoid chained references that force multi-hop loads. Run bundled scripts through --help before reading their source — black-box first, context pollution second.

3. Script bundling (scripts/)

1. First check for an existing tool: npx, uvx, pipx, bunx — take an existing one, write your own only when none exists.
2. If you bundle a script, it must be self-contained: document dependencies in SKILL.md or compatibility.
3. Agent-safe design:
   • NO interactive prompts — the agent will hang on a TTY. Input only via arguments.
   • --help with usage; clear error messages.
   • Structured output: result to stdout, diagnostics to stderr.
   • Idempotency; --dry-run for destructive operations.
   • Predictable output size (agents truncate ~10–30K characters).

4. Best practices and antipatterns

Do:

• Small, composable, like a function: one coherent task.
• Description in the imperative: «Use when …», list the triggers. Agents under-trigger.
• Add what the agent does not know; drop what it already can do.
• Gotchas sections — the most valuable content; checklists for multi-step processes; output templates.
• Defaults, not menus; procedures, not declarations; explain «why».
• Calibrate detail to fragility: for fragile operations — prescriptively.