|
| 1 | +# Contributing to claude-red |
| 2 | + |
| 3 | +Thanks for contributing. This guide explains the skill format, the review process, and the conventions to keep the library coherent as it grows. |
| 4 | + |
| 5 | +## Quick Rules |
| 6 | + |
| 7 | +1. **One skill, one surface.** Prefer focused skills (`offensive-kerberoasting`) over monolithic overviews (`offensive-active-directory`). |
| 8 | +2. **YAML frontmatter is required.** Skills without it won't load via the Claude Skills system. |
| 9 | +3. **Cite sources.** Every technique should be attributable. Link CVEs, advisories, original research. |
| 10 | +4. **No unauthorized targeting.** Don't include hardcoded victim domains, real customer data, or credentials. |
| 11 | +5. **Use code blocks with language tags.** It's how Claude (and humans) parse them best. |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## Skill Format |
| 16 | + |
| 17 | +A skill lives at: |
| 18 | + |
| 19 | +``` |
| 20 | +Skills/<category>/<skill-folder>/SKILL.md |
| 21 | +``` |
| 22 | + |
| 23 | +The folder name **must** match the `name:` field in the frontmatter. |
| 24 | + |
| 25 | +### Frontmatter (required) |
| 26 | + |
| 27 | +```yaml |
| 28 | +--- |
| 29 | +name: offensive-<bug-class-or-domain> |
| 30 | +description: "One paragraph (50–500 words). State the surface, the techniques covered, and when to use this skill. Claude uses this for trigger matching — be specific about scenarios, tools, and sub-topics." |
| 31 | +--- |
| 32 | +``` |
| 33 | + |
| 34 | +The `description` is what Claude matches against. Make it dense with relevant terms an operator would mention. Avoid marketing language. |
| 35 | + |
| 36 | +### Body Structure (recommended) |
| 37 | + |
| 38 | +```markdown |
| 39 | +# <Short Skill Title> |
| 40 | + |
| 41 | +<One-paragraph framing. Why this matters, what makes it distinct.> |
| 42 | + |
| 43 | +## Quick Workflow |
| 44 | + |
| 45 | +1. <Numbered, ordered steps an operator follows in the field> |
| 46 | + |
| 47 | +--- |
| 48 | + |
| 49 | +## <Section per phase or technique cluster> |
| 50 | + |
| 51 | +<Concrete, copy-paste commands or code blocks. Annotate the why.> |
| 52 | + |
| 53 | +--- |
| 54 | + |
| 55 | +## Detection / Defender View |
| 56 | + |
| 57 | +<Optional but valuable — what defenders will see, common evasions.> |
| 58 | + |
| 59 | +--- |
| 60 | + |
| 61 | +## Engagement Cheatsheet |
| 62 | + |
| 63 | +<A short copy-paste-ready sequence summarizing the methodology.> |
| 64 | + |
| 65 | +--- |
| 66 | + |
| 67 | +## Key References |
| 68 | + |
| 69 | +- MITRE ATT&CK / CWE / OWASP IDs |
| 70 | +- Canonical research papers, conference talks |
| 71 | +- Tool docs, advisory URLs |
| 72 | +- Source: link to upstream checklist if applicable |
| 73 | +``` |
| 74 | + |
| 75 | +### Style Guide |
| 76 | + |
| 77 | +- **Voice:** technical, second-person ("you"), present tense |
| 78 | +- **Length:** 200–800 lines is typical; aim for depth in one surface, not breadth across many |
| 79 | +- **Code blocks:** always specify the language (`bash`, `python`, `c`, `powershell`, `sql`, `yaml`, `http`) |
| 80 | +- **Tables:** use for compact reference (CVE → exploitation, capability → escape, etc.) |
| 81 | +- **No emoji** unless used as visual markers in tables (✓ ✗ ⚠) and only sparingly |
| 82 | + |
| 83 | +--- |
| 84 | + |
| 85 | +## Adding a New Skill |
| 86 | + |
| 87 | +1. Pick the right category folder. If none fits, propose a new one in your PR description. |
| 88 | +2. Create `Skills/<category>/<skill-name>/SKILL.md`. |
| 89 | +3. Write the frontmatter and body following the structure above. |
| 90 | +4. Update [`README.md`](README.md) — add the skill to the relevant category table. |
| 91 | +5. Update [`CHANGELOG.md`](CHANGELOG.md) under the next version. |
| 92 | +6. Update [`claude-skills.json`](claude-skills.json) if it exists (run `python tools/build_manifest.py` if available). |
| 93 | +7. Run any local lint: |
| 94 | + ```bash |
| 95 | + ./tools/check-skill.sh Skills/<category>/<skill-name>/SKILL.md |
| 96 | + ``` |
| 97 | + |
| 98 | +## Modifying an Existing Skill |
| 99 | + |
| 100 | +- Preserve the `name:` field (it's a public identifier; renames are breaking changes) |
| 101 | +- Note the edit briefly in CHANGELOG.md |
| 102 | +- For substantive rewrites, link the prior version's SHA so reviewers can diff |
| 103 | + |
| 104 | +## Splitting a Monolithic Skill |
| 105 | + |
| 106 | +When a skill grows beyond one surface (e.g. `offensive-wifi` covering WPA2, WPA3, BLE, Zigbee), split it: |
| 107 | + |
| 108 | +1. Keep the original as a brief overview that points to the new focused skills |
| 109 | +2. Move detailed content into new per-surface skills |
| 110 | +3. Update README, CHANGELOG, and the manifest |
| 111 | + |
| 112 | +The roadmap in README tracks current splits. |
| 113 | + |
| 114 | +## Review Process |
| 115 | + |
| 116 | +Pull requests are reviewed for: |
| 117 | + |
| 118 | +- Technical accuracy (does this work? is it current?) |
| 119 | +- Clarity (would a competent operator understand and execute?) |
| 120 | +- Scope (one surface, not three) |
| 121 | +- Attribution (sources cited?) |
| 122 | +- Safety (no real targets, no live secrets, no malicious helpers) |
| 123 | + |
| 124 | +Expect one round of review. Maintainers may request edits before merging. |
| 125 | + |
| 126 | +--- |
| 127 | + |
| 128 | +## What We Won't Accept |
| 129 | + |
| 130 | +- Skills that hardcode real victim infrastructure |
| 131 | +- Tooling that has destructive defaults without warnings |
| 132 | +- Bypasses for vendor-mandated security telemetry without legitimate red team context |
| 133 | +- Content under non-MIT-compatible licenses |
| 134 | +- AI-generated skills without operator review (use Claude to draft, then verify and edit) |
| 135 | + |
| 136 | +--- |
| 137 | + |
| 138 | +## Questions |
| 139 | + |
| 140 | +Open a GitHub Discussion before a large PR so the maintainers can confirm the direction. For sensitive findings (a leaked credential in an example, etc.), see [SECURITY.md](SECURITY.md). |
0 commit comments