hermes

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.

context

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.

task

Write CONTRIBUTING.md for this project.

repo facts

Only if [PROJECT_POLICIES] is given:

project policies

Only if [GOOD_FIRST_AREAS] is given:

good first areas

  1. 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.
  2. 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.
  1. 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.
constraints
  • 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.
output format

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

Edit on GitHubReport a problem

use in

Hodios CLI
npx @hermes-hq/hodios install write-contributing-guide --target claude-code
Agent Skills
npx skills add hermes-hq/hodios-dist --skill write-contributing-guide -a claude-code
Add the Hodios marketplace (once)
claude plugin marketplace add hermes-hq/hodios-dist
Install the software-engineering plugin
claude plugin install hodios-software-engineering@hodios

The plugin brings every entry in this domain at once.

pairs well with

All of Documentation
PersonaDocumentation

Technical 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-writer
PromptDocumentation

Write 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-readme
PromptDocumentation

Write 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-guide
PromptCode review

Write 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-guidelines
PromptCoding-agent operations

Write 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-md
PromptDocumentation

Document 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