{
  "markdown": "<!-- mcp-name: io.github.jcc-ne/mcp-skill-server -->\n\nMost coding assistants now support skills natively, so an MCP server just for skill discovery isn't necessary. Where this package adds value is making skills' execution **deterministic and deployable** — with a fixed entry point and controlled execution, skills developed in your editor can run in non-sandboxed production environments. It also supports incremental loading, so agents discover skills on demand instead of loading everything upfront.\n\n---\n# MCP Skill Server\n\n[![CI](https://github.com/jcc-ne/mcp-skill-server/actions/workflows/ci.yml/badge.svg)](https://github.com/jcc-ne/mcp-skill-server/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/mcp-skill-server)](https://pypi.org/project/mcp-skill-server/)\n[![Python](https://img.shields.io/pypi/pyversions/mcp-skill-server)](https://pypi.org/project/mcp-skill-server/)\n[![License](https://img.shields.io/github/license/jcc-ne/mcp-skill-server)](LICENSE)\n\nBuild agent skills where you work. Write a Python script, add a `SKILL.md`, and your agent can use it immediately. Iterate in real-time as part of your daily workflow. When it's ready, deploy the same skill to production — no rewrite needed.\n\n## Why?\n\nMost skill development looks like this: write code → deploy → test in a staging agent → realize it's wrong → redeploy → repeat. It's slow, and you never get to actually *use* the skill while building it.\n\nMCP Skill Server flips this. It runs **on your machine, inside your editor** — Claude Code, Cursor, or Claude Desktop. You develop a skill and use it in your real work at the same time. That tight feedback loop (edit → save → use) means you discover what's missing naturally, not through artificial test scenarios.\nThe premise is if the skill doesn't work well with Claude Code, it's unlikely to work with a less sophisticated agent.\n\n\n### How skills mature to survive in the outside world\n\nClaude skills can already have companion scripts, but there's no formalized entry point — the agent decides how to invoke them. That works for local use, but it's not deployable: a production MCP server can't reliably call a skill if the execution path isn't fixed.\n\nMCP Skill Server enforces a declared **`entry` field** in your SKILL.md frontmatter (e.g. `entry: uv run python my_script.py`). This gives you a single, fixed entry point that the server controls. Commands and parameters are discovered from the script's `--help` output — that's the source of truth, not the LLM's interpretation of your code.\n\n```\n1. Claude/coding agent skill                → SKILL.md + scripts, but no fixed entry — agent decides how to run them\n2. Local MCP skill (+ entry)   → Fixed entry point, schema from --help, usable daily via this server\n3. Production                  → Same skill, same entry — deployed to your enterprise MCP server\n```\n\n### Sharpen locally, then harden for production\n\nEvery agent that connects to the MCP server gets the same interface — `list_skills`, `get_skill`, `run_skill` — so the skill's description, parameter names, and help text are identical regardless of which agent calls them. That said, different agents have different strengths — a skill that works locally still needs testing with your production agent.\n\n1. **Use it yourself** — build the skill, use it daily via Claude Code or Cursor. Fix descriptions and param names when the agent misuses the skill.\n2. **Test with a weaker model** — try a smaller model to surface interface ambiguity.\n3. **Add a deterministic entry point** — declare `entry` in SKILL.md for reliable, secure execution. Use `skill init` to scaffold it, `skill validate` to check readiness.\n4. **Test with your production agent** — verify end-to-end in your target environment, then deploy.\n\n## Install\n\n### Claude Desktop (one-click)\n\n[![Install with Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Install_Server-orange?logo=claude)](claudedesktop://install?config=%7B%22mcpServers%22%3A%7B%22skills%22%3A%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-skill-server%22%2C%22serve%22%2C%22.%2Fmy-skills%22%5D%7D%7D%7D)\n\nAfter installing, edit the skills path in your Claude Desktop config to point to your skills directory.\n\n### Claude Code\n\n```bash\nclaude mcp add skills -- uvx mcp-skill-server serve /path/to/my/skills\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json` in your project (or Settings → MCP → Add Server):\n\n```json\n{\n  \"mcpServers\": {\n    \"skills\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-skill-server\", \"serve\", \"/path/to/my/skills\"]\n    }\n  }\n}\n```\n\n### Manual install\n\n```bash\n# From PyPI (recommended)\nuv pip install mcp-skill-server\n\n# Or from source\ngit clone https://github.com/jcc-ne/mcp-skill-server\ncd mcp-skill-server && uv sync\n\n# Run the server\nuvx mcp-skill-server serve /path/to/my/skills\n```\n\nThen add to your editor's MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"skills\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-skill-server\", \"serve\", \"/path/to/my/skills\"]\n    }\n  }\n}\n```\n\n## Creating a Skill\n\n### Option A: Use `skill init` (recommended)\n\n```bash\n# Create a new skill\nuv run mcp-skill-server init ./my_skills/hello -n \"hello\" -d \"A friendly greeting\"\n\n# Or use the standalone command\nuv run mcp-skill-init ./my_skills/hello -n \"hello\" -d \"A friendly greeting\"\n\n# Promote an existing prompt-only Claude skill to a runnable MCP skill\nuv run mcp-skill-init ./existing_claude_skill\n```\n\n### Option B: Manual setup\n\n#### 1. Create a folder with your script\n\n```\nmy_skills/\n└── hello/\n    ├── SKILL.md\n    └── hello.py\n```\n\n#### 2. Add SKILL.md with frontmatter\n\n```yaml\n---\nname: hello\ndescription: A friendly greeting skill\nentry: uv run python hello.py\n---\n\n# Hello Skill\n\nGreets the user by name.\n```\n\n#### 3. Write your script with argparse\n\n```python\n# hello.py\nimport argparse\n\nparser = argparse.ArgumentParser(description=\"Greeting skill\")\nparser.add_argument(\"--name\", default=\"World\", help=\"Name to greet\")\nargs = parser.parse_args()\n\nprint(f\"Hello, {args.name}!\")\n```\n\nThat's it. The server auto-discovers commands and parameters from your `--help` output — no config needed.\n\n## Validating for Deployment\n\nWhen a skill is ready to graduate to production:\n\n```bash\nuv run mcp-skill-server validate ./my_skills/hello\n# or\nuv run mcp-skill-validate ./my_skills/hello\n```\n\nChecks:\n- Required frontmatter fields (name, description, entry)\n- Entry command uses allowed runtime\n- Script file exists\n- Commands discoverable via `--help`\n\n## How It Works\n\n### MCP Tools\n\nThe server exposes four tools to your agent:\n\n| Tool | Description |\n|------|-------------|\n| `list_skills` | List all available skills |\n| `get_skill` | Get details about a skill (commands, parameters) |\n| `run_skill` | Execute a skill with parameters |\n| `refresh_skills` | Reload skills after you make changes |\n\n### Schema Discovery\n\nThe server automatically discovers your skill's interface by parsing `--help` output:\n\n```python\n# Subcommands become separate commands\nsubparsers = parser.add_subparsers(dest='command')\nanalyze = subparsers.add_parser('analyze', help='Run analysis')\n\n# Arguments become parameters with inferred types\nanalyze.add_argument('--year', type=int, required=True)  # int, required\nanalyze.add_argument('--file', type=str)                  # string, optional\n```\n\n### Output Files\n\nFiles saved to `output/` are automatically detected. Alternatively, print `OUTPUT_FILE:/path/to/file` to stdout.\n\n## Plugins\n\n### Output Handlers\n\nProcess files generated by skills (upload, copy, transform, etc.):\n\n```python\nfrom mcp_skill_server.plugins import OutputHandler, LocalOutputHandler\n\n# Default: tracks local file paths\nhandler = LocalOutputHandler()\n\n# Optional GCS handler (requires `uv sync --extra gcs`)\nfrom mcp_skill_server.plugins import GCSOutputHandler\nhandler = GCSOutputHandler(\n    bucket_name=\"my-bucket\",\n    folder_prefix=\"skills/outputs/\",\n)\n```\n\n### Response Formatters\n\nCustomize how execution results are formatted in MCP tool responses:\n\n```python\nfrom mcp_skill_server.plugins import ResponseFormatter\n\nclass CustomFormatter(ResponseFormatter):\n    def format_execution_result(self, result, skill, command):\n        return f\"Result: {result.stdout}\"\n\n# Use with create_server()\nfrom mcp_skill_server import create_server\nserver = create_server(\n    \"/path/to/skills\",\n    response_formatter=CustomFormatter()\n)\n```\n\n## Development\n\n```bash\ngit clone https://github.com/jcc-ne/mcp-skill-server\ncd mcp-skill-server\nuv sync --dev\nuv run pytest\nuv run mcp-skill-server serve examples/\n```\n\n## Further Reading\n\n- [Tool Design for LLMs](docs/TOOL_DESIGN_FOR_LLMS.md) — Why skills use a list/get/run pattern instead of exposing raw tools, and how it affects LLM accuracy\n\n## License\n\nMIT\n",
  "bytes": 8742,
  "sha": "076bb0fd15bea4a6b59a06c27e82420ab9703d4c56ea337c801920bf846bf8b1",
  "repo_slug": "jcc-ne/mcp-skill-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jcc_ne_mcp_skill_server_85301ee1/readme"
}