@rui.branco/claude-commands-mcp

MCP server that serves Claude Code skill definitions from a private git repository. Each skill is registered as its own MCP tool with trigger keywords — Claude automatically discovers and calls them.

Setup

Install globally:

npm install -g @rui.branco/claude-commands-mcp

Add to Claude Code:

claude mcp add --transport stdio claude-commands -e COMMANDS_REPO=https://github.com/your-user/your-private-repo.git -- claude-commands-mcp

COMMANDS_REPO (required) — URL of the git repo containing your skills and config. Private repos work as long as git credentials are configured locally.

Restart Claude Code to activate.

How it works

On startup the server clones COMMANDS_REPO to ~/.cache/claude-commands-mcp/ (subsequent starts pull in the background without blocking). It reads commands.yaml and registers each skill as a dedicated MCP tool with trigger keywords in the description. Claude discovers these tools automatically via ToolSearch.

Skill tools

Each skill defined in commands.yaml becomes its own MCP tool. For example, a skill named my-skill becomes mcp__claude-commands__my_skill. When the user's message matches the trigger keywords, Claude calls the tool and receives the full instructions.

Utility tools

get_skill(name)

Manual skill lookup by name. Use this to access any .md file in the commands/ directory, including data files not registered as tools.

save_file(path, content, message?)

Saves or updates a file in the commands/ directory, commits, and pushes to git.

save_file("reports/2026-02-07.md", "# Daily Report\n\n- Deployed v2.1...", "update: daily report")

list_skills()

Lists all available skills discovered in the commands/ directory.

refresh()

Pulls latest changes from the git repository.

Repository structure

Your private git repo should contain:

commands.yaml          # Routing rules — each skill becomes an MCP tool
commands/
└── *.md               # Skill definitions (nested folders supported)

commands.yaml format

skills:
  - skill: my-skill
    category: General
    when: |
      User says: "do something", "run my skill", etc.

  - skill: folder/nested
    category: General
    when: |
      User says: "nested thing", etc.

general_rules:
  - Some general instruction for the AI.

Each entry in skills registers an MCP tool. The when field becomes the tool description so Claude knows when to call it.

Skill files

Each .md file in commands/ is a skill. Only skills listed in commands.yaml get their own tool. Other .md files are accessible via get_skill().

• commands/my-skill.md + yaml entry → tool mcp__claude-commands__my_skill
• commands/folder/nested.md + yaml entry → tool mcp__claude-commands__folder_nested

Persisting data with save_file

Skills can produce data that needs to persist across sessions. The save_file tool writes files to the commands/ directory, commits, and pushes — so everything stays in git.

Typical use cases:

• Tracking files — a skill that logs activity can append entries over time
• Generated configs — a skill that produces configuration can save it for future reference
• Accumulated data — any skill that builds up state across sessions

Updating

npm update -g @rui.branco/claude-commands-mcp

Restart Claude Code to pick up the new version.