Skills Directory

A Go MCP server that exposes a skills directory as MCP tools, making skills available to any MCP-compatible model.

Quick start

# Build
go build -o skills-mcp-server .

# Run against a skills directory
./skills-mcp-server --skills-dir /path/to/skills --watch

Tools exposed

Tool	Description
list_skills	Lists all skills with name, description, and resource count
get_skill	Loads the full SKILL.md body for a named skill
get_skill_resource	Loads a bundled resource file from a skill (docs, scripts, etc.)

Skill format

A skill is a directory containing a SKILL.md file with optional YAML frontmatter:

my-skill/
├── SKILL.md           # Required — instructions with optional frontmatter
├── reference.md       # Optional — loaded via get_skill_resource
├── script.sh          # Optional
└── templates/
    └── template.txt   # Optional — nested directories supported

The SKILL.md file:

---
name: my-skill
description: Brief description shown in list_skills output
---
# Instructions

The body content is returned by get_skill.

• name defaults to the parent directory name if omitted from frontmatter
• description is optional
• All non-SKILL.md files in the directory are indexed as resources

.skill bundles

Skills can be distributed as .skill files — zip archives placed in the skills directory. On startup (and on hot-reload), the server extracts each bundle to a temporary directory and indexes its contents alongside regular skill directories.

• Regular directory skills take priority over bundle skills on name conflicts
• Zip entries with path traversal (..) are rejected
• Individual files are capped at 64 MB during extraction
• Temporary extraction directories are cleaned up on shutdown

Flags

--skills-dir  Path to skills directory (default: ./skills)
--transport   stdio or http (default: stdio)
--port        HTTP port, only used with --transport http (default: 3333)
--watch       Hot-reload skills on file changes
--log-file    Write logs here instead of stderr

Claude Desktop config

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "skills": {
      "command": "/path/to/skills-mcp-server",
      "args": ["--skills-dir", "/path/to/skills", "--watch"]
    }
  }
}

Notes

• Only stdio transport is implemented; HTTP transport is not yet available
• In stdio mode, logs go to stderr (never stdout, which carries the JSON-RPC stream)
• Skill name matching is fuzzy: exact → case-insensitive → prefix → substring
• Path traversal in resource names is rejected

Suggested prompt

Begin each new conversation with something like the following:

You have access to a skills server via three tools:

- list_skills — discover available skills and their descriptions
- get_skill(name) — load the full instructions for a skill
- get_skill_resource(skill, resource) — load a supplementary file a skill references

## When to use skills

At the start of any non-trivial task, call list_skills to see what's available.
If a skill matches the task, call get_skill to load it, then follow its instructions
precisely. A skill may direct you to call get_skill_resource for additional reference
files — do so before proceeding.

Prefer skills over your own judgment when one is relevant. Skills encode specific
workflows, constraints, and output formats that you should not deviate from.

## Matching rules

- Skill names support partial matching — "typescript" will match "typescript-react"
- If unsure which skill applies, call list_skills first rather than guessing

## Discipline

Do not skip loading a skill just because you think you know how to do the task.
The skill may contain project-specific requirements, templates, or constraints
that are not in your training data. Always load and read it first.