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)

name

description

argument-hint

[file-path]

disable-model-invocation

true

user-invocable

false

/

allowed-tools

model

context

fork

agent

hooks

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

"Reviews code"

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

$ARGUMENTS

${CLAUDE_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

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

Explore

Plan

general-purpose

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:

Bash(git:*)

Bash(npm:*)

Bash(gh:*)

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

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

Bash(git:*)

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