@intentsolutionsio/skill-creator 5.0.0

package/skills/agent-creator/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: agent-creator
+description: |
+  Create production-grade agent .md files aligned with the Anthropic 2026 spec (16-field schema).
+  Also validates existing agents against the marketplace compliance rules. Use when building custom
+  subagents, reviewing agent quality, or creating parallel agent architectures for orchestrator skills.
+  Trigger with "/agent-creator", "create an agent", "build a subagent", or "validate my agent".
+  Make sure to use this skill whenever creating agents/*.md files for plugins or standalone use.
+allowed-tools: "Read,Write,Edit,Glob,Grep,Bash(python:*),AskUserQuestion"
+version: 1.0.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatible-with: claude-code, codex, openclaw
+tags: [agent-creation, validation, meta-tooling, subagents]
+model: inherit
+---
+
+# Agent Creator
+
+Creates spec-compliant agent .md files following the Anthropic 2026 16-field schema. Supports
+both creation of new agents and validation of existing ones.
+
+## Overview
+
+Agent Creator fills the gap between ad-hoc agent files and production-grade agents that pass
+marketplace validation. It enforces the Anthropic agent schema (14 valid fields), prevents
+common mistakes (using `allowed-tools` instead of `disallowedTools`, adding invalid fields like
+`capabilities` or `expertise_level`), and produces agents with substantive body content that
+actually guides Claude's behavior.
+
+Key difference from skill-creator: **agents support both `tools` (allowlist) AND `disallowedTools`
+(denylist)**, while skills only use `allowed-tools` (allowlist). Agents also support `effort`,
+`maxTurns`, `skills`, `memory`, `isolation`, `permissionMode`, `background`, `color`, and
+`initialPrompt` — fields that don't exist for skills. The agent body becomes the **system prompt**
+that drives the subagent — it does NOT receive the full Claude Code system prompt.
+
+## Prerequisites
+
+- Claude Code CLI with agent support
+- Target directory writable (`agents/` within a plugin or `~/.claude/agents/` for standalone)
+- Familiarity with what the agent should specialize in
+
+## Instructions
+
+### Mode Detection
+
+Determine user intent from their prompt:
+- **Create mode**: "create an agent", "build a subagent", "new agent" -> Step 1
+- **Validate mode**: "validate agent", "check agent", "grade agent" -> Validation Workflow
+
+### Step 1: Understand Requirements
+
+Ask the user with AskUserQuestion:
+
+**Agent Identity:**
+- Name (kebab-case, 1-64 chars, e.g., `risk-assessor`, `clause-analyzer`)
+- Specialty description (20-200 chars — shown in agent selection UI)
+
+**Execution Context:**
+- Plugin agent (`plugins/*/agents/`) or standalone (`~/.claude/agents/`)?
+- Will it be spawned by an orchestrator skill via `Task` tool?
+- Does it need to preload specific skills? (`skills: [skill-name]`)
+
+**Behavioral Controls:**
+- Model override? (`sonnet` for speed, `opus` for quality, `inherit` for default)
+- Reasoning effort? (`low` for simple, `medium` default, `high` for complex analysis)
+- Max iterations? (`maxTurns` — how many tool-use loops before stopping)
+- Tools to deny? (`disallowedTools` — denylist approach, opposite of skills)
+
+**Plugin Restrictions (if plugin agent):**
+- `hooks` — NOT supported in plugin agents (use plugin-level hooks)
+- `mcpServers` — NOT supported in plugin agents
+- `permissionMode` — standalone only, NOT plugin agents
+
+### Step 2: Plan the Agent
+
+Before writing, determine:
+
+**Agent Role Clarity:**
+The agent body must make three things unambiguous:
+1. **What it IS responsible for** — its specific domain/methodology
+2. **What it is NOT responsible for** — boundaries with other agents
+3. **How it communicates results** — output format and structure
+
+**Body Structure Pattern:**
+All production agents should follow this body structure:
+
+| Section | Purpose | Required? |
+|---------|---------|-----------|
+| `# Title` | Agent name as heading | Yes |
+| `## Role` | 2-3 sentence domain description with boundaries | Yes |
+| `## Inputs` | Parameters the agent receives when spawned | Yes (if spawned by orchestrator) |
+| `## Process` | Step-by-step methodology (numbered steps with ### headings) | Yes |
+| `## Output Format` | Structured output spec (JSON, markdown, or table) | Yes |
+| `## Guidelines` | Do/don't behavioral rules | Yes |
+| `## When Activated` | Trigger conditions (when spawned or auto-detected) | Recommended |
+| `## Communication Style` | Tone and formatting preferences | Recommended |
+| `## Success Criteria` | What good vs poor output looks like | Recommended |
+| `## Examples` | Concrete interaction examples | For complex agents |
+
+**Output Structure Decision:**
+- If the agent feeds into an orchestrator: use **JSON output** (machine-parseable)
+- If the agent is user-facing: use **markdown output** (human-readable)
+- If the agent produces both: JSON primary with markdown summary
+
+### Step 3: Write the Agent File
+
+Generate the agent .md using the template from
+`${CLAUDE_SKILL_DIR}/../skill-creator/templates/agent-template.md`.
+
+**Frontmatter Rules (Anthropic 16-field schema):**
+
+See [Anthropic Agent Spec](references/anthropic-agent-spec.md) for the full official reference.
+
+Required fields:
+```yaml
+name: {agent-name}         # Lowercase letters and hyphens, unique identifier
+description: "{specialty}"  # When Claude should delegate to this subagent
+```
+
+Optional fields (include only what's needed):
+```yaml
+tools: "Read, Glob, Grep"  # Allowlist — inherits all tools if omitted
+disallowedTools: "Write"   # Denylist — removed from inherited/specified list
+model: sonnet              # sonnet|haiku|opus|inherit|full model ID
+effort: medium             # low|medium|high|max (max = Opus 4.6 only)
+maxTurns: 15               # Max agentic turns before stopping
+skills: [skill-name]       # Skills to inject at startup (full content loaded)
+memory: project            # user|project|local — persistent cross-session
+background: false          # Always run as background task
+isolation: worktree        # Run in temporary git worktree
+color: blue                # Display: red|blue|green|yellow|purple|orange|pink|cyan
+initialPrompt: "..."       # Auto-submitted first turn (--agent mode only)
+permissionMode: default    # Standalone only, NOT plugin agents
+hooks: {}                  # Standalone only, NOT plugin agents
+mcpServers: {}             # Standalone only, NOT plugin agents
+```
+
+**Tool access:**
+- `tools` = allowlist (like skills' `allowed-tools`)
+- `disallowedTools` = denylist (remove specific tools)
+- If both set: disallowed applied first, then tools resolved
+- If neither set: inherits all tools from parent conversation
+
+**Invalid fields (ERROR — never use these):**
+- `capabilities` — looks valid but flagged by validator
+- `expertise_level` — invented, not in Anthropic spec
+- `activation_priority` — invented, not in Anthropic spec
+- `activation_triggers`, `type`, `category` — not in spec
+- `allowed-tools` — that's the skill-only syntax; agents use `tools` or `disallowedTools`
+
+**Body Content Guidelines:**
+
+1. **Role section must set boundaries.** Don't just say what the agent does — say what it
+   does NOT do. Example: "You analyze contract clauses for risk. You do NOT provide legal
+   advice or make recommendations — that is the recommendations agent's responsibility."
+
+2. **Process steps must be concrete.** Each step should tell Claude exactly what to do,
+   not vaguely gesture at an activity. Bad: "Analyze the document." Good: "Read the full
+   contract. For each clause, extract: (a) the exact text, (b) the clause category from
+   the taxonomy below, (c) a plain English summary in one sentence."
+
+3. **Output format must be machine-parseable if feeding an orchestrator.** Use JSON with
+   a concrete schema example. Include field descriptions so Claude knows what each field means.
+
+4. **Guidelines should include both DO and DON'T rules.** Example:
+   - DO: "Be specific — quote exact clause text, don't paraphrase"
+   - DON'T: "Don't make legal recommendations — only identify and score risks"
+
+5. **Keep under 300 lines** (agent body limit — prevents context bloat in subagent window).
+   If the agent needs extensive reference material, create a companion skill with
+   `references/` directory and preload it via the `skills` field.
+
+### Step 4: Validate the Agent
+
+Run validation against the Anthropic 16-field schema:
+
+**Manual checklist:**
+
+| Check | Rule |
+|-------|------|
+| `name` present | 1-64 chars, kebab-case |
+| `description` present | 20-200 chars |
+| No invalid fields | None of: capabilities, expertise_level, activation_priority, type, category |
+| No skill-only fields | No `allowed-tools` (use `disallowedTools` instead) |
+| Plugin restrictions | No hooks/mcpServers/permissionMode if plugin agent |
+| Body has Role section | Clear domain + boundaries |
+| Body has Process section | Numbered steps |
+| Body has Output Format | Concrete schema example |
+| Body has Guidelines | Do/don't rules |
+| Body under 300 lines | Offload to references if longer (prevents context bloat) |
+
+**Automated validation:**
+```bash
+python3 ${CLAUDE_SKILL_DIR}/../skill-creator/scripts/validate-skill.py --agents-only {plugin-dir}/
+```
+
+### Step 5: Test the Agent
+
+Test the agent by spawning it via the `Task` tool or the `Agent` tool:
+
+1. Write a test prompt that exercises the agent's core capability
+2. Spawn the agent with that prompt
+3. Check: Does the output match the declared Output Format?
+4. Check: Does the agent stay within its declared Role boundaries?
+5. Check: Does it follow the Process steps?
+6. Iterate on the body content if the agent strays
+
+### Step 6: Report
+
+Provide a summary:
+- Agent name and file path
+- Frontmatter field count (of 14 possible)
+- Body line count
+- Sections present
+- Validation result (pass/fail with specific issues)
+- Test result summary
+
+## Validation Workflow
+
+When the user wants to validate an existing agent:
+
+1. Locate the agent .md file
+2. Parse YAML frontmatter
+3. Check against the 16-field Anthropic schema:
+   - `name` present and valid (1-64 chars, kebab-case)?
+   - `description` present and valid (20-200 chars)?
+   - Any invalid fields? (capabilities, expertise_level, activation_priority, etc.)
+   - Any skill-only fields? (allowed-tools)
+   - Plugin restrictions respected?
+4. Check body content:
+   - Has `## Role` section?
+   - Has `## Process` section with numbered steps?
+   - Has `## Output Format` with concrete example?
+   - Has `## Guidelines`?
+   - Under 300 lines? (agent body limit)
+5. Report findings with severity (ERROR/WARNING/INFO)
+6. Suggest specific fixes for each issue
+
+## Output
+
+- **Create mode**: A complete agent .md file with valid frontmatter and substantive body,
+  plus a creation report with validation status.
+- **Validate mode**: A compliance report listing errors, warnings, and info items with
+  specific fix recommendations for each.
+
+## Examples
+
+### Subagent for Orchestrator Skill
+
+**Input:** "Create a risk assessment agent that scores contract clauses"
+
+**Output:** `agents/risk-assessor.md` with frontmatter:
+
+```yaml
+name: risk-assessor
+description: "Score contract clauses for legal and financial risk on a 1-10 scale"
+model: sonnet
+effort: high
+maxTurns: 10
+```
+
+Body sections: Role (risk scoring specialist, does NOT make recommendations), Inputs
+(contract_text, contract_type, output_path), Process (4 steps: read, categorize, score,
+aggregate), Output Format (JSON with clause scores and risk matrix), Guidelines (be specific,
+cite clause text, use 4-factor scoring methodology).
+
+### Standalone User-Facing Agent
+
+**Input:** "Create a code review agent"
+
+**Output:** `~/.claude/agents/code-reviewer.md` with frontmatter:
+
+```yaml
+name: code-reviewer
+description: "Review code for bugs, performance issues, and security vulnerabilities"
+effort: high
+```
+
+Body sections: Role (code quality specialist), Process (read code, check patterns, identify
+issues, suggest fixes), Output Format (markdown with severity-rated findings), Guidelines
+(cite line numbers, explain why not just what), Communication Style (direct, educational,
+actionable).
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `allowed-tools` in agent | Used skill-only field | Replace with `disallowedTools` (denylist) or remove |
+| `capabilities` field | Common mistake — looks valid but isn't in Anthropic spec | Remove field entirely |
+| `expertise_level` field | Invented field from community templates | Remove — express expertise in body content |
+| Description > 200 chars | Exceeds Anthropic limit | Shorten to 20-200 char range |
+| Description < 20 chars | Below minimum | Expand to describe agent's specific specialty |
+| `permissionMode` in plugin agent | Standalone-only field used in plugin context | Remove — only valid in `~/.claude/agents/` |
+| `hooks` in plugin agent | Plugin agents can't have hooks | Move to plugin-level `hooks/hooks.json` |
+| Body has no Process section | Agent lacks step-by-step methodology | Add numbered steps under `## Process` |
+| Body over 300 lines | Too long for agent context | Extract reference material to companion skill |
+
+## Resources
+
+- [Anthropic Agent Spec](references/anthropic-agent-spec.md) — Official 16-field schema from code.claude.com/docs/en/sub-agents
+- [Agent template](${CLAUDE_SKILL_DIR}/../skill-creator/templates/agent-template.md) — Skeleton with placeholders
+- [Frontmatter spec](${CLAUDE_SKILL_DIR}/../skill-creator/references/frontmatter-spec.md) — Field reference (internal)
+- [Source of truth](${CLAUDE_SKILL_DIR}/../skill-creator/references/source-of-truth.md) — Canonical spec
+- [Validation rules](${CLAUDE_SKILL_DIR}/../skill-creator/references/validation-rules.md) — Agent validation section

package/skills/agent-creator/references/anthropic-agent-spec.md

@@ -0,0 +1,89 @@
+# Anthropic Agent Spec — Official Reference
+
+Source: https://code.claude.com/docs/en/sub-agents (fetched 2026-04-05)
+
+## Supported Frontmatter Fields
+
+Only `name` and `description` are required.
+
+| Field | Required | Description |
+|:------|:---------|:------------|
+| `name` | Yes | Unique identifier using lowercase letters and hyphens |
+| `description` | Yes | When Claude should delegate to this subagent |
+| `tools` | No | Tools the subagent can use (allowlist). Inherits all tools if omitted |
+| `disallowedTools` | No | Tools to deny, removed from inherited or specified list |
+| `model` | No | `sonnet`, `opus`, `haiku`, a full model ID, or `inherit`. Defaults to `inherit` |
+| `permissionMode` | No | `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, or `plan` |
+| `maxTurns` | No | Maximum number of agentic turns before the subagent stops |
+| `skills` | No | Skills to load into the subagent's context at startup (full content injected) |
+| `mcpServers` | No | MCP servers available to this subagent (inline definition or string reference) |
+| `hooks` | No | Lifecycle hooks scoped to this subagent |
+| `memory` | No | Persistent memory scope: `user`, `project`, or `local` |
+| `background` | No | Set to `true` to always run as background task. Default: `false` |
+| `effort` | No | `low`, `medium`, `high`, `max` (Opus 4.6 only). Default: inherits from session |
+| `isolation` | No | `worktree` — run in temporary git worktree |
+| `color` | No | Display color: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` |
+| `initialPrompt` | No | Auto-submitted as first user turn when running as main agent via `--agent` |
+
+Total: 16 official fields.
+
+## Key Facts
+
+- The **body** (markdown after frontmatter) becomes the **system prompt** that guides the subagent
+- Subagents receive ONLY the system prompt + basic environment details, NOT the full Claude Code system prompt
+- `tools` is an **allowlist** (like skills' `allowed-tools`)
+- `disallowedTools` is a **denylist** — if both set, disallowed applied first, then tools resolved
+- Subagents **cannot spawn other subagents** (no nesting)
+- Subagents **don't inherit skills** from parent conversation — must list explicitly via `skills` field
+
+## Plugin Agent Restrictions
+
+Plugin agents (`plugins/*/agents/*.md`) do NOT support:
+- `hooks` — ignored when loading from plugin
+- `mcpServers` — ignored when loading from plugin
+- `permissionMode` — ignored when loading from plugin
+
+These are standalone-only features. If needed, copy the agent to `.claude/agents/` or `~/.claude/agents/`.
+
+## Tool Scoping
+
+Subagents can use `Agent(type)` syntax to restrict which subagents they can spawn (only for main-thread agents via `--agent`).
+
+## Skills Preloading
+
+```yaml
+skills:
+  - api-conventions
+  - error-handling-patterns
+```
+
+Full content of each skill is injected at startup. This is the inverse of `context: fork` in skills.
+
+## Model Resolution Order
+
+1. `CLAUDE_CODE_SUBAGENT_MODEL` env var
+2. Per-invocation `model` parameter
+3. Subagent definition's `model` frontmatter
+4. Main conversation's model
+
+## Example Agent File
+
+```markdown
+---
+name: code-reviewer
+description: Reviews code for quality and best practices
+tools: Read, Glob, Grep
+model: sonnet
+---
+
+You are a code reviewer. When invoked, analyze the code and provide
+specific, actionable feedback on quality, security, and best practices.
+```
+
+## Scope Priority (highest to lowest)
+
+1. Managed settings (organization-wide)
+2. `--agents` CLI flag (current session only)
+3. `.claude/agents/` (project)
+4. `~/.claude/agents/` (personal)
+5. Plugin `agents/` directory (where plugin enabled)

package/skills/skill-creator/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: skill-creator
+description: |
+  Create production-grade agent skills aligned with the 2026 AgentSkills.io spec and Anthropic
+  best practices (2026). Also validates existing skills against the Intent Solutions 100-point rubric.
+  Use when building, testing, validating, or optimizing Claude Code skills.
+  Trigger with "/skill-creator", "create a skill", "validate my skill", or "check skill quality".
+  Make sure to use this skill whenever creating a new skill, slash command, or agent capability.
+allowed-tools: "Read,Write,Edit,Glob,Grep,Bash(mkdir:*),Bash(chmod:*),Bash(python:*),Bash(claude:*),Task,AskUserQuestion"
+version: 5.1.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatible-with: claude-code, codex, openclaw
+tags: [skill-creation, validation, meta-tooling]
+model: inherit
+---
+
+# 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:
+
+```bash
+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](references/creation-guide.md).
+
+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](references/creation-guide.md).
+
+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](https://agentskills.io/specification), [Anthropic docs](https://code.claude.com/docs/en/skills), [Lee Han Chung deep dive](https://leehanchung.github.io/blogs/2025/10/26/claude-skills-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](references/creation-guide.md) and `${CLAUDE_SKILL_DIR}/references/advanced-eval-workflow.md`.