Skip to content
wyattowalsh/agents | AI Agent Configs
Docs
skill-creator

skill-creator

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.

skill-creator 1147 words MIT v2.0.0 wyattowalsh opus Custom

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

Section titled “Quick Start”

Install:

Terminal window
npx skills add wyattowalsh/agents/skills/skill-creator -g

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

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

What It Does

Section titled “What It Does”

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

Modes

Section titled “Modes”
$ARGUMENTSActionExample
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
audit <name>Audit/skill-creator audit honest-review
audit --allAudit All/skill-creator audit --all
dashboardDashboard/skill-creator dashboard
package <name> / package --allPackage/skill-creator package wargame
Natural language skill ideaAuto: Develop (new)"tool that audits Python type safety"
Skill name + modification verbAuto: Develop (existing)"refactor the wargame skill"
Path to SKILL.mdAuto: Develop (existing)skills/wargame/SKILL.md
”MCP server” / “agent” / “run”Refuse + redirect—
EmptyGallery/skill-creator

Quick Start

Section titled “Quick Start”
Terminal window
wagents new skill <name>           # Scaffold from template
wagents validate                   # Check all skills
uv run python skills/skill-creator/scripts/audit.py skills/<name>/  # Score quality
wagents package <name>             # Package as portable ZIP

Skill Development

Section titled “Skill Development”

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

StepNew SkillExisting Skill
1. UnderstandDefine use cases, scope, patternsAudit + understand user’s intent
2. PlanStructure, description, frontmatterGap analysis + improvement plan (approval gate)
3. Scaffoldwagents new skill <name>Skip
4. BuildWrite/edit body, references, scripts, templates, evalsSame
5. Validatewagents validate + audit.pySame
6. IterateTest, identify issues, loop to Step 4Same

Audit

Section titled “Audit”

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

Audit All

Section titled “Audit All”

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

Package

Section titled “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.

Terminal window
wagents package <name>            # Single skill → <name>-v<version>.skill.zip
wagents package --all             # All skills → dist/ with manifest.json
wagents package --all --dry-run   # Check portability without creating ZIPs

Core Principles

Section titled “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

Section titled “Critical Rules”
  1. Run uv run wagents validate before declaring any skill complete
  2. Run uv run python skills/skill-creator/scripts/audit.py after every significant SKILL.md change
  3. Never create a skill without a dispatch table — it is the routing contract
  4. Never create a dispatch table without an empty-args handler — unrouted input is a bug
  5. Every reference file must appear in the Reference File Index — orphan refs are invisible
  6. Every indexed reference must exist on disk — phantom refs cause agent errors
  7. Body must stay under 500 lines (below frontmatter) — move detail to references
  8. Description must include “Use when” trigger phrases AND “NOT for” exclusions
  9. Names must be kebab-case, 2-64 chars, no consecutive hyphens, no reserved words
  10. Scripts use argparse + JSON to stdout — no custom output formats
  11. Templates are self-contained HTML with no external dependencies
  12. Do NOT call wagents docs generate — delegate to docs-steward
  13. Do NOT create agents or MCP servers — refuse gracefully and redirect
  14. Improving existing skills requires presenting an improvement plan and getting user approval before implementing changes
  15. Audit mode is read-only — never modify the skill being audited
  16. Update evals when dispatch behavior or modes change — stale evals are invisible 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+), “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”
FieldValue
Nameskill-creator
LicenseMIT
Version2.0.0
Authorwyattowalsh
Section titled “Related Skills”
prompt-engineer Prompt engineering for any AI system. Craft, analyze, convert between models, evaluate with rubrics. Use for system prompts, agent prompts, tool defs.
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
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"
      hooks:
        - type: command
          command: "jq -r '.tool_input.file_path // empty' | grep -q 'skills/.*/SKILL.md' && wagents validate 2>/dev/null || true"
---


# Skill Creator


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


**Scope:** Skills only. NOT for creating agents (`wagents new agent`), 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` |
| `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
wagents new skill <name>           # Scaffold from template
wagents validate                   # Check all skills
uv run python skills/skill-creator/scripts/audit.py skills/<name>/  # Score quality
wagents package <name>             # Package as portable ZIP
```


## 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 | `wagents new skill <name>` | Skip |
| 4. Build | Write/edit body, references, scripts, templates, evals | Same |
| 5. Validate | `wagents validate` + `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.


## 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
wagents package <name>            # Single skill → <name>-v<version>.skill.zip
wagents package --all             # All skills → dist/ with manifest.json
wagents package --all --dry-run   # Check portability without creating ZIPs
```


## 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.


## State Management


Creation progress persists at `~/.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/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` | 11 scoring dimensions, 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.


## Critical Rules


1. Run `uv run wagents validate` before declaring any skill complete
2. Run `uv run python skills/skill-creator/scripts/audit.py` after every significant SKILL.md change
3. Never create a skill without a dispatch table — it is the routing contract
4. Never create a dispatch table without an empty-args handler — unrouted input is a bug
5. Every reference file must appear in the Reference File Index — orphan refs are invisible
6. Every indexed reference must exist on disk — phantom refs cause agent errors
7. Body must stay under 500 lines (below frontmatter) — move detail to references
8. Description must include "Use when" trigger phrases AND "NOT for" exclusions
9. Names must be kebab-case, 2-64 chars, no consecutive hyphens, no reserved words
10. Scripts use argparse + JSON to stdout — no custom output formats
11. Templates are self-contained HTML with no external dependencies
12. Do NOT call `wagents docs generate` — delegate to docs-steward
13. Do NOT create agents or MCP servers — refuse gracefully and redirect
14. Improving existing skills requires presenting an improvement plan and getting user approval before implementing changes
15. Audit mode is read-only — never modify the skill being audited
16. Update evals when dispatch behavior or modes change — stale evals are invisible 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+), "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"

Download from GitHub

Resources

Section titled “Resources”
All Skills Browse the full skill catalog.
CLI Reference Install and manage skills.
agentskills.io The open ecosystem for cross-agent skills.

View source on GitHub

Graph View

Backlinks

Built & designed by shadcn. Ported to Astro Starlight by Adrián UB. The source code is available on GitHub.
Home Skills 40 MCP 38 CLI

Skills

Overview

MCP Servers

Overview