Documentation > User Guides > Command Reference

Guide ID	UG-1
Audience	All users, CI/CD engineers
Prerequisites	GS-1 (Installation)
Time	Reference (browse as needed)
Difficulty	All levels

Command Reference

skill-creator is the command-line interface for managing Claude Code skills. It provides commands for creating, validating, testing, calibrating, and optimizing skills throughout their lifecycle. This page documents every command with its synopsis, options, examples, and exit codes.

Cheat Sheet

Quick reference for all commands organized by workflow stage.

Create: Skill Authoring

Command	Alias	Description	Example
create	c	Create a new skill through guided workflow	skill-creator c -p
list	ls	List all available skills with metadata	skill-creator ls --scope=project
search	s	Search skills by keyword interactively	skill-creator s
delete	del, rm	Delete a skill	skill-creator rm my-skill -p
resolve	res	Show which version of a skill is active	skill-creator res my-skill

Validate: Quality Assurance

Command	Alias	Description	Example
validate	v	Validate skill structure and metadata	skill-creator v --all -p
detect-conflicts	dc, conflicts	Detect semantic conflicts between skills	skill-creator dc --json
score-activation	sa, score	Score skill activation likelihood	skill-creator sa --all -v

Test: Activation Testing

Command	Alias	Description	Example
test add	t add	Add a new test case	skill-creator t add my-skill
test list	t ls	List test cases for a skill	skill-creator t ls my-skill --json
test run	t run	Run tests for one or all skills	skill-creator t run --all
test edit	t edit	Edit an existing test case	skill-creator t edit my-skill abc123
test delete	t rm, t del	Delete a test case	skill-creator t rm my-skill abc123
test generate	t gen	Generate test cases automatically	skill-creator t gen my-skill
simulate	sim	Predict which skill would activate for a prompt	skill-creator sim "commit changes"

Calibrate: Threshold Optimization

Command	Alias	Description	Example
calibrate	cal	Optimize activation threshold from calibration data	skill-creator cal --preview
calibrate rollback	cal rollback	Revert to the previous threshold	skill-creator cal rollback
calibrate history	cal history	Show threshold history	skill-creator cal history
benchmark	bench	Measure simulator accuracy vs real activation	skill-creator bench -v

Utilities

Command	Alias	Description	Example
migrate	mg	Migrate legacy flat-file skills to subdirectory format	skill-creator mg -p
migrate-agent	ma	Migrate agents with legacy tools format	skill-creator ma --dry-run
budget	bg	Show character budget usage across all skills	skill-creator bg -p
invoke	i	Manually invoke a skill by name	skill-creator i react-hooks
status	st	Show active skills and token budget	skill-creator st
suggest	sg	Analyze patterns and review skill suggestions	skill-creator sg
suggestions	sgs	List/manage skill suggestions	skill-creator sgs list
feedback	fb	View feedback for skills	skill-creator fb list my-skill
refine	rf	Generate and apply skill refinements	skill-creator rf my-skill
history	hist	View skill version history	skill-creator hist my-skill
rollback	rb	Rollback skill to previous version	skill-creator rb my-skill
agents	ag	Manage agent suggestions from skill clusters	skill-creator ag suggest
sync-reserved	sync	Show/update reserved skill names list	skill-creator sync
reload-embeddings	re	Reload embedding model (retry after fallback)	skill-creator re -v

Discover: Pattern Discovery

Command	Alias	Description	Example
discover	disc	Scan session logs, extract patterns, rank candidates, generate draft skills	skill-creator disc --rescan

Teams: Multi-Agent Coordination

Command	Alias	Description	Example
team create	tm c	Create a team from pattern template	skill-creator tm c
team list	tm l, tm ls	List all teams with member counts	skill-creator tm ls --json
team validate	tm v	Validate team config(s)	skill-creator tm v --all
team spawn	tm sp	Check team readiness (agent resolution)	skill-creator tm sp my-team
team status	tm s	Show team details and validation summary	skill-creator tm s my-team

Global Options

Options that apply across multiple commands. Understanding the distinction between targeting and filtering is important for correct usage.

Option	Type	Description	Applies To
--project, -p	Target	Operate on project-level scope (.claude/skills/)	create, delete, validate, migrate, budget, detect-conflicts, score-activation, simulate
--scope=<value>	Filter	Filter output: user, project, or all (default)	list, team commands
--verbose, -v	Output	Show detailed output with additional information	score-activation, simulate, reload-embeddings, benchmark, test run
--quiet, -q	Output	Suppress non-essential output; machine-friendly	detect-conflicts, score-activation, team list, team validate, team spawn, team status
--json	Output	Output as JSON for scripting and CI integration	detect-conflicts, score-activation, test list, test run, simulate, benchmark, team commands

Target vs Filter: --project changes where the operation runs (target). --scope changes what is shown (filter). Without --project, operations default to user-level scope at ~/.claude/skills/.

Create: Skill Authoring

create

Create a new skill through an interactive guided workflow. Prompts for skill name, description, and content, then creates a properly formatted skill with YAML frontmatter.

skill-creator create [--project]

Option	Description
--project, -p	Create at project-level scope (.claude/skills/)

# Create a user-level skill (stored in ~/.claude/skills/)
skill-creator create

# Create a project-level skill (stored in .claude/skills/)
skill-creator create --project

# Short form
skill-creator c -p

list

List all available skills with name, scope indicator, and description preview. Project-level skills take precedence when names conflict.

skill-creator list [--scope=<value>]

Option	Description
--scope=user|project|all	Filter by scope (default: all)

# List all skills from both scopes
skill-creator list

# List only project-level skills
skill-creator ls --scope=project

search

Interactive fuzzy search across skill names and descriptions. Type to filter, use arrow keys to navigate, press Enter to select.

skill-creator search
skill-creator s

delete

Remove a skill from the specified scope. If a version exists at both user and project scope, deleting one makes the other become active.

skill-creator delete <skill-name> [--project]

Option	Description
--project, -p	Delete from project-level scope

# Delete from user scope (default)
skill-creator delete my-commit-helper

# Delete from project scope
skill-creator rm my-skill -p

resolve

Show which version of a skill is active when it exists at both user and project scope. Project-level takes precedence.

skill-creator resolve <skill-name>
skill-creator res react-patterns

Validate: Quality Assurance

validate

Run comprehensive validation checks: name validation (lowercase, hyphens, no reserved names), directory structure, metadata schema (YAML frontmatter), and directory/name match.

skill-creator validate [<skill-name>] [--all] [--project]

Option	Description
--all, -a	Validate all skills in scope
--project, -p	Target project-level scope

# Validate a specific skill
skill-creator validate my-commit-helper

# Validate all project-level skills
skill-creator validate --all --project

detect-conflicts

Use embedding-based semantic analysis to find skills with overlapping descriptions that may cause activation confusion. Generates rewrite suggestions when ANTHROPIC_API_KEY is available.

skill-creator detect-conflicts [<skill-name>] [options]

Option	Description
--threshold=<n>	Similarity threshold (default: 0.85, range: 0.5-0.95)
--quiet, -q	Minimal output (one line per conflict)
--json	JSON output for scripting
--project, -p	Target project-level scope

Severity Levels: HIGH (>90% similarity) requires review. MEDIUM (85-90%) is worth checking.

# Check all skills for conflicts
skill-creator detect-conflicts

# Use stricter threshold
skill-creator dc --threshold=0.90

# JSON output for CI pipeline
skill-creator detect-conflicts --json

score-activation

Analyze skill descriptions to predict activation reliability. Scores range 0-100 based on specificity, trigger phrases, length, imperative verbs, and generic penalty.

skill-creator score-activation [<skill-name>] [options]

Option	Description
--all, -a	Score all skills in batch mode
--verbose, -v	Show factor breakdown
--quiet, -q	Minimal output (skillName,score,label)
--json	JSON output for scripting
--llm	Use Claude API for deep analysis (requires ANTHROPIC_API_KEY)
--project, -p	Target project-level scope

Label	Score	Meaning
Reliable	90+	Very likely to auto-activate correctly
Likely	70-89	Good chance of correct activation
Uncertain	50-69	May need improvement
Unlikely	<50	Needs significant improvement

# Score a single skill with breakdown
skill-creator sa my-commit-helper --verbose

# Score all skills as JSON
skill-creator sa --all --json

# LLM-powered deep analysis
skill-creator sa my-skill --llm --verbose

Test: Activation Testing

test add

Add a test case to a skill. Runs interactively when called without flags, or accepts flags for scripted usage. Test cases define expected behavior: positive (should activate), negative (should not), or edge-case (borderline).

skill-creator test add <skill-name> [options]

Option	Description
--prompt="..."	Test prompt (required in flag mode)
--expected=<value>	Expected: positive, negative, or edge-case
--description="..."	Description of what test verifies
--tags=tag1,tag2	Comma-separated tags for filtering
--difficulty=<value>	Test difficulty: easy, medium, or hard
--min-confidence=<n>	Minimum confidence for positive tests (0-1)
--max-confidence=<n>	Maximum confidence for negative tests (0-1)
--reason="..."	Why skill should not activate (negative tests)

# Interactive mode
skill-creator test add my-commit-skill

# Positive test case with flags
skill-creator test add my-commit-skill \
  --prompt="commit my changes with a good message" \
  --expected=positive

# Negative test case
skill-creator test add my-commit-skill \
  --prompt="what is a git commit?" \
  --expected=negative \
  --reason="Information query, not an action request"

test list

Display all test cases for a skill in table format. Supports filtering and JSON output.

skill-creator test list <skill-name> [options]

Option	Description
--expected=<value>	Filter by expected: positive, negative, or edge-case
--tags=tag1,tag2	Filter by tags (matches any)
--json	Output as JSON

test run

Execute test cases and report pass/fail results. Supports CI integration with JSON output (auto-detected via CI=true) and quality gate thresholds.

skill-creator test run <skill-name> [options]
skill-creator test run --all [options]

Option	Description
--all, -a	Run tests for all skills
--verbose, -v	Show confidence scores for all results
--json=<format>	JSON output: compact or pretty (auto in CI)
--threshold=<n>	Activation threshold (default: 0.75)
--min-accuracy=<n>	Fail if accuracy below N%
--max-false-positive=<n>	Fail if false positive rate above N%

# Run tests for a single skill
skill-creator test run my-commit-skill --verbose

# CI mode with quality gates
skill-creator test run --all --min-accuracy=90 --max-false-positive=5

test edit

Open an interactive editor to modify an existing test case. The test ID can be a partial match (first 8 characters are typically sufficient).

skill-creator test edit <skill-name> <test-id>

# Edit by partial ID
skill-creator test edit my-commit-skill abc12345

test delete

Remove a test case from a skill. Shows test details and asks for confirmation unless --force is used.

skill-creator test delete <skill-name> <test-id> [--force]

# Delete without confirmation
skill-creator t rm my-skill abc12345 -f

test generate

Automatically generate test cases using LLM analysis (Claude Haiku when ANTHROPIC_API_KEY is available) or heuristic patterns. Generated tests go through a review workflow.

skill-creator test generate <skill-name> [options]

Option	Description
--count=<n>	Tests per type (default: 5, max: 50)
--no-review	Save all generated tests without review
--no-llm	Skip LLM, use heuristic only

# Generate with defaults (5 positive, 5 negative)
skill-creator test generate my-skill

# Generate more tests, skip review
skill-creator test generate my-skill --count=20 --no-review

simulate

Run activation simulation to predict which skill would activate for a given prompt. Supports single prompts and batch mode (one prompt per line from a file).

skill-creator simulate "<prompt>" [options]
skill-creator simulate --batch=<file> [options]

Option	Description
--verbose, -v	Show all predictions and trace details
--threshold=<n>	Activation threshold (default: 0.75)
--json	Output as JSON
--batch=<file>	Read prompts from file (one per line)
--project, -p	Use project scope

# Single prompt
skill-creator simulate "commit my changes" --verbose

# Batch mode
skill-creator simulate --batch=prompts.txt --json

Calibrate: Threshold Optimization

calibrate

Analyze collected activation events to find the F1-optimal threshold. Requires at least 75 events with known outcomes. Events are collected automatically during normal skill usage.

skill-creator calibrate [options]

Option	Description
--preview	Show proposed changes without applying
--force, -f	Skip confirmation prompt

# Preview calibration
skill-creator calibrate --preview

# Apply without confirmation
skill-creator calibrate --force

calibrate rollback

Undo the most recent threshold change by reverting to the previous value in threshold history.

skill-creator calibrate rollback
skill-creator cal rollback

calibrate history

Display all threshold snapshots with timestamps, F1 scores, and the reason for each change. The current active threshold is highlighted.

skill-creator calibrate history

benchmark

Compute correlation between simulated predictions and actual activation outcomes. Reports Matthews Correlation Coefficient (MCC), agreement rate, and confusion matrix. Results are always written to .planning/calibration/benchmark.json.

skill-creator benchmark [options]

Option	Description
--verbose, -v	Show per-skill breakdown
--json	Output JSON only

# Summary view
skill-creator benchmark

# Detailed per-skill breakdown
skill-creator bench -v

Utilities

migrate

Scan for skills using the legacy flat-file format (skill-name.md) and migrate them to the current subdirectory format (skill-name/SKILL.md). Without a skill name, interactively migrates all detected legacy skills.

skill-creator migrate [<skill-name>] [--project]

# Migrate all legacy skills
skill-creator migrate

# Migrate project-level skills
skill-creator mg -p

migrate-agent

Detect and fix agents using the legacy array-style tools format. Converts to the required comma-separated string format and corrects tool name casing.

skill-creator migrate-agent [<agent-name>] [--dry-run]

Option	Description
--dry-run, -d	Preview changes without writing to files

# Check all agents for legacy format issues
skill-creator migrate-agent

# Preview changes
skill-creator ma --dry-run

budget

Display current character budget consumption with visual progress bar and per-skill breakdown. Claude Code limits skills to approximately 15,000 characters per skill and 15,500 characters cumulative.

skill-creator budget [--project]

# Check project-level skill budget
skill-creator bg -p

status

Display currently loaded skills in the session with token counts, remaining budget, loading projection, and any skills flagged for review. See Token Budget Management for details on the loading projection display.

skill-creator status
skill-creator st

invoke

Manually load a specific skill into the current session. Shows token usage, remaining budget, and a content preview.

skill-creator invoke <skill-name>
skill-creator i react-hooks

suggest

Analyze usage patterns from .planning/patterns/sessions.jsonl and surface skill suggestions when patterns repeat 3+ times. Provides an interactive review workflow: Accept, Preview, Defer, Dismiss, Skip, or Quit.

skill-creator suggest
skill-creator sg

suggestions

View statistics about skill suggestions or manage dismissed suggestions.

skill-creator suggestions [list|clear]

# Show suggestion statistics
skill-creator sgs

# Clear dismissed suggestions
skill-creator sgs clear

feedback

View correction history and feedback statistics for skills. Feedback is collected when you override or correct skill output.

skill-creator feedback [list <skill-name>]

# Show feedback statistics
skill-creator fb

# List feedback for a specific skill
skill-creator fb list my-commit-skill

refine

Generate bounded refinements based on accumulated feedback. Requires at least 3 corrections, limits changes to 20% content per application, with a 7-day cooldown between refinements. Always requires user confirmation.

skill-creator refine <skill-name>
skill-creator rf my-skill

history

Show the git commit history for a skill file. Each entry displays commit hash, date, version number, and commit message.

skill-creator history <skill-name>
skill-creator hist my-skill

rollback

Revert a skill to a previous version from git history. Without a hash, presents an interactive selection. With a hash, rolls back directly.

skill-creator rollback <skill-name> [hash]

# Interactive version selection
skill-creator rb my-skill

# Rollback to specific commit
skill-creator rb my-skill a1b2c3d

agents

Analyze skill co-activation patterns and manage agent suggestions. When skills frequently activate together (5+ co-activations over 7+ days), suggests creating composite agents. Subcommands: suggest, list, validate.

skill-creator agents <subcommand>

# Analyze patterns and suggest agents
skill-creator ag suggest

# List agents with validation status
skill-creator ag ls

# Validate all agent files
skill-creator ag v

sync-reserved

Display the current reserved skill names configuration with categories and examples. Reserved names are skill names that conflict with Claude Code built-in commands.

skill-creator sync-reserved
skill-creator sync

reload-embeddings

Check the embedding service status and attempt to reload the model if currently in fallback (heuristic) mode. Use after GPU becomes available or network connectivity is restored.

skill-creator reload-embeddings [--verbose]
skill-creator re -v

Discover: Pattern Discovery

discover

Run the full 6-stage pattern discovery pipeline: Scan (enumerate projects and parse JSONL sessions), Extract (identify tool sequence n-grams, classify Bash commands), Cluster (group similar prompts using DBSCAN), Rank (multi-factor scoring with deduplication), Present (display ranked candidates), and Draft (generate SKILL.md files).

skill-creator discover [options]

Option	Description
--exclude <project>	Skip a specific project during scanning (repeatable)
--rescan	Force full rescan, ignoring stored watermarks

# Run full discovery pipeline
skill-creator discover

# Exclude a project from scanning
skill-creator discover --exclude my-private-project

# Force full rescan
skill-creator disc --rescan

First run scans all sessions (30-60s for large corpora). Subsequent runs are fast due to watermark-based incremental scanning. Scan state is stored at ~/.gsd-skill-creator/discovery/scan-state.json. Framework noise (patterns in 15+ projects AND 80%+ of tracked projects) is automatically filtered.

Teams: Multi-Agent Coordination

team create

Interactive wizard or flag-based team creation from pattern templates. Available patterns: leader-worker (one leader, multiple workers), pipeline (sequential stages with orchestrator), swarm (peer agents with coordinator).

skill-creator team create [options]

Option	Description
--pattern=<pattern>	leader-worker, pipeline, or swarm
--name=<name>	Team name (lowercase, hyphens)
--members=<n>	Number of workers (default: 3)
--scope=<scope>	Storage scope: project (default) or user
--description=<text>	Team description

# Interactive wizard
skill-creator team create

# Non-interactive with flags
skill-creator team create --pattern=leader-worker --name=my-team

# Pipeline with 4 members
skill-creator team create --pattern=pipeline --name=data-flow --members=4

team list

Discover teams from both project and user scopes. Shows name, topology pattern, member count, and scope in a styled table.

skill-creator team list [options]

Option	Description
--scope=<scope>	Filter: project, user (default: both)
--quiet, -q	CSV-like output: name,topology,memberCount,scope
--json	JSON output for scripting

team validate

Run the full validation pipeline: schema validation, member resolution, topology rules, tool overlap detection, skill conflict detection, and role coherence. Errors are blocking; warnings are informational.

skill-creator team validate [<name>] [options]

Option	Description
--all, -a	Validate all discovered teams
--scope=<scope>	project (default) or user
--quiet, -q	Minimal: name,pass or name,fail
--json	Full validation result as JSON

# Validate all teams
skill-creator team validate --all

# JSON output for CI
skill-creator tm v my-team --json

team spawn

Validate that all member agent files exist on disk. When agents are missing, displays fuzzy name suggestions and offers to generate the missing files interactively.

skill-creator team spawn <name> [options]

Option	Description
--scope=<scope>	Scope to search: project, user, or both
--quiet, -q	name,ready or name,not-ready
--json	JSON with per-member resolution details

# Check if team is ready
skill-creator team spawn my-team

# Quick readiness check
skill-creator tm sp my-team --quiet

team status

Display full team configuration: name, topology, description, lead agent, creation date, member table (Agent ID, Name, Type, Model), and compact validation summary.

skill-creator team status <name> [options]

Option	Description
--scope=<scope>	Scope to search: project, user, or both
--quiet, -q	name,topology,memberCount,valid
--json	Full config with validation summary

skill-creator team status my-team
skill-creator tm s my-team --json

Exit Codes

Commands return structured exit codes for CI/scripting integration.

Command	Exit 0	Exit 1
validate	All validations pass	Any validation fails
detect-conflicts	No high-severity conflicts	HIGH severity found (>90%)
test run	All tests pass AND thresholds met	Failures OR thresholds exceeded
benchmark	Correlation >= 85%	Correlation < 85%
budget	Success	Error reading skills
migrate-agent	Success or no migration needed	Error during migration
team validate	All teams valid (or warnings only)	One or more teams have errors
team spawn	All member agents resolved	One or more agents missing
discover	Pipeline completes, drafts written	Error during scan/extract/rank
(all others)	Success	Error occurred

CI Integration

Commands supporting --json output for CI pipelines and scripting.

Command	JSON Flag	Output Content
detect-conflicts	--json	Conflict array with severity
score-activation	--json	Scores array with factors
test list	--json	Test case array
test run	--json=compact|pretty	Results with metrics
simulate	--json	Prediction with confidence
benchmark	--json	Report with correlation
team list	--json	Team array with topology/scope
team validate	--json	Validation with errors/warnings
team spawn	--json	Readiness with member resolution
team status	--json	Full config with validation

GitHub Actions Example

# .github/workflows/skill-quality.yml
name: Skill Quality

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install skill-creator
        run: npm install -g skill-creator

      - name: Validate skills
        run: skill-creator validate --all

      - name: Check conflicts
        run: |
          skill-creator detect-conflicts --json > conflicts.json
          jq -e '.conflicts | length == 0' conflicts.json

      - name: Run tests
        run: skill-creator test run --all --min-accuracy=90 --max-false-positive=5

      - name: Validate teams
        run: skill-creator team validate --all --quiet

      - name: Benchmark accuracy
        run: skill-creator benchmark

JSON Schema: detect-conflicts

{
  "conflicts": [
    {
      "skill1": "commit-helper",
      "skill2": "git-workflow",
      "similarity": 0.92,
      "severity": "high"
    }
  ],
  "threshold": 0.85,
  "scanned": 5
}

JSON Schema: test run

{
  "skill": "my-skill",
  "metrics": {
    "total": 10,
    "passed": 8,
    "failed": 2,
    "accuracy": 80.0,
    "falsePositiveRate": 10.0
  },
  "results": [
    {
      "id": "abc123",
      "prompt": "commit my changes",
      "expected": "positive",
      "actual": "positive",
      "confidence": 0.92,
      "passed": true
    }
  ]
}

What's Next

• Skill Workflows — Standard workflows combining these commands into end-to-end processes
• Token Budget Management — Understanding and managing skill loading budgets
• Configuration Guide — Tuning thresholds, budgets, and integration settings
• Installation — Getting started with skill-creator