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

Documentation > User Guides > Troubleshooting

Troubleshooting

Centralized troubleshooting for common issues with skill-creator. Each issue follows the Symptom/Cause/Solution format for quick resolution.

Installation Issues

Command not found: skill-creator

Symptom: Running skill-creator returns “command not found” or “not recognized”.

Cause: Global link not in PATH or npm link not executed.

Solution:

  1. Verify npm global bin is in PATH: 
    npm bin -g
echo $PATH | grep -o "$(npm bin -g)"
  2. If not in PATH, add it: 
    export PATH="$PATH:$(npm bin -g)"
source ~/.bashrc
  3. Re-run npm link: 
    cd /path/to/gsd-skill-creator
npm link

Alternative: Run directly without linking:

node /path/to/gsd-skill-creator/dist/cli.js help

Cannot find module errors

Symptom: Running any command returns “Cannot find module” or “MODULE_NOT_FOUND”.

Cause: Project not built or build is outdated.

Solution:

cd /path/to/gsd-skill-creator
npm install
npm run build

Permission errors during npm link

Symptom: npm link fails with EACCES or permission denied.

Solution:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$PATH:$HOME/.npm-global/bin"' >> ~/.bashrc
source ~/.bashrc
npm link

Node version incompatibility

Symptom: Build fails with syntax errors or TypeScript compilation errors.

Cause: Node.js version below 18.

Solution: Check your version with node --version. If below v18, upgrade Node.js.

Skill Creation Issues

Skill not activating

Symptom: Skill exists but doesn’t activate when expected.

Cause: Description lacks activation triggers or is too generic.

Solution:

  1. Check activation score: skill-creator score-activation my-skill --verbose
  2. Improve the description with the “Use when…” pattern
  3. Verify with simulation: skill-creator simulate "your test prompt" --verbose

Validation failures

Solution by error type:

Error Fix
Name must be lowercase Rename to lowercase with hyphens: my-skill
Invalid characters in name Use only lowercase letters, numbers, hyphens
Reserved name Choose a different name
Directory structure invalid Move SKILL.md to skill-name/SKILL.md subdirectory
Metadata schema invalid Check YAML frontmatter for syntax errors
Directory/name mismatch Ensure directory name matches name: in frontmatter

Testing Issues

High false positive rate

Symptom: Skill activates for unrelated prompts.

Solution:

  1. Check for conflicts: skill-creator detect-conflicts
  2. Make description more specific with unique keywords
  3. Add negative test cases

High false negative rate

Symptom: Skill doesn’t activate when it should.

Solution:

  1. Check current threshold: skill-creator calibrate --preview
  2. Lower threshold if appropriate: skill-creator test run my-skill --threshold=0.70
  3. Add activation triggers to the description

Calibration data insufficient

Symptom: skill-creator calibrate fails with “insufficient data”.

Cause: Fewer than 75 calibration events recorded.

Solution: Continue using skills normally. Events are recorded automatically. Check current count with skill-creator benchmark.

Conflict Detection Issues

Embedding model fallback

Symptom: Conflict detection shows “Using heuristic (fallback)”.

Solution:

  1. Check status: skill-creator reload-embeddings --verbose
  2. Attempt reload: skill-creator reload-embeddings
  3. If still failing, check network connectivity and memory (~500MB for model)

Team Issues

Missing agent files after team creation

Solution:

  1. Check which files are missing: skill-creator team spawn my-team
  2. Regenerate: skill-creator team create --name=my-team --pattern=leader-worker
  3. Verify: skill-creator team status my-team

Invalid topology errors

Topology Common Error Fix
leader-worker No leader agent Ensure one member has agentType: "coordinator"
leader-worker Multiple leaders Only one member should be the leader
pipeline Cycle detected Remove circular dependsOn references
swarm No coordinator Swarm topologies still require one coordinating agent

CI/CD Issues

JSON output not working

Solution: Explicitly enable JSON output:

skill-creator detect-conflicts --json
# Or set CI environment:
export CI=true

Exit codes not propagating

Solution: Use set -e in scripts or check exit codes explicitly:

set -e
skill-creator validate --all
skill-creator detect-conflicts
skill-creator test run --all --min-accuracy=90

Still Stuck?

Run diagnostics:

node --version
npm --version
skill-creator --version
skill-creator list
skill-creator status