oss-skills

Agent skills that make your coding agent maintain open source like a senior maintainer.

Install · The skills · How it works · Contributing

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Español · Français · Deutsch · Português

---

Your agent can write code. It is much weaker at the other 80% of open source: choosing a license, designing an API you cannot take back, cutting a release without breaking everyone, reviewing a stranger's first PR so they come back, saying no to a feature request without losing the person.

oss-skills is 18 skills that load on demand and give an agent that judgment.

You:   I want to open source this internal tool.

Agent: [loads open-source-playbook → repo-bootstrap → license-and-legal]

       Read the repo first. Three things before anything else:

       1. There's an AWS key in commit 8f3a91c (src/config.py, deleted in 4b2e).
          It's still in history — rotate it. Rewriting history is cleanup,
          not remediation.
       2. No LICENSE. Right now nobody may legally use this. Apache-2.0 fits:
          you have corporate contributors, so the patent grant matters.
       3. README is one line. That's the whole product page for 95% of visitors.

       Want me to start with the secret, or the license?

The skills encode what experienced maintainers actually do — including the parts that are social rather than technical, and the parts that are unglamorous enough that most guides skip them.

Install

Claude Code — as a plugin:

/plugin marketplace add the-open-agent/oss-skills

/plugin install oss-skills@the-open-agent

Any agent that reads SKILL.md directories — clone into your skills path:

git clone https://github.com/the-open-agent/oss-skills ~/.claude/skills/oss-skills

A single skill, vendored into your own repo:

curl -sL https://raw.githubusercontent.com/the-open-agent/oss-skills/main/skills/release-engineering/SKILL.md \
  -o .claude/skills/release-engineering/SKILL.md

Verify the install by asking your agent something a skill should catch:

"Is bumping our minimum Node version a minor or a major release?"

If it answers major, and explains that users who upgrade within a range would break, the skills are loading.

The skills

Start with open-source-playbook — it diagnoses what stage your project is in and routes to the rest. The others load on demand when their trigger conditions match.

Foundation

Skill	Use it when
open-source-playbook	You have an open-source goal but not a specific task. Diagnoses and routes.
repo-bootstrap	Starting a repo, or publishing internal code. Includes the pre-publication secret scrub.
license-and-legal	Choosing a license, DCO vs CLA, vendoring, relicensing, "can I use this?"

Craft

Skill	Use it when
api-design	Designing a public interface you cannot take back. Deprecation, stability guarantees, CLI ergonomics.
testing-strategy	The suite is slow, flaky, or missing. Also: making tests runnable by strangers in one command.
code-review	Reviewing a PR — including the 3,000-line unsolicited one, and how to close a PR kindly.
refactor-safely	Restructuring code other people depend on. Strangler fig, codemods, and when not to rewrite.
performance-benchmarking	Making a speed claim you can defend, or reviewing someone else's.

Automation

Skill	Use it when
ci-pipelines	CI is slow, flaky, or fails on fork PRs. Matrix sizing, caching, pull_request_target safety.
release-engineering	Versioning, changelogs, publishing with provenance, and yanking a bad release.
supply-chain-security	SECURITY.md, handling a vulnerability report, pinning actions, signing, maintainer handoff.
dependency-hygiene	Dependency bloat, upgrade churn, 50 open Dependabot PRs nobody reads.

Community

Skill	Use it when
readme-that-converts	Nobody understands what your project does within 30 seconds.
docs-architecture	Docs have sprawled. Diátaxis, versioning, testing your examples.
issue-triage	The backlog is unmanageable. Labels, forms, and closing messages that don't burn people.
contributor-experience	Stars but no contributors. Diagnosing which step of the funnel leaks.
launch-and-growth	Announcing a project. Show HN etiquette, and what actually converts a visitor.

Sustainability

Skill	Use it when
governance-and-sustainability	Decision-making, burnout, funding, forks, and how to step away responsibly.

How it works

Each skill is a directory with a SKILL.md:

skills/release-engineering/
├── SKILL.md                        # frontmatter (name, description) + the content
└── assets/release-checklist.md     # templates the skill points the agent at

The description is the only part always in context. When your request matches its trigger conditions, the agent loads the full body — so eighteen skills cost you almost nothing until one is relevant. This is progressive disclosure, and it is why a skill collection can be deep without drowning the model.

Three rules every skill follows:

• Decision tables, not principles. "Raising the minimum Node version is a major" is usable. "Follow semver carefully" is not.
• Anti-patterns are stated explicitly. Knowing that pull_request_target plus a checkout of the PR head is a full repository compromise is worth more than a paragraph on CI best practices.
• The social half is included. How to say no, how to close a PR without losing the contributor, what to do when you are burned out. Most engineering guides omit this, and it is where most projects actually fail.

Contributing

Contributions are very welcome — a correction from someone who has maintained a real project is worth more than a new skill. See CONTRIBUTING.md.

Especially wanted:

• Corrections from experience. If a skill says something that fails in practice, say so. Open an issue with what happened.
• Translations. See i18n/ and the guide in docs/translations.md.
• New skills. Open an issue first — see docs/authoring-skills.md for the quality bar and the format.

python scripts/validate_skills.py --strict

Scope

In scope: the practices of building and maintaining open-source software — the repo, the code, the automation, the community, and the maintainer.

Out of scope: general programming skills, language-specific tutorials, and anything that only applies to closed-source work. This project is deliberately narrow.

License

Apache-2.0 — see LICENSE.