Config: Skill Conventions ยท diff
git:20260813.874484b to git:20260813.199d770
22 added, 17 removed. Audit A to A.
---
name: "Skill: Conventions"
- description: "{{ ๐ซ๐ซ๐ซ }} Jason's placement and model-tag conventions for creating or editing skills"
+ description: "Jason's placement and model-tag conventions for creating or editing skills"
when_to_use: "Before creating or editing a skill โ checking where it should live and how to tag its model in frontmatter."
# No model/effort override: reference content that loads inline โ an override
# would downgrade the very session that's editing skills
disable-model-invocation: false # Claude must be able to load the conventions at the moment it's creating or editing a skill; read-only guidance needs no gate
+ metadata:
+ family: clod-config
---
# Skill creation conventions
- All skills live in `~/.claude/skills/` as `SKILL.md` files.
- Command skills (invoked explicitly) get `disable-model-invocation: true`; knowledge skills (always available for reference, never directly invoked) get `user-invocable: false`.
- Exception: a command skill may set `disable-model-invocation: false` when its `when_to_use` describes a moment Claude recognises before the user does (stale PR description, post-merge status drift, "add this to the roadmap" phrasing) **and** the skill contains its own approval gate before anything irreversible. The gate is the safety net; without one, keep it `true`.
## Where to create a skill
1. Always create in the project-local `.claude/skills/` directory unless explicitly told to create it globally.
2. Check for naming conflicts with personal-level skills (`~/.claude/skills/`) โ personal scope shadows project scope.
3. Use the new frontmatter convention below when creating or editing skills; recognise the old convention when reading existing skills.
- ## Model-tag convention (new)
+ ## Metadata convention (current)
- Runic letters in the YAML frontmatter `description` field signal which model the command uses:
+ Model and taxonomy live in real frontmatter, never in the `description` text:
- | Runes | Model |
- |---|---|
- | `๐ซ๐ซ๐ซ` | haiku |
- | `ฦฦฦ` | sonnet |
- | `๐๐๐` | opus |
+ ```yaml
+ model: opus # explicit on every command skill; omit on knowledge skills (inherit)
+ effort: high # explicit on every command skill; omit on knowledge skills (inherit)
+ metadata:
+ glyph: แ # mirrors the model: field โ omit when model is omitted
+ family: pr # the skill's family prefix (pr, roadmap, doc, clod-lens, โฆ)
+ bundle: roadmap-system # only on skills shipped by build-roadmap-zip.sh
+ ```
- Format: `description: "{{ ฦฦฦ }} Command description here"`
+ | Glyph | Rune | Model |
+ |---|---|---|
+ | `แบ` | hagalaz | haiku |
+ | `แ` | sowilo | sonnet |
+ | `แ` | othala | opus |
+ | `แ ` | fehu | fable |
- ## Model-tag convention (old โ recognise, don't write)
+ Knowledge skills (`user-invocable: false`) set neither `model` nor `effort`: both fields override the session absolutely while the skill is active, so an inline reference skill would hijack the very turn that triggered it.
- | Runes | Model |
- |---|---|
- | `แปแ` | haiku |
- | `แแค` | sonnet |
- | `แแน` | opus |
- | `แจแ` | fable |
+ ## Model-tag conventions (old โ recognise, don't write)
- Format: `description: "{{ แแค }} Command description here"`
+ Retired forms that tagged the model inside `description` as `"{{ X }} โฆ"`: Greek triples (`๐ซ๐ซ๐ซ` haiku, `ฦฦฦ` sonnet, `๐๐๐` opus) and before that runic pairs (`แปแ` haiku, `แแค` sonnet, `แแน` opus, `แจแ` fable). On sight, migrate the skill to the metadata convention above.