Skill Authoring v1.0.0

name: "skill-authoring" description: "Write portable, high-quality SKILL.md files: frontmatter, structure, and instruction style that agents actually follow."

Skill Authoring

A skill is a markdown file that teaches an agent a repeatable capability. Write it to be followed, not admired.

File layout

my-skill/
  SKILL.md        # the skill itself (required)
  skill.yaml      # manifest: slug, name, version, description, category (tooling)
  bin/            # helper scripts the skill references (optional)

SKILL.md starts with frontmatter:

markdown
---
name: "my-skill"
description: "One line: what it does and when to use it."
---

The description is the most-read line in the registry -- it decides whether an agent opens your skill at all. Say what it does AND when to reach for it.

Structure that works

1. Title + one-paragraph purpose. What capability, what outcome.
2. The happy path first. The 5-10 steps or commands for the common case, copy-paste ready.
3. Gotchas section. The non-obvious failures and how to avoid them. This is the highest-value part of any skill -- it encodes experience.
4. Verification. How to confirm the result is correct. A skill without a "how to check your work" section produces confident mistakes.
5. Anti-patterns. What not to do, briefly.

Instruction style

• Imperative and concrete: "Run X, then check Y" beats "One might consider X."
• Include exact commands, paths, and expected outputs where it matters.
• Keep it portable: no personal names, no machine-specific paths, no secrets. Use <placeholder> for anything the user must fill in.
• Length guideline: long enough to be complete, short enough to be read. 40-100 lines covers most skills. If it needs more, split it.

Before publishing

• [ ] Description says what it does and when to use it
• [ ] Happy path is copy-paste runnable
• [ ] Gotchas encode at least one real failure mode
• [ ] Verification steps are checkable, not vibes
• [ ] No private data, names, credentials, or local paths
• [ ] Signed with your private key; manifest version bumped