enhance-skills

# enhance-skills

Analyze skill definitions for trigger quality, structure, and discoverability.

## Workflow

1. **Discover** - Find all SKILL.md files
2. **Parse** - Extract frontmatter and content
3. **Check** - Run all pattern checks against knowledge below
4. **Filter** - Apply certainty filtering
5. **Report** - Generate markdown output
6. **Fix** - Apply auto-fixes if --fix flag present

---

## Skill Knowledge Reference

### Frontmatter Fields (Complete Reference)

| Field | Required | Description | Validation |
|-------|----------|-------------|------------|
| `name` | No | Display name, defaults to directory name | lowercase, max 64 chars |
| `description` | Recommended | What skill does and when to use | max 1024 chars, should include trigger |
| `argument-hint` | No | Autocomplete hint, e.g., `[file-path]` | keep under 30 chars |
| `disable-model-invocation` | No | `true` = manual only (for side effects) | boolean, default false |
| `user-invocable` | No | `false` = hidden from `/` menu (auto-only) | boolean, default true |
| `allowed-tools` | No | Tools Claude can use without permission | comma-separated list |
| `model` | No | Specific model when skill is active | opus, sonnet, haiku |
| `context` | No | `fork` = run in isolated subagent context | fork or omit |
| `agent` | No | Subagent type for execution | Explore, Plan, general-purpose |
| `hooks` | No | Skill-scoped lifecycle hooks | PreToolUse, PostToolUse |

### Directory Structure

```
skills/my-skill/
├── SKILL.md           # Required - core definition (under 500 lines)
├── reference.md       # Optional - detailed documentation
├── examples.md        # Optional - usage examples
└── scripts/           # Optional - helper scripts
    └── helper.py
```

**Storage Locations:**
- Enterprise: Managed settings
- Personal: `~/.claude/skills/<name>/SKILL.md`
- Project: `.claude/skills/<name>/SKILL.md`

### Invocation Control Patterns

**Manual Only (for skills with side effects):**
```yaml
---
name: deploy
description: Deploy to production
disable-model-invocation: true
---
```

**Background Knowledge (auto-only, hidden from menu):**
```yaml
---
name: legacy-context
description: How the legacy payment system works
user-invocable: false
---
```

**Full Access (default - both auto and manual):**
```yaml
---
name: review
description: Use when user asks to review code. Checks quality and security.
---
```

### Trigger Phrases

Description should include trigger context for auto-discovery:
- "Use when user asks..."
- "Use when..."
- "Invoke when..."

**Good:** `"Use when user asks to 'review code', 'check PR', or 'code review'"`
**Bad:** `"Reviews code"` (no trigger context)

### Dynamic Context Injection

Skills can inject dynamic content using backtick syntax:

```yaml
---
name: pr-summary
description: Summarize PR changes
context: fork
agent: Explore
allowed-tools: Bash(gh:*)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`
```

**Rules:**
- Use `!` followed by backtick-wrapped command
- Limit to 3 injections per skill
- Each injection adds to context budget

### String Substitutions

| Variable | Description |
|----------|-------------|
| `$ARGUMENTS` | All arguments passed when invoking |
| `${CLAUDE_SESSION_ID}` | Current session ID |

### Context Budget

- Skill descriptions have ~15,000 character default limit
- Content beyond limit is truncated
- Check with `/context` command
- Increase via: `SLASH_COMMAND_TOOL_CHAR_BUDGET=30000`

### Subagent Execution

When using `context: fork`:

```yaml
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---

Research $ARGUMENTS thoroughly:
1. Find relevant files
2. Analyze the code
3. Summarize findings
```

**Agent Types:**
| Agent | Purpose | Tool Access |
|-------|---------|-------------|
| `Explore` | Read-only codebase exploration | Read, Grep, Glob only |
| `Plan` | Planning-focused reasoning | Read, analysis tools |
| `general-purpose` | Full capabilities | All tools |

### Skill-Scoped Hooks

```yaml
---
name: secure-operations
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---
```

### Tool Restrictions

Use scoped tool patterns for security:

| Pattern | Meaning |
|---------|---------|
| `Bash(git:*)` | Only git commands |
| `Bash(npm:*)` | Only npm commands |
| `Bash(gh:*)` | Only GitHub CLI |
| `Read(src/**)` | Only files in src/ |

---

## Detection Patterns

### 1. Frontmatter Validation (HIGH Certainty)

**Required:**
- YAML frontmatter with `---` delimiters
- `name` field (lowercase, max 64 chars)
- `description` field (max 1024 chars)

**Recommended:**
- `version` field for tracking
- `argument-hint` for skills accepting input
- `allowed-tools` for security
- `model` when specific model required

**Flag:**
- Missing frontmatter delimiters
- Invalid field values (uppercase name, description >1024 chars)

### 2. Trigger Quality (HIGH Certainty)

**Check:** Description includes trigger phrase
**Trigger patterns:** "Use when", "Invoke when", "Use when user asks"

**Flag:**
- Description without trigger context
- Vague descriptions like "Useful tool" or "Does stuff"

### 3. Invocation Control (HIGH Certainty)

**Check:** Side-effect skills are protected

**Flag:**
- Skills with deploy/ship/publish in name but `disable-model-invocation` not set
- Dangerous auto-invocable skills (can accidentally trigger)

### 4. Tool Restrictions (HIGH Certainty)

**Check:** Tools are appropriately scoped

**Flag:**
- Unrestricted `Bash` (should be `Bash(git:*)` or similar)
- Read-only skills with Write/Edit
- Research skills with Task tool

### 5. Content Scope (MEDIUM Certainty)

**Guidelines:**
- SKILL.md under 500 lines
- Large content in `references/` subdirectory
- Max 3 dynamic injections

**Flag:**
- SKILL.md over 500 lines
- More than 3 `!`backtick`` injections
- Embedded large examples (move to examples.md)

### 6. Structure Quality (MEDIUM Certainty)

**Recommended Sections:**
- Purpose/overview
- Required checks or workflow steps
- Output format
- Examples (if complex)

### 7. Context Configuration (MEDIUM Certainty)

**Check:** Context settings are appropriate

**Flag:**
- `context: fork` without `agent` type
- `agent` type without `context: fork`
- Mismatch between agent type and allowed-tools

### 8. Anti-Patterns (LOW Certainty)

- Vague descriptions without specific triggers
- Too many responsibilities (should split into multiple skills)
- Missing `argument-hint` for skills that clearly need input
- Redundant chain-of-thought instructions (modern models don't need "think step by step")

---

## Auto-Fix Implementations

### 1. Missing frontmatter
```yaml
---
name: skill-name
description: "Use when..."
version: 4.2.0
---
```

### 2. Missing trigger phrase
Add "Use when user asks..." prefix to description

### 3. Unrestricted Bash
Replace `Bash` with `Bash(git:*)` or appropriate scope

---

## Output Format

```markdown
## Skill Analysis: {skill-name}

**File**: {path}

### Summary
- HIGH: {count} issues
- MEDIUM: {count} issues

### Frontmatter Issues ({n})
| Issue | Fix | Certainty |

### Trigger Issues ({n})
| Issue | Fix | Certainty |

### Invocation Issues ({n})
| Issue | Fix | Certainty |

### Tool Issues ({n})
| Issue | Fix | Certainty |

### Scope Issues ({n})
| Issue | Fix | Certainty |
```

---

## Pattern Statistics

| Category | Patterns | Auto-Fixable |
|----------|----------|--------------|
| Frontmatter | 5 | 2 |
| Trigger | 2 | 1 |
| Invocation | 3 | 1 |
| Tool | 3 | 1 |
| Scope | 3 | 0 |
| Structure | 2 | 0 |
| Context | 3 | 0 |
| Anti-Pattern | 4 | 0 |
| **Total** | **25** | **5** |

---

<examples>
### Example: Missing Trigger Phrase

<bad_example>
```yaml
name: code-review
description: "Reviews code for issues"
```
**Why it's bad**: No trigger context for auto-discovery.
</bad_example>

<good_example>
```yaml
name: code-review
description: "Use when user asks to 'review code', 'check this PR'. Reviews code for issues."
```
**Why it's good**: Clear trigger phrases enable auto-discovery.
</good_example>

### Example: Dangerous Auto-Invocation

<bad_example>
```yaml
name: deploy
description: "Deploys code to production"
```
**Why it's bad**: Side-effect skill could be auto-invoked accidentally.
</bad_example>

<good_example>
```yaml
name: deploy
description: "Deploy to production environment"
disable-model-invocation: true
```
**Why it's good**: Manual-only prevents accidental deployments.
</good_example>

### Example: Unrestricted Tools

<bad_example>
```yaml
name: git-helper
allowed-tools: Bash
```
**Why it's bad**: Unrestricted Bash allows any command.
</bad_example>

<good_example>
```yaml
name: git-helper
allowed-tools: Bash(git:*)
```
**Why it's good**: Scoped to only git commands.
</good_example>

### Example: Oversized Skill

<bad_example>
```markdown
# Complex Analysis
[800 lines of detailed instructions]
```
**Why it's bad**: Large skills consume context budget (15K char limit).
</bad_example>

<good_example>
```markdown
# Complex Analysis
Core instructions here (under 500 lines).
For details, see `references/detailed-guide.md`.
```
**Why it's good**: Core skill is concise; details in separate files.
</good_example>

### Example: Context/Agent Mismatch

<bad_example>
```yaml
name: researcher
context: fork
# Missing agent type
```
**Why it's bad**: Fork context without specifying agent type.
</bad_example>

<good_example>
```yaml
name: researcher
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
```
**Why it's good**: Agent type matches allowed tools (Explore = read-only).
</good_example>
</examples>

---

## Constraints

- Only apply auto-fixes for HIGH certainty issues
- Consider skill context when evaluating trigger quality
- Never remove content, only suggest improvements
- Validate against embedded knowledge reference above