# AGENTS.md Instructions for AI agents (and humans) authoring skills in this repository. ## What this repo is A collection of [skills.sh](https://www.skills.sh)-compatible **agent skills**. Each skill is reusable, on-demand context for an AI coding agent. One skill = one folder under `skills/` with a `SKILL.md`. **Project tracking:** [Linear — Skills](https://linear.app/stealth-company/project/skills-2bf14f088070/overview). ## Layout ``` skills//SKILL.md # flat (preferred) skills///SKILL.md # only if you have enough to categorise ``` `` is kebab-case and matches the `name:` in the frontmatter. No manifest file is needed — the `skills` CLI auto-discovers these paths. ## SKILL.md format ```markdown --- name: my-skill # kebab-case, matches the folder description: # SEE BELOW — this is the most important field metadata: author: stealth-factory version: "1.0.0" # bump on meaningful change (semver) --- # Title ``` ### The `description` is the trigger (write it carefully) It's the **only** part of a skill that's always in the agent's context; the body loads **only when the description matches** the task. So write it as **concrete triggers**, not marketing: - Good: `Use when an iPhone/iPad page shows black bars, content is cut off at the bar edge, a cropped shadow, or the page jumps after the keyboard closes.` - Bad: `Helps with iOS Safari styling.` Lead with what the skill does, then "Use when …" listing the situations, symptoms, and phrases a user might say. ### The body - Write for the **agent**, not end users — actionable facts, steps, rules. - Keep it **scannable** (headings, short sections, tables, code blocks). - **Progressive disclosure:** keep `SKILL.md` focused; if a skill needs heavy reference material or scripts, put them in sibling files and link to them so they load only when needed. - Prefer **facts and case-dependent guidance** over a single rigid recipe, so the skill stays useful across situations. - Note provenance (how a non-obvious claim was verified) when it helps trust. ## Bundling files in a skill A skill is a **directory**, not just `SKILL.md`. You may ship reference docs, scripts, templates, or assets alongside it: ``` skills// SKILL.md # entry: frontmatter + concise body reference/*.md # optional — deep detail, read on demand scripts/* # optional — runnable helpers the skill invokes templates/* # optional — boilerplate the skill copies ``` Only `SKILL.md`'s body loads when the skill fires; everything else loads/reads/ runs **only when `SKILL.md` references it** (by relative path). Keep `SKILL.md` short and push heavy material into siblings. The CLI installs the whole directory, so relative links keep working. Small skills are fine as a single `SKILL.md` — split only when it gets large or needs helpers. ## Adding a skill ```bash npx skills init skills/ # scaffolds the folder + SKILL.md ``` Then fill in the frontmatter + body, add a row to the **Skills** table in `README.md`, and commit. ## Dogfooding — these skills are available while working in this repo Every skill under `skills//` is symlinked into the agent-discovery dirs so **Claude Code and Codex (and other agents) pick them up automatically** when working in this repo: ``` .claude/skills/ -> ../../skills/ # Claude Code .agents/skills/ -> ../../skills/ # Codex / universal ``` The links are **relative**, so they resolve in any clone or worktree, and they point at the **working-tree** skill (edits are live — no reinstall). When you add a skill, re-link it: ```bash for d in skills/*/; do n=$(basename "$d"); \ ln -sfn "../../skills/$n" ".claude/skills/$n"; \ ln -sfn "../../skills/$n" ".agents/skills/$n"; done ``` (Consumers of this repo install instead with `npx skills add stealth-factory/skills`.) ## Environment facts — verify the toolchain; don't assume the docs These gaps were verified on `gh` **2.45.0** and each cost a real defect in a shipped skill. **They are compatibility notes, not a claim about the current machine.** `gh` versions vary across checkouts (2.45.0, 2.91.0, and 2.96.0 have all shown up). Detect the installed version (`gh --version`) and **run the exact invocation in the form it will ship** — a flag in a manual is not verification. | Assumption | Reality on `gh` 2.45.0 | How it fails | | --- | --- | --- | | `gh pr checks --json …` | **`unknown flag: --json`** (present on 2.91+) | A loop that captures empty output and fails closed **spins forever and times out**, looking like slow CI rather than a broken command | | `gh api --jq --arg k v '…'` | **`accepts 1 arg(s), received 4`** — `gh api` takes `--jq ` but forwards **no** jq CLI flags (still true on 2.91) | The query never runs; its subject looks *silent* rather than unqueried. Use exported vars + `env.NAME` | | `gh api --slurp` | **absent** on 2.45.0 (present on 2.91+) | Suggested by reviewers as a paginate fix; adopting it on an older `gh` reintroduces the same class of bug | | `gh skill install …` | **`unknown command`** on 2.45.0 (present on 2.91+) | `gh extension install` still works | | exit code `1` = "checks failed" | **overloaded** — a nonexistent PR, an unknown repo and a bad flag *all* exit 1 | An API error reads as "CI finished red" and you triage a build that never ran | | `timeout` is available | **GNU coreutils** — absent on stock macOS/BSD | A "portable" recipe dies with `command not found` | **The rule this earned: run the exact invocation, in the form it will ship.** Reading a flag in a manual is not verification — three separate defects here passed a docs check and failed on first execution. The API is the source of truth; an exit code is a hint. ## Review bots in this repo Both PR-driving skills depend on these; re-verify if behaviour diverges. - **CodeRabbit** (`coderabbitai[bot]`) — check-backed, but its green tick is **not proof of review**: `state=success` with `description="Review rate limited"` means it never looked (vs `"Review completed"`). Read the description, never the colour. It is also **starved by a fast push cadence** — on one 16-commit PR it was throttled on 7 of the last 9 heads, because each push consumed the slot the previous throttle had released. Batch a whole round into one push. - **Codex** (`chatgpt-codex-connector[bot]`) — posts **no status check at all**, so it never appears in the rollup and silence from it is ambiguous. It is nonetheless the **highest-signal reviewer** observed here. On one 16-commit PR it arrived **2–4 minutes after every push, 17/17** — that is one observed path, not a guarantee. The bot snapshot also records a slow path (no response ~8 minutes after an explicit trigger). Neither a push nor a tag guarantees timely review. Bound the wait, then disclose if it never reported — don't treat a short quiet period as proof it looked. - **Findings arrive as comments, not check failures.** On a 16-commit PR: **44 comment-delivered findings, 0 failing checks.** Any wait that only watches checks — including `gh pr checks --watch` — reports "all settled" while every real finding sits unread. Always pair a check wait with a comment sweep. **Driving a PR here:** `/autofix-pr` is enabled on this account and can drive a PR from a cloud session, pushing commits itself. **Only one agent should push to a branch at a time** — if a cloud session owns the branch, stay read-only and branch off `main` for unrelated work. ## Branching & pull requests This repo uses a **feature-branch + PR** workflow. Do **not** commit directly to `main`. - **Branch per change:** `feature/` off `main` (e.g. `feature/conventional-commits`). Build larger work in a git **worktree** so each change stays isolated. - **Open a PR** with a **Conventional Commits title** — it becomes the squash-merge commit message, so it must be semantic (`feat(skill): …`, `docs: …`, `fix: …`). - **Squash merge** to `main` (one PR = one commit on `main`). - **Don't self-merge:** leave the PR for review and **ask before merging**. ## Conventions - One concern per skill. Split rather than overload. - Bump `metadata.version` (semver) on a meaningful change. Publisher metadata alone (`author:` rename, display-name/branding) is not a version bump — consumers resolve skills by repo path, not by that field. - Conventional Commits for messages (`feat(skill): …`, `docs: …`, `fix: …`). ## Writing skills that survive review These are not style preferences. Each is a failure pattern that produced multiple real defects here, and each is cheap to avoid once named. - **Shipping shell in a judgment skill creates an unbounded review surface.** One 30-line recipe drew a defect in *nearly every review round* of a 16-commit PR; the two blocks reduced to *stated requirements* produced none afterwards. Prefer stating the rule ("check each lookup independently") over shipping a reference implementation of it. Prose cannot rot; shell does. When an addition keeps attracting findings, **simplify or drop it** rather than patch it a third time. - **Any construct that folds several results into one exit status will hide the one that failed.** Same defect, three costumes, three separate rounds: `$(cmd) || echo 0` turned an API error into "zero results"; `export VAR=$(cmd)` always returns 0; `{ a; b; }` takes the *last* command's status; a pipeline does too unless `pipefail` is set. Capture and test each lookup on its own. - **A failed lookup is missing evidence, never a negative result.** Fail closed. Most fail-open cases here were error paths quietly reading as "nothing found". - **Prefer an allowlist of the terminal state over a denylist of pending ones.** Enumerating `queued|in_progress|pending` went stale the moment `waiting`/`requested` appeared. Treat only `status == "completed"` as terminal; then read `conclusion` to distinguish `success`, `failure`, `cancelled`, and other outcomes. - **Silence is not success.** A guard, watcher, or query that cannot emit on its failure path is indistinguishable from a quiet system. Two watchers in one session were each half-dead for many rounds without ever announcing it. Before trusting one, make it prove it fires on a known event. - **When adding to a file, diff against what the file already claims.** Three defects came from writing something that contradicted correct guidance already present 70 lines away. Simplification is the same hazard in reverse: **diff what you delete** — one "cleanup" silently removed a safeguard and reopened a closed fail-open. - **Verify a reviewer's suggested *mechanism*, not just its concern.** Twice a proposed fix (`--slurp`) was itself unavailable on the `gh` that shipped the skill. Take the finding; check the remedy. ## Driving review (see `skills/autonomous-pr-driver/`) - **Stop pushing ≠ stop watching.** Diminishing returns should end the *fix cadence*, not the session's attention. Ending both is what makes a driver look like it gave up. - **Prefer a stateless re-sweep over a clever incremental watcher.** The watcher bugs here came from incremental state — seen-sets and per-page `jq` — and from incorrect author-filter handling. Re-running the full enumeration from scratch has nothing to rot. - **A PR subscription that processes its own events feeds itself.** Independently observed in two separate implementations: the loop's own replies wake it. Filter out the current agent's identity even when the sweep is stateless. - **Pushed events can be stale.** A webhook describes the moment it was emitted, so an event may name a commit that is no longer HEAD. Re-read HEAD before acting; polling always reads current state, push does not.