Contributing To Awesome Claude

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

• 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).

• 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.

• 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.

• 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.

• 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.

• 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

• 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.

• 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).

• 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).

• 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.

• 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.