/skill-creator

name: skill-creator
description: Scaffold, author, and validate an Agent Skill. Use when the user wants to create a new skill, turn a repeatable workflow into a reusable SKILL.md, or fix a skill that fails to load.

Skill Creator

A *skill* is a reusable, task-specific playbook stored as a `SKILL.md` file in a directory named after the skill. Skills are advertised in the system prompt by name + description (progressive disclosure); their full instructions are loaded on demand with the `read_skill` tool.

Use this skill whenever the user asks to create, author, or improve a skill.

1. Choose a scope

A skill lives in one of three scopes. Pick based on how widely it should apply:

• **project** — `<project_root>/.agents/skills/<name>/` — specific to one repo.

Load with `read_skill(project="<project-name>", name="<name>")`; read its resources with `read_files(project="<project-name>", ...)`.

• **user** — `~/.agents/skills/<name>/` — your personal skills, available in

every project (and shared with other agent harnesses). Addressed by the scope token `:config:`; load with `read_skill(project=":config:", ...)`.

• **system** — token `:system:` — bundled skills (like this one). Usually

read-only.

On a name collision, project wins over user wins over system.

2. Write `SKILL.md`

The file MUST start with a YAML frontmatter block delimited by `---` lines, followed by a free-form Markdown body:

---
name: my-skill
description: One-paragraph routing description the model uses to decide when to load this skill.
---

# My Skill

...instructions...

Frontmatter rules (enforced by the loader):

• `name` is required, must be **lowercase letters, digits, and hyphens** only,

at most 64 characters, and must **equal the directory name**.

• `description` is required, at most 1024 characters. Write it as a routing

signal: say *when* to use the skill, not just what it does.

• `disable-model-invocation` (optional, default `false`): when `true`, the

skill is hidden from the model-facing catalog and the `list_skills` tool so the model never auto-invokes it. It stays loadable via `read_skill` (e.g. when a user explicitly activates it) and visible in the settings UI. Use this for skills that should only run on explicit user request.

• Other keys (license, allowed-tools, metadata, etc.) are allowed and ignored

for now.

3. Add resources (optional)

Bundle supporting files under the skill directory and reference them from the body with paths relative to the skill directory:

• `scripts/` — runnable helpers. Prefer running them with `execute_command`

rather than reading them into context.

• `references/` — longer docs to read on demand with `read_files`.
• `assets/` — templates or output skeletons.

Keep `SKILL.md` itself short: it should orchestrate, pointing at the right resource for each sub-task instead of inlining everything.

4. Validate

• The directory name equals `name`.
• Frontmatter parses and `name`/`description` satisfy the rules above.
• Referenced resource paths exist and are relative to the skill directory.
• Load it once with `read_skill` to confirm the body renders as expected.

Template

---
name: <kebab-case-name>
description: Use this skill when <trigger>. It <what it does>.
---

# <Human Title>

## When to use
<one or two sentences>

## Workflow
1. <step>
2. <step>

## Resources
- `references/<doc>.md` — <what it contains>
- `scripts/<tool>` — <what it does> (run with execute_command)

Quality checklist

• Single responsibility: one skill, one job.
• The description is a strong routing signal (the model only sees this until it

loads the skill).

• Progressive disclosure: short body, details in `references/`.
• Deterministic work lives in `scripts/`, not in prose.