# Troubleshooting

## Common Issues

### "Skill not found" when running a skill

**Cause:** The skill is not installed in the registry.

**Fix:**

```bash
# Check what's installed
skilllane list

# Install the skill
skilllane install --builtin systematic-debugging
# or
skilllane install ./my-skill
```

---

### "Missing required files" when validating

**Cause:** The skill directory is missing one or more required files.

**Fix:** Ensure your skill directory contains all 5 required files:

```
my-skill/
├── metadata.json
├── SKILL.md
├── tools.json
├── examples.md
└── eval.md
```

Use `skilllane create` to scaffold a complete skill:

```bash
skilllane create my-skill
```

---

### "metadata.name is not kebab-case"

**Cause:** The skill name uses uppercase or special characters.

**Fix:** Use lowercase letters and hyphens only: `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`

- Good: `my-skill`, `code-review`, `debug-helper`
- Bad: `MySkill`, `my_skill`, `mySkill`

---

### "metadata.version is not semver-like"

**Cause:** The version doesn't match semver format.

**Fix:** Use `X.Y.Z` format: `0.1.0`, `1.0.0`, `2.1.3-beta.1`

---

### "Potential secret detected"

**Cause:** A file contains what looks like an API key, password, or token.

**Fix:** Remove the secret from the file. Use environment variables or a `.env` file instead.

---

### API server won't start

**Cause:** Port already in use or module not built.

**Fix:**

```bash
# Check if port is in use
lsof -i :3080

# Build first if using from source
npm run build

# Use a different port
skilllane serve --port 8080
```

---

### "Cannot find module" when running commands

**Cause:** The project hasn't been built.

**Fix:**

```bash
npm run build
```

---

### MCP server not responding

**Cause:** The server expects JSON-RPC on stdin, not interactive input.

**Fix:** Use an MCP-compatible client, or pipe JSON-RPC:

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | skilllane mcp
```

---

### Python client: "Cannot connect to SkillLane"

**Cause:** The API server is not running.

**Fix:**

```bash
# Start the server in another terminal
skilllane serve

# Then use the Python client
skilllane-py health
```

---

### Registry out of sync

**Cause:** Files were manually added or removed from `~/.skilllane/skills/`.

**Fix:**

```bash
skilllane registry rebuild
```

---

### Validation score is low

**Cause:** Missing files, empty content, or warnings.

**Fix:**

1. Run with `--json` to see all issues: `skilllane validate ./my-skill --json`
2. Add content to empty files
3. Add tags to metadata
4. Add section headers to `examples.md` and `eval.md`
5. Ensure `SKILL.md` is at least 50 characters

---

### "Skill already installed" error

**Cause:** A skill with the same name exists in the registry.

**Fix:**

```bash
# Overwrite existing
skilllane install ./my-skill --force

# Or remove first
skilllane remove my-skill
skilllane install ./my-skill
```

---

## Getting Help

```bash
# Show all commands
skilllane --help

# Show help for a specific command
skilllane create --help

# Run health checks
skilllane doctor
```