skill-author

skill-author

When to use

The user asks to create, write, author, build, or scaffold a new skill. Or you (the agent) need to extend your own capabilities by writing a new SKILL.md.

What a skill is

A skill is a directory containing a SKILL.md file. It tells an agent when to use a capability and how to invoke it. Skills are procedural documentation, not reference docs. The agent reads a skill on demand via skills show <name>.

Directory structure

skills/<skill-name>/
├── SKILL.md           # required: the skill definition
├── README.md          # optional: human-facing notes
└── <other files>      # optional: scripts, templates, data

Frontmatter spec

---
name: my-skill
description: One or two sentences. Be specific about WHEN to use the skill.
metadata:
  shelllm:
    requires:
      env: ["API_KEY"]           # all must be set
      bins: ["curl", "jq"]      # all must exist on PATH
      anyBins: ["gh", "hub"]    # at least one must exist
      os: ["darwin", "linux"]   # current OS must be in list
---

Required: name (kebab-case, matches directory name), description.

Description matters. It's matched against user intent. Bad: "manages files." Good: "Read, write, search, and append notes in an Obsidian vault. Use when the user mentions Obsidian or asks to interact with markdown notes."

Requirements are optional. Only declare metadata.shelllm if the skill needs env vars, binaries, or a specific OS. Skills with unmet requirements are filtered from skills list.

Writing the body

Write for an agent reader, not a human:

• Skip marketing language and "why use this"
• Lead with concrete commands, not prose
• Use tables for command references when they fit
• Keep it under 1,000 tokens -- agent context is precious
• Examples should be copy-pasteable shell commands, not pseudocode
• Don't enumerate all flags -- teach the patterns specific to this tool

Recommended structure

## When to use
[Concrete intent triggers]

## Setup
[One-time prerequisites: env vars, services to enable]

## Common operations

### Operation 1
\`\`\`bash
exact command here
\`\`\`
One sentence on when/why.

### Operation 2
\`\`\`bash
exact command here
\`\`\`

## Tips
[Edge cases, gotchas, composition with other skills]