create-skill · git:20261116.c35b66a · 2026-11-16 · sha256 24fb82760401f995
create-skill git:20261116.c35b66aA
Immutable. This exact content never changes and is served at /api/v1/blob/24fb82760401f995.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_m7z6diuos2t3fwns/24fb82760401f995d5df16a919c9c928e519562ecbe9ce174b9a2859cb20575e.json
Then /plugin install create-skill@markdownregistry-m7z6diuos2t3fwns in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: create-skill
description: Scaffold a new bundled skill (.koda/skills/<name>/SKILL.md) with correct frontmatter, tool scoping, and a clear when_to_use trigger.
tags: [skill, scaffold, create, meta]
when_to_use: Use when the user asks to create a new skill, capture a workflow as a skill, or extend koda with reusable expert instructions.
allowed_tools: [Read, Write, Glob, List, AskUser]
---
# Create Skill
You are scaffolding a new koda skill. The goal: produce a working
`.koda/skills/<name>/SKILL.md` (or `~/.config/koda/skills/<name>/SKILL.md`)
that the user can immediately invoke via `ActivateSkill` or `/<name>`.
## Principles
- **Read before writing.** Open `koda-skills/skills/code-review/SKILL.md`
or `koda-skills/skills/debug/SKILL.md` first to ground yourself in the
canonical structure before generating the file.
- **Concise is key.** The skill body is loaded into context every time
the skill is activated. Don't pad. Skip explanations koda already knows
(it's a code agent, you don't need to explain what `Grep` is).
- **`when_to_use` is the most important field.** It's what the model uses
to decide whether to auto-activate the skill. Include trigger phrases.
- **Scope tools.** A code-review skill should not have `Write` access. A
research skill should not have `Edit`. Use `allowed_tools` to
enforce least privilege.
## Process
### 1. Clarify intent (if ambiguous)
Use `AskUser` only when genuinely ambiguous. Skip it for obvious requests
like "create a skill that runs the tests." Things worth asking when unclear:
- **Project or personal scope?** Project = `.koda/skills/<name>/`,
personal/cross-project = `~/.config/koda/skills/<name>/`
- **What triggers it?** Slash command (`/<name>`)? Auto-activated when
the model sees a matching task? Both?
- **What tools does it need?** Read-only analysis (`Read`, `Grep`,
`Glob`), or also write (`Write`, `Edit`)?
### 2. Choose the file path
| Scope | Path | When |
| -------- | ------------------------------------------------------- | ---------------------------------------------- |
| Project | `.koda/skills/<name>/SKILL.md` | Workflow specific to this repo. |
| Personal | `~/.config/koda/skills/<name>/SKILL.md` | Cross-project workflow that follows the user. |
**Note:** Personal path is `~/.config/koda/`, **not** `~/.koda/`.
The `<name>` is both the directory name and the slash-command name (e.g.
`code-review` becomes `/code-review`). Use kebab-case.
### 3. Write the SKILL.md
```markdown
---
name: my-skill
description: One-line purpose (shown in skill listing — keep under 200 chars)
when_to_use: Use when the user asks to <trigger>. Example phrases: "<phrase>", "<phrase>".
tags: [topic-a, topic-b]
allowed_tools: [Read, Grep, Glob, List, Bash]
---
# My Skill
You are <role>. <One-sentence statement of the goal>.
## Principles
- <key behavioral constraint #1>
- <key behavioral constraint #2>
## Process
1. <First concrete step>
2. <Second concrete step>
...
## Anti-patterns
- <thing not to do, with reason>
```
### 4. Field reference
**Required frontmatter:**
- `name` — skill identifier; matches the directory name and the
slash-command name (`/<name>`)
- `description` — one-line purpose shown in the skill listing in the
system prompt. **Keep it ≤200 chars** — the listing is for discovery
only, the model loads full content on activation.
**Highly recommended:**
- `when_to_use` — guidance for the model on when to auto-activate. Start
with "Use when…" and include 1-2 example trigger phrases. **This drives
auto-activation accuracy.**
- `tags` — searchable tags; helps users find the skill via `/skills`
- `allowed_tools` — security/scoping. Empty = all tools (rare). Most
skills should explicitly list only what they need.
**Optional:**
- `argument_hint` — usage hint for skills that take parameters,
e.g. `"<file_path>"` or `"[issue description]"`
- `user_invocable` — defaults to `true`. Set `false` for model-only
skills (hidden from `/skills` but still activatable by the model).
### 5. Anatomy of the body
Mirror the structure of bundled skills:
- **Title** — `# Skill Name` (markdown H1)
- **Role + goal** — one or two sentences
- **Principles** — 3-5 bullets of key behavioral constraints
- **Process** — numbered steps; each step concrete and actionable
- **Anti-patterns / gotchas** — what NOT to do, with brief reasoning
Optionally add:
- **Reference example** — point at a real file the model can `Read`
- **Output format** — if the skill produces structured output
### 6. Write and confirm
1. Use `Write` to create the file at `<chosen-path>/<name>/SKILL.md`.
Note: koda needs the **directory** to exist; the `Write` tool will
create parent directories if needed.
2. Tell the user:
- Where the file was saved
- How to invoke it: `/<name>` or via `ActivateSkill("<name>")`
- That they can edit the SKILL.md directly to refine it
## Anti-patterns to avoid
- **Don't omit `when_to_use`.** Without it, the model has no signal for
when to auto-activate. The skill becomes user-invoke-only by accident.
- **Don't grant `Write`/`Edit` unless the skill actually modifies
files.** A code-review skill with `Write` access is a footgun.
- **Don't write a 500-line SKILL.md for a 5-step workflow.** Concision is
a public good — every skill activation pays the token cost.
- **Don't duplicate context the model already has.** Don't explain what
`Grep` does. Don't list every git command. Skills add value by
encoding *workflow* and *constraints*, not basic knowledge.
- **Don't conflate creating a skill with capturing a session.** This
skill scaffolds a new SKILL.md from a description. If the user wants
to capture an in-progress workflow, that's a different (future)
skillify-style operation.
## Reference
For a battle-tested example, read `koda-skills/skills/code-review/SKILL.md`
or `koda-skills/skills/debug/SKILL.md`. They demonstrate: tight `when_to_use`
phrasing, scoped `allowed_tools`, and concise process sections.