---
name: skill-management
description: >-
  Skill routing and execution. Enables efficient routing of tools
  with token-saving isolation. Uses semantic AI categorization to support ANY
  tool configuration. Cache at .opencode/skill-tools.json for fast tool discovery.
compatibility: "OpenCode with any MCP server"
metadata:
  author: nano-step
  version: "5.0.0"
---

# Skill Management

**Version**: 5.0.0 | **Architecture**: 3-Tier Progressive Disclosure | **Categorization**: Semantic AI

## Overview

This skill enables the skill-manager agent to efficiently route and execute tools. By isolating tool definitions in a dedicated subagent context, we reduce main agent token usage by 80-95%.

## When to Use This Skill

| Trigger | Category | Example |
|---------|----------|---------|
| Browser automation | `browser` | "Take a screenshot", "Click the login button" |
| GitHub operations | `github` | "Get PR #123 details", "List open issues" |
| GraphQL queries | `graphql` | "Get the schema", "List available mutations" |
| Documentation lookup | `docs` | "How do I use useState?", "Find React docs" |
| Complex reasoning | `reasoning` | "Analyze this step by step" |

## Quick Reference

### Tool Categories (AI-Generated)

Categories are generated by `/skill-refresh` using semantic AI analysis. Common categories include:

| Category | Description | Example Tools |
|----------|-------------|---------------|
| browser-automation | Web interaction, screenshots, DOM | click, screenshot, navigate |
| version-control | Git, PRs, issues, code review | get_pull_request, list_issues |
| documentation | Library docs, API references | query-docs, resolve-library-id |
| communication | Messaging, notifications | post_message, list_channels |
| database | SQL queries, data operations | query, insert, update |

**Note**: Your actual categories depend on your tool configuration. Run `/skill-refresh` to generate.

### Most Common Tools

| Task | Tool | Category |
|------|------|----------|
| Screenshot | `take_screenshot` | browser |
| Click element | `click` | browser |
| Fill form | `fill`, `fill_form` | browser |
| Navigate | `navigate_page` | browser |
| Get page content | `take_snapshot` | browser |
| Get PR details | `get_pull_request` | github |
| List issues | `list_issues` | github |
| Search code | `search_code` | github |
| Query docs | `query-docs` | docs |
| Step-by-step analysis | `sequentialthinking` | reasoning |

## Routing Decision Tree

```
Task received
│
├─ Contains '__' (exact tool name)?
│  └─ YES → DIRECT PASSTHROUGH: Execute immediately
│
├─ Starts with 'BATCH:'?
│  └─ YES → Parse JSON array, execute sequentially
│
├─ Starts with 'CHAIN:'?
│  └─ YES → Parse chain, execute with variable passing
│
├─ Matches workflow trigger?
│  └─ YES → Check prerequisites, execute if needed
│
├─ Explicit tool name mentioned?
│  └─ YES → Use that tool directly
│
├─ Read .opencode/skill-tools.json cache
│  └─ Match task keywords against category keywords
│
├─ Multiple categories match?
│  └─ YES → Prefer category with more keyword matches
│
└─ No match?
   └─ Search tool descriptions or ask for clarification
```

## Advanced Features

### Direct Passthrough

When you know the exact tool name (contains `__`), skip routing entirely:

```
Task: "Use MetaMCP_chrome-devtools__take_screenshot"
→ Executes directly without category lookup
```

### Batch Operations

Execute multiple tools in one request using `BATCH:` prefix:

```
BATCH: [
  {"tool": "take_screenshot", "params": {}},
  {"tool": "get_title", "params": {}}
]
```

- Maximum 10 tools per batch
- Returns array of results in execution order
- Partial failures reported per-tool

### Tool Chaining

Chain tools with output passing using `CHAIN:` prefix:

```
CHAIN: [
  {"tool": "get_element", "params": {"selector": "#btn"}, "output_as": "el"},
  {"tool": "click", "params": {"element": "$el"}}
]
```

- Use `$varname` to reference previous outputs
- Maximum 5 tools per chain
- Chain aborts on first failure

### Retry Mechanism

All tool executions automatically retry on failure:

- Up to 3 attempts
- Delays: 0s → 1s → 2s
- Failure report if all attempts fail:
  ```json
  {"tool": "name", "attempts": 3, "errors": [...], "suggestion": "..."}
  ```

## Workflows

Define prerequisite steps that automatically execute before certain tool operations.

### What are Workflows?

Workflows enforce best practices by requiring prerequisite steps before tool execution. For example:
- Always inspect database structure before running queries
- Take a page snapshot before clicking elements
- Review PR details before merging

### Quick Start

```bash
# Add a workflow from template
/skill-workflow add --template database

# List active workflows
/skill-workflow list

# Disable temporarily
/skill-workflow disable database-safe-query
```

### Built-in Templates

| Template | Triggers | Prerequisites |
|----------|----------|---------------|
| `database` | query, select, insert | list_databases → list_tables → inspect_table |
| `browser` | click, fill, submit | take_snapshot |
| `github-pr` | merge, review | get_pr → get_files → get_status |

### Workflow Modes

| Mode | Behavior |
|------|----------|
| `enforce` | Auto-run prerequisites (default) |
| `warn` | Show warning, allow skip |
| `suggest` | Mention only, don't block |

**Full documentation**: [workflows.md](references/workflows.md)

## Cache Usage

**Location**: `.opencode/skill-tools.json`

### If Cache Exists
1. Read and parse JSON (v2.0.0 schema)
2. Use `categories` for keyword-based routing
3. Use `tools` map for O(1) tool lookup
4. Check `generated_at` - if >24h old, suggest `/skill-refresh`

### If Cache Missing
1. Inform user: "Run `/skill-refresh` to create tool cache"
2. Fall back to dynamic tool discovery (slower)

**Full cache schema**: [tool-execution.md](references/tool-execution.md#cache-schema)

## Execution Flow

1. **Parse Intent** → Extract keywords from task
2. **Match Category** → Find best category match
3. **Select Tool** → Choose specific tool within category
4. **Execute** → Call tool with mapped parameters
5. **Summarize** → Return concise result to main agent

**Detailed patterns**: [tool-execution.md](references/tool-execution.md)

## Result Handling

### Summarization Rules

| Result Type | Action |
|-------------|--------|
| Large (>1000 chars) | Extract key info only |
| File operations | "File X read/written successfully (N chars)" |
| Data queries | "Found N items. First 3: [...]" |
| Screenshots | "Screenshot saved to /path" |
| Errors | Include error + suggestions |

### Always Include
- Success/failure status
- Key identifiers (IDs, paths, URLs)
- Count of items (for lists)
- Actionable next steps
- Error details (if failed)

**Full patterns**: [result-handling.md](references/result-handling.md)

## Error Recovery

| Error | Recovery |
|-------|----------|
| Tool not found | Suggest similar tools |
| Execution failed | Include context + retry suggestions |
| Timeout | Report partial result + suggestions |
| Cache missing | Prompt `/skill-refresh` |

**Full recovery procedures**: [error-handling.md](references/error-handling.md)

## Example Invocations

### Browser: Take Screenshot
```
Task: "Take a screenshot of the current page"
Tool: MetaMCP_chrome-devtools__take_screenshot
Result: "Screenshot saved to ./screenshot.png"
```

### GitHub: Get PR
```
Task: "Get details of PR #123 in owner/repo"
Tool: MetaMCP_github-zengaming__get_pull_request
Params: { owner: "owner", repo: "repo", pull_number: 123 }
Result: "PR #123: 'Fix bug' by @user, open, +50/-20, 3 files"
```

### Docs: Query Library
```
Task: "How do I use useState in React?"
1. MetaMCP_context7__resolve-library-id → "/facebook/react"
2. MetaMCP_context7__query-docs → Usage examples
Result: "useState returns [state, setState]. Example: ..."
```

## Reference Documentation

| Document | Content | When to Read |
|----------|---------|--------------|
| [tool-categories.md](references/tool-categories.md) | Full tool lists per category | Need specific tool |
| [tool-execution.md](references/tool-execution.md) | Routing algorithm, cache schema | Complex routing |
| [result-handling.md](references/result-handling.md) | Summarization patterns | Large results |
| [error-handling.md](references/error-handling.md) | Recovery procedures | Errors occur |

## Best Practices

1. **Prefer Cached Routing** - Always check cache first
2. **Batch Operations** - Execute related operations in sequence
3. **Summarize Aggressively** - Main agent needs actions, not data
4. **Fail Fast** - Ask for clarification rather than guessing
5. **Include Context** - Errors should be actionable