agents AGENTS.md

General

• Be concise
• Do not use em-dashes, use commas or parentheses instead
• One sentence per line
• Avoid using the following terms (unless it is the most appropriate): shape, honest, load bearing
• When a skill explicitly recommends running another skill as an upstream/prerequisite (for example create-article recommending research-article when sources are not yet gathered), and you choose not to follow that recommendation, you must say so and give your reasoning before proceeding, so it can be course-corrected. Surfacing the deviation after the fact is not sufficient.

Python

• Use uv for package management
• When creating a project, always use the most recent Python LTS version
• Use type hints
• Use pytest for testing
• Use ruff for linting/formatting
• Run tests before committing
• Run linter/formatter before committing
• Create "green path" tests that cover the main functionality
• Use structlog for logging
• When adding dependencies, use uv add ... over adding the version directly to pyproject.toml
• Keep init.py files minimal/empty, only for package initialization
• Do NOT use/add all in init.py files

Per-repository instructions

• Before working in a git repository, check for per-repository overrides stored outside that repository.
• Find the skills library root by resolving the real path of this AGENTS.md (follow symlinks), then look in its repositories/ directory, which is a sibling of skills/.
• Derive {owner}/{repository} from the current repository's GitHub remote URL.
• If repositories/{owner}/{repository}/AGENTS.md exists, read and apply it together with these base instructions.
• For forks, symlink repositories/{fork-owner}/{repository} to the upstream repositories/{owner}/{repository} so both resolve to the same instructions.

Per-machine instructions

• Some machines carry local overrides that should not be shared (e.g. employer-specific conventions).
• Find the skills library root by resolving the real path of this AGENTS.md (follow symlinks), then look in its machines/ directory, which is a sibling of skills/.
• machines/*/ profiles are gitignored and exist only on the current machine. Read and apply every machines/*/AGENTS.md that is present, together with these base instructions.