skill-creator

skill-creator1450 wordsMITRepo-owned

Create, improve, and audit AI agent skills. 14 structural patterns, deterministic scoring. Use when building or reviewing skills. NOT for agents, MCP servers, or running skills.

Quick Start

Install:

npx skills add github:wyattowalsh/agents --skill skill-creator -y -g --agent antigravity --agent claude-code --agent codex --agent crush --agent cursor --agent gemini-cli --agent github-copilot --agent grok --agent opencode

Use: /skill-creator <mode> [name]

Research context (evidence, not authority)

Problem: Create, improve, and audit AI agent skills. 14 structural patterns, deterministic scoring. Use when building or reviewing skills. NOT for agents, MCP servers, or running skills. Stack / assumptions: Requires Python 3.13+; optional uv for project tooling; optional Node.js/npm for install commands; hook support varies by agent client. Comparable alternative: A general-purpose agent instruction without a scoped skill contract

Works with Claude Code, Gemini CLI, OpenCode, and other agentskills.io-compatible agents.

Repo skill (hand-maintained)

Composed compose-custom-wave-7 from skills/skill-creator/SKILL.md with full SKILL disclosure. Do not run wagents docs generate on this file (HAND-MAINTAINED sentinel).

What It Does

Create, improve, and audit AI agent skills. Every skill follows 14 proven structural patterns.

Modes

$ARGUMENTS	Action	Example
create <name> / new <name>	Develop (new)	/skill-creator create my-analyzer
create <name> --from <source>	Develop (new, from exemplar)	/skill-creator create my-analyzer --from wargame
improve <name> / improve <path>	Develop (existing)	/skill-creator improve add-badges
plan <name> / plan <path>	Plan (existing)	/skill-creator plan honest-review
plan --all / plan repo	Plan (repo-wide)	/skill-creator plan --all
audit <name>	Audit	/skill-creator audit honest-review
audit --all	Audit All	/skill-creator audit --all
dashboard	Dashboard	/skill-creator dashboard
package <name> / package --all	Package	/skill-creator package wargame
Natural language skill idea	Auto: Develop (new)	"tool that audits Python type safety"
Skill name + modification verb	Auto: Develop (existing)	"refactor the wargame skill"
Path to SKILL.md	Auto: Develop (existing)	skills/wargame/SKILL.md
”MCP server” / “agent” / “run”	Refuse + redirect	—
Empty	Gallery	/skill-creator

Quick Start

python skills/skill-creator/scripts/scaffold_skill.py <name>  # Scaffold from template
python scripts/check.py                                        # Validate from skill directory
uv run python skills/skill-creator/scripts/audit.py skills/<name>/  # Score quality
python skills/skill-creator/scripts/package.py skills/<name>/ --dry-run  # Portability check

Skill Development

Unified process for creating new skills and improving existing ones. Load references/workflow.md for the full procedure.

Step	New Skill	Existing Skill
1. Understand	Define use cases, scope, patterns	Audit + understand user’s intent
2. Plan	Structure, description, frontmatter	Gap analysis + improvement plan (approval gate)
3. Scaffold	scaffold_skill.py <name>	Skip
4. Build	Write/edit body, references, scripts, templates, evals	Same
5. Validate	scripts/check.py + audit.py	Same
6. Iterate	Test, identify issues, loop to Step 4	Same

Audit

Score a skill using deterministic analysis + AI review. Load references/audit-guide.md.

Audit All

Comparative ranking of all repository skills. Load references/audit-guide.md § Audit All.

Package

Package skills into portable ZIP files for Claude Code Desktop import. Load references/packaging-guide.md for ZIP structure, manifest schema, portability checks, and cross-agent compatibility.

python skills/skill-creator/scripts/package.py skills/<name>/ --dry-run  # Check before emitting a ZIP
python skills/skill-creator/scripts/package.py skills/<name>/            # Single skill → <name>-v<version>.skill.zip

Core Principles

Conciseness is respect — The context window is shared. Every line competes with the agent’s working memory. Earn every line or delete it.

Progressive disclosure — Frontmatter for discovery (~100 tokens), body for dispatch (<5K tokens), references for deep knowledge (on demand), scripts/templates for execution (never loaded).

Self-exemplar — This skill follows every pattern it teaches. When in doubt, look at how skill-creator applies it.

Critical Rules

1. Run python scripts/check.py from the target skill directory before declaring any skill complete
2. Re-run python scripts/check.py after changing evals and before declaring the skill complete
3. Run uv run python skills/skill-creator/scripts/audit.py after every significant SKILL.md change
4. Never create a skill without a dispatch table — it is the routing contract
5. Never create a dispatch table without an empty-args handler — unrouted input is a bug
6. Every reference file must appear in the Reference File Index — orphan refs are invisible
7. Every indexed reference must exist on disk — phantom refs cause agent errors
8. Body must stay under 500 lines (below frontmatter) — move detail to references
9. Description must include “Use when” trigger phrases AND “NOT for” exclusions
10. Names must be kebab-case, 2-64 chars, no consecutive hyphens, no reserved words
11. Scripts use argparse + JSON to stdout — no custom output formats
12. Templates are self-contained HTML with no external dependencies
13. Do NOT call repo-specific docs generators directly — delegate to docs-steward
14. Do NOT create agents or MCP servers — refuse gracefully and redirect
15. Improving existing skills requires presenting an improvement plan and getting user approval before implementing changes
16. Audit mode is read-only — never modify the skill being audited
17. Update evals when dispatch behavior or modes change — stale evals are invisible bugs
18. plan <name> and plan --all are read-only planning modes — never edit during planning
19. Repo-wide or multi-skill requests require a ranked plan and standalone refinement-plan output before any implementation begins
20. Stop hooks must include a stop_hook_active guard — recursive hook loops are implementation bugs

Canonical terms (use these exactly throughout):

• Modes: “Develop (new)”, “Develop (existing)”, “Audit”, “Audit All”, “Dashboard”, “Package”, “Gallery”
• Steps (Development): “Understand”, “Plan”, “Scaffold”, “Build”, “Validate”, “Iterate”
• Grade scale: “A” (90-100), “B” (75-89), “C” (60-74), “D” (40-59), “F” (<40)
• Patterns: “dispatch-table”, “reference-file-index”, “critical-rules”, “canonical-vocabulary”, “scope-boundaries”, “classification-gating”, “scaling-strategy”, “state-management”, “scripts”, “templates”, “hooks”, “progressive-disclosure”, “body-substitutions”, “stop-hooks”
• Audit dimensions: “frontmatter”, “description”, “dispatch-table”, “body-structure”, “pattern-coverage”, “reference-quality”, “critical-rules”, “script-quality”, “portability”, “conciseness”, “canonical-vocabulary”, “evaluation-coverage”, “validation-contract”

Repo-Wide / Multi-Skill Planning

Use plan <name> for an existing-skill refinement plan without editing and plan --all or plan repo for a ranked repo-wide planning pass.

Required planning output:

1. baseline audit summary
2. highest-value findings
3. explicit file targets
4. expected score impact
5. approval gate before any edits

For repo-wide planning, produce a ranked queue plus one standalone refinement plan per promoted skill or skill cluster. Do not edit any skill until the user approves the plan.

Load references/refinement-plan.md when producing the standalone refinement-plan packet.

Dashboard

Render visual creation process monitor or audit quality dashboard. Load references/audit-guide.md § Dashboard.

Auto-detects mode from data: phases field → process monitor; skills array → audit overview.

Gallery (Empty Arguments)

Present skill inventory with scores and available actions. Run uv run python skills/skill-creator/scripts/audit.py --all --format table, display results, offer mode menu.

Hooks

PreToolUse hooks intercept tool calls during skill execution. The hooks: frontmatter field scopes hooks to this skill only — they activate when the skill is loaded and deactivate when it completes.

Post-edit enforcement for this skill:

• SKILL.md edits trigger validate_skill.py
• evals/*.json edits trigger validate_evals.py
• hook-bearing skill/settings edits trigger validate_hooks.py
• failures surface to the agent instead of being swallowed

Stop hook enforcement:

• runs uv run python skills/skill-creator/scripts/verify.py stop
• validates dirty skill-definition, eval, and hook surfaces before exit
• exits immediately when hook input has stop_hook_active: true to avoid recursive Stop-hook loops

State Management

Creation progress persists at ~/.{gemini\|copilot\|codex\|claude}/skill-progress/<name>.json. Read/write via scripts/progress.py. Survives session restarts. Use --state-dir to override the default location.

Validation Contract

Run from this skill directory before declaring changes complete:

python scripts/check.py

Completion criteria:

1. scripts/check.py exits 0.
2. No portable-CLI violations remain under this skill directory.

Public Metadata

Field	Value
Source Type	repo-owned
Display Source	github:wyattowalsh/agents
Source Kind	repo
Installability	portable command
Review State	reviewed
Target Agents	antigravity, claude-code, codex, crush, cursor, gemini-cli, github-copilot, grok, opencode

General

Field	Value
Name	skill-creator
License	MIT
Version	2.0.0
Author	wyattowalsh

Claude Code

Field	Value
Model	opus
Argument Hint	[mode] [name]

Compatibility

Field	Value
Compatibility	Requires Python 3.13+; optional uv for project tooling; optional Node.js/npm for install commands; hook support varies by agent client.

Related Skills

prompt-engineer Prompt engineering. Craft, analyze, harden, convert, design tool prompts, and build PromptOps/eval plans. Use for system, agent, tool, RAG prompts.

mcp-creator Build MCP servers with FastMCP v3. Research, scaffold, implement, test, deploy. Use when creating MCP servers or integrating APIs via MCP.

View Full SKILL.md

SKILL.md

---
name: skill-creator
description: >-
  Create, improve, and audit AI agent skills. 14 structural patterns,
  deterministic scoring. Use when building or reviewing skills. NOT for
  agents, MCP servers, or running skills.
argument-hint: "<mode> [name]"
model: opus
license: MIT
compatibility: "Requires Python 3.13+; optional uv for project tooling; optional Node.js/npm for install commands; hook support varies by agent client."
metadata:
  author: wyattowalsh
  version: "2.0.0"
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - command: "echo 'skill-creator: Bash access granted for script execution'"
  PostToolUse:
    - matcher: "Write|Edit|MultiEdit"
      hooks:
        - type: command
          command: "uv run python skills/skill-creator/scripts/verify.py post-tool-use"
  Stop:
    - hooks:
        - type: command
          command: "uv run python skills/skill-creator/scripts/verify.py stop"
---

# Skill Creator

Create, improve, and audit AI agent skills. Every skill follows 14 proven structural patterns.

**Scope:** Skills only. NOT for creating agents (use `agent-conventions`), building MCP servers (`/mcp-creator`), or running existing skills. This repo uses raw `SKILL.md` format committed directly to `skills/`.

## Dispatch

| $ARGUMENTS                          | Action                       | Example                                            |
| ----------------------------------- | ---------------------------- | -------------------------------------------------- |
| `create <name>` / `new <name>`      | Develop (new)                | `/skill-creator create my-analyzer`                |
| `create <name> --from <source>`     | Develop (new, from exemplar) | `/skill-creator create my-analyzer --from wargame` |
| `improve <name>` / `improve <path>` | Develop (existing)           | `/skill-creator improve add-badges`                |
| `plan <name>` / `plan <path>`       | Plan (existing)              | `/skill-creator plan honest-review`                |
| `plan --all` / `plan repo`          | Plan (repo-wide)             | `/skill-creator plan --all`                        |
| `audit <name>`                      | Audit                        | `/skill-creator audit honest-review`               |
| `audit --all`                       | Audit All                    | `/skill-creator audit --all`                       |
| `dashboard`                         | Dashboard                    | `/skill-creator dashboard`                         |
| `package <name>` / `package --all`  | Package                      | `/skill-creator package wargame`                   |
| Natural language skill idea         | Auto: Develop (new)          | `"tool that audits Python type safety"`            |
| Skill name + modification verb      | Auto: Develop (existing)     | `"refactor the wargame skill"`                     |
| Path to SKILL.md                    | Auto: Develop (existing)     | `skills/wargame/SKILL.md`                          |
| "MCP server" / "agent" / "run"      | Refuse + redirect            | —                                                  |
| Empty                               | Gallery                      | `/skill-creator`                                   |

### Auto-Detection Heuristic

If no explicit mode keyword is provided:

1. Path ending in `SKILL.md` or directory under `skills/` → **Develop (existing)**
2. Existing skill name + modification verb (improve, refactor, enhance, update, fix, rewrite, optimize, polish, revise, change) → **Develop (existing)**
3. `--from <source>` in arguments → **Develop (new, from exemplar)**
4. New capability description ("I want to build...", "tool that...", "skill for...") → **Develop (new)** — derive name, confirm before scaffolding
5. "MCP server", "agent", "run" → refuse gracefully and redirect
6. Ambiguous → ask the user which mode they want

## Quick Start

```bash
python skills/skill-creator/scripts/scaffold_skill.py <name>  # Scaffold from template
python scripts/check.py                                        # Validate from skill directory
uv run python skills/skill-creator/scripts/audit.py skills/<name>/  # Score quality
python skills/skill-creator/scripts/package.py skills/<name>/ --dry-run  # Portability check
```

## Skill Development

Unified process for creating new skills and improving existing ones. Load `references/workflow.md` for the full procedure.

| Step          | New Skill                                                 | Existing Skill                                  |
| ------------- | --------------------------------------------------------- | ----------------------------------------------- |
| 1. Understand | Define use cases, scope, patterns                         | Audit + understand user's intent                |
| 2. Plan       | Structure, description, frontmatter                       | Gap analysis + improvement plan (approval gate) |
| 3. Scaffold   | `scaffold_skill.py <name>`                                | Skip                                            |
| 4. Build      | Write/edit body, references, scripts, templates, evals    | Same                                            |
| 5. Validate   | `scripts/check.py` + `audit.py`                           | Same                                            |
| 6. Iterate    | Test, identify issues, loop to Step 4                     | Same                                            |

## Repo-Wide / Multi-Skill Planning

Use `plan <name>` for an existing-skill refinement plan without editing and `plan --all` or `plan repo` for a ranked repo-wide planning pass.

Required planning output:

1. baseline audit summary
2. highest-value findings
3. explicit file targets
4. expected score impact
5. approval gate before any edits

For repo-wide planning, produce a ranked queue plus one standalone refinement plan per promoted skill or skill cluster. Do not edit any skill until the user approves the plan.

Load `references/refinement-plan.md` when producing the standalone refinement-plan packet.

## Audit

Score a skill using deterministic analysis + AI review. Load `references/audit-guide.md`.

## Audit All

Comparative ranking of all repository skills. Load `references/audit-guide.md` § Audit All.

## Dashboard

Render visual creation process monitor or audit quality dashboard. Load `references/audit-guide.md` § Dashboard.

Auto-detects mode from data: `phases` field → process monitor; `skills` array → audit overview.

## Gallery (Empty Arguments)

Present skill inventory with scores and available actions.
Run `uv run python skills/skill-creator/scripts/audit.py --all --format table`, display results, offer mode menu.

## Package

Package skills into portable ZIP files for Claude Code Desktop import. Load `references/packaging-guide.md` for ZIP structure, manifest schema, portability checks, and cross-agent compatibility.

```bash
python skills/skill-creator/scripts/package.py skills/<name>/ --dry-run  # Check before emitting a ZIP
python skills/skill-creator/scripts/package.py skills/<name>/            # Single skill → <name>-v<version>.skill.zip
```

## Hooks

PreToolUse hooks intercept tool calls during skill execution. The `hooks:` frontmatter field scopes hooks to this skill only — they activate when the skill is loaded and deactivate when it completes.

Post-edit enforcement for this skill:

- `SKILL.md` edits trigger `validate_skill.py`
- `evals/*.json` edits trigger `validate_evals.py`
- hook-bearing skill/settings edits trigger `validate_hooks.py`
- failures surface to the agent instead of being swallowed

Stop hook enforcement:

- runs `uv run python skills/skill-creator/scripts/verify.py stop`
- validates dirty skill-definition, eval, and hook surfaces before exit
- exits immediately when hook input has `stop_hook_active: true` to avoid recursive Stop-hook loops

## State Management

Creation progress persists at `~/.{gemini|copilot|codex|claude}/skill-progress/<name>.json`. Read/write via `scripts/progress.py`. Survives session restarts. Use `--state-dir` to override the default location.

## Reference File Index

| File                              | Content                                                                              | Read When                                          |
| --------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------- |
| `references/workflow.md`          | Unified 6-step skill development process for new and existing skills                 | Develop (new), Develop (existing)                  |
| `references/refinement-plan.md`   | Standalone refinement-plan contract for existing-skill and repo-wide planning output | Plan (existing), Plan (repo-wide)                  |
| `references/audit-guide.md`       | Audit procedure, Audit All, Dashboard rendering, Gallery, grade thresholds           | Audit, Audit All, Dashboard, Gallery               |
| `references/proven-patterns.md`   | 14 structural patterns with examples from repo skills                                | Step 4 (Build), gap analysis                       |
| `references/best-practices.md`    | Anthropic guide + superpowers methodology + cross-agent awareness                    | Step 2 (Plan), Step 4 (Build), description writing |
| `references/frontmatter-spec.md`  | Full field catalog, invocation matrix, decision tree                                 | Step 3 (Scaffold), frontmatter configuration       |
| `references/packaging-guide.md`   | ZIP structure, manifest schema, portability checks, import instructions              | Package                                            |
| `references/evaluation-rubric.md` | 13 weighted scoring dimensions normalized to 100, grade thresholds, pressure testing | Audit (pressure testing), scoring targets          |

Read reference files as indicated by the "Read When" column above. Do not rely on memory or prior knowledge of their contents.

## Core Principles

**Conciseness is respect** — The context window is shared. Every line competes with the agent's working memory. Earn every line or delete it.

**Progressive disclosure** — Frontmatter for discovery (~100 tokens), body for dispatch (<5K tokens), references for deep knowledge (on demand), scripts/templates for execution (never loaded).

**Self-exemplar** — This skill follows every pattern it teaches. When in doubt, look at how skill-creator applies it.

## Validation Contract

Run from this skill directory before declaring changes complete:

```bash
python scripts/check.py
```

Completion criteria:

1. `scripts/check.py` exits 0.
2. No portable-CLI violations remain under this skill directory.

## Critical Rules

1. Run `python scripts/check.py` from the target skill directory before declaring any skill complete
2. Re-run `python scripts/check.py` after changing evals and before declaring the skill complete
3. Run `uv run python skills/skill-creator/scripts/audit.py` after every significant SKILL.md change
4. Never create a skill without a dispatch table — it is the routing contract
5. Never create a dispatch table without an empty-args handler — unrouted input is a bug
6. Every reference file must appear in the Reference File Index — orphan refs are invisible
7. Every indexed reference must exist on disk — phantom refs cause agent errors
8. Body must stay under 500 lines (below frontmatter) — move detail to references
9. Description must include "Use when" trigger phrases AND "NOT for" exclusions
10. Names must be kebab-case, 2-64 chars, no consecutive hyphens, no reserved words
11. Scripts use argparse + JSON to stdout — no custom output formats
12. Templates are self-contained HTML with no external dependencies
13. Do NOT call repo-specific docs generators directly — delegate to docs-steward
14. Do NOT create agents or MCP servers — refuse gracefully and redirect
15. Improving existing skills requires presenting an improvement plan and getting user approval before implementing changes
16. Audit mode is read-only — never modify the skill being audited
17. Update evals when dispatch behavior or modes change — stale evals are invisible bugs
18. `plan <name>` and `plan --all` are read-only planning modes — never edit during planning
19. Repo-wide or multi-skill requests require a ranked plan and standalone refinement-plan output before any implementation begins
20. Stop hooks must include a `stop_hook_active` guard — recursive hook loops are implementation bugs

**Canonical terms** (use these exactly throughout):

- Modes: "Develop (new)", "Develop (existing)", "Audit", "Audit All", "Dashboard", "Package", "Gallery"
- Steps (Development): "Understand", "Plan", "Scaffold", "Build", "Validate", "Iterate"
- Grade scale: "A" (90-100), "B" (75-89), "C" (60-74), "D" (40-59), "F" (<40)
- Patterns: "dispatch-table", "reference-file-index", "critical-rules", "canonical-vocabulary", "scope-boundaries", "classification-gating", "scaling-strategy", "state-management", "scripts", "templates", "hooks", "progressive-disclosure", "body-substitutions", "stop-hooks"
- Audit dimensions: "frontmatter", "description", "dispatch-table", "body-structure", "pattern-coverage", "reference-quality", "critical-rules", "script-quality", "portability", "conciseness", "canonical-vocabulary", "evaluation-coverage", "validation-contract"

Download from GitHub

Resources

Skill Catalog Browse custom and external skills.

CLI Reference Install and manage skills.

agentskills.io The open ecosystem for cross-agent skills.

---

View source on GitHub