author-skill

Essential Principles

Skills are prompts. Be clear, be direct, use Markdown headings. Only add context the model doesn't already have.
SKILL.md is always loaded. Keep it lean — details go in workflows/ and references/. Layout: references/skill-structure.md.
Pure Markdown structure. No XML tags. Standardized headings per template. Anti-patterns: references/anti-patterns.md.
Token efficiency. Every token loads on every invocation. Say it once, tables over prose, eliminate filler. Checklist: references/token-efficiency.md.
Write for understanding. Models generalize better from reasoning than mandates — explain why, not just what. Escalate to authority language only when reasoning fails in testing. Details: references/writing-effective-skills.md.
Test before shipping. After writing or editing a skill, verify it works by walking through realistic scenarios inline. Check that instructions are clear, complete, and unambiguous.

Resolve {skills-dir} before proceeding. Check cwd for project skill directories first, fall back to global:

Check	`{skills-dir}`
A project skills directory exists in cwd or ancestor dirs (`.agents/skills/`, or harness-specific e.g. `.claude/skills/`, `.pi/skills/`)	That project directory
Otherwise	The global skills directory (`~/.agents/skills/`, or harness-specific e.g. `~/.claude/skills/`, `~/.pi/agent/skills/`)