skill-writer

skill-writer

Meta-skill that governs how AI agents author and refactor skills (and rules) inside mind-vault or any sibling repository that follows the same convention. Fully IDE-agnostic: the same rules apply whether the invoking host is Claude Code, Cursor, Antigravity, OpenCode, Copilot, or any other skill-aware agent.

When to use

TRIGGER when: user asks to "create/add/write a new skill", "extract a pattern into mind-vault", "formalize an AI codebase rule", "refactor a skill"; or when reviewing/rewriting any file matching skills/*/SKILL.md or rules/RULE_*.md.

SKIP for: one-off prose docs, changelogs, READMEs, ADRs, or in-project configuration files — these are not agent-invoked skills and do not need the SKILL.md contract.

File layout

A skill lives in its own folder whose name is the skill slug:

skills/
└── <skill-slug>/
    ├── SKILL.md              # Pattern body (required, target <500 lines)
    ├── references/           # Long examples, configs, deep-dive docs (loaded on demand)
    │   └── *.md
    ├── assets/               # Templates/snippets the agent emits verbatim
    │   └── *.{py,sh,yml,…}
    └── scripts/              # Executable helpers the agent runs
        └── *.sh

• Filename must be SKILL.md (uppercase). Lowercase skill.md is not discovered by most hosts.
• Folder name = name: frontmatter field, kebab-case, no skill- prefix (the folder is already under skills/).

Frontmatter contract

Required minimum:

---
name: <kebab-case-slug>         # matches folder name
description: <one-line trigger> # <200 chars, noun-dense
---

Optional on larger skills (use when the skill is versioned, replaces older skills, or needs provenance):

license: Apache-2.0
metadata:
  author: mind-vault
  version: "1.0"
  replaces:
     - <older-skill-name>

Writing the description

The description is the probabilistic trigger — the only text the host agent inspects when deciding whether to load the skill. Bad descriptions = skill never fires, or fires on the wrong turns.