copilot-instructions.md · git:20260907.99db6c5 · 2026-09-07 · sha256 90e1c2a128da6fa0
copilot-instructions.md git:20260907.99db6c5B
Immutable. This exact content never changes and is served at /api/v1/blob/90e1c2a128da6fa0.
# Copilot Cloud Agent Instructions
## What This Repository Is
This repo ships **one public skill** — `nitpicker`, a hostile audit toolkit invoked as
`/nitpicker <command> [extra instructions]` — in the open Agent Skills format. The router is
`skills/nitpicker/SKILL.md`; each command's instructions live in `skills/nitpicker/commands/<command>.md`.
It installs into Claude Code (`/plugins` marketplace `ivuorinen/skills`), Copilot, pi, and any
SKILL.md-reading agent via `npx skills add ivuorinen/skills`. Copilot reads skills from
`.github/skills/`, `.claude/skills/`, and `.agents/skills/`; pi invokes `/skill:nitpicker`.
Shared cross-agent rules live in `AGENTS.md` — read it first. `CLAUDE.md` holds Claude Code
specifics. This file adds the Copilot cloud-agent specifics.
## Repository Layout
```text
skills/nitpicker/
SKILL.md # The router: frontmatter + dispatch + Commands table
commands/
_conventions.md # Shared conventions binding every command (severity, findings protocol)
<command>.md # One file per command, no frontmatter
scripts/ # Shipped tools: findings.py, fetch-pr-comments.py,
# fetch-pr-status.py, pr_common.py + pr_{github,gitlab,bitbucket}.py,
# process-sarif.py, check-rules-anatomy.py,
# mcp_server.py, skill_catalog.py — stdlib-only, plain python3
.claude/
skills/ # Internal dev skills (new-command, release-prep, skills, skill-tester,
# validate-skills) — not shipped to consumers.
# Also holds graphify (vendored third-party — see
# .claude/rules/vendored-skills.md) and nitpicker,
# a symlink to skills/nitpicker
rules/ # Enforced conventions (skill-format, skill-style, use-uv-runner, …)
settings.json # Shared PostToolUse hooks
agents/ # Sub-agent definitions — do NOT read or modify
.claude-plugin/ # plugin.json + marketplace.json (plugin identity + version)
scripts/ # Internal dev tooling: validate-skill.py, bump-version.py, hooks, …
docs/audit/findings/ # Per-finding audit store (see below)
tests/ # pytest suite for the tooling
```
## The Commands
The authoritative command listing (categorized; each 1.x-era command keeps its skill-name alias,
while commands added since 2.0 have none) is the
`## Commands` section of `skills/nitpicker/SKILL.md` — do not duplicate it here. Nitpicker in one
line: adversarial, exhaustive auditing across code, security, tests, docs, architecture,
performance, dependencies, error handling, CI, commits, migrations, observability, contracts,
a11y, privacy, config, leaks, i18n, and concurrency, plus PR review and review-comment
implementation.
## File Format — Non-Negotiable Rules
Enforced by `scripts/validate-skill.py` (run via `make validate`, part of `make check` and CI):
The normative format is the open
[Agent Skills specification](https://agentskills.io/specification); the rules below are
that spec plus this repo's stricter conventions.
**Router (`skills/nitpicker/SKILL.md`)** — the only file with YAML frontmatter:
- `name` must match the directory name exactly (kebab-case), be ≤ 64 characters, contain only
lowercase letters, digits and hyphens, and never start, end, or double up on a hyphen
- `description` must contain `"Use when"`, be ≤ 1024 characters, and be wrapped in single
quotes when the value contains `": "` (colon + space)
- optional spec fields: `license`, `compatibility` (≤ 500 chars), `metadata` (a map of string
keys to string values), `allowed-tools` (one space-separated string). Any other top-level
key is an **error** — client-specific properties go under `metadata`, quoted as strings.
This holds for internal dev skills too; there is no allowlist
- body warns past 500 lines or ~5000 tokens; move reference material into separate files
**Command files (`commands/*.md`)** — no frontmatter. Required shape:
- h1 `# /nitpicker <command> — <Title>` where `<command>` matches the filename
- a `## When to use` section
- no header-level jumps (h2 → h4 is an error)
- every command file in `commands/` whose name does not begin with `_` must have a row in one
of the command tables of SKILL.md (`## Commands` or `## Internal commands`), **1:1**, enforced
by `scripts/validate-skill.py` — a table row without a file or a non-`_` file without a row
fails validation; shared files prefixed `_` (e.g. `_conventions.md`) are exempt from the cross-check
- never restate `_conventions.md` content (severity table, findings protocol, generic rules)
- no reliance on Claude-only features (`$ARGUMENTS`, `argument-hint`) in skill bodies:
arguments are parsed from the free text after the invocation so the skill works in Copilot and pi
## Findings Store
Audits write one file per open finding — never a monolithic report — and append resolved findings to a ledger:
```text
docs/audit/findings/
INDEX.md # generated — never hand-edit
resolved.jsonl # append-only ledger of fixed/invalid findings
.gitattributes # marks the store linguist-generated (self-written)
<auditor>/open/<id>.md # <auditor> is the command name; IDs are content-hashed
```
Drive the store only through the shipped CLI:
```bash
python3 skills/nitpicker/scripts/findings.py new|resolve|list|show|validate|index|baseline|migrate ...
```
Every finding carries `## Problem`, `## Evidence`, `## Impact`, `## Fix`. `migrate` converts
1.x `docs/audit/*-findings.md` documents.
## Two Script Classes
| Class | Location | Runner |
| -------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Shipped skill tools | `skills/*/scripts/*.py` | plain `python3`, stdlib-only, `#!/usr/bin/env python3` — consumers cannot be assumed to have uv or any installed package |
| Internal dev tooling | `scripts/`, `scripts/hooks/`, `tests/` | `uv run --quiet <script>`, shebang `#!/usr/bin/env -S uv run --quiet` + `# /// script` block |
Every shipped tool answers `--help`/`-h` with its interface on stdout at exit 0, handled before
any positional argument resolves as a path. Structured data goes to stdout, diagnostics to
stderr, and exit codes are distinct per failure class: 0 success, 1 runtime/IO error, 2 usage
error. Bad input fails non-zero — an empty-but-valid result at exit 0 reads as "nothing found".
## Validation — Run Before Every Commit
```bash
make check # validate skill+commands + evals + rules + version sync + lockfile + findings store + findings index + lint + format check + bandit security scan + typecheck + pytest + pre-commit
make list # list the skill and its commands
make test # pytest suite for the tooling
```
CI runs the same checks on every push/PR touching skills, scripts, tests, rules, or version files.
## Versioning — Every Manifest Must Stay in Sync
The canonical version lives in `package.json`. These must match it: `package.json`,
`.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` (`plugins[0].version`),
`.release-please-manifest.json`, `pyproject.toml`. Use `scripts/bump-version.py [major|minor|patch]`
for manual bumps — never edit version fields by hand in individual files.
`uv.lock` holds one more copy in its root `[[package]]` entry that neither
`check-version-sync.py` nor release-please updates. `make lock-check`
(`uv lock --check`) gates it.
`bump-version.py` re-locks on a best-effort basis. When `uv` is absent, times
out, or fails, it reports that and continues rather than aborting a bump whose
manifests are already written.
Run `uv lock` to resync — that is the supported way to move the version in the
lockfile. Hand-edit `uv.lock` only where uv cannot run at all, and treat that as
a stopgap: the next `uv lock` overwrites the value.
## Commit Message Convention (Controls Release Automation)
| Prefix | Effect |
| ------------------------------------- | ----------------------------------------- |
| `feat:` | Minor bump (new command or feature) |
| `fix:` | Patch bump (command improvement, bug fix) |
| `feat!:` or `BREAKING CHANGE:` footer | Major bump |
| `chore:`, `docs:`, `refactor:`, `ci:` | No bump |
release-please derives releases from these prefixes; a wrong prefix mis-versions the release.
## Adding a New Command
1. Create `skills/nitpicker/commands/<name>.md` (short kebab-case name, 2.0 vocabulary — no
`-auditor` suffixes) with the required h1 and `## When to use`.
2. Add its row to the `## Commands` table in `skills/nitpicker/SKILL.md`.
3. Add it to the Routing Guide in `.claude/skills/skills/SKILL.md`.
4. Add it to the command table in `README.md` and mention it here if it changes the rules above.
5. `make check` must pass (the validator enforces table ↔ file sync).
6. Commit with `feat: add /nitpicker <name> command`.
## Common Mistakes to Avoid
- **Do not** duplicate `_conventions.md` content into a command file — commands inherit it.
- **Do not** hand-edit `docs/audit/findings/INDEX.md` — it is generated by `findings.py index`.
- **Do not** add uv invocations or non-stdlib imports to shipped tools under
`skills/nitpicker/scripts/` — they must run with plain `python3` on any consumer machine.
- **Do not** add a Commands-table row without its command file, or a command file without its
row — the 1:1 sync check fails CI.
- **Do not** use `$ARGUMENTS` or other Claude-only substitution in skill bodies — parse the
free text after the invocation instead.
- **Do not** add frontmatter to command files, or omit it from the router SKILL.md.
- **Do not** update the version in only one manifest — every manifest listed above moves together.
- **Do not** read or modify anything under `.claude/agents/` — those are restricted.
- **Do not** commit finding files silently — audits ask "Commit findings to git? (y/n)" first.