| name | ai-tools-architect |
| description | AI-tool architecture for instructions, prompts, rules, agents, commands, skills, hooks, and provider context. Use for setup, refactoring, or audits needing clear boundaries, deterministic automation, reproducibility, or lean context. Use software-engineering for application architecture. |
AI Tools Architecture Playbook
Enforce progressive disclosure and deterministic execution boundaries for this
project's AI setup. Keep model context focused on judgment while routing exact,
repeatable mechanics through tools or bundled scripts.
For an existing AI configuration tree, run the structural audit before manual
review:
python3 <skill-dir>/scripts/audit_ai_tools.py <ai-tools-root> --format markdown
The audit is read-only. Treat errors as objective structural failures and
warnings as review candidates; architecture decisions remain with the agent.
Review implicit and explicit-only skill counts before adding another automatic
trigger. Treat the description budget as advisory because host limits vary.
After changing canonical skills, run every bundled unit suite with:
python3 <skill-dir>/scripts/run_skill_tests.py <canonical-skills-root>
Treat root AGENTS.md as registry and keep detailed workflow or domain guidance
in gated leaf nodes.
Core Doctrine: Nudges, Not Documentation
Apply these tests to every AGENTS.md, rule, skill, and agent file you design or
review, in any repository:
- Human docs are canon. If the project documents a convention for all
contributors (
CONTRIBUTING.md, docs/, style guides), agent files must
point there; never paraphrase or fork it. The root registry should instruct
reading the canon doc before making changes. Duplicating canon into agent
files costs little context (they rarely co-load) but guarantees drift.
- Models know the technology. Never spend agent-file lines teaching the
language, framework, OS, or tool itself (syntax, standard commands,
well-known APIs). The model already knows systemd units, flake syntax, git.
Cut any content a competent engineer new to this repo would not need.
- Keep only the nudges. Agent files exist solely for what neither canon
docs nor model knowledge covers: project-specific layout and naming, policy
choices among valid alternatives, environment quirks, and corrections for
behaviors models repeatedly get wrong here.
- Dedupe across co-loading files. Duplication only costs tokens when both
copies load together (sibling path-gated rules, registry + rule). State
shared guidance once in the file with the widest matching gate.
- Encode mechanics; explain judgment. Prefer parameterized scripts or CLIs
for fragile or repeated queries, transformations, validation, and mutations.
Keep selection, ambiguity resolution, and result interpretation in the
playbook unless those decisions also have an exact contract.
Execution Routing
Do not guess or hallucinate architectural standards. For advice about a specific
AI-configuration component, read its reference in refs/ before responding:
If AI-configuration scope remains broad, ask which component fits the need.
Example: "How should I structure this new agent workflow?"
