# Skill Creator

> 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: `stippi/skill-creator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add stippi/skill-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stippi/skill-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: stippi (https://skillmd.com/u/stippi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/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.