skills

Skills

A skill is one reusable workflow with one job, written so the agent can invoke it by name. This folder is the authoring guide plus one worked, generic example.

Anatomy

skills/
  <skill-name>/
    SKILL.md      # frontmatter (name, description) + when to use + steps + anti-patterns
    scripts/      # optional helper scripts the skill calls

The description in the frontmatter is what the agent matches against to decide relevance, so it carries the triggers. Write it for retrieval, not for humans.

What makes a skill good

• A sharp trigger. Say when to use it and, just as important, when not to. A skill that fires on everything is noise.
• A deterministic core. The same input should produce the same shape of output. Push the variable judgment to the edges, keep the middle repeatable.
• Explicit anti-patterns. List the mistakes the agent should avoid. This is where most of the value lives, because it encodes what you learned the hard way.
• Token safety. Keep large intermediate output on disk; read back only the salient parts. Never paste a full transcript into the conversation.

Worked example

See example-second-brain-link/SKILL.md: a skill that ingests any link, extracts its core ideas, cross-references a local notes folder, and returns action items, without dumping the full text into chat.

Authoring loop

1. Notice a workflow you have repeated two or more times.
2. Apply a quality filter: will it recur within a month? Is it more than a quick search? Does it need several steps to do by hand? If not, do not write it.
3. Draft the SKILL.md. Lead with the trigger and the anti-patterns.
4. Run it on a real task. Fix what broke. Repeat until it works unattended.