diff --git a/src/skills/builtin/converting-mcps-to-skills/references/skill-templates.md b/src/skills/builtin/converting-mcps-to-skills/references/skill-templates.md index a787dc8..a7cb27c 100644 --- a/src/skills/builtin/converting-mcps-to-skills/references/skill-templates.md +++ b/src/skills/builtin/converting-mcps-to-skills/references/skill-templates.md @@ -1,6 +1,10 @@ # Skill Templates for MCP Servers -Use these templates when creating dedicated skills for MCP servers. +When to create a dedicated skill: +- **One-off use**: No skill needed - just use `converting-mcps-to-skills` scripts directly +- **Repeated use**: Create a self-contained skill with customized scripts + +Skills should be self-contained per the [Agent Skills spec](https://agentskills.io/specification). ## Naming Rules (from Agent Skills spec) @@ -11,75 +15,11 @@ The `name` field must: - Not contain consecutive hyphens (`--`) - Match the parent directory name exactly -Examples: `using-obsidian-mcp`, `mcp-filesystem`, `github-mcp` +Examples: `using-github-mcp`, `mcp-filesystem`, `slack-mcp` -## Simple Skill Template (Documentation Only) +## Skill Template -Use this when: -- The MCP server has straightforward tools -- Usage patterns are simple -- No convenience wrappers needed - -Keep SKILL.md under 500 lines. Move detailed docs to `references/`. - -```markdown ---- -name: using- -description: . Use when . -# Optional fields: -# license: MIT -# compatibility: Requires network access to -# metadata: -# author: -# version: "1.0" ---- - -# Using - - - -## Prerequisites - -- -- - -## Quick Start - -```bash -# Set up (if auth required) -export ="your-key" - -# List available tools -npx tsx ~/.letta/skills/converting-mcps-to-skills/scripts/mcp-.ts list-tools - -# Common operations -npx tsx ... call '{"action":"..."}' -``` - -## Available Tools - - - -### - - -```bash -call '{"param": "value"}' -``` - -## Environment Variables - -- `` - -``` - ---- - -## Rich Skill Template (With Convenience Scripts) - -Use this when: -- The MCP server will be used frequently -- You want simpler command-line interface -- Server has complex auth or configuration +Use this template when creating a self-contained skill for an MCP server. ### Directory Structure @@ -87,7 +27,7 @@ Use this when: using-/ ├── SKILL.md └── scripts/ - └── .ts # Convenience wrapper + └── .ts # Customized client (copied from converting-mcps-to-skills) ``` ### SKILL.md Template @@ -96,7 +36,9 @@ using-/ --- name: using- description: . Use when . -# Optional: license, compatibility, metadata (see simple template) +# Optional fields: +# license: MIT +# compatibility: Requires network access to --- # Using @@ -117,12 +59,12 @@ export _API_KEY="your-key" npx tsx /scripts/.ts list-tools # Call a tool -npx tsx /scripts/.ts '{"action":"..."}' +npx tsx /scripts/.ts call '{"arg":"value"}' ``` -## Commands +## Available Tools - + ## Environment Variables @@ -130,42 +72,46 @@ npx tsx /scripts/.ts '{"action":"..."}' - `_URL` - Override server URL (default: ) ``` -### Convenience Wrapper Template (scripts/.ts) +### Script Template (scripts/.ts) + +Copy the HTTP client from `converting-mcps-to-skills/scripts/mcp-http.ts` (or `mcp-stdio.ts` for stdio servers) and customize: + +1. Set `DEFAULT_URL` to this server's URL +2. Rename the API key env var (e.g., `GITHUB_MCP_KEY` instead of generic) +3. Optionally simplify the CLI for common operations + +The copied code is self-contained - no external dependencies for HTTP transport. ```typescript #!/usr/bin/env npx tsx /** - * CLI - Convenience wrapper for MCP server - * - * Usage: - * npx tsx .ts list-tools - * npx tsx .ts '{"action":"..."}' + * CLI - Self-contained MCP client */ -// Configuration -const DEFAULT_URL = ""; +// Customize these for your server +const DEFAULT_URL = ""; const API_KEY = process.env._API_KEY; -const SERVER_URL = process.env._URL || DEFAULT_URL; -// Import the parent skill's HTTP client -// For HTTP servers, you can inline the client code or import it -// For stdio, import from the parent skill - -// ... implementation similar to obsidian-mcp.ts ... -// Key differences: -// - Bake in the server URL/command as defaults -// - Simplify the CLI interface for this specific server -// - Add server-specific convenience commands if needed +// Copy the rest of mcp-http.ts here and adjust as needed +// ... ``` ---- +## Example: Self-Contained Filesystem Skill -## Example: Simple Skill for Filesystem Server +A complete example of a self-contained skill for the MCP filesystem server: +``` +using-mcp-filesystem/ +├── SKILL.md +└── scripts/ + └── filesystem.ts # Copied and customized from mcp-stdio.ts +``` + +**SKILL.md:** ```markdown --- name: using-mcp-filesystem -description: Access local filesystem via MCP filesystem server. Use when user wants to read, write, or search files via MCP. +description: Access local filesystem via MCP. Use when user wants to read, write, or search files via MCP protocol. --- # Using MCP Filesystem Server @@ -175,18 +121,8 @@ Access local files via the official MCP filesystem server. ## Quick Start ```bash -# Start by listing available tools -npx tsx ~/.letta/skills/converting-mcps-to-skills/scripts/mcp-stdio.ts \ - "npx -y @modelcontextprotocol/server-filesystem ." list-tools - -# Read a file -npx tsx ... call read_file '{"path":"./README.md"}' - -# List directory -npx tsx ... call list_directory '{"path":"."}' - -# Search files -npx tsx ... call search_files '{"path":".","pattern":"*.ts"}' +npx tsx /scripts/filesystem.ts list-tools +npx tsx /scripts/filesystem.ts call read_file '{"path":"./README.md"}' ``` ## Available Tools @@ -198,14 +134,8 @@ npx tsx ... call search_files '{"path":".","pattern":"*.ts"}' - `get_file_info` - Get file metadata ``` ---- - -## Example: Rich Skill for Obsidian - -See `~/.letta/skills/using-obsidian-mcp-plugin/` for a complete example of a rich skill with a convenience wrapper script. - -Key features of the rich skill: -- Custom `obsidian-mcp.ts` script with defaults baked in -- Simplified CLI: just `call vault '{"action":"list"}'` -- Environment variables for auth: `OBSIDIAN_MCP_KEY` -- Comprehensive documentation of all tools +**scripts/filesystem.ts:** +Copy `converting-mcps-to-skills/scripts/mcp-stdio.ts` and set the default command to: +```typescript +const DEFAULT_COMMAND = "npx -y @modelcontextprotocol/server-filesystem ."; +```