@nano-step/skill-manager 4.0.0

package/templates/command-refresh.md

@@ -0,0 +1,100 @@
+# /agent-skill-refresh
+
+Re-index and categorize all available MCP tools for intelligent routing.
+
+## Purpose
+
+Create a semantic tool index in `.opencode/agent-skill-tools.json` by analyzing **all available tools** in the current agent context. Categorization is AI-only and based on tool names + descriptions (no prefixes).
+
+## When to Run
+
+- First time setup (cache doesn't exist)
+- After adding/removing MCP servers or tools
+- When routing seems incorrect or tools are missing
+- Periodically to keep index fresh
+
+## Auto-Refresh Triggers
+
+The agent-skill-manager will suggest running `/agent-skill-refresh` automatically when:
+
+- **Tool not found**: A requested tool doesn't exist in the cache
+- **Cache missing**: The `.opencode/agent-skill-tools.json` file doesn't exist
+- **Cache stale**: The cache is older than 24 hours
+- **Tool count mismatch**: Available tools differ from cached count
+
+When you see a suggestion to refresh, run this command to update the cache.
+
+## Execution Steps
+
+### Step 1: Enumerate All Tools (Introspection)
+
+List every tool available to the agent in its current context (functions/tools list). For each tool, extract:
+
+- `tool_id` (exact tool name)
+- `description` (tool description text)
+
+Produce a full list; do not skip any tools.
+
+### Step 2: Semantic Categorization (Single Holistic Pass)
+
+Use the following prompt to categorize **all tools at once**:
+
+```
+You have access to the following tools. Analyze each tool's name and description,
+then group them into semantic categories based on what they DO (not where they come from).
+
+Tools:
+- tool_id_1: "description 1"
+- tool_id_2: "description 2"
+...
+
+For each category, provide:
+1. name: Short identifier (lowercase, hyphenated)
+2. description: One sentence describing the category's purpose
+3. keywords: 5-10 words for routing user requests to this category
+4. tools: List of tool IDs belonging to this category
+
+Output as JSON.
+```
+
+### Step 3: Write Cache File (v2.0.0)
+
+Write `.opencode/agent-skill-tools.json` with this schema:
+
+```json
+{
+  "version": "2.0.0",
+  "generated_at": "2026-01-27T03:00:00Z",
+  "tool_count": 75,
+  "categories": {
+    "browser-automation": {
+      "name": "Browser Automation",
+      "description": "Web page interaction, screenshots, DOM manipulation",
+      "keywords": ["screenshot", "click", "navigate", "page", "browser", "element"],
+      "tools": ["MetaMCP_chrome-devtools__take_screenshot", "MetaMCP_chrome-devtools__click"]
+    }
+  },
+  "tools": {
+    "MetaMCP_chrome-devtools__take_screenshot": {
+      "category": "browser-automation",
+      "description": "Take a screenshot of the page or element"
+    }
+  }
+}
+```
+
+### Step 4: Report Summary
+
+```
+Agent Skill Tools Index Refreshed:
+
+Categories:
+  - browser-automation: 25 tools
+  - docs: 4 tools
+  - github: 15 tools
+
+Summary:
+  - Total tools: 75
+  - Categories: 3
+  - Cache: .opencode/agent-skill-tools.json
+```

package/templates/command-workflow.md

@@ -0,0 +1,188 @@
+# /agent-skill-workflow
+
+Manage workflow rules that define prerequisite steps before tool execution.
+
+## Purpose
+
+Create, list, edit, and remove workflow definitions that automatically execute prerequisite steps when certain tools are triggered. For example, always inspect database structure before running queries.
+
+## Subcommands
+
+### List Workflows
+
+```
+/agent-skill-workflow list
+```
+
+Display all defined workflows with their status, triggers, and prerequisite count.
+
+**Output format:**
+```
+Workflows (3 defined):
+
+✓ database-safe-query [enforce]
+  Triggers: category=database, keywords=[query, select]
+  Prerequisites: 4 steps
+  
+✓ browser-safe-interaction [enforce]
+  Triggers: category=browser
+  Prerequisites: 1 step
+
+○ github-pr-review [disabled]
+  Triggers: tools=[merge_pull_request]
+  Prerequisites: 3 steps
+```
+
+### Add Workflow (Interactive)
+
+```
+/agent-skill-workflow add <name>
+```
+
+Create a new workflow interactively. The agent will prompt for:
+
+1. **Description**: What does this workflow do?
+2. **Triggers**: 
+   - Category (optional): Which tool category triggers this?
+   - Tools (optional): Which specific tools trigger this?
+   - Keywords (optional): Which words in the task trigger this?
+3. **Prerequisites**: For each step:
+   - Tool name
+   - Description (why this step is needed)
+   - Required? (yes/no)
+4. **Mode**: enforce, warn, or suggest
+
+**Example session:**
+```
+> /agent-skill-workflow add api-safety
+
+Description: Check API schema before making requests
+Trigger category (or skip): api
+Trigger tools (comma-separated, or skip): execute_request, post_request
+Trigger keywords (comma-separated, or skip): api call, request
+
+Prerequisite 1:
+  Tool: get_schema
+  Description: Fetch API schema
+  Required? yes
+  
+Add another prerequisite? yes
+
+Prerequisite 2:
+  Tool: list_endpoints
+  Description: List available endpoints
+  Required? no
+
+Add another prerequisite? no
+
+Mode (enforce/warn/suggest): warn
+
+✓ Workflow 'api-safety' created with 2 prerequisites
+```
+
+### Add from Template
+
+```
+/agent-skill-workflow add --template <template-name>
+```
+
+Create a workflow from a built-in template. Available templates:
+
+| Template | Description | Prerequisites |
+|----------|-------------|---------------|
+| `database` | Safe database queries | list_databases → list_tables → inspect_table → get_indexes |
+| `browser` | Safe browser interaction | take_snapshot |
+| `github-pr` | PR review workflow | get_pull_request → get_files → get_status |
+| `graphql` | Schema-aware GraphQL | get_schema → filter_types |
+
+**Example:**
+```
+> /agent-skill-workflow add --template database
+
+✓ Created workflow 'database-safe-query' from template
+  Mode: enforce
+  Prerequisites: 4 steps
+```
+
+To list available templates:
+```
+/agent-skill-workflow add --template
+```
+
+### Edit Workflow
+
+```
+/agent-skill-workflow edit <name>
+```
+
+Modify an existing workflow. Shows current values and allows changing any field.
+
+### Remove Workflow
+
+```
+/agent-skill-workflow remove <name>
+```
+
+Delete a workflow after confirmation.
+
+```
+> /agent-skill-workflow remove api-safety
+
+Remove workflow 'api-safety'? This cannot be undone. (yes/no): yes
+
+✓ Workflow 'api-safety' removed
+```
+
+### Enable/Disable Workflow
+
+```
+/agent-skill-workflow enable <name>
+/agent-skill-workflow disable <name>
+```
+
+Toggle a workflow's enabled status without removing it.
+
+```
+> /agent-skill-workflow disable database-safe-query
+
+✓ Workflow 'database-safe-query' disabled
+  (Prerequisites will not run until re-enabled)
+```
+
+## Workflow Modes
+
+| Mode | Behavior |
+|------|----------|
+| `enforce` | Prerequisites run automatically before main action |
+| `warn` | Warning shown, user can skip prerequisites |
+| `suggest` | Prerequisites mentioned but don't block execution |
+
+## Storage
+
+Workflows are stored in `.opencode/agent-skill-tools.json` under the `workflows` key. They persist across sessions and are preserved when running `/agent-skill-refresh`.
+
+## Session State
+
+Completed prerequisites are tracked in `.opencode/.agent-skill-session.json`. Within a session, prerequisites only run once per workflow (unless the session expires after 24 hours).
+
+## Examples
+
+### Create a custom workflow for file operations
+```
+/agent-skill-workflow add file-safety
+```
+Then define triggers for file tools and prerequisites like "list directory" before "delete file".
+
+### Use database template and customize
+```
+/agent-skill-workflow add --template database
+/agent-skill-workflow edit database-safe-query
+```
+Modify the default database workflow to fit your needs.
+
+### Temporarily disable a workflow
+```
+/agent-skill-workflow disable browser-safe-interaction
+# ... do some quick browser tasks without snapshots ...
+/agent-skill-workflow enable browser-safe-interaction
+```

package/templates/skill/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: agent-skill-management
+description: >-
+  Agent skill routing and execution. Enables efficient routing of MCP tools
+  with token-saving isolation. Uses semantic AI categorization to support ANY
+  MCP configuration. Cache at .opencode/agent-skill-tools.json for fast tool discovery.
+compatibility: "OpenCode with any MCP server"
+metadata:
+  author: Sisyphus
+  version: "4.0.0"
+---
+
+# Agent Skill Management Skill
+
+**Version**: 4.0.0 | **Architecture**: 3-Tier Progressive Disclosure | **Categorization**: Semantic AI
+
+## Overview
+
+This skill enables the agent-skill-manager agent to efficiently route and execute MCP (Model Context Protocol) tools. By isolating MCP 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 `/agent-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 MCP configuration. Run `/agent-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/agent-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
+/agent-skill-workflow add --template database
+
+# List active workflows
+/agent-skill-workflow list
+
+# Disable temporarily
+/agent-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/agent-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 `/agent-skill-refresh`
+
+### If Cache Missing
+1. Inform user: "Run `/agent-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 `/agent-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