skill-creator

Skill Creator

Creates complete, spec-compliant skill packages following AgentSkills.io and Anthropic standards. Supports both creation and validation workflows with 100-point marketplace grading.

Overview

Skill Creator solves the gap between writing ad-hoc agent skills and producing marketplace-ready packages that score well on the Intent Solutions 100-point rubric. It enforces the 2026 spec (top-level identity fields, ${CLAUDE_SKILL_DIR} paths, scored sections) and catches contradictions that would cost marketplace points. Supports two modes: create new skills from scratch with full validation, or grade/audit existing skills with actionable fix suggestions.

Prerequisites

• Claude Code CLI with skill support (v2.1.78+ for advanced features like effort, maxTurns)
• Python 3.10+ for validation scripts (validate-skill.py, aggregate_benchmark.py)
• Target skill directory writable (~/.claude/skills/ or .claude/skills/)

Instructions

Mode Detection

Determine user intent from their prompt:

• Create mode: "create a skill", "build a skill", "new skill" -> proceed to Step 1
• Validate mode: "validate", "check", "grade", "score", "audit" -> jump to Validation Workflow

Communicating with the User

Pay attention to context cues to understand the user's technical level. Skill creator is used by people across a wide range of familiarity — from first-time coders to senior engineers. In the default case:

• "evaluation" and "benchmark" are borderline but OK
• For "JSON" and "assertion", check for cues the user knows these terms before using them without explanation
• Briefly explain terms if in doubt

Step 1: Understand Requirements

If the current conversation already contains a workflow the user wants to capture (e.g., "turn this into a skill"), extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. Confirm with the user before proceeding.

Ask the user with AskUserQuestion:

Skill Identity:

• Name (kebab-case, gerund preferred: processing-pdfs, analyzing-data)
• Purpose (1-2 sentences: what it does + when to use it)

Execution Model:

• User-invocable via /name? Or background knowledge only?
• Accepts arguments? ($ARGUMENTS substitution)
• Needs isolated context? (context: fork for subagent execution)
• Explicit-only invocation? (disable-model-invocation: true — prevents auto-activation, requires /name)

Required Tools:

• Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, Task, AskUserQuestion, Skill
• Bash must be scoped: Bash(git:*), Bash(npm:*), etc.
• MCP tools: ServerName:tool_name

Complexity:

• Simple (SKILL.md only)
• With scripts (automation code in scripts/)
• With references (documentation in references/)
• With templates (boilerplate in templates/)
• Full package (all directories)

Location:

• Global: ~/.claude/skills/<skill-name>/
• Project: .claude/skills/<skill-name>/

Step 2: Plan the Skill

Before writing, determine:

Degrees of Freedom:

Level	When to Use
High	Creative/open-ended tasks (analysis, writing)
Medium	Defined workflow, flexible content (most skills)
Low	Strict output format (compliance, API calls, configs)

Think of it as narrow bridge vs open field: a deployment skill is a narrow bridge (one safe path, guard rails everywhere), while a writing skill is an open field (Claude roams freely within broad boundaries). Match constraint level to the task.

Workflow Pattern (see ${CLAUDE_SKILL_DIR}/references/workflows.md):

• Sequential: fixed steps in order
• Conditional: branch based on input
• Wizard: interactive multi-step gathering
• Plan-Validate-Execute: verifiable intermediates
• Feedback Loop: iterate until quality met
• Checklist Workflow: copy-pasteable progress tracking for complex multi-step processes
• Search-Analyze-Report: explore and summarize

Output Pattern (see ${CLAUDE_SKILL_DIR}/references/output-patterns.md):

• Strict template (exact format)
• Flexible template (structure with creative content)
• Examples-driven (input/output pairs)
• Visual (HTML generation)
• Structured data (JSON/YAML)

Step 3: Initialize Structure

Create the skill directory and files:

mkdir -p {location}/{skill-name}
mkdir -p {location}/{skill-name}/scripts      # if needed
mkdir -p {location}/{skill-name}/references   # if needed
mkdir -p {location}/{skill-name}/templates    # if needed
mkdir -p {location}/{skill-name}/assets       # if needed
mkdir -p {location}/{skill-name}/evals        # for eval-driven development

Steps 4-10: Write, Validate, Test, Iterate, Optimize, Report

For detailed guidance on writing SKILL.md (frontmatter rules, description scoring, body guidelines, string substitutions, DCI syntax), creating supporting files, validation, testing, iteration, description optimization, and final reporting, see Creation Guide.

Key rules:

• version, author, license, tags, compatible-with are TOP-LEVEL fields (not nested under metadata:)
• Scope Bash: Bash(git:*) not bare Bash
• Keep under 500 lines; offload to references/ if longer
• Include "Use when" and "Trigger with" in description for enterprise scoring
• No XML tags in name or description (Anthropic spec prohibition)
• No time-sensitive information; use 'old patterns' section for deprecated approaches
• Include feedback loops for quality-critical workflows
• Run python3 ${CLAUDE_SKILL_DIR}/scripts/validate-skill.py --grade {skill-dir}/SKILL.md to validate
• Create evals/evals.json with 3+ scenarios, iterate until all assertions pass

Validation Workflow

When the user wants to validate, grade, or audit an existing skill. For detailed steps (V1-V5), see Creation Guide.

1. Locate the SKILL.md (global ~/.claude/skills/ or project .claude/skills/)
2. Run python3 ${CLAUDE_SKILL_DIR}/scripts/validate-skill.py --grade {path}/SKILL.md
3. Review grade against the 100-point rubric (A: 90+, B: 80-89, C: 70-79, D: 60-69, F: <60)
4. Report results with prioritized fix recommendations
5. Auto-fix if requested: add missing sections, fix description patterns, move nested metadata to top-level

Output

The skill produces one of two outputs depending on mode:

• Create mode: A complete skill package directory containing SKILL.md, optional scripts/, references/, templates/, assets/, and evals/ subdirectories, plus a creation summary report with validation grade and eval results.
• Validate mode: A grade report showing the 100-point rubric score across 5 pillars (Progressive Disclosure, Ease of Use, Utility, Spec Compliance, Writing Style), with prioritized fix recommendations sorted by point value.

Examples

Simple Skill (Create Mode)

User: Create a skill called "code-review" that reviews code quality

Creates:
~/.claude/skills/code-review/
├── SKILL.md
└── evals/
    └── evals.json

Frontmatter:
---
name: code-review
description: |
  Make sure to use this skill whenever reviewing code for quality, security
  vulnerabilities, and best practices. Use when doing code reviews, PR analysis,
  or checking code quality. Trigger with "/code-review" or "review this code".
allowed-tools: "Read,Glob,Grep"
version: 1.0.0
author: Jeremy Longshore <jeremy@intentsolutions.io>
license: MIT
model: inherit
---

Full Package with Arguments (Create Mode)

User: Create a skill that generates release notes from git history

Creates:
~/.claude/skills/generating-release-notes/
├── SKILL.md              (argument-hint: "[version-tag]")
├── scripts/
│   └── parse-commits.py
├── references/
│   └── commit-conventions.md
├── templates/
│   └── release-template.md
└── evals/
    └── evals.json

Uses $ARGUMENTS[0] for version tag.
Uses context: fork for isolated execution.

Validate Mode

User: Grade my skill at ~/.claude/skills/code-review/SKILL.md

Runs: python3 ${CLAUDE_SKILL_DIR}/scripts/validate-skill.py --grade ~/.claude/skills/code-review/SKILL.md

Output:
  Grade: B (84/100)
  Improvements:
    - Add "Trigger with" to description (+3 pts)
    - Add ## Output section (+2 pts)
    - Add ## Prerequisites section (+2 pts)

Edge Cases

• Name conflicts: Check if skill directory already exists before creating
• Empty arguments: If skill uses $ARGUMENTS, handle the empty case
• Long content: If SKILL.md exceeds 300 lines during writing, stop and split to references
• Bash scoping: If user requests raw Bash, always scope it
• Model selection: Default to inherit, only override with good reason
• Undertriggering: If skill isn't activating, make description more aggressive/pushy
• Legacy metadata nesting: If found, move author/version/license to top-level

Error Handling

Error	Cause	Solution
Name exists	Directory already present	Choose different name or confirm overwrite
Invalid name	Not kebab-case or >64 chars	Fix to lowercase-with-hyphens
Validation fails	Missing fields or anti-patterns	Run validator, fix reported issues
Resource missing	${CLAUDE_SKILL_DIR}/ ref points to nonexistent file	Create the file or fix the reference
Undertriggering	Description too passive	Add "Make sure to use whenever..." phrasing
Eval failures	Skill not producing expected output	Iterate on instructions and re-test
Low grade	Missing scored sections or fields	Add Overview, Prerequisites, Output sections

Resources

References: ${CLAUDE_SKILL_DIR}/references/

• creation-guide.md — Detailed Steps 4-10 and Validation Workflow (V1-V5)
• source-of-truth.md — Canonical spec (AgentSkills.io, Anthropic docs, Lee Han Chung deep dive) | frontmatter-spec.md — Field reference | validation-rules.md — 100-point rubric
• workflows.md — Workflow patterns | output-patterns.md — Output formats | schemas.md — JSON schemas (evals, grading, benchmarks)
• anthropic-comparison.md — Gap analysis | advanced-eval-workflow.md — Eval, iteration, optimization, platform notes

Agents (read when spawning subagents): ${CLAUDE_SKILL_DIR}/agents/

• grader.md — Assertion evaluation | comparator.md — Blind A/B comparison | analyzer.md — Benchmark analysis

Scripts: ${CLAUDE_SKILL_DIR}/scripts/

• validate-skill.py — 100-point rubric grading | quick_validate.py — Lightweight validation
• aggregate_benchmark.py — Benchmark stats | run_eval.py — Trigger accuracy testing
• run_loop.py — Description optimization loop | improve_description.py — LLM-powered rewriting
• generate_report.py — HTML reports | package_skill.py — .skill packaging | utils.py — Shared utilities

Eval Viewer: ${CLAUDE_SKILL_DIR}/eval-viewer/ — generate_review.py + viewer.html (interactive output comparison) Assets: ${CLAUDE_SKILL_DIR}/assets/eval_review.html (trigger eval set editor) Templates: ${CLAUDE_SKILL_DIR}/templates/skill-template.md (SKILL.md skeleton)

---

For advanced workflows (empirical eval, description optimization, blind comparison, packaging, platform notes), see Creation Guide and ${CLAUDE_SKILL_DIR}/references/advanced-eval-workflow.md.