| name | write-a-skill |
| description | Guide writing a new skill file following Shane's authoring conventions — principle-first, anti-patterns before steps, _lib/ references over inline duplication. Use when invoked as /write-a-skill or when Shane says "create a new skill for X", "add a skill", "write a skill that does X". |
Skill: /write-a-skill [name]
A skill is a short, opinionated document — write the minimum that removes ambiguity, then stop.
Don't: embed blocks that appear in other skills — extract them to _lib/. Don't lead with numbered steps before stating what the skill is for.
Conventions
Length targets:
- Simple delegation skill (Qwen, one task): under 40 lines
- Complex ritual skill (multi-step, fallback): under 80 lines
- If over limit, find what to extract to
_lib/
Structure (in order):
- Frontmatter:
name, description (include trigger phrases and "Do NOT use for" guards)
- H1 with skill name
- Principle line — one sentence stating what the skill produces and why it's valuable; not "this skill does X" — just the thing itself
- Anti-patterns — 1–3
**Don't:** lines naming specific failure modes and the right alternative
- Steps or happy path
- Fallback (if tool-dependent) — kept short via
_lib/ references
Principle line pattern:
Combine WHAT and WHY into one sentence. Examples:
/connect: "Surface the non-obvious bridges between two concepts the vault hasn't linked yet — the value is in connections that surprise, not the ones you'd expect."/trace: "Map the arc of how Shane's thinking on a topic evolved — not the current position, but the path that led there and the inflection points along the way."
_lib/ candidates:
- Any block >10 lines that appears in more than one skill
- Tool invocation protocols (Qwen delegation loop, obsidian commit sequence)
- Save/commit sequences
Process
- Determine the skill name and its trigger phrases.
- Write the
description frontmatter: trigger phrases + "Do NOT use for..." guard.
- Write the principle line — one sentence, WHAT + WHY combined.
- Write 1–3 anti-patterns using the
**Don't:** format; name the right alternative.
- Write steps — collapse any step that just restates what to do without showing how. If the skill depends on an external tool (Qwen, MCP), add a Fallback section.
- Identify
_lib/ candidates — any block you've seen in another skill.
- Count lines. If over target, extract one more thing or delete it.
- Save to
plugins/shane/<plugin>/skills/<name>/SKILL.md.
