contributing-to-awesome-claude

name

contributing-to-awesome-claude

description

Use when writing, testing, or preparing ANY contribution or pull request to the JSONbored/awesome-claude (HeyClaude) repo — adding a community content entry (agent/MCP server/skill/hook/command/rule/guide/collection/statusline), or making a platform/code change (website, registry package, MCP package, scripts). The repo has two separate review paths: a private, one-shot "HeyClaude submission gate" that decides single-file content PRs, and the shared gittensory-orb bot that posts an advisory readiness/linked-issue comment on platform/code PRs but does not itself merge or close content PRs. Unlike JSONbored/gittensory and JSONbored/metagraphed, a linked issue is OPTIONAL here — do not import their mandatory-linked-issue rule into this repo. Invoke for any "contribute to / open a PR against / submit an entry to / fix a bug in awesome-claude (HeyClaude)" task.

Contributing to awesome-claude (HeyClaude)

HeyClaude is a file-backed directory of Claude/AI workflow resources (content/<category>/<slug>.mdx) plus a website, registry package, and MCP package that serve that content. It has two kinds of contribution with two different review mechanisms — get the kind right first, everything else follows from it.

reference.md (next to this file) has the exhaustive command tables, the two-gate architecture in detail, the current Codecov numbers, and the content-PR pitfalls. Read it when a section below tells you to.

---

Step 0 — Which kind of contribution is this?

You are...	Contribution type	Review mechanism
Adding/editing one content/<category>/<slug>.mdx entry (agent, MCP server, skill, hook, command, rule, guide, collection, statusline)	Community content	Private HeyClaude submission gate (one-shot, aggressive)
Changing apps/web/**, packages/registry/**, packages/mcp/**, scripts/**, workflows	Platform/code	Standard CI + the shared gittensory-orb bot (advisory)

These are handled by genuinely different systems (see reference.md §1). Do not mix them in one PR — CONTRIBUTING.md is explicit that a content PR touches exactly one content/<category>/<slug>.mdx file, and platform/code changes should stay separate from individual content imports.

---

If you're adding a content entry

1. Read the schema and examples first: content/SCHEMA.md (required/optional fields per category) and examples/content/SUBMISSION_EXAMPLES.md (accepted vs. rejected/rerouted examples — read this before you draft anything non-trivial).
2. One file, one PR. Add exactly one content/<category>/<slug>.mdx. Do not touch README.md, apps/web/public/data/**, apps/web/src/generated/**, apps/web/src/routeTree.gen.ts, or apps/web/public/downloads/** — those are maintainer-owned generated outputs and editing them in a content PR is a reject reason.
3. Source-back everything. Canonical source/docs/repo URLs, not affiliate or tracking links. For hooks, MCP servers, skills, commands, and statuslines, fill safetyNotes (execution, install, writes, destructive actions, background workers, network access, account writes) and privacyNotes (local files, logs, credentials, telemetry, retained data) — use prerequisites only for setup requirements and disclosure only for commercial/listing status, not runtime safety.
4. A linked issue is genuinely optional here. CONTRIBUTING.md says plainly: "a PR with no linked issue is fine." Filing your own issue and resolving it is fine too. What is not fine is multi-account farming (opening an issue on one account, "resolving" it from another) — see reference.md §4 for the exact contrast with gittensory/metagraphed's mandatory policy.
5. Validate narrowly — a content PR does not need the full platform test suite:

   pnpm install --frozen-lockfile
   pnpm validate:content:strict
   

   Do not run generate:readme / generate:openapi or commit build output for a one-file content submission — those are build-time outputs regenerated by CI/deploy.
6. Understand who actually decides your PR's fate. It is the private submission gate, not gittensory-orb — see the Step 1 architecture note below and reference.md §2 for the full disposition table.

---

If you're making a platform/code change

1. Trace an existing analogue in apps/web/src/, packages/registry/src/, or packages/mcp/ before writing new code — the repo has a strong existing house style per surface.
2. Scope your validation to the surface you touched — see reference.md §3 for the exact command lists AGENTS.md prescribes per change type (README, submission/API, or general platform).
3. Codecov is enforcing, not informational, on code changes. codecov/patch requires 70% coverage of your changed lines (5% threshold), and codecov/project compares against your PR's own base commit (target: auto, 1% threshold). Both post a real pass/fail status — see reference.md §5 for the exact codecov.yml values and what's ignored (tests/, **/*.test.ts, **/*.config.ts, apps/web/src/generated, apps/web/public/data, integrations).
4. Regenerate what you invalidate, then commit it — see reference.md §3 for the exact regen command per surface (README, OpenAPI, etc.). Keep generated-artifact churn out of PRs that don't need it; external contributors especially should leave generated output out unless a maintainer asks for it.
5. gittensory-orb reviews your PR, but advisory only. It posts a readiness score, linked-issue/no-issue check, and coverage-evidence comment — useful signal, but it is not the merge authority for platform PRs either; ordinary CI + maintainer review is (see reference.md §2).

---

Common pitfalls (both paths)

• Editing generated files. README.md, apps/web/public/data/**, apps/web/src/generated/**, apps/web/src/routeTree.gen.ts are maintainer-owned outputs. Hand-editing them (in either a content or platform PR) is flagged/rejected.
• Requesting HeyClaude host your ZIP/MCPB. Community package uploads for hosting at /downloads/... are not accepted — link the source repo, an install command, or copyable source content instead. Maintainer-built download artifacts are a separate, post-review, maintainer-only path.
• Bringing gittensory/metagraphed's mandatory-linked-issue habit here. It does not apply — see reference.md §4.
• Missing safety/privacy notes on a risk-bearing entry (a hook, MCP server, skill, command, or statusline that executes code, writes files, calls out to third parties, or runs in the background). Generic boilerplate is a common review nit; be specific about what the resource can actually do.
• Multi-account issue/PR farming. Explicitly against policy and is a permanent, cross-repo block per CODE_OF_CONDUCT.md — not a gray area.
• Chasing a review. CONTRIBUTING.md warns that pinging for status on a queued submission deprioritizes it (adds ~5 days to the manual queue) rather than speeding it up.

---

When you need the exact command lists, the full two-gate disposition tables, or the current Codecov numbers verified against the live codecov.yml, read reference.md in this skill directory.