AGENTS.md git:20261006.d90c98dA

Immutable. This exact content never changes and is served at /api/v1/blob/06a395815050c0a3.

# AGENTS.md

evident-charts is an agent skill for explanatory charts. The installable skill is `skills/evident-charts/`; everything else supports it.

## Commands

- Tests: `uv run --with matplotlib --with numpy --with pandas --with pytest pytest -q tests`
- Lint a matplotlib chart: `python skills/evident-charts/scripts/check_chart.py <chart.py> --dest <preset>` (`--list-checks` for names)
- Lint an SVG from any other stack: `python skills/evident-charts/scripts/check_svg.py <chart.svg> --dest <preset> [--spec <json>]` (needs Chrome)
- Validate palettes: `python skills/evident-charts/scripts/check_palette.py --preset all`
- Prepare a release: sync versions in root, Claude, Codex, Gemini, and skill metadata; update `CHANGELOG.md`; run tests, palette checks, `gh skill publish --dry-run`, `claude plugin validate --strict .`, and `uvx --from "git+https://github.com/agentskills/agentskills#subdirectory=skills-ref" skills-ref validate skills/evident-charts`.
- Package: `python3 scripts/build_release.py` writes `dist/evident-charts-VERSION.zip` and prints its SHA256. Update its explicit file list when adding resources. Keep root and Codex OpenAI interface metadata identical; paths start with `./` and resolve from the plugin root.
- Acceptance: use `docs/acceptance.md` from the unpacked ZIP; record results and skipped checks in `.local/`. Check user-facing prose with writing-humanizer; instructions and code are excluded by that skill.
- Publish only when explicitly requested: push and run `gh skill publish --tag vX.Y.Z`, or upload the ZIP to the OpenAI dashboard. Developer verification, hosted scans, review, and approval happen outside this repo.

## Writing the skill

- The audience is agents. Be concise; use minimal formatting.
- Encode behavior as data (`assets/*.json`), code (`scripts/`), or CLI commands first. Use prose only for judgment, and keep it short.
- Edit holistically: revise or remove outdated text instead of appending. The skill must always read as if written once.
- SKILL.md is a router (workflow, core defaults, file table). Details live in `references/`, read only when their decision comes up.
- Rule format, one line each: `ID [tag] rule. Break: escape hatch. check: name`. Tags: `[E]` experimental evidence, `[P]` practitioner consensus, `[T]` taste or convention.
- Charts the skill produces are finished products: nothing addressed to the user appears on a chart.
- Cite and paraphrase third-party guidance; never copy its text.

## Changing rules

- Tag each new or changed rule honestly and key its citation in `references/sources.md` to the same ID.
- Renumber cleanly (no suffixed IDs) and update every cross-reference.
- `check:` names must match `check_chart.py --list-checks` or `palette`; `check_svg.py` reuses a subset of them.
- Any script behavior change gets a fixture and a test in `tests/`.

## Evaluating

- Keep private notes, eval data, and results in `.local/` (gitignored). Never commit them.
- Iterate on dev cases; measure on held-out cases you never tune on.
- Never copy eval data or answers into rule examples.
- Compare against the same agent without the skill, judging rendered images, not code.