# oss-skills-mcp

Guided open-source contribution skills, served as an MCP server.

The philosophy: **the agent researches, you think and code.** Each skill walks
the agent through deep research for one stage of the contribution journey —
finding issues, reading codebases, writing tests, responding to reviews — while
the decisions and the code stay with you. The result is contributions that
maintainers actually want to merge, from a human who actually learned the repo.

Works with any MCP client, including [goose](https://github.com/aaif-goose/goose).

## Skills

**Evaluation**

| Skill | What it does |
| --- | --- |
| `oss-evaluate-repo` | Assess a repo's health, governance, and trajectory before investing time |

**The contribution workflow** (roughly in order)

| Skill | What it does |
| --- | --- |
| `oss-find-issue` | Find unclaimed issues filed by maintainers, matched to your skills |
| `oss-prep-to-contribute` | Read the contribution docs and fill knowledge gaps before coding |
| `oss-setup-dev-env` | Get an unfamiliar repo building and testing locally |
| `oss-contribute` | Research an issue deeply, then implement it yourself |
| `oss-submit-pr` | Open a PR that follows the repo's guidelines |
| `oss-post-pr` | Understand review feedback and respond to it well |
| `oss-debug-ci` | Diagnose CI failures in unfamiliar pipelines |

**Contribution types**

| Skill | What it does |
| --- | --- |
| `oss-write-tests` | Add tests for untested code as a standalone contribution |
| `oss-write-docs` | Fix documentation gaps verified against the source |

**Going deeper**

| Skill | What it does |
| --- | --- |
| `oss-review-prs` | Learn a codebase and build trust by reviewing others' PRs |
| `oss-second-contribution` | Move from one-off contributor to regular |
| `oss-find-real-issues` | Find code problems that aren't in the issue tracker |
| `oss-explore-repo` | Guided tour of a repo's architecture and patterns |
| `oss-learn-stack` | Learn unfamiliar tech from how the repo actually uses it |

## Install

```bash
uvx --from git+https://github.com/chiruu12/oss-skills-mcp oss-skills-mcp
```

### goose

**CLI**

```
goose configure
```

Add a `Command-Driven Extension` with:

- **Name**: `oss-skills`
- **Command**: `uvx --from git+https://github.com/chiruu12/oss-skills-mcp oss-skills-mcp`

**Desktop**

Add a custom extension with:

- **Type**: STDIO
- **Command**: `uvx`
- **Arguments**: `--from git+https://github.com/chiruu12/oss-skills-mcp oss-skills-mcp`

## Usage

Each skill is available as an MCP prompt — invoke `oss-find-issue`,
`oss-contribute`, and so on from your client's prompt picker. Two tools are
also exposed for programmatic access:

- `list_skills()` — names and descriptions of all bundled skills
- `get_skill(name)` — full skill content

## Development

```bash
uv sync
uv run pytest
```

## License

MIT