npm package: @rui.branco/claude-commands-mcp
Description: MCP server that serves Claude Code skill definitions from a git repo
Author: Rui Branco
Latest version: 2.0.45

# @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:

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

Add to Claude Code:

```bash
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

```yaml
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

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

Restart Claude Code to pick up the new version.