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//SKILL.md
• Project: .claude/skills//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

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

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

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

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

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

---

Example: Missing Trigger Phrase

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

Why it's bad: No trigger context for auto-discovery.

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.

Example: Dangerous Auto-Invocation

name: deploy
description: "Deploys code to production"

Why it's bad: Side-effect skill could be auto-invoked accidentally.

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

Why it's good: Manual-only prevents accidental deployments.

Example: Unrestricted Tools

name: git-helper
allowed-tools: Bash

Why it's bad: Unrestricted Bash allows any command.

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

Why it's good: Scoped to only git commands.

Example: Oversized Skill

# Complex Analysis
[800 lines of detailed instructions]

Why it's bad: Large skills consume context budget (15K char limit).

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

Example: Context/Agent Mismatch

name: researcher
context: fork
# Missing agent type

Why it's bad: Fork context without specifying agent type.

name: researcher
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob

Why it's good: Agent type matches allowed tools (Explore = read-only).

---

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agent-sh
• Source: agent-sh/agentsys
• License: MIT
• Homepage: https://agent-sh.github.io/agentsys/

Install and usage instructions live in the source repository linked above.