@nano-step/skill-manager 4.0.0

package/templates/skill/assets/tools-template.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Agent Skill Tools Cache v2.0.0",
+  "description": "Cache file for MCP tool routing. Generated by /agent-skill-refresh command using semantic AI categorization.",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "Schema version (2.0.0 for semantic categorization)",
+      "const": "2.0.0"
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when cache was generated"
+    },
+    "tool_count": {
+      "type": "integer",
+      "description": "Total number of tools indexed",
+      "minimum": 0
+    },
+    "categories": {
+      "type": "object",
+      "description": "AI-generated categories for tool routing",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Human-readable category name"
+          },
+          "description": {
+            "type": "string",
+            "description": "One sentence describing what this category does"
+          },
+          "keywords": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "5-10 routing keywords for matching user requests",
+            "minItems": 5,
+            "maxItems": 10
+          },
+          "tools": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "List of tool IDs in this category"
+          }
+        },
+        "required": ["name", "description", "keywords", "tools"]
+      }
+    },
+    "tools": {
+      "type": "object",
+      "description": "Tool lookup map for O(1) access by tool ID",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "category": {
+            "type": "string",
+            "description": "Category ID this tool belongs to"
+          },
+          "description": {
+            "type": "string",
+            "description": "Tool description"
+          }
+        },
+        "required": ["category", "description"]
+      }
+    }
+  },
+  "required": ["version", "generated_at", "tool_count", "categories", "tools"],
+  "example": {
+    "version": "2.0.0",
+    "generated_at": "2026-01-27T03:00:00.000Z",
+    "tool_count": 75,
+    "categories": {
+      "browser-automation": {
+        "name": "Browser Automation",
+        "description": "Web page interaction, screenshots, DOM manipulation, navigation",
+        "keywords": ["screenshot", "click", "navigate", "page", "browser", "element", "form", "DOM"],
+        "tools": [
+          "MetaMCP_chrome-devtools__take_screenshot",
+          "MetaMCP_chrome-devtools__click",
+          "MetaMCP_chrome-devtools__fill",
+          "MetaMCP_chrome-devtools__navigate_page"
+        ]
+      },
+      "version-control": {
+        "name": "Version Control",
+        "description": "Git operations, pull requests, issues, code review",
+        "keywords": ["PR", "pull request", "issue", "commit", "branch", "merge", "review", "git"],
+        "tools": [
+          "MetaMCP_github-zengaming__get_pull_request",
+          "MetaMCP_github-zengaming__list_issues",
+          "MetaMCP_github-zengaming__list_commits"
+        ]
+      },
+      "documentation": {
+        "name": "Documentation",
+        "description": "Library documentation lookup and API references",
+        "keywords": ["docs", "documentation", "library", "API", "reference", "example", "usage"],
+        "tools": [
+          "MetaMCP_context7__resolve-library-id",
+          "MetaMCP_context7__query-docs"
+        ]
+      },
+      "communication": {
+        "name": "Communication",
+        "description": "Messaging and notifications across platforms",
+        "keywords": ["message", "send", "post", "channel", "notify", "chat", "slack"],
+        "tools": [
+          "slack_post_message",
+          "slack_list_channels"
+        ]
+      }
+    },
+    "tools": {
+      "MetaMCP_chrome-devtools__take_screenshot": {
+        "category": "browser-automation",
+        "description": "Take a screenshot of the page or element"
+      },
+      "MetaMCP_chrome-devtools__click": {
+        "category": "browser-automation",
+        "description": "Click on the provided element"
+      },
+      "MetaMCP_github-zengaming__get_pull_request": {
+        "category": "version-control",
+        "description": "Get details of a specific pull request"
+      },
+      "MetaMCP_context7__query-docs": {
+        "category": "documentation",
+        "description": "Query library documentation"
+      },
+      "slack_post_message": {
+        "category": "communication",
+        "description": "Post a message to a Slack channel"
+      }
+    }
+  }
+}

package/templates/skill/assets/workflow-schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Agent Skill Workflow Definition",
+  "description": "Schema for defining prerequisite workflows in Agent Skill Manager",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "default": true,
+      "description": "Whether this workflow is active"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of the workflow"
+    },
+    "triggers": {
+      "type": "object",
+      "description": "Conditions that activate this workflow (OR logic - any match triggers)",
+      "properties": {
+        "category": {
+          "type": "string",
+          "description": "Tool category that triggers this workflow"
+        },
+        "tools": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Specific tool names that trigger this workflow"
+        },
+        "keywords": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Keywords in task text that trigger this workflow"
+        }
+      }
+    },
+    "prerequisites": {
+      "type": "array",
+      "description": "Steps to execute before the main action",
+      "items": {
+        "type": "object",
+        "required": ["step", "tool", "description"],
+        "properties": {
+          "step": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Execution order (1-based)"
+          },
+          "tool": {
+            "type": "string",
+            "description": "Tool name to execute"
+          },
+          "description": {
+            "type": "string",
+            "description": "Why this prerequisite is needed"
+          },
+          "required": {
+            "type": "boolean",
+            "default": true,
+            "description": "Whether this step can be skipped"
+          },
+          "params": {
+            "type": "object",
+            "description": "Default parameters for this tool"
+          }
+        }
+      }
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["enforce", "warn", "suggest"],
+      "default": "enforce",
+      "description": "How strictly to apply prerequisites: enforce (auto-run), warn (ask), suggest (mention only)"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When this workflow was created"
+    }
+  },
+  "required": ["description", "triggers", "prerequisites"]
+}

package/templates/skill/assets/workflow-templates.json

@@ -0,0 +1,112 @@
+{
+  "templates": {
+    "database": {
+      "name": "database-safe-query",
+      "description": "Inspect database structure before executing queries",
+      "triggers": {
+        "category": "database",
+        "tools": ["execute_query", "select_query"],
+        "keywords": ["query", "select", "insert", "update", "delete", "sql"]
+      },
+      "prerequisites": [
+        {
+          "step": 1,
+          "tool": "list_databases",
+          "description": "List available databases to know what's accessible",
+          "required": true
+        },
+        {
+          "step": 2,
+          "tool": "list_tables",
+          "description": "List tables in the target database",
+          "required": true
+        },
+        {
+          "step": 3,
+          "tool": "inspect_table",
+          "description": "Check column names, types, and constraints",
+          "required": true
+        },
+        {
+          "step": 4,
+          "tool": "get_indexes",
+          "description": "Check indexes for query optimization",
+          "required": false
+        }
+      ],
+      "mode": "enforce"
+    },
+    "browser": {
+      "name": "browser-safe-interaction",
+      "description": "Take snapshot before interacting with page elements",
+      "triggers": {
+        "category": "browser",
+        "tools": ["click", "fill", "fill_form", "submit"],
+        "keywords": ["click", "fill", "submit", "form", "button"]
+      },
+      "prerequisites": [
+        {
+          "step": 1,
+          "tool": "take_snapshot",
+          "description": "Capture current page state and element UIDs",
+          "required": true
+        }
+      ],
+      "mode": "enforce"
+    },
+    "github-pr": {
+      "name": "github-pr-review",
+      "description": "Gather PR context before reviewing or merging",
+      "triggers": {
+        "category": "github",
+        "tools": ["merge_pull_request", "create_pull_request_review"],
+        "keywords": ["merge", "review pr", "approve pr"]
+      },
+      "prerequisites": [
+        {
+          "step": 1,
+          "tool": "get_pull_request",
+          "description": "Get PR details and description",
+          "required": true
+        },
+        {
+          "step": 2,
+          "tool": "get_pull_request_files",
+          "description": "List changed files",
+          "required": true
+        },
+        {
+          "step": 3,
+          "tool": "get_pull_request_status",
+          "description": "Check CI/CD status and reviews",
+          "required": true
+        }
+      ],
+      "mode": "warn"
+    },
+    "graphql": {
+      "name": "graphql-schema-aware",
+      "description": "Understand schema before executing queries",
+      "triggers": {
+        "category": "graphql",
+        "tools": ["execute_query", "execute_mutation"],
+        "keywords": ["graphql query", "graphql mutation"]
+      },
+      "prerequisites": [
+        {
+          "step": 1,
+          "tool": "get_schema",
+          "description": "Fetch GraphQL schema",
+          "required": true
+        },
+        {
+          "step": 2,
+          "tool": "filter_types",
+          "description": "Identify relevant types",
+          "required": false
+        }
+      ],
+      "mode": "suggest"
+    }
+  }
+}

package/templates/skill/references/error-handling.md

@@ -0,0 +1,260 @@
+# Agent Skill Error Handling Reference
+# Scope: recovery flows, templates, and decisioning.
+# Do not include routing logic, cache schema, or result summarization here.
+
+## Error Classes
+1. Tool not found
+2. Execution failure
+3. Timeout
+4. Cache missing or invalid
+5. Partial success
+6. Invalid parameters
+
+## Automatic Retry Mechanism
+
+The agent-skill-manager automatically retries failed tool executions before returning errors.
+
+### Retry Configuration
+- Maximum attempts: 3
+- Backoff delays: 0s (immediate), 1s, 2s
+- Applies to: All tool executions (single, batch, chain, passthrough)
+
+### Retry Behavior
+1. First attempt fails → Immediate retry (0s delay)
+2. Second attempt fails → Wait 1s, then retry
+3. Third attempt fails → Return failure report
+
+### Failure Report Format
+When all retry attempts fail, return structured report:
+```json
+{
+  "tool": "tool_name",
+  "attempts": 3,
+  "errors": [
+    "Attempt 1: connection timeout",
+    "Attempt 2: connection timeout",
+    "Attempt 3: service unavailable"
+  ],
+  "suggestion": "Check network connectivity or try again later"
+}
+```
+
+### Retry Scope in Batch/Chain
+- **Batch mode**: Each tool has independent retry budget
+- **Chain mode**: Failed tool retries before aborting chain
+- Partial results preserved when possible
+
+### Non-Retryable Errors
+Some errors should NOT trigger retry:
+- Invalid parameters (user error)
+- Tool not found (cache issue)
+- Permission denied (auth issue)
+
+For these, return error immediately with actionable suggestion.
+
+## Tool Not Found Recovery
+Symptoms:
+- Tool id does not exist in registry or cache.
+- Prefix is unknown or misspelled.
+
+Recovery steps:
+1. Suggest likely tool names based on prefix and category.
+2. Provide a short list (3-5 options) from the matched category.
+3. If prefix unknown, suggest known prefixes.
+4. Offer to run discovery or refresh cache.
+
+Template:
+```
+Error: Tool not found: <tool-id>
+Suggestions: <tool-a>, <tool-b>, <tool-c>
+Next: confirm the intended tool or run /agent-skill-refresh.
+```
+
+## Execution Failure Handling
+Symptoms:
+- Tool exists but returns error.
+- Element not found, API error, invalid resource.
+
+Recovery steps:
+1. Report the error message verbatim.
+2. Include context (tool name, key params).
+3. Propose next actions (snapshot, retry, refine filters).
+4. Avoid re-running without user confirmation.
+
+Template:
+```
+Error: <message>
+Tool: <tool-id>
+Params: <key params>
+Suggestions:
+1) <action>
+2) <action>
+Next: confirm retry or provide new parameters.
+```
+
+## Timeout Handling
+Symptoms:
+- Tool exceeds configured timeout.
+- Partial output may be returned.
+
+Recovery steps:
+1. Report timeout duration.
+2. If partial results exist, summarize them.
+3. Suggest narrower scope or smaller payload.
+4. Offer retry with adjusted parameters.
+
+Template:
+```
+Timeout: <tool-id> after <ms>ms
+Partial: <summary or none>
+Suggestions: narrow scope, reduce output, retry
+Next: confirm retry with new parameters
+```
+
+## Cache Missing Recovery
+Symptoms:
+- `.opencode/agent-skill-tools.json` missing.
+- Cache file invalid or unreadable.
+
+Recovery steps:
+1. Inform that cache is missing or invalid.
+2. Recommend /agent-skill-refresh to regenerate.
+3. Proceed with dynamic tool discovery if possible.
+
+Template:
+```
+Cache missing or invalid at .opencode/agent-skill-tools.json
+Suggestion: run /agent-skill-refresh
+Fallback: dynamic discovery enabled
+```
+
+## Invalid Parameters
+Symptoms:
+- Required parameters missing.
+- Parameter type mismatch.
+
+Recovery steps:
+1. State which parameters are missing or invalid.
+2. Show expected parameter names and types.
+3. Ask for clarification or corrected values.
+
+Template:
+```
+Error: invalid parameters for <tool-id>
+Missing: <param-a>, <param-b>
+Expected: <param-a: string>, <param-b: number>
+Next: provide missing values
+```
+
+## Partial Success Handling
+Symptoms:
+- Tool completes with warnings.
+- Mixed success in batch operations.
+
+Recovery steps:
+1. Report success items and failures separately.
+2. Provide counts and identifiers.
+3. Suggest retry for failed subset only.
+
+Template:
+```
+Partial success: 3 succeeded, 2 failed
+Succeeded: [id1, id2, id3]
+Failed: [id4, id5]
+Next: retry failed items with adjusted params
+```
+
+## Fallback Procedures
+Fallback hierarchy:
+1. Cached tool lookup (fast)
+2. Dynamic tool registry lookup
+3. Ask for clarification or alternative approach
+
+For browser tools:
+- If element not found, use take_snapshot to refresh uids.
+- If click fails repeatedly, try scroll or hover before clicking.
+
+For GitHub tools:
+- If repository not found, verify owner/repo spelling.
+- If rate-limited, reduce query frequency and request retry later.
+
+For GraphQL tools:
+- If schema fetch fails, verify endpoint and auth.
+- If type not found, re-check filter_types output.
+
+For Docs tools:
+- If library resolution fails, request full package name.
+- If query returns no matches, broaden query terms.
+
+## Error Response Templates
+Generic error:
+```
+Status: failure
+Error: <message>
+Tool: <tool-id>
+Context: <key params>
+Next: <suggested action>
+```
+
+Browser error:
+```
+Status: failure
+Error: element not found
+Tool: MetaMCP_chrome-devtools__click
+Params: uid=<uid>
+Next: run take_snapshot to refresh uids
+```
+
+GitHub error:
+```
+Status: failure
+Error: 404 repository not found
+Tool: MetaMCP_github-zengaming__get_pull_request
+Params: owner=<owner>, repo=<repo>, pull_number=<n>
+Next: confirm repository name or access rights
+```
+
+GraphQL error:
+```
+Status: failure
+Error: field not found
+Tool: MetaMCP_graphql-tools__get_field_details
+Params: field_name=<field>
+Next: list available fields with filter_queries
+```
+
+Docs error:
+```
+Status: failure
+Error: library not resolved
+Tool: MetaMCP_context7__resolve-library-id
+Params: libraryName=<name>
+Next: provide full package name or repo
+```
+
+## Recovery Decision Tree
+Decision tree (text form):
+1. Is tool id invalid?
+   - Yes -> suggest alternatives and refresh cache.
+   - No -> continue.
+2. Did execution timeout?
+   - Yes -> summarize partial output and retry with narrower scope.
+   - No -> continue.
+3. Did execution return a known error?
+   - Yes -> apply category-specific recovery.
+   - No -> continue.
+4. Are params missing/invalid?
+   - Yes -> request corrected params.
+   - No -> continue.
+5. Is cache missing?
+   - Yes -> recommend /agent-skill-refresh and use dynamic discovery.
+   - No -> continue.
+6. Unknown failure
+   - Provide generic error template and ask for clarification.
+
+## Recovery Checklist
+- [ ] Identify error class
+- [ ] Provide concise error summary
+- [ ] Include tool id and key params
+- [ ] Suggest concrete next steps
+- [ ] Avoid automatic retries without confirmation