Write a CONTRIBUTING guide
Writes a CONTRIBUTING.md from a repository's real setup, covering the dev environment, tests, branch and commit rules, PR checklist, review process and where newcomers can start.
A CONTRIBUTING guide is the difference between a first pull request that lands and one that is abandoned after the third round of "please rebase, sign off and run the linter". Most guides fail because they are copied from another project: they list commands that do not exist in this repo, omit the one check CI actually enforces, and never say what kind of contribution is welcome. A good guide is accurate to the repo, gets a newcomer from clone to a passing test run in minutes, and states every rule CI or the maintainers will enforce before the contributor discovers it the hard way.
Write CONTRIBUTING.md for this project.
Only if [PROJECT_POLICIES] is given:
Only if [GOOD_FIRST_AREAS] is given:
- If you can read the repo, verify the facts against it: the package manifest and lockfile, version files (.nvmrc, .tool-versions, rust-toolchain and similar), the scripts or Makefile, CI workflow files, linters and formatters configs, issue and PR templates, CODEOWNERS, and any existing README, CONTRIBUTING or AGENTS file. Where the repo and the facts disagree, trust the repo and list the difference.
- Write the guide in this order:
- Welcome: one short paragraph on what contributions are welcome (bugs, docs, features, translations) and what is not, plus a link placeholder to the code of conduct if one exists.
- Before you start: when to open an issue or discussion first (for example new features or large changes) and when a pull request alone is fine (typos, small fixes).
- Set up: prerequisites with versions, then clone, install, build and run, as copy-pasteable commands, and how to know it worked.
- Make a change: branch naming, code style and how formatting is enforced, how to run tests (all, one file, one test), how to add tests, and how to run every check CI runs locally in one command if one exists.
- Commits: the message convention with one real example, sign-off (DCO) or CLA requirements with the exact command or link, and squash or rebase expectations.
- Pull requests: a checklist (linked issue, tests, docs, changelog entry if used, checks passing, screenshots for UI changes), what reviewers look for, and expected response time stated honestly.
- Where to start: the labels for starter issues and the areas from the good first areas input, with what makes each a safe first contribution.
- Reporting bugs and security issues: what a good bug report includes, and that security problems go through the private channel in the security policy, never public issues.
- Getting help: where to ask questions.
- Keep it scannable: short sections, commands in fenced blocks, and nothing a contributor would never need. Put long reference material (architecture, release process) behind links.
- Every command, script name, version, label and branch name must come from the repo or the facts given. Never invent one; use a clearly marked placeholder such as [TODO: confirm test command] and list it under Unverified items.
- Do not add policies the project did not state (CLA, DCO, commit conventions, response times). If a common one is missing, mention it under Unverified items as a suggestion.
- Write in a welcoming, direct tone; no "simply" or "just" before steps that may not be simple.
- Read the relevant code before making a claim about it. Do not guess what a file, function or config contains.
- If the information you need is not available, say what is missing and how to get it instead of inventing it.
CONTRIBUTING.md
The complete file in one fenced markdown block, ready to commit.
Unverified items
Bullets: placeholders you left, facts you could not confirm in the repo, differences between the facts given and the repo, and suggested policies the maintainers may want to add. "None" if everything was verified.
1 required value still a placeholder; the assistant will ask for it.
details
- kind
- Prompt: a task you run by name to get one finished thing back
- domain
- Software engineering
- category
- Documentation
- level
- Intermediate
- made for
- Open-source maintainer, Developer advocate, Tech lead / staff engineer, Technical writer
- needs
- repo-read
- risk
- read-only
- version
- v1.0.0 · incubating
- reviewed
- 2026-10-02
- works in
- Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md
use in
npx @hermes-hq/hodios install write-contributing-guide --target claude-codenpx skills add hermes-hq/hodios-dist --skill write-contributing-guide -a claude-codeclaude plugin marketplace add hermes-hq/hodios-distclaude plugin install hodios-software-engineering@hodiosThe plugin brings every entry in this domain at once.
pairs well with
All of DocumentationTechnical writer
Writes and edits developer documentation that is accurate to the code, task-oriented and easy to scan. Use as the voice for READMEs, API references, guides and changelogs.
technical-writerWrite a README
Writes or improves a project README from what the code actually does, with an install and quick start that work when copied. Use for a new project or a README that has drifted.
write-readmeWrite a developer onboarding guide
Writes an onboarding guide for a repository covering setup, an architecture map, first tasks and known gotchas, with every command checked against the repo. Use for new hires or contributors.
write-onboarding-guideWrite code review guidelines
Writes a team's code review guidelines covering what blocks a merge, comment labels, size limits, response times, author and reviewer duties and how to disagree. Use when setting review norms.
write-code-review-guidelinesWrite an AGENTS.md
Writes or updates a repository's AGENTS.md with the verified commands, layout, conventions and boundaries a coding agent needs, and nothing generic. Use when setting up a repo for coding agents.
write-agents-mdDocument a public API
Writes reference docs for a module's exported functions, classes or endpoints in the native doc-comment format, covering real behaviour, errors and edge cases. Use before a release.
document-public-api