Add skills.sh integration for AI agent discovery#64
Conversation
Adds a SKILL.md following the Agent Skills specification (agentskills.io) so qmd can be discovered and used by AI agents via skills.sh. - skills/qmd/SKILL.md: Main skill definition with search commands, options, workflows, and MCP tool documentation - skills/qmd/references/MCP-SETUP.md: Detailed MCP server setup guide - .gitignore: Allow .md files in skills/ directory Users can install via: npx skills add tobi/qmd The skill supports both CLI usage (via Bash) and MCP server integration, documenting all qmd_* tools and their CLI equivalents. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This pull request adds Agent Skills specification support to enable AI agent discovery of qmd via skills.sh. The PR creates comprehensive documentation for both CLI and MCP usage patterns.
Changes:
- Adds
skills/qmd/SKILL.mdwith Agent Skills specification format, documenting CLI commands, options, workflows, and MCP tool mappings - Adds
skills/qmd/references/MCP-SETUP.mdwith detailed MCP server configuration and tool parameter documentation - Updates
.gitignoreto allow markdown files in the skills/ directory
Reviewed changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| skills/qmd/SKILL.md | Agent Skills specification file documenting qmd commands, search modes, MCP integration, and usage workflows |
| skills/qmd/references/MCP-SETUP.md | MCP server setup guide with configuration instructions and tool parameter documentation |
| .gitignore | Adds exception pattern to allow markdown files in skills directory |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # Semantic vector search (finds conceptually similar content) | ||
| qmd vsearch "your query" | ||
|
|
||
| # Hybrid search with re-ranking (best quality) |
There was a problem hiding this comment.
Inconsistent spelling of "reranking". The codebase consistently uses "reranking" without a hyphen (see README.md:29, 69 and src/mcp.ts:360, 367), but this file uses "re-ranking" with a hyphen. For consistency with the rest of the codebase, use "reranking" instead.
| # Hybrid search with re-ranking (best quality) | |
| # Hybrid search with reranking (best quality) |
| Retrieve a document by path or docid. | ||
|
|
||
| **Parameters:** | ||
| - `path` (required): Document path or docid (e.g., `#abc123`) | ||
| - `full` (optional): Return full content (default: true) |
There was a problem hiding this comment.
The parameter documentation for qmd_get is incorrect. According to the MCP implementation (src/mcp.ts:454-458), the parameter name should be file not path, and there is no full parameter. The actual parameters are: file (required), fromLine (optional), maxLines (optional), and lineNumbers (optional). The full parameter appears to be a CLI option but is not available in the MCP tool.
| Retrieve a document by path or docid. | |
| **Parameters:** | |
| - `path` (required): Document path or docid (e.g., `#abc123`) | |
| - `full` (optional): Return full content (default: true) | |
| Retrieve a document by file path or docid. | |
| **Parameters:** | |
| - `file` (required): Document path or docid (e.g., `#abc123`) | |
| - `fromLine` (optional): Starting line number (1-based) for partial content | |
| - `maxLines` (optional): Maximum number of lines to return |
| - `limit` (optional): Number of results (default: 5) | ||
| - `minScore` (optional): Minimum relevance score | ||
|
|
||
| ### qmd_vsearch | ||
| Semantic vector search for conceptual similarity. | ||
|
|
||
| **Parameters:** | ||
| - `query` (required): Search query string | ||
| - `collection` (optional): Restrict to specific collection | ||
| - `limit` (optional): Number of results (default: 5) | ||
| - `minScore` (optional): Minimum relevance score |
There was a problem hiding this comment.
The default limit values documented here are inconsistent with the actual MCP implementation. According to src/mcp.ts lines 265, 306, and 370, the default limit for all search tools (qmd_search, qmd_vsearch, qmd_query) is 10, not 5. Update these descriptions to reflect the correct default of 10 results.
| - `query` (required): Search query string | ||
| - `collection` (optional): Restrict to specific collection | ||
| - `limit` (optional): Number of results (default: 5) | ||
| - `minScore` (optional): Minimum relevance score |
There was a problem hiding this comment.
The minScore parameter documentation is incomplete for qmd_vsearch. According to src/mcp.ts:307, qmd_vsearch has a default minScore of 0.3 (not 0), which should be documented. This is an important difference from qmd_search which defaults to 0.
|
|
||
| **Parameters:** | ||
| - `pattern` (required): Glob pattern or comma-separated list | ||
| - `maxBytes` (optional): Skip files larger than this (default: 10KB) |
There was a problem hiding this comment.
The qmd_multi_get parameter documentation is incomplete. According to src/mcp.ts:519-521, qmd_multi_get also supports maxLines (optional) and lineNumbers (optional) parameters in addition to pattern and maxBytes. These should be documented.
| - `maxBytes` (optional): Skip files larger than this (default: 10KB) | |
| - `maxBytes` (optional): Skip files larger than this (default: 10KB) | |
| - `maxLines` (optional): Maximum number of lines to return per file | |
| - `lineNumbers` (optional): Include line numbers in returned content |
Summary
skills/qmd/SKILL.mdwith search commands, options, workflows, and MCP tool documentationskills/qmd/references/MCP-SETUP.mdwith detailed MCP server setup guide.gitignoreto allow .md files in skills/ directoryUsage
Once merged, users can install via:
The skill supports both:
qmdcommandsqmd_*tools and their CLI equivalentsTest plan
npx skills add🤖 Generated with Claude Code