skills: Instructions file for Claude Code

Skills — Agent Guidelines

Repo: https://github.com/pandoscope/skills

Project Specifics

Terminology

Ubiquitous language is defined in docs/glossary/. Use

uvx disambiguate==0.4.0 <term>

to get a topologically ordered glossary disambiguating all relevant terms to understand the given term.

Before working on a ticket, run:

uvx disambiguate==0.4.0 --from <ticket-file>

or for GitHub issues:

ghx issue view <number> --json body -q .body | uvx disambiguate==0.4.0 --from -

to resolve all referenced terms at once.

Prose that names a term without linking it, or uses an avoided spelling, is drift. The disambiguate --drift hook reports it on every commit. .drift-baseline.json lists the findings this repo carried when the hook arrived; a new finding fails, and a fixed one fails until

uvx disambiguate==0.4.0 --drift --write-baseline

shrinks the file and the shrink is committed.

Architecture

Read docs/architecture.md before touching any code.

Rules

• Small, single-purpose files
• Readability over brevity — straightforward, easy-to-follow code. No compact "one-liners" stretching across multiple lines (e.g. nested ternaries). Stretching across multiple lines is only allowed if it aids readability.
• When removing a feature, erase every mention of it — docs, help text, comments, tests. Don't leave "no longer supported" notes: readers who never knew it existed pay to learn it did. State what is, not what stopped being. (Migration notes belong in the commit's BREAKING CHANGE: footer, which is where someone upgrading looks.)
• In prose, don't state facts maintained elsewhere — counts ("the seven examples above"), far positional references, restated section names. Link the target instead. Immediate-adjacency words ("the examples above", "the following table") are fine — they only break if adjacency breaks.
• All routes and non-trivial functions: docstring contracts (params, returns, errors)
• Test cases cover edge cases and every @returns line