@nano-step/skill-manager 4.0.0

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

@@ -0,0 +1,242 @@
+# Agent Skill Result Handling Reference
+# Scope: summarization rules and response patterns.
+# Do not include routing, cache, or error recovery content here.
+
+## Result Types
+1. Text or scalar results
+2. Lists or collections
+3. File operation results
+4. Data query results
+5. Screenshot or binary results
+6. Structured objects
+
+## Global Summarization Rules
+- Always state success or failure clearly.
+- Always include key identifiers (IDs, paths, URLs, uids).
+- Always include counts for list-like results.
+- Always include actionable next steps when applicable.
+- Never dump raw large payloads into the response.
+
+## Large Result Handling (>1000 chars)
+When result size exceeds 1000 characters:
+1. Provide a short summary (1-3 lines).
+2. Include counts and key identifiers.
+3. Offer a follow-up query or refined filter.
+4. If a file was generated, include file path.
+
+Example:
+```
+Result (large): 12,450 chars
+Summary: Returned 325 items across 6 pages.
+Key IDs: [101, 102, 103]
+Next: Ask for a specific page or filter by label.
+```
+
+## File Operation Result Patterns
+Pattern: read/write/create/delete/move
+
+Required fields to report:
+- Path(s)
+- Size or line count (if available)
+- Operation status
+
+Example: read
+```
+Success: file read
+Path: /tmp/output.log
+Size: 4,892 chars (120 lines)
+Next: specify line range for deeper inspection.
+```
+
+Example: write
+```
+Success: file written
+Path: /tmp/report.json
+Size: 1,204 chars
+Next: open the file to review content.
+```
+
+Example: delete
+```
+Success: file deleted
+Path: /tmp/old.png
+Next: none
+```
+
+Example: move
+```
+Success: file moved
+From: /tmp/a.txt
+To: /tmp/archive/a.txt
+Next: verify new location if needed.
+```
+
+## Data Query Result Patterns
+Pattern: lists, rows, records, JSON arrays
+
+Required fields:
+- Count
+- Key identifiers or first few items
+- Filters used
+
+Example: small list
+```
+Success: 3 items
+IDs: [11, 12, 13]
+Filter: state=open
+Next: request details for a specific ID.
+```
+
+Example: large list
+```
+Success: 250 items
+Sample: [id: 1, id: 2, id: 3]
+Filter: label=bug, sort=updated
+Next: narrow by date range or page.
+```
+
+Example: structured object
+```
+Success: retrieved PR #42
+Repo: owner/repo
+Status: open, checks=3
+Next: request file list or reviews.
+```
+
+## Screenshot Result Patterns
+Pattern: binary output + path
+
+Required fields:
+- Path or attachment name
+- Whether full page or element
+- If element: uid or selector
+
+Example: full page
+```
+Success: screenshot captured
+Path: /tmp/screen.png
+Mode: fullPage
+Next: request another region if needed.
+```
+
+Example: element
+```
+Success: element screenshot captured
+Path: /tmp/button.png
+Element: uid=btn-login
+Next: use take_snapshot to verify other uids.
+```
+
+## Console/Network Result Patterns
+Pattern: browser logs and network lists
+
+Required fields:
+- Count
+- Severity or resource type
+- Example snippet or first item id
+
+Example: console errors
+```
+Success: 2 console errors
+First: [msgid=14] "TypeError: ..."
+Next: open specific message id for details.
+```
+
+Example: network list
+```
+Success: 18 network requests
+Types: xhr=5, fetch=6, document=1
+Next: open request id for full headers/body.
+```
+
+## Performance Trace Result Patterns
+Required fields:
+- Trace file path
+- Whether autoStop occurred
+- Insight names (if provided)
+
+Example:
+```
+Success: trace recorded
+Path: trace.json.gz
+Insights: LCPBreakdown, DocumentLatency
+Next: analyze specific insight by name.
+```
+
+## Documentation Query Result Patterns
+Required fields:
+- Library ID
+- Match count or snippet count
+- Example snippet or key excerpt
+
+Example:
+```
+Success: docs retrieved
+Library: /vercel/next.js
+Matches: 4
+Snippet: "useRouter" example with push()
+Next: ask for detailed example or version-specific docs.
+```
+
+## GraphQL Result Patterns
+Required fields:
+- Count of items or types
+- Sample names
+- Endpoint used
+
+Example: filter_queries
+```
+Success: 12 queries
+Sample: [user, repo, search]
+Endpoint: http://localhost:5555/graphql
+Next: get_field_details for a specific query.
+```
+
+Example: get_type_details
+```
+Success: type User
+Fields: 9
+Sample: id, name, email
+Next: fetch field details for specific field.
+```
+
+## Reasoning Result Patterns
+Required fields:
+- Thought count
+- Final conclusion
+
+Example:
+```
+Success: reasoning completed
+Thoughts: 5
+Conclusion: pick tool A due to lower latency.
+Next: proceed with tool execution.
+```
+
+## Always Include in Responses
+- Status: success or failure
+- IDs or paths or URLs
+- Counts for list results
+- Next steps or suggestions
+
+## Example Summary Formats
+Format A (compact):
+```
+Success: 5 items (ids: 1,2,3...) | Next: request item details
+```
+
+Format B (structured):
+```
+Status: success
+Count: 5
+IDs: [1,2,3]
+Next: request details
+```
+
+Format C (file-first):
+```
+Status: success
+Path: /tmp/output.json
+Size: 2,043 chars
+Next: open file for review
+```

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

@@ -0,0 +1,247 @@
+# Agent Skill Tool Categories Reference (Semantic)
+# Scope: semantic category mapping and example tool lists
+# Do not include routing algorithm, execution, results, or errors here.
+
+## Categorization System (Semantic Only)
+
+This skill uses **semantic categorization**:
+
+1. **Tool discovery** - `/agent-skill-refresh` enumerates all tools available to the agent
+2. **Semantic analysis** - the AI reads each tool's **name + description**
+3. **Dynamic grouping** - tools are grouped into categories based on what they do
+
+Categories are **AI-generated at refresh time** and are not predefined. The same
+tool set may yield different category labels if the tool descriptions change.
+
+## How Semantic Categorization Works
+
+Semantic categorization is a meaning-based process rather than a pattern match.
+The AI looks at each tool's:
+
+- Action verbs (e.g., "click", "list", "introspect", "fetch")
+- Domain nouns (e.g., "page", "repository", "schema", "documentation")
+- Operation scope (e.g., UI interaction vs. metadata discovery)
+- Input/output shape described in the tool description
+
+The result is a set of categories that represent **intent clusters**, such as
+"Browser Automation", "GitHub Operations", or "GraphQL Introspection". These
+categories are **labels**, not fixed contracts, and can evolve with the tool set.
+
+## Categories Are Generated, Not Predefined
+
+- Categories are **not hard-coded**
+- Category names are **derived from the tools** at refresh time
+- Custom MCP servers are handled automatically
+- The system works with any MCP configuration (MetaMCP, standalone, or custom)
+
+## Cache File (v2.0.0) - How to Read It
+
+The `/agent-skill-refresh` command writes a cache file using the v2.0.0 schema. This
+file is the **source of truth** for the current categorization state.
+
+### Schema Overview
+
+```json
+{
+  "categories": {
+    "browser-automation": {
+      "name": "Browser Automation",
+      "description": "Web page interaction, screenshots, DOM manipulation",
+      "keywords": ["screenshot", "click", "navigate", "page"],
+      "tools": ["tool_id_1", "tool_id_2"]
+    }
+  },
+  "tools": {
+    "tool_id_1": {
+      "category": "browser-automation",
+      "description": "Tool description"
+    }
+  }
+}
+```
+
+### Reading Tips
+
+- **categories**: a map of generated category IDs to human-friendly metadata
+- **categories.<id>.tools**: the list of tool IDs grouped into that category
+- **tools**: a map of tool IDs to their assigned category and descriptions
+- **tools.<id>.category**: the category ID that tool currently belongs to
+
+Use the cache to understand the **current routing shape**. Do not assume the
+same category IDs will exist across different environments or refresh runs.
+
+## Example Categories That Might Be Generated
+
+These are illustrative only. Actual categories depend on the installed tools.
+
+- Browser Automation
+- GitHub Operations
+- GraphQL Introspection
+- Documentation Lookup
+
+## Browser Automation Category (Example)
+
+Category name: Browser Automation
+Keywords: screenshot, click, navigate, page, browser, dom, element, fill, hover,
+drag, upload, dialog, network, console, performance, emulation
+Description: Interact with live pages, DOM elements, and browser instrumentation.
+
+Example tools that might appear in this category:
+- take_screenshot
+  - Capture a page or element screenshot (png/jpeg/webp).
+- take_snapshot
+  - Capture a text snapshot of the a11y tree with uids.
+- click
+  - Click a page element by uid (optional double click).
+- fill
+  - Fill a single input, textarea, or select element.
+- fill_form
+  - Fill multiple form fields in one call.
+- press_key
+  - Press a key or key combination (e.g., Enter, Control+Shift+R).
+- hover
+  - Hover over a page element by uid.
+- drag
+  - Drag one element and drop onto another element.
+- upload_file
+  - Upload a local file using a file input element.
+- handle_dialog
+  - Accept or dismiss a browser dialog, with optional prompt text.
+- wait_for
+  - Wait for specific text to appear on the page.
+- navigate_page
+  - Navigate to URL, back, forward, or reload.
+- new_page
+  - Open a new page and optionally navigate to URL.
+- close_page
+  - Close an existing page by ID.
+- list_pages
+  - List all open pages with IDs.
+- select_page
+  - Select an active page for future tool calls.
+- resize_page
+  - Resize the viewport to a specific width and height.
+- emulate
+  - Emulate network, CPU, and geolocation conditions.
+- evaluate_script
+  - Run a JavaScript function in the page context.
+- list_network_requests
+  - List recent network requests for the page.
+- get_network_request
+  - Get a single network request by request id.
+- list_console_messages
+  - List recent console messages on the page.
+- get_console_message
+  - Get a single console message by message id.
+- performance_start_trace
+  - Start a performance trace recording.
+- performance_stop_trace
+  - Stop an active performance trace recording.
+- performance_analyze_insight
+  - Analyze a specific performance insight set.
+
+Notes:
+- Browser category often contains the largest tool set.
+- Tools require a page context; select or create a page first.
+- Prefer take_snapshot for element discovery before click/hover/drag.
+
+## GitHub Operations Category (Example)
+
+Category name: GitHub Operations
+Keywords: pr, pull request, issue, repo, repository, commit, branch, review,
+code search
+Description: Query and manage GitHub metadata, issues, PRs, and repository content.
+
+Example tools that might appear in this category:
+- search_repositories
+  - Search repositories by query string.
+- search_users
+  - Search GitHub users.
+- search_code
+  - Search code across repositories.
+- get_file_contents
+  - Fetch file or directory contents from a repo.
+- list_issues
+  - List issues with filters (state, labels, sort).
+- get_issue
+  - Get details for a specific issue.
+- search_issues
+  - Search issues and PRs across repositories.
+- list_commits
+  - List commits for a branch or SHA.
+- create_branch
+  - Create a new branch from a base branch.
+- get_pull_request
+  - Get details for a specific pull request.
+- list_pull_requests
+  - List pull requests with filters (state, base, head).
+- get_pull_request_files
+  - Get the files changed in a pull request.
+- get_pull_request_status
+  - Get the combined status checks for a PR.
+- get_pull_request_reviews
+  - Get reviews and review states for a PR.
+
+
+## GraphQL Introspection Category (Example)
+
+Category name: GraphQL Introspection
+Keywords: graphql, schema, query, mutation, type, field, introspection
+Description: Introspect GraphQL schemas and discover query/mutation shapes.
+
+Example tools that might appear in this category:
+- get_graphql_schema
+  - Fetch full schema introspection.
+- filter_queries
+  - Filter and list available queries.
+- filter_mutations
+  - Filter and list available mutations.
+- filter_types
+  - Filter and list types by kind.
+- get_type_details
+  - Get fields and metadata for a type.
+- get_field_details
+  - Get details for a specific query or mutation field.
+
+
+## Documentation Lookup Category (Example)
+
+Category name: Documentation Lookup
+Keywords: docs, documentation, reference, api, usage, example, how to
+Description: Resolve library identifiers and query documentation.
+
+Example tools that might appear in this category:
+- resolve_library_id
+  - Resolve a library or package name to a library ID.
+- query_docs
+  - Query documentation for a given library ID.
+
+
+## Category Boundary Examples
+Use these to avoid misclassification:
+- "take a screenshot" -> Browser Automation
+- "list pull requests" -> GitHub Operations
+- "list graphql queries" -> GraphQL Introspection
+- "find docs for lodash" -> Documentation Lookup
+
+## Common Intent Phrases by Category
+Browser intents:
+- "click", "hover", "fill form", "upload file", "take snapshot"
+GitHub intents:
+- "get PR", "list issues", "search repo", "read file"
+GraphQL intents:
+- "introspect schema", "list types", "get field details"
+Docs intents:
+- "find docs", "usage example", "API reference"
+
+## Tool Naming Conventions (Observed Patterns)
+- Tool names tend to be verb-first (get_, list_, search_, filter_, take_).
+- UI interaction tools often use imperative verbs (click, hover, drag).
+- Metadata tools tend to be resource-based (get_issue, list_commits).
+
+
+## Category Ownership Notes (Semantic Only)
+- Browser Automation: runtime web UI interaction and diagnostics.
+- GitHub Operations: repository metadata and collaboration artifacts.
+- GraphQL Introspection: schema discovery and field metadata only.
+- Documentation Lookup: documentation discovery and lookup.