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

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:
   ```sh
   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.