CLI Commands Guide

Overview

The skill-creator CLI is the primary interface for managing the entire skill lifecycle: initialization, creation, validation, testing, calibration, pattern discovery, conflict detection, team management, and GSD orchestration. All commands are invoked via npx skill-creator <command> (or skill-creator <command> if installed globally). This guide documents every command with its full synopsis, available flags, expected output, and practical examples.

Commands are organized into four categories: Core Operations for daily skill management, Discovery and Analysis for pattern detection and quality assurance, Teams and Agents for multi-agent coordination, and GSD Orchestration for project lifecycle integration.

Key Concepts

Core Operations

These commands handle the fundamental skill lifecycle: project initialization, skill creation, validation, testing, and threshold calibration.

start

Initialize skill-creator for a project. Creates the .claude/skills/ directory structure, generates default configuration files, and optionally installs project-level skills from a template repository. This is typically the first command you run in a new project.

Synopsis:

npx skill-creator start

What it creates:

.claude/
  skills/           # Project-level skill storage
  agents/           # Agent configuration files
  teams/            # Team definitions
  settings.json     # skill-creator configuration
.planning/
  patterns/
    sessions.jsonl  # Session observation log

Example:

$ npx skill-creator start
Initializing skill-creator...
  Created .claude/skills/
  Created .claude/agents/
  Created .claude/teams/
  Created .claude/settings.json
  Created .planning/patterns/sessions.jsonl

skill-creator initialized successfully.
Run 'npx skill-creator status' to verify setup.

If the project already has a .claude/skills/ directory, the command will detect the existing installation and offer to reset or upgrade the configuration without deleting existing skills.

status

Display the current state of skill-creator: loaded skills with token counts, budget consumption as a visual bar, loading projection (which skills would load on next session start), and any skills flagged for review due to low activation scores or pending refinements.

Synopsis:

npx skill-creator status [--json]

Example (human-readable):

$ npx skill-creator status

Installed Skills
  beautiful-commits     [P]  1,247 tokens  loaded
  react-patterns        [U]  2,891 tokens  loaded
  test-runner           [P]    956 tokens  loaded
  openstack-deploy      [P]  3,412 tokens  deferred

Budget Status
  Context window:    200,000 tokens
  Budget ceiling:      5,000 tokens (2.5%)
  Skills loaded:     5,094 / 5,000  [==========>] 102%
  Remaining:            -94 tokens (1 skill deferred)

Flagged for Review
  openstack-deploy — deferred (exceeds budget by 94 tokens)

The --json flag outputs structured JSON with skills array (name, scope, tokens, state), budget object (contextWindow, ceiling, used, remaining), flagged array, and projection object (wouldLoad, wouldDefer). Pipe to jq for extraction: npx skill-creator status --json | jq '.budget.used'.

create

Launch the interactive skill creation wizard. Prompts for skill name, description, trigger patterns, and content. Generates a properly formatted SKILL.md file with YAML frontmatter in the appropriate directory structure. Skills created through this command are pre-validated against all 15 validators.

Synopsis:

npx skill-creator create [--project]

Example:

$ npx skill-creator create --project

Skill Creation Wizard

Skill name (lowercase, hyphens): deploy-checker
Description: Validate deployment manifests before applying to production

Creating skill: deploy-checker
  Location: .claude/skills/deploy-checker/SKILL.md
  Scope: project

  Running validators... 15/15 passed

Skill created successfully.
Run 'npx skill-creator test add deploy-checker' to add test cases.

The wizard validates the skill name against reserved names (built-in Claude Code commands), checks for naming conflicts with existing skills, and ensures the directory structure follows the required skill-name/SKILL.md format.

validate

Run the full validation suite against one or all skills. The 15 validators check: name format (lowercase, hyphens, no reserved names), directory structure (subdirectory format with SKILL.md), YAML frontmatter schema (required fields, correct types), description quality (length, specificity, trigger phrases), content structure (sections, code blocks, examples), and cross-references (links to other skills resolve correctly).

Synopsis:

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

Example:

$ npx skill-creator validate --all --project

Validating 4 project-level skills...

  beautiful-commits    15/15 passed
  deploy-checker       15/15 passed
  test-runner          14/15 passed
    WARN: description lacks imperative trigger phrases
  openstack-deploy     15/15 passed

Summary: 4 skills, 59/60 checks passed, 1 warning
Exit code: 0 (warnings do not fail)

Exit codes: Returns 0 if all validations pass (warnings are non-blocking). Returns 1 if any validation fails (errors are blocking). Use in CI pipelines to gate merges on skill quality.

test run

Execute activation test cases against the skill simulator and report pass/fail results. Test cases define prompts with expected outcomes: positive (skill should activate), negative (skill should not activate), or edge-case (borderline). The simulator scores each prompt and compares against the configured activation threshold.

Synopsis:

npx skill-creator test run [<skill-name>] [--all] [--verbose] [--json] [--threshold=<n>] [--min-accuracy=<n>] [--max-false-positive=<n>]

Example:

$ npx skill-creator test run beautiful-commits --verbose

Testing: beautiful-commits (6 test cases)

  PASS  "commit my changes with a good message"
        Expected: positive | Confidence: 0.94
  PASS  "write a conventional commit for this bug fix"
        Expected: positive | Confidence: 0.91
  PASS  "what is the conventional commits specification?"
        Expected: negative | Confidence: 0.12
  PASS  "explain git commit best practices"
        Expected: negative | Confidence: 0.23
  FAIL  "save my work"
        Expected: positive | Confidence: 0.62 (below threshold 0.75)
  PASS  "commit and push to main"
        Expected: edge-case | Confidence: 0.78

Results: 5/6 passed (83.3% accuracy)
False positive rate: 0.0%
Exit code: 0

CI usage with quality gates:

$ npx skill-creator test run --all --min-accuracy=90 --max-false-positive=5
# Returns exit code 1 if any skill fails the quality gates

calibrate

Analyze collected activation events to find the F1-optimal activation threshold using grid search. The calibration process examines historical activation data (collected automatically during normal usage) and finds the threshold value that maximizes the harmonic mean of precision and recall. Requires at least 75 activation events with known outcomes.

Synopsis:

npx skill-creator calibrate [--preview] [--force]

Example:

$ npx skill-creator calibrate --preview

Calibration Analysis
  Activation events: 312
  Current threshold: 0.75
  Optimal threshold: 0.72

  Current F1:  0.847
  Proposed F1: 0.891

  Grid search: tested 50 thresholds from 0.50 to 0.99
  Best candidate: 0.72 (F1: 0.891, precision: 0.88, recall: 0.90)

Preview mode — no changes applied.
Run without --preview to apply.

Calibration history is stored at .planning/calibration/history.json. Use npx skill-creator calibrate history to view past threshold changes and npx skill-creator calibrate rollback to revert to the previous threshold.

Discovery and Analysis

These commands scan session data for patterns, detect skill conflicts, and measure prediction accuracy.

discover

Run the full 6-stage pattern discovery pipeline. The pipeline scans session logs from .planning/patterns/sessions.jsonl, extracts tool sequence n-grams, clusters similar prompts, ranks candidates by frequency and recency, presents findings interactively, and optionally drafts SKILL.md files for approved patterns.

Synopsis:

npx skill-creator discover [--threshold=<n>] [--since=<date>] [--incremental] [--rescan] [--dry-run] [--exclude=<project>] [--allow=<project>]

Example:

$ npx skill-creator discover --dry-run

Pattern Discovery Pipeline
  Stage 1/6: Scan ... 47 sessions across 3 projects
  Stage 2/6: Extract ... 128 tool sequences identified
  Stage 3/6: Cluster ... 23 prompt clusters formed
  Stage 4/6: Rank ... 8 candidates above threshold (3)
  Stage 5/6: Present

  Candidate 1: "lint-test-fix" (score: 0.94)
    Pattern: eslint → vitest → edit → eslint (12 occurrences)
    Projects: gsd-skill-creator, my-webapp
    Suggested name: lint-test-fix-cycle

  Candidate 2: "git-commit-workflow" (score: 0.87)
    Pattern: git status → git diff → edit → git add → git commit (9 occurrences)
    Projects: gsd-skill-creator, api-server, my-webapp
    Suggested name: structured-commit

  ... (6 more candidates)

  Stage 6/6: Draft — dry-run mode, no files written.

Summary: 8 candidates found. Run without --dry-run to draft skills.

Scan state is stored at ~/.gsd-skill-creator/discovery/scan-state.json. First run scans all sessions (30-60 seconds for large corpora). Subsequent runs use watermark-based incremental scanning and complete in seconds. Framework noise (patterns appearing in 15+ projects and 80%+ of tracked projects) is automatically filtered to avoid generating skills for universal behaviors like "read file, edit file."

detect-conflicts

Use embedding-based semantic analysis to find skills with overlapping activation descriptions. When two skills have descriptions that are too similar, Claude Code may activate the wrong one. This command identifies those overlaps and, when ANTHROPIC_API_KEY is available, generates rewrite suggestions to differentiate them.

Synopsis:

npx skill-creator detect-conflicts [--threshold=<n>] [--json] [--quiet] [--project]

Severity levels: HIGH (>90% similarity) — requires immediate review, skills will likely misfire. MEDIUM (85–90%) — worth investigating, may cause occasional wrong activations.

Example:

$ npx skill-creator detect-conflicts --threshold=0.85

Conflict Detection (threshold: 0.85)

  HIGH   commit-helper <> git-workflow  (similarity: 0.92)
         Both skills trigger on "commit" prompts.
         Suggestion: Differentiate by scope — commit-helper for
         message formatting, git-workflow for the full commit process.

  MEDIUM test-runner <> test-debug  (similarity: 0.87)
         Overlap on "run tests" prompts.
         Suggestion: Add "debug" and "failing" trigger words to
         test-debug description.

Summary: 2 conflicts found (1 HIGH, 1 MEDIUM)
Exit code: 1 (HIGH severity conflict found)

Exit codes: Returns 0 if no HIGH severity conflicts are found. Returns 1 if any HIGH severity conflict exists. Use in CI to prevent merging skills with dangerous overlaps.

benchmark

Compute the correlation between simulated skill predictions and actual activation outcomes. Reports Matthews Correlation Coefficient (MCC), agreement rate, and a full confusion matrix. This measures how accurately the simulator predicts which skill will activate for a given prompt, compared to what actually happened in real sessions.

Synopsis:

npx skill-creator benchmark [--verbose] [--json]

Example:

$ npx skill-creator benchmark --verbose

Benchmark Results
  Events analyzed: 247
  Agreement rate:  91.5%
  MCC:             0.83

  Confusion Matrix:
                    Predicted Active  Predicted Inactive
  Actually Active        112               11
  Actually Inactive        10              114

  Per-Skill Breakdown:
    beautiful-commits   95.2% agreement (42/44 events)
    react-patterns      89.1% agreement (49/55 events)
    test-runner         90.7% agreement (39/43 events)

Results written to .planning/calibration/benchmark.json
Exit code: 0 (correlation >= 85%)

Exit codes: Returns 0 if agreement rate is 85% or above. Returns 1 if below 85%, indicating the simulator needs recalibration.

Teams and Agents

These commands manage multi-agent configurations: creating teams, validating their structure, and discovering agent composition opportunities from co-activation patterns.

team create

Create a team configuration from a pattern template. Teams organize multiple agents into coordinated groups with defined topologies. Three patterns are available: leader-worker (one leader delegates to workers), pipeline (sequential stages with orchestrator), and swarm (peer agents with coordinator).

Synopsis:

npx skill-creator team create [--pattern=<pattern>] [--name=<name>] [--members=<n>] [--scope=<scope>] [--description=<text>]

Example (non-interactive):

$ npx skill-creator team create \
    --pattern=leader-worker \
    --name=deploy-team \
    --members=4 \
    --description="Handles deployment validation and execution"

Creating team: deploy-team
  Pattern: leader-worker
  Members: 1 leader + 4 workers = 5 agents
  Scope: project
  Location: .claude/teams/deploy-team/team.json

  Generated agent stubs:
    deploy-team-leader (leader)
    deploy-team-worker-1 (worker)
    deploy-team-worker-2 (worker)
    deploy-team-worker-3 (worker)
    deploy-team-worker-4 (worker)

Team created. Run 'npx skill-creator team validate deploy-team'
to check configuration.

When invoked without flags, the command runs an interactive wizard that guides you through pattern selection, naming, and member configuration.

team validate

Run the full team validation pipeline: schema validation (required fields, correct types), member resolution (agent files exist on disk), topology rules (leader-worker has exactly one leader, pipeline has no cycles), tool overlap detection (agents sharing tools may conflict), skill conflict detection (member skills have high semantic overlap), and role coherence (agent descriptions match their assigned role).

Synopsis:

npx skill-creator team validate [<name>] [--all] [--scope=<scope>] [--json] [--quiet]

Example:

$ npx skill-creator team validate deploy-team

Validating team: deploy-team

  Schema validation ............ PASS
  Member resolution ............ PASS (5/5 agents found)
  Topology rules ............... PASS (leader-worker: 1 leader, 4 workers)
  Tool overlap detection ....... WARN (worker-1 and worker-2 share 'Bash')
  Skill conflict detection ..... PASS (no semantic overlaps > 0.85)
  Role coherence ............... PASS

Result: PASS (1 warning)
Exit code: 0

Exit codes: Returns 0 if all checks pass (warnings are non-blocking). Returns 1 if any check produces an error (errors are blocking). Warnings indicate potential issues worth reviewing but do not indicate a broken team configuration.

agent suggest

Analyze skill co-activation patterns across session history and suggest composite agents. When skills frequently activate together (5+ co-activations over 7+ days), they are candidates for agent composition — bundling related skills into a single agent that loads as one unit, reducing activation overhead and ensuring the skills are always available together.

Synopsis:

npx skill-creator agent suggest

Example:

$ npx skill-creator agent suggest

Co-Activation Analysis
  Sessions analyzed: 89
  Time span: 21 days

  Cluster 1: "commit-workflow" (confidence: HIGH)
    Skills: beautiful-commits, lint-runner, test-checker
    Co-activations: 34 (over 18 days)
    Suggestion: Create agent "commit-workflow" combining all three.
    Combined token cost: 3,891 tokens

  Cluster 2: "react-dev" (confidence: MEDIUM)
    Skills: react-patterns, css-modules
    Co-activations: 12 (over 9 days)
    Suggestion: Create agent "react-dev" combining both.
    Combined token cost: 4,203 tokens

Summary: 2 agent suggestions (1 HIGH, 1 MEDIUM confidence)
Run 'npx skill-creator agent suggest --apply' to create agent files.

Agent composition requires explicit user confirmation. The system never auto-creates agents, even when confidence is high. Composition thresholds (5 co-activations, 7 days) are enforced as bounded learning guardrails.

GSD Orchestration

These commands integrate skill-creator with the GSD (Get Shit Done) project management framework, providing command discovery, natural language intent classification, and lifecycle-aware action suggestions.

orchestrator discover

List all available GSD commands with their descriptions and usage summaries. Scans the .claude/commands/gsd/ directory for command definitions and presents them organized by lifecycle stage: starting, planning, executing, validating, and managing scope.

Synopsis:

npx skill-creator orchestrator discover

Example:

$ npx skill-creator orchestrator discover

GSD Commands (22 discovered)

Starting Work
  new-project       Initialize with questioning, research, and roadmap
  new-milestone     Add a milestone to an existing project
  progress          Show roadmap position and suggest next action

Planning Work
  discuss-phase     Explore phase vision through discussion
  plan-phase        Create a detailed execution plan
  research-phase    Deep ecosystem investigation

Executing Work
  execute-phase     Run plans with fresh context and atomic commits
  quick             Lightweight ad-hoc task execution

Validating Work
  verify-work       User acceptance testing for a phase
  audit-milestone   Comprehensive milestone completion check

Managing Scope
  add-phase / insert-phase / remove-phase
  add-todo / check-todos

orchestrator classify

Classify a natural language request into the most appropriate GSD command. Uses a 5-stage classification pipeline: exact match, lifecycle filtering, Bayesian classification, semantic fallback, and confidence resolution. Returns the matched command with a confidence score.

Synopsis:

npx skill-creator orchestrator classify "<intent>"

Examples:

$ npx skill-creator orchestrator classify "let's plan out the auth feature"
  Matched: /gsd:plan-phase  |  Confidence: 0.94
  Stage: Exact keyword match ("plan")

$ npx skill-creator orchestrator classify "what should I work on next"
  Matched: /gsd:progress  |  Confidence: 0.87
  Stage: Bayesian classification

$ npx skill-creator orchestrator classify "maybe we should think about caching"
  Matched: /gsd:discuss-phase OR /gsd:add-todo  |  Confidence: 0.52
  Stage: Confidence resolution (below threshold)
  Action: Ask user to clarify intent.

When confidence falls below the configured threshold (default: 0.70), the classifier returns multiple candidates and recommends asking the user for clarification rather than guessing. A wrong routing is worse than a clarifying question.

orchestrator lifecycle

Suggest the next action based on the current project lifecycle position. Reads .planning/ROADMAP.md and .planning/STATE.md to determine where the project stands and what the natural next step would be.

Synopsis:

npx skill-creator orchestrator lifecycle

Example:

$ npx skill-creator orchestrator lifecycle

Project Lifecycle Analysis
  Milestone: v3.0  |  Phase 4 (API Integration)  |  Status: planned
  Last action: /gsd:plan-phase 4 (2 hours ago)

Suggested: /gsd:execute-phase 4
  Phase 4 has a completed plan and no blockers.

Alternatives:
  /gsd:verify-work 3 — Phase 3 executed but not verified
  /gsd:progress — Review full roadmap position

The lifecycle command is read-only. It never modifies files or executes actions — it reads ROADMAP.md and STATE.md to recommend the natural next step, accounting for blockers, uncompleted verification, and pending todos.

# Find skills consuming more than 2000 tokens
npx skill-creator status --json | jq '.skills[] | select(.tokens > 2000) | .name'

npx skill-creator detect-conflicts --json | jq '[.conflicts[] | select(.severity == "high")] | length'

for threshold in 0.70 0.75 0.80 0.85; do
  echo "Threshold: $threshold"
  npx skill-creator test run --all --threshold=$threshold --json=compact | \
    jq '.metrics.accuracy'
done

# Alert if budget exceeds 90%
USAGE=$(npx skill-creator status --json | jq '.budget.used / .budget.ceiling * 100')
if (( $(echo "$USAGE > 90" | bc -l) )); then
  echo "WARNING: Skill budget at ${USAGE}%" | mail -s "Budget Alert" admin@example.com
fi

# Essential CI steps (add to your workflow)
- run: npx skill-creator validate --all --project
- run: npx skill-creator detect-conflicts --project --json | jq -e '.conflicts | length == 0'
- run: npx skill-creator test run --all --min-accuracy=90 --max-false-positive=5
- run: npx skill-creator team validate --all --quiet
- run: npx skill-creator benchmark

Troubleshooting

What's Next

• UG-1: Command Reference — Complete reference with JSON schemas and exit codes
• UG-2: Skill Workflows — End-to-end workflows combining these commands
• T-4: Calibrating Thresholds — Step-by-step calibration tutorial
• T-9: Pattern Discovery — Deep dive into the discovery pipeline
• T-5: Creating Agent Teams — Tutorial for team creation and validation
• UG-3: Token Budget — Understanding budget constraints and optimization
• UG-4: Configuration — All configurable settings and their effects
• Specialized Systems Overview — The six subsystems these commands manage