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)

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):

---
name: deploy
description: Deploy to production
disable-model-invocation: true
---

Background Knowledge (auto-only, hidden from menu):

---
name: legacy-context
description: How the legacy payment system works
user-invocable: false
---

Full Access (default – both auto and manual):

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

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

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:

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

Skill-Scoped Hooks

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

Tool Restrictions

Use scoped tool patterns for security:

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

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

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

<bad_example>

name: code-review
description: "Reviews code for issues"

Why it’s bad: No trigger context for auto-discovery. </bad_example>

<good_example>

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>

name: deploy
description: "Deploys code to production"

Why it’s bad: Side-effect skill could be auto-invoked accidentally. </bad_example>

<good_example>

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>

name: git-helper
allowed-tools: Bash

Why it’s bad: Unrestricted Bash allows any command. </bad_example>

<good_example>

name: git-helper
allowed-tools: Bash(git:*)

Why it’s good: Scoped to only git commands. </good_example>

Example: Oversized Skill

<bad_example>

# Complex Analysis
[800 lines of detailed instructions]

Why it’s bad: Large skills consume context budget (15K char limit). </bad_example>

<good_example>

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

name: researcher
context: fork
# Missing agent type

Why it’s bad: Fork context without specifying agent type. </bad_example>

<good_example>

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>

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