Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add skills/chama-x/groundrules/improve-codebase-architecturenpx skills add chama-x/GroundRules --skill improve-codebase-architecturegit clone --depth 1 https://github.com/chama-x/GroundRulesWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.00068 | $0.00722 |
| Opus 5 | $0.00034 | $0.00361 |
| Sonnet 5 | $0.00014 | $0.00144 |
| Haiku 4.5 | $0.00007 | $0.00072 |
Grade A, and why
improve-codebase-architecture scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 66 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Improve Codebase Architecture
Surface architectural friction and propose deepening opportunities: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
Glossary
Use these terms exactly in every suggestion. Full definitions are in LANGUAGE.md.
- Module: anything with an interface and an implementation.
- Interface: everything a caller must know to use the module correctly.
- Implementation: the code inside.
- Depth: leverage at the interface. Deep means high leverage; shallow means the interface is nearly as complex as the implementation.
- Seam: where an interface lives; a place behavior can be altered without editing in place.
- Adapter: a concrete thing satisfying an interface at a seam.
- Leverage: what callers get from depth.
- Locality: what maintainers get from depth.
Key principles:
- Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across many callers, it was earning its keep.
- The interface is the test surface.
- One adapter means a hypothetical seam. Two adapters means a real seam.
Process
1. Explore
Read the project's domain glossary and any ADRs in the area first. Then inspect the codebase organically and note where understanding creates friction:
- Where does understanding one concept require bouncing between many small modules?
- Where are modules shallow?
- Where have pure functions been extracted only for testability, while real bugs hide in how they are called?
- Where do tightly-coupled modules leak across seams?
- Which parts are untested, or hard to test through their current interface?
Apply the deletion test to anything suspected of being shallow.
2. Present Candidates
Present a numbered list of deepening opportunities. For each candidate include:
- Files: which files/modules are involved.
- Problem: why current architecture causes friction.
- Solution: plain-English description of what would change.
- Benefits: explain locality, leverage, and how tests would improve.
What ships with it
3 files beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2d ago First seen · 66 lines · 68 tokens per session scan A 8f4a0a71958d
improve-codebase-architecture is a skill published in the GitHub repository chama-x/GroundRules (5 stars, last pushed 19d ago), licensed MIT. It adds 68 tokens to every session and 722 once invoked, about $0.0003 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.
Other skills, from other repositories
hive.worker-delegation
Concrete patterns for breaking colony work into parallel worker jobs via runplaybook — when fan-out helps, how to model the goal as a tracker table, write the worker skill, author the playbook, pilot, and let convergence retry/resume the gap.
hive.chart-creation-foundations
Required reading whenever any chart tool is available. Teaches the one-tool embedding contract (call chartrender → live chart appears in chat AND a downloadable PNG lands in the queen session dir), the ECharts (data viz) vs Mermaid (structural diagrams) decision, the BI/financial-grade aesthetic baseline (no…
seedance
Generate AI videos using Volcengine Seedance model. Supports text-to-video (T2V), image-to-video (I2V), and audio-synced video generation. Use this skill when the user wants to create or generate videos.
develop-web-game
Use when Codex is building or iterating on a web game (HTML/JS) and needs a reliable development + testing loop: implement small changes, run a Playwright-based test script with short input bursts and intentional pauses, inspect screenshots/text, and review console errors with rendergametotext.
pr-feedback
Fetches PR review feedback and inline comments, categorizes them, and presents options to the user. Use when the user asks to get, read, address, or fix review comments on a pull request.
stock-explorer
A Yahoo Finance (yfinance) powered financial analysis tool. Get real-time quotes, generate technical indicator reports (RSI/MACD/Bollinger/VWAP/ATR), summarize fundamentals, and run a one-shot report that outputs a text summary.