nano-step/skill-management

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:

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

# 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

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

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

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

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

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 | Full tool lists per category | Need specific tool | | tool-execution.md | Routing algorithm, cache schema | Complex routing | | result-handling.md | Summarization patterns | Large results | | 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