skilllisted

# Skill Authoring Guidelines Read this before creating or modifying any skill. These conventions ensure skills are consistent, minimal, and fast to invoke. ## Skill structure ``` skills/<skill-name>/ ├── SKILL.md # Entry point (required) ├── scripts/ # Helper scripts (optional) └── references/ # Reference docs cited from SKILL.md (optional) ``` - Entry point is always `SKILL.md` - Place in `~/.claude/skills/` for global skills, `.claude/skills/` for project-local - Shared resources go in `~/.claude/skills/shared/` - **Creating the directory is not enough to keep the skill.** A skills directory is normally ignore-everything-then-allowlist, so a new skill is untracked and invisible until you add its un-ignore line — see [Gitignore](#gitignore) for the exact check. Do it when you create the directory, not at the end; the `skill-tracked.py` hook flags a miss when the SKILL.md is written, but the hook is a net, not the plan. ### One skill per user-facing task, one implementation underneath A distinct thing the user asks for gets its own skill, even when it is a thin wrapper over a skill that already exists. Skills are the user's interface — `/repo-status` is typed, `repos-status.py --repo .` is not — so folding a second task into an existing skill as a flag hides it behind prose nobody reads at the moment they want it. Single Source of Logic still applies, one layer down: the new skill gets its own `SKILL.md` and **no `scripts/` of its own**,