--- name: jsonbored-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 read" license: "MIT" metadata: decimalai-skill-id: "eb36e12a-f105-4e9e-ba2e-cf8ba1331d32" decimalai-version-id: "4c735911-82bf-4a4e-a0f8-68172d353402" decimalai-version: "1" decimalai-body-sha256: "2e472e1a5d42fb338ea1359fd4e98c97797ddc7ecbb53cd7bf6771b58070114b" decimalai-name: "jsonbored/contributing-to-awesome-claude" decimalai-format: "1" decimalai-invocation: "model" decimalai-category: "documentation" decimalai-source: "https://app.decimal.ai/s/jsonbored-contributing-to-awesome-claude@1/SKILL.md" --- # Contributing to awesome-claude (HeyClaude) HeyClaude is a file-backed directory of Claude/AI workflow resources (`content//.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//.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//.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//.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.