logo1
GSD Skill Creator
CLI Reference
Source: View on GitHub · Raw markdown

Documentation > Reference > CLI Reference

CLI Reference

skill-creator is the command-line interface for managing Claude Code skills. It provides commands for creating, validating, testing, and optimizing skills throughout their lifecycle.

Cheat Sheet

Quick reference for all commands organized by workflow stage.

Create: Skill Authoring

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

Validate: Quality Assurance

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

Test: Activation Testing

Command Alias Description
test t Manage skill test cases
simulate sim Predict which skill would activate for a prompt

Calibrate: Threshold Optimization

Command Alias Description
calibrate cal Optimize activation threshold from calibration data
benchmark bench Measure simulator accuracy vs real activation

Utilities

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

Discover: Pattern Discovery

Command Alias Description
discover disc Scan session logs, extract patterns, rank candidates, generate draft skills

Teams: Multi-Agent Coordination

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

Global Options

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

Target vs Filter

  • --project, -p = TARGET (where to operate)
  • --scope=<value> = FILTER (what to show)

–project, -p

Target project-level scope for operations. Without this flag, operations default to user-level (~/.claude/skills/).

  • --project: Use project-level skills at .claude/skills/
  • -p: Short form

Applies to: create, delete, validate, migrate, budget, detect-conflicts, score-activation

# Create skill at user level (default)
skill-creator create

# Create skill at project level
skill-creator create --project

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

–scope=<value>

Filter list output by scope. Only applies to the list command.

  • --scope=user: Show only user-level skills
  • --scope=project: Show only project-level skills
  • --scope=all: Show skills from both scopes (default)

Team commands accept --scope=project or --scope=user to filter by storage scope. Without --scope, commands search both scopes.

# Show all skills (default)
skill-creator list

# Show only user-level skills
skill-creator list --scope=user

# Show only project-level skills
skill-creator list --scope=project

–verbose, -v

Show detailed output with additional information.

Applies to: score-activation, simulate, reload-embeddings

# Score with factor breakdown
skill-creator sa my-skill --verbose

# Simulation with trace details
skill-creator simulate "commit changes" -v

–quiet, -q

Suppress non-essential output. Produces minimal, machine-friendly output.

Applies to: detect-conflicts, score-activation

# One line per conflict
skill-creator dc --quiet

# Minimal score output (skillName,score,label)
skill-creator sa --all --quiet

–json

Output as JSON for scripting and CI integration.

Applies to: detect-conflicts, score-activation, test list, simulate, benchmark

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

# Parse scores programmatically
skill-creator sa --all --json | jq '.results[].score'

Create: Skill Authoring

Commands for creating, browsing, and managing skills.

create

Create a new skill through guided workflow.

Synopsis:

skill-creator create [--project]

Description:

Interactive workflow that prompts for skill name, description, and content. Creates a properly formatted skill with YAML frontmatter in the appropriate location.

Options:

  • --project, -p: Create at project-level scope (.claude/skills/)

Examples:

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

Synopsis:

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

Description:

Shows all skills with their name, scope indicator, and description preview. Skills are displayed from both user and project scopes by default, with project-level skills taking precedence when names conflict.

Options:

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

Examples:

# List all skills from both scopes
skill-creator list

# List only user-level skills
skill-creator list --scope=user

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

Search skills by keyword interactively.

Synopsis:

skill-creator search

Description:

Interactive fuzzy search across skill names and descriptions. Type to filter, use arrow keys to navigate, and press Enter to select. Useful when you have many skills and need to quickly find one.

Examples:

# Launch interactive search
skill-creator search

# Short form
skill-creator s

delete

Delete a skill.

Synopsis:

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

Description:

Removes a skill from the specified scope. If a version exists at both user and project scope, deleting one will make the other become active. The command warns about this before confirming deletion.

Options:

  • --project, -p: Delete from project-level scope

Examples:

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

# Delete from project scope
skill-creator delete react-patterns --project

# Short forms
skill-creator del my-skill
skill-creator rm my-skill -p

resolve

Show which version of a skill is active.

Synopsis:

skill-creator resolve <skill-name>

Description:

When a skill exists at both user and project scope, project-level takes precedence. This command shows which version Claude Code will actually use and whether another version is being shadowed.

Examples:

# Check which version is active
skill-creator resolve my-commit-helper

# Short form
skill-creator res react-patterns

Sample Output:

Skill: my-commit-helper

+ Active: Project-level
  Path: .claude/skills/my-commit-helper/SKILL.md
  Description: Generate conventional commit messages...

o Shadowed: User-level
  Path: ~/.claude/skills/my-commit-helper/SKILL.md
  This version exists but is overridden by project-level.

Validate: Quality Assurance

Commands for checking skill correctness and identifying potential issues.

validate

Validate skill structure and metadata.

Synopsis:

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

Description:

Runs comprehensive validation checks on skills:

  1. Name validation – Follows official Claude Code specification (lowercase, hyphens, no reserved names)
  2. Directory structure – Correct subdirectory format with SKILL.md
  3. Metadata schema – Valid YAML frontmatter with required fields
  4. Directory/name match – Directory name matches frontmatter name field

Options:

  • --all, -a: Validate all skills in scope
  • --project, -p: Target project-level scope

Exit Codes:

Code Meaning
0 All validations passed
1 One or more validations failed

Examples:

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

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

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

# Short form
skill-creator v my-skill

detect-conflicts

Detect semantic conflicts between skills.

Synopsis:

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

Description:

Uses embedding-based semantic analysis to find skills with overlapping descriptions that may cause activation confusion. When skills are too similar, Claude may activate the wrong one or activate multiple skills unexpectedly.

The command generates rewrite suggestions to differentiate conflicting skills. When ANTHROPIC_API_KEY is available, suggestions use Claude; otherwise, heuristic suggestions are provided.

Options:

  • --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

Exit Codes:

Code Meaning
0 No conflicts or only MEDIUM severity
1 HIGH severity conflicts detected (>90% similarity)

Severity Levels:

  • HIGH (>90% similarity): Very likely conflict, review required
  • MEDIUM (85-90% similarity): Possible conflict, worth reviewing

Examples:

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

# Check specific skill against others
skill-creator detect-conflicts my-commit-helper

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

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

# Count conflicts
skill-creator dc --quiet | wc -l

# Short forms
skill-creator dc my-skill
skill-creator conflicts --threshold=0.80

score-activation

Score skill activation likelihood.

Synopsis:

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

Description:

Analyzes skill descriptions to predict how reliably they will trigger auto-activation. Scores range from 0-100 based on description quality factors like specificity, trigger phrases, and length.

The command uses local heuristics by default (no API calls, instant results). The --llm flag enables deeper analysis using Claude API for single-skill analysis.

Options:

  • --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

Score Labels:

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

Scoring Factors:

  • Specificity: Unique terms vs generic terms
  • Activation phrases: Explicit triggers like “use when…”
  • Length: 50-150 characters optimal
  • Imperative verbs: Action verbs at start (Generate, Run, etc.)
  • Generic penalty: Reduction for overused terms

Examples:

# Score a single skill
skill-creator score-activation my-commit-helper

# Score with detailed factor breakdown
skill-creator sa my-commit-helper --verbose

# Score all skills
skill-creator score-activation --all

# JSON output for CI
skill-creator sa --all --json

# Sort skills by score
skill-creator sa --all --quiet | sort -t, -k2n

# LLM-powered deep analysis (single skill only)
skill-creator sa my-commit-helper --llm

# Short forms
skill-creator score my-skill
skill-creator sa --all -v

Test: Activation Testing

Commands for managing and running test cases that verify skill activation behavior.

test

Manage skill test cases.

Synopsis:

skill-creator test <subcommand> [options]

Description:

The test command manages activation test cases – defining expected behavior for “should this skill activate for this prompt?” Test cases verify that skills activate correctly for intended prompts and don’t activate for unrelated prompts.

Subcommands:

Subcommand Description
add Add a new test case
list List test cases for a skill
run Run tests for one or all skills
edit Edit an existing test case
delete Delete a test case
generate Generate test cases automatically
help Show help text

Global Options:

  • --project, -p: Use project scope (.claude/skills/)

test add

Add a test case to a skill.

Synopsis:

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

Description:

Creates a new test case for the specified skill. Can run interactively (prompting for each field) or with flags for scripted usage.

Options:

Option Description
--prompt="..." Test prompt (required in flag mode)
--expected=<value> Expected behavior: 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 (for negative tests)

Examples:

# Interactive mode - prompts for all fields
skill-creator test add my-commit-skill

# Flag mode - positive test case
skill-creator test add my-commit-skill \
  --prompt="commit my changes with a good message" \
  --expected=positive \
  --description="Should activate for explicit commit requests"

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

# Edge case with tags and difficulty
skill-creator test add my-commit-skill \
  --prompt="save my work" \
  --expected=edge-case \
  --tags=ambiguous,regression \
  --difficulty=hard

test list

List test cases for a skill.

Synopsis:

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

Options:

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

test run

Run tests for one or all skills.

Synopsis:

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

Options:

Option Description
--all, -a Run tests for all skills
--verbose, -v Show confidence scores for all results
--json=<format> Output as JSON: compact or pretty (auto-detected 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%

test edit

Edit an existing test case.

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

test delete

Delete a test case.

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

test generate

Generate test cases automatically.

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

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

simulate

Predict which skill would activate for a prompt.

Synopsis:

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

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

Calibrate: Threshold Optimization

Commands for optimizing activation thresholds and measuring simulator accuracy.

Calibration Workflow

  1. Use skills normally – Activation events are recorded automatically
  2. Accumulate data – Wait until you have at least 75 events with known outcomes
  3. Run calibration – skill-creator calibrate finds the F1-optimal threshold
  4. Review and apply – Preview the proposed threshold and confirm before applying
  5. Verify improvement – skill-creator benchmark measures real-world accuracy

calibrate

Optimize activation threshold from calibration data.

skill-creator calibrate [options]
skill-creator calibrate rollback
skill-creator calibrate history

Options:

  • --preview: Show proposed changes without applying
  • --force, -f: Skip confirmation prompt

benchmark

Measure simulator accuracy vs real activation.

skill-creator benchmark [options]

Options:

  • --verbose, -v: Show per-skill breakdown
  • --json: Output JSON only

Exit Codes:

Code Meaning
0 Correlation >= 85%
1 Correlation < 85%

Utils: Utilities

Commands for migration, budget management, pattern detection, and system maintenance.

migrate

Migrate legacy flat-file skills to subdirectory format.

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

migrate-agent

Migrate agents with legacy tools format.

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

budget

Show character budget usage across all skills.

skill-creator budget [--project]

status

Show active skills and token budget.

skill-creator status

invoke

Manually invoke a skill by name.

skill-creator invoke <skill-name>

suggest

Analyze patterns and review skill suggestions.

skill-creator suggest

suggestions

List and manage skill suggestions.

skill-creator suggestions [list|clear]

feedback

View feedback for skills.

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

refine

Generate and apply skill refinements. Requires at least 3 corrections before suggestions become available. Refinements are limited to 20% content change with a 7-day cooldown.

skill-creator refine <skill-name>

history

View skill version history.

skill-creator history <skill-name>

rollback

Rollback skill to previous version.

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

agents

Manage agent suggestions from skill clusters.

skill-creator agents <subcommand>

Subcommands: suggest, list, validate

sync-reserved

Show and update reserved skill names list.

skill-creator sync-reserved

reload-embeddings

Reload the embedding model.

skill-creator reload-embeddings [--verbose]

Teams: Multi-Agent Coordination

Commands for creating, managing, and validating agent teams.

team create

Create a new team from a pattern template.

skill-creator team create [options]

Available patterns: leader-worker, pipeline, swarm

Options:

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

team list

List all teams with member counts.

skill-creator team list [options]

team validate

Validate team configuration(s).

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

Runs the full validation pipeline: schema validation, member resolution, topology rules, tool overlap detection, skill conflict detection, and role coherence.

team spawn

Check team readiness by validating agent resolution.

skill-creator team spawn <name> [options]

team status

Show team details and validation summary.

skill-creator team status <name> [options]

discover

Scan Claude Code session logs to discover recurring interaction patterns and generate draft skills.

skill-creator discover [options]

Options:

  • --exclude <project>: Skip a specific project during scanning
  • --rescan: Force full rescan, ignoring previously stored watermarks

The discover command runs the full pattern discovery pipeline: Scan, Extract, Cluster, Rank, Present, Draft.

Exit Codes

Command Exit 0 Exit 1
validate All validations pass Any validation fails
detect-conflicts No high-severity conflicts High-severity conflicts found
test run All tests pass AND thresholds met Failures OR thresholds exceeded
benchmark Correlation >= 85% Correlation < 85%
team validate All teams valid One or more teams have errors
team spawn All member agents resolved One or more agents missing
discover Pipeline completes Error during scan/extract/rank

CI Integration

Commands supporting --json output for scripting: detect-conflicts, score-activation, test list, test run, simulate, benchmark, team list, team validate, team spawn, team status.

Example CI Pipeline

# GitHub Actions workflow for skill quality
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
      - 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

Common Tasks

Check Skill Quality

# Validate structure and metadata
skill-creator validate my-skill

# Check for semantic conflicts
skill-creator detect-conflicts my-skill

# Score activation likelihood
skill-creator score-activation my-skill --verbose

Test Activation Behavior

# Add test cases
skill-creator test add my-skill

# Run tests with details
skill-creator test run my-skill --verbose

# Simulate a specific prompt
skill-creator simulate "my test prompt" --verbose

Optimize Activation Threshold

# Preview calibration changes
skill-creator calibrate --preview

# Apply optimal threshold
skill-creator calibrate

# Verify improvement
skill-creator benchmark

Migrate Legacy Files

# Scan and migrate all legacy skills
skill-creator migrate

# Check agents for format issues
skill-creator agents validate

# Fix agent format issues
skill-creator migrate-agent

Monitor Budget Usage

# Check user-level budget
skill-creator budget

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

# See active skills
skill-creator status