@nano-step/skill-manager 4.0.0

package/templates/skill/references/tool-execution.md

@@ -0,0 +1,347 @@
+# Agent Skill Tool Execution Reference
+# Scope: cache usage, routing, parameter mapping, orchestration.
+# Do not include category catalogs, result summarization, or error templates here.
+
+## Cache Access and Reading
+Cache location: .opencode/agent-skill-tools.json
+Purpose: fast tool routing without reloading full MCP schemas.
+
+How to read the cache:
+1. Check if file exists at project root `.opencode/agent-skill-tools.json`.
+2. Parse JSON into a structured object.
+3. Validate minimal fields: version, refreshed_at, tool_count, categories.
+4. If missing or malformed, fall back to dynamic discovery.
+
+Cache staleness heuristic:
+- If refreshed_at is older than 24 hours, prefer refresh for long sessions.
+- For short sessions, use cache but mention staleness when routing is ambiguous.
+
+## Cache Schema (TypeScript Interface)
+```ts
+interface AgentSkillToolCache {
+  version: string;
+  refreshed_at: string; // ISO string
+  mcp_servers: string[];
+  tool_count: number;
+  categories: {
+    [name: string]: {
+      description: string;
+      keywords: string[];
+      tools: Array<{
+        id: string;          // tool id or fully qualified name
+        description: string; // short summary
+        prefix?: string;     // optional server prefix
+      }>;
+    };
+  };
+  uncategorized: Array<{
+    id: string;
+    description: string;
+  }>;
+}
+```
+
+## Routing Algorithm (4 Steps)
+Step 1: Parse intent
+- Extract verbs, objects, constraints, and explicit tool hints.
+- Normalize to lowercase tokens.
+
+Step 2: Match category
+- Match extracted tokens against category keywords.
+- Prefer explicit prefix matches (e.g., MetaMCP_chrome-devtools__).
+- If multiple categories match, choose the one with highest keyword hits.
+
+Step 3: Select tool
+- Scan matched category tools for semantic match.
+- Prefer exact tool-name hints from user text.
+- If multiple tools plausible, choose most specific or ask for clarification.
+
+Step 4: Execute
+- Load tool schema (from cache or tool registry).
+- Map parameters from intent to schema fields.
+- Execute tool and return summarized output.
+
+## Parameter Mapping Patterns
+Mapping strategy:
+- Match explicit parameter names in user text (uid, pageId, owner, repo).
+- Convert common user phrases into schema fields.
+- Use defaults only when tool schema allows optional params.
+
+Common patterns:
+- page selection
+  - "use page 2" -> { pageId: 2 }
+  - "open new tab" -> new_page { url: ... }
+- element targeting
+  - "click uid btn-1" -> click { uid: "btn-1" }
+  - "drag a to b" -> drag { from_uid: "a", to_uid: "b" }
+- navigation
+  - "go to https://x" -> navigate_page { type: "url", url: "https://x" }
+  - "reload hard" -> navigate_page { type: "reload", ignoreCache: true }
+- network/console
+  - "show last xhr" -> list_network_requests { resourceTypes: ["xhr"] }
+  - "console errors" -> list_console_messages { types: ["error"] }
+- GitHub
+  - "PR 123 in owner/repo" -> get_pull_request { owner, repo, pull_number: 123 }
+  - "issues labeled bug" -> list_issues { labels: ["bug"], state: "open" }
+- GraphQL
+  - "list mutations" -> filter_mutations { search?: "" }
+  - "type User details" -> get_type_details { type_name: "User" }
+- Docs
+  - "docs for react useState" -> resolve-library-id then query-docs
+- Reasoning
+  - "analyze step by step" -> sequentialthinking with incrementing thoughtNumber
+
+## Multi-Tool Orchestration
+Use when a task requires sequential dependencies or cross-category steps.
+
+Example 1: Browser + Console
+1. take_snapshot -> get uid for button
+2. click -> trigger action
+3. list_console_messages -> capture errors
+
+Example 2: Docs resolution chain
+1. resolve-library-id -> get libraryId
+2. query-docs -> retrieve examples
+
+Example 3: GraphQL discovery + detail
+1. filter_queries -> list query fields
+2. get_field_details -> inspect specific query
+
+Example 4: GitHub PR inspection
+1. get_pull_request -> summary
+2. get_pull_request_files -> file list
+3. get_pull_request_status -> checks
+
+## Cache vs Dynamic Discovery
+Prefer cache when:
+- Tool cache exists and is fresh.
+- Task maps to known categories.
+- The agent must be fast and token-efficient.
+
+Prefer dynamic discovery when:
+- Cache missing or malformed.
+- Tools are new or recently updated.
+- Task uses an uncategorized or unknown prefix.
+
+Hybrid approach:
+- Use cache for category match.
+- Validate against runtime tool registry when exact tool names are needed.
+
+## Execution Guardrails
+- Ensure tool parameters match required schema types.
+- Avoid passing undefined fields.
+- For optional params, include only when explicitly set or needed.
+- If user input is ambiguous, request clarification rather than guessing.
+
+## Orchestration Output Format (Internal)
+- Selected category
+- Selected tool name
+- Input parameters
+- Dependent steps (if any)
+- Execution order
+
+Example internal routing trace:
+```
+intent: ["screenshot", "login page"]
+category: browser
+tool: MetaMCP_chrome-devtools__take_screenshot
+params: { fullPage: true }
+```
+
+## When to Use the Cache
+- For repeated routing in a session.
+- For large tool inventories where scanning the registry is expensive.
+- For well-known categories and stable tool names.
+
+## When to Avoid Cache
+- During tool upgrades or when discrepancies are reported.
+- When a tool id from cache fails execution.
+- When the user references a new MCP server prefix.
+
+## Execution Prerequisites
+- Ensure selected tool exists in cache or registry.
+- Confirm required parameters are present.
+- Confirm required page context for browser tools.
+- Validate file paths for uploads or outputs when required.
+
+## Execution Patterns
+Simple single-call execution:
+1. Select tool
+2. Map params
+3. Execute
+4. Return summarized output
+
+Dependent execution:
+1. Execute prerequisite tool
+2. Extract identifiers
+3. Execute dependent tool
+4. Summarize combined result
+
+Conditional execution:
+1. Try preferred tool
+2. If mismatch, choose fallback tool
+3. Execute fallback and report reason
+
+## Parameter Mapping Examples
+Browser example:
+```
+User: "Click the submit button"
+Steps: take_snapshot -> find uid -> click { uid }
+```
+
+GitHub example:
+```
+User: "List open PRs for owner/repo"
+Tool: list_pull_requests { owner, repo, state: "open" }
+```
+
+GraphQL example:
+```
+User: "Show mutations containing auth"
+Tool: filter_mutations { search: "auth" }
+```
+
+Docs example:
+```
+User: "Docs for Next.js app router"
+Tool 1: resolve-library-id { libraryName: "next.js", query: "app router" }
+Tool 2: query-docs { libraryId, query: "app router" }
+```
+
+Reasoning example:
+```
+User: "Break down this decision"
+Tool: sequentialthinking { thought: "...", thoughtNumber: 1, totalThoughts: 4, nextThoughtNeeded: true }
+```
+
+## Parameter Validation Checklist
+- [ ] Required params present
+- [ ] Types match schema (number, string, boolean, arrays)
+- [ ] Optional params omitted unless specified
+- [ ] Enumerations validated (resourceTypes, state, sort)
+
+## Orchestration Batching Guidance
+- Chain tools only when outputs are required for the next step.
+- Avoid parallel execution when steps depend on a prior result.
+- Provide a short plan when multiple steps are needed.
+
+## Dynamic Discovery Trigger Conditions
+- Cache not available
+- Tool id in cache but missing in registry
+- User mentions an unrecognized prefix
+- Tool description seems outdated
+
+## Cache Refresh Recommendation Text
+Recommended message:
+```
+Cache appears stale or missing. Run /agent-skill-refresh to rebuild tool metadata.
+```
+
+## Execution Output Metadata (Internal)
+- timestamp
+- tool id
+- duration (if available)
+- success/failure flag
+- raw result size
+
+## Execution Guardrails (Supplement)
+ - Do not invent parameters not supported by schema.
+ - Do not auto-retry on non-idempotent actions.
+ - For write actions, confirm target path when ambiguous.
+
+## Batch Execution
+
+Execute multiple tools in a single request for efficiency.
+
+### Batch Syntax
+```
+BATCH: [
+  {"tool": "tool_name", "params": {...}},
+  {"tool": "tool_name2", "params": {...}}
+]
+```
+
+### Batch Execution Flow
+1. Parse BATCH JSON array
+2. Validate all tool names exist
+3. Execute tools sequentially (order preserved)
+4. Collect results into array
+5. Return combined results
+
+### Batch Result Format
+```json
+[
+  {"tool": "screenshot", "status": "success", "result": {...}},
+  {"tool": "get_title", "status": "success", "result": "Page Title"}
+]
+```
+
+### Batch Limits
+- Maximum 10 tools per batch
+- Each tool has independent retry budget
+- Partial failures don't abort batch
+
+## Tool Chaining
+
+Execute tools in sequence with output passing between them.
+
+### Chain Syntax
+```
+CHAIN: [
+  {"tool": "get_element", "params": {"selector": "#btn"}, "output_as": "element"},
+  {"tool": "click", "params": {"target": "$element"}}
+]
+```
+
+### Variable Binding
+- `output_as`: Store tool output in named variable
+- `$varname`: Reference stored variable in params
+- `$varname.field`: Access nested field in stored output
+
+### Chain Execution Flow
+1. Parse CHAIN JSON array
+2. Execute first tool
+3. Store output in variable (if output_as specified)
+4. Substitute $variables in next tool's params
+5. Execute next tool
+6. Repeat until chain complete or failure
+
+### Chain Failure Handling
+```json
+{
+  "completed": [{"tool": "A", "result": {...}}],
+  "failed": {"tool": "B", "error": "element not found"},
+  "skipped": ["C", "D"]
+}
+```
+
+### Chain Limits
+- Maximum 5 tools per chain
+- Chain aborts on first failure
+- Partial results preserved
+
+## Direct Passthrough
+
+Skip routing for known tool names.
+
+### Detection Pattern
+Tool name contains `__` (double underscore) → passthrough mode
+
+### Passthrough Examples
+```
+MetaMCP_chrome-devtools__take_screenshot → execute directly
+MetaMCP_github__get_pull_request {"owner": "x", "repo": "y"} → execute with params
+```
+
+### Passthrough Benefits
+- No cache lookup overhead
+- No category matching
+- Fastest execution path
+
+ ## Quick Checklist
+ - [ ] Cache loaded or fallback chosen.
+ - [ ] Intent tokens extracted.
+ - [ ] Category matched by keywords or prefix.
+ - [ ] Tool selected with minimal ambiguity.
+ - [ ] Parameters mapped to schema.
+ - [ ] Execute and return result summary.

package/templates/skill/references/workflows.md

@@ -0,0 +1,233 @@
+# Agent Skill Workflow Reference
+
+Define prerequisite steps that automatically execute before certain tool operations.
+
+## Overview
+
+Workflows enforce best practices by requiring prerequisite steps before tool execution. For example, always inspect database structure before running queries, or take a page snapshot before clicking elements.
+
+## Workflow Schema
+
+```json
+{
+  "workflow-name": {
+    "enabled": true,
+    "description": "Human-readable description",
+    "triggers": {
+      "category": "database",
+      "tools": ["execute_query", "select_query"],
+      "keywords": ["query", "select", "insert"]
+    },
+    "prerequisites": [
+      {
+        "step": 1,
+        "tool": "list_databases",
+        "description": "List available databases",
+        "required": true
+      },
+      {
+        "step": 2,
+        "tool": "list_tables",
+        "description": "List tables in database",
+        "required": true
+      }
+    ],
+    "mode": "enforce",
+    "created_at": "2026-02-04T..."
+  }
+}
+```
+
+## Trigger Types
+
+Workflows trigger when ANY condition matches (OR logic):
+
+| Trigger | Description | Example |
+|---------|-------------|---------|
+| `category` | Tool belongs to this category | `"database"` |
+| `tools` | Tool name is in this list | `["execute_query", "select_query"]` |
+| `keywords` | Task text contains these words | `["query", "select"]` |
+
+## Execution Modes
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `enforce` | Auto-run prerequisites before main action | Critical safety (database, destructive ops) |
+| `warn` | Show warning, allow skip | Important but skippable |
+| `suggest` | Mention prerequisites, don't block | Nice-to-have patterns |
+
+## Prerequisite Definition
+
+Each prerequisite step has:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `step` | Yes | Execution order (1-based) |
+| `tool` | Yes | Tool name to execute |
+| `description` | Yes | Why this step is needed |
+| `required` | No | Can this step be skipped? (default: true) |
+| `params` | No | Default parameters for the tool |
+
+## Session State
+
+Completed prerequisites are tracked in `.opencode/.agent-skill-session.json`:
+
+```json
+{
+  "session_id": "abc123",
+  "started_at": "2026-02-04T10:00:00Z",
+  "completed": {
+    "database-safe-query": {
+      "list_databases": {
+        "at": "2026-02-04T10:05:00Z",
+        "result": "Found 3 databases: main, analytics, test"
+      },
+      "list_tables": {
+        "at": "2026-02-04T10:05:30Z",
+        "result": "Found 12 tables in main"
+      }
+    }
+  }
+}
+```
+
+### Session Rules
+
+- Prerequisites only run once per session per workflow
+- Session expires after 24 hours (configurable)
+- New session clears all completion state
+- Result summaries are truncated to 200 chars
+
+## Built-in Templates
+
+### Database Template
+
+```json
+{
+  "name": "database-safe-query",
+  "triggers": {
+    "category": "database",
+    "keywords": ["query", "select", "insert", "update", "delete"]
+  },
+  "prerequisites": [
+    {"step": 1, "tool": "list_databases", "description": "Know available databases"},
+    {"step": 2, "tool": "list_tables", "description": "Know table structure"},
+    {"step": 3, "tool": "inspect_table", "description": "Check columns and types"},
+    {"step": 4, "tool": "get_indexes", "description": "Check indexes", "required": false}
+  ],
+  "mode": "enforce"
+}
+```
+
+### Browser Template
+
+```json
+{
+  "name": "browser-safe-interaction",
+  "triggers": {
+    "category": "browser",
+    "tools": ["click", "fill", "submit"]
+  },
+  "prerequisites": [
+    {"step": 1, "tool": "take_snapshot", "description": "Capture page state and UIDs"}
+  ],
+  "mode": "enforce"
+}
+```
+
+### GitHub PR Template
+
+```json
+{
+  "name": "github-pr-review",
+  "triggers": {
+    "tools": ["merge_pull_request", "create_pull_request_review"]
+  },
+  "prerequisites": [
+    {"step": 1, "tool": "get_pull_request", "description": "Get PR details"},
+    {"step": 2, "tool": "get_pull_request_files", "description": "List changed files"},
+    {"step": 3, "tool": "get_pull_request_status", "description": "Check CI status"}
+  ],
+  "mode": "warn"
+}
+```
+
+## Workflow Execution Flow
+
+```
+Task: "Query all users with status active"
+│
+├─ 1. Check for workflow triggers
+│     └─ Match: "database-safe-query" (keyword: "query")
+│
+├─ 2. Check session state
+│     └─ Prerequisites not completed
+│
+├─ 3. Mode is "enforce" → Run prerequisites
+│     ├─ Step 1: list_databases → "3 databases found"
+│     ├─ Step 2: list_tables → "users, orders, products"
+│     └─ Step 3: inspect_table → "id, name, email, status"
+│
+├─ 4. Update session state
+│
+└─ 5. Execute main action
+      └─ SELECT * FROM users WHERE status = 'active'
+```
+
+## Error Handling
+
+### Prerequisite Failure
+
+If a prerequisite fails:
+1. Retry mechanism applies (3 attempts)
+2. If all retries fail, workflow aborts
+3. Error report includes which step failed
+
+```
+Workflow 'database-safe-query' failed at step 2 (list_tables):
+  Error: Connection refused
+  Suggestion: Check database connection settings
+```
+
+### Multiple Workflow Matches
+
+If multiple workflows match:
+1. First defined workflow is used
+2. Warning logged about conflict
+
+```
+Multiple workflows matched. Using 'database-safe-query'.
+Also matched: 'custom-db-workflow'
+```
+
+## Managing Workflows
+
+Use `/agent-skill-workflow` command:
+
+```bash
+# List all workflows
+/agent-skill-workflow list
+
+# Add from template
+/agent-skill-workflow add --template database
+
+# Add custom workflow
+/agent-skill-workflow add my-workflow
+
+# Edit existing
+/agent-skill-workflow edit my-workflow
+
+# Disable temporarily
+/agent-skill-workflow disable my-workflow
+
+# Remove
+/agent-skill-workflow remove my-workflow
+```
+
+## Best Practices
+
+1. **Start with templates** - Use built-in templates, customize as needed
+2. **Use enforce sparingly** - Only for critical safety workflows
+3. **Keep prerequisites minimal** - Each step adds latency
+4. **Mark optional steps** - Use `required: false` for nice-to-have steps
+5. **Review session state** - Check `.agent-skill-session.json` if prerequisites seem stuck