name: enhance-skills description: "Use when reviewing SKILL.md files for structure and trigger quality." version: 5.0.0 argument-hint: "[path] [--fix]"

OpenCode Note: Invoke agents using @agent-name syntax. Available agents: task-discoverer, exploration-agent, planning-agent, implementation-agent, deslop-agent, delivery-validator, sync-docs-agent, consult-agent Example: @exploration-agent analyze the codebase

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