CheatSheetSeries Agent Skills & AI Rules

# AGENTS.md — Rules for AI Tools in the OWASP Cheat Sheet Series

This file governs **every AI tool** used in this repository — Claude Code, Codex, Cursor, Copilot, and anything else. If you are an AI assistant generating issues, pull requests, comments, or content, these rules are mandatory. `CLAUDE.md` imports this file; treat it as the single source of truth.

The full human documentation lives in [CONTRIBUTING.md](CONTRIBUTING.md) (process + policy) and [GUIDELINE.md](GUIDELINE.md) (how to write good content). Read them. This file distills the rules that matter most and that AI tools most often break.

> The audience for every cheat sheet is **developers, not security experts**. Content must be accurate, practical, concise, and opinionated. We would rather have _good_ advice a developer can follow than _best_ advice they cannot.

---

## Non-negotiable rules

These are the rules whose violation gets a contribution closed. Most rejected contributions break one of these.

### 1. Sources must be real, read, and supportive

Anti-fabrication (always):

- You must have **actually fetched and read** each source and confirmed it supports the specific claim. Do **not** rely on training-data memory or summaries.
- **Never invent or guess a URL.** Fabricated citations, links that 404 or redirect to a homepage, and links to a page that does not actually support the claim are the single most common reason PRs are reverted. If you cannot find a real supporting source, do not make the claim.
- Link the **specific page or section** that supports the claim, not an index or landing page.
- Do not link to cheat sheet pages or anchors that do not exist — verify the target is present in the repo first.

How much to cite (calibrated to what actually gets merged):

- **Every new `## H2` section must contain at least one inline citation** `[text](https://...)` — this is the CI floor (`citation-check`). Beyond that, any **novel, surprising, parameter-specific, or contestable** claim needs its own source. Well-established common practice does not need a citation on every sentence.
- **Every cheat sheet must end with a `## References` section**, using that exact heading. Usually list **2–3 key authoritative primary sources**, such as standards bodies, government publications, or official technical specifications/documentation. Do not use blogs, marketing pages, or generic resource lists in this section.
- Internal cross-links to other cheat sheets are encouraged (see rule 4) but do **not** satisfy the CI citation gate, which only counts `https://` links.
- Cite **authoritative** sources: RFCs, NIST, OWASP, official vendor/project documentation, MDN, reputable tool docs and canonical source repositories (e.g. GitHub), or peer-reviewed research. Prefer the most authoritative source available and avoid SEO/marketing content farms — but a solid project doc, MDN page, or canonical repo is a valid citation (these are in fact the most-cited sources across the series).
- The citation gate is a **floor, not a ceiling**: maintainers merge on overall soundness and may accept content that trips the gate, or reject well-cited content that is wrong.
- Additional authoritative inline citations are welcome where they support specific claims; the final References section may repeat key sources cited inline. Keep links selective. The 2–3 reference target is not a reason to remove necessary claim support; if citations become extensive, narrow or split the cheat sheet.

### 2. Claims must be correct and within the security threat model

Citations are necessary, not sufficient — the most detailed rejections in this project are fully-cited content that was simply wrong or off-topic.

- Pair every threat with a concrete countermeasure, and state explicitly what a control **does and does not** protect against.
- Do not drag in attacks outside the topic's threat model (e.g. endpoint compromise under MFA) without a caveat.
- Add only guidance that is genuinely a **security** control or risk. General code-quality, performance, or architecture advice belongs elsewhere.

### 3. Stay in scope — one topic, one PR, one branch

- A PR modifies a **single cheat sheet** (or a small, clearly-coordinated set). CI enforces a hard limit of **3 cheat sheets** and **1500 net added lines** without a linked tracking issue. (The scope check counts only `cheatsheets/` and `cheatsheets_draft/` Markdown — dependency/CI/typo-sweep PRs are not bound by it. It is skipped for PRs opened by repository owners, members, and collaborators.)
- Work from a **clean branch off `master`, one topic per branch**. Never open two PRs from the same branch — it leaks unrelated changes between them (this has caused reverts here).
- A new or substantially updated cheat sheet requires an **approved issue first** (see CONTRIBUTING.md). Do not open a large unsolicited PR.
- Do not bundle unrelated changes, drive-by reformatting, or mass edits across files.

### 4. Don't duplicate — link instead

- Before adding a section, check whether it already exists in this or another cheat sheet (`cheatsheets/` and `Index.md`). If the topic is covered elsewhere, **link to it** instead of restating it.
- Coordinated multi-sheet families (e.g. the XSS, injection, and authorization sheets) are **intentional** and cross-link in a hub-and-spoke pattern — that is correct, not duplication. What's prohibited is reproducing another sheet's guidance instead of linking it.
- Confirm the content belongs in the cheat sheet you are editing. If it is really a different topic, it belongs in a different (or new) cheat sheet.

### 5. Keep cheat sheets conceptual

- Lead with security concepts, architectural patterns, design decisions, and control limitations. Explain what developers should do and why. Avoid code-heavy tutorials.
- Do not add complete applications, deployment pipelines, or reusable implementations that the project would need to maintain. Link to authoritative upstream implementation documentation instead.
- Include code or configuration only when essential to explain a specific security control, using the smallest accurate example. Language-specific, injection, parameterization, and hardening topics may need syntax examples; they are not blanket exceptions to this rule.
- Keep examples clearly illustrative, state relevant assumptions and limitations, and language-tag fences where practical. Never present examples as production-ready or guaranteed safe, or imply that project review replaces application-specific security review and testing. Illustrative status does not excuse incorrect or insecure guidance.
- When reviewing code-heavy contributions, request a shorter conceptual revision with upstream implementation links. Successful execution or passing CI does not justify making a cheat sheet responsible for maintaining a complete implementation.

### 6. No slop

- Be concise and opinionated. Cut generic filler, verbose preambles, restated obvious background, and "in today's world…" intros. Recommend a specific approach; don't enumerate every option.
- If a section reads like generic AI output, rewrite or remove it. Maintainers close contributions that read as AI-slop.

### 7. Declare AI usage

- Any PR whose content was generated or materially assisted by AI **must** disclose it in the PR description (the template's AI Tool Usage section): tool name (Claude, Copilot, Cursor, Codex, …), version if known, and the prompt used. This applies to **all** AI tools, not just one. Failure to disclose can get the contribution deleted.

### 8. Cheatsheet Size

- Cheatsheets are meant to be **concise cheats** on a topic, not complete or comprehensive resources.
- If a cheatsheet is getting too large, the cheatsheet is possibly getting bulky and may need to split it up into several smaller cheatsheets, or be reduced in size.

---

## Format & style (partly enforced by CI)

- US English. Spell-check. Keep language simple for non-native readers. Define non-obvious acronyms on first use (not "HTTP"/"URL").
- Markdown only — avoid raw HTML (only `details`/`summary` allowed). Lists use `-`. Bold uses `**`. Quotes use `>`.
- **Structure (typical shape; References is required):** H1 = cheat sheet name → `## Introduction` → main H2 sections → final `## References`. Typically 3–6 H2 sections, but more is fine for broad topics. Use the exact final heading `References`, not "Other Links" or "Further Reading". Blank line after every heading (markdownlint-enforced). The TOC is auto-generated — do not add one.
- Filenames: letters/numbers/hyphens/underscores only, ending `_Cheat_Sheet.md`. New sheets start from [`templates/New_CheatSheet.md`](templates/New_CheatSheet.md).
- Assets go in `assets/`, images in PNG, referenced as `![alt](../assets/NAME.png)`.
- Links are inline with a descriptive label: `[Description](https://example.org)`. Always HTTPS where possible.

## Run the local checks before proposing changes

CI runs these on every PR; run them locally first so you don't ship obvious failures:

```bash
npm run lint-markdown      # markdownlint
npm run lint-terminology   # textlint (US English / terminology)
npm run link-check -- --base origin/master   # links your branch adds or breaks
```

CI also enforces: **PR scope** (`pr-scope-check`), **citation density** (`citation-check`: every new H2 must contain at least one inline `[text](https://...)` citation), and the link check above. These catch mechanical problems — they do **not** judge whether a source actually supports its claim, whether advice is correct and in-scope, or whether content is duplicated. That judgment is on you and the maintainers.

---

## For maintainers reviewing PRs

This repo ships an aggressive, multi-dimensional review workflow that is written to work across agent runtimes, including Claude Code and GitHub Agents. From the repo root:

```
/review-cheatsheet-pr <PR number | PR URL | (omit for local diff)>
```

It evaluates security, developer practicality, links/source quality, duplication & placement, and language, then returns a single verdict — **MERGE / REQUEST_CHANGES / CLOSE** — with evidence. When the runtime supports independent reviewers it can fan them out in parallel; otherwise it falls back to a single-agent review of the same dimensions. See [`.claude/commands/review-cheatsheet-pr.md`](.claude/commands/review-cheatsheet-pr.md). Use it to triage the backlog and fact-check sources at scale.

The same review contract is mirrored for GitHub-native tooling in [`.github/skills/code-review/SKILL.md`](.github/skills/code-review/SKILL.md), which Copilot code review picks up, with the authoring conventions in [`.github/instructions/cheatsheets.instructions.md`](.github/instructions/cheatsheets.instructions.md). Keep them in step: a rule that changes in one belongs in the others.

### Workflow approvals before merge or close

When authorized to merge or close a PR, first run `npm run check-pr-approvals -- <PR> --repo OWASP/CheatSheetSeries` after the last push or description edit. Resolve every approval hold across its history, including old commits and duplicate runs, and verify the final commit's CI separately. Follow [the maintainer procedure](CONTRIBUTING.md#before-merging-or-closing-a-pull-request): review before approval, cancel obsolete runs after they queue, and confirm terminal status. Never auto-approve unreviewed code, weaken fork approval settings, or delete failure history to clear this audit.