stippi / skill-creator

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.