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 skills add jamestexas/agents --skill design-doc-reviewgit clone --depth 1 https://github.com/jamestexas/agentsWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/jamestexas/agents/design-doc-review)<a href="https://agentmods.dev/skills/jamestexas/agents/design-doc-review"><img src="https://agentmods.dev/badge/skills/jamestexas/agents/design-doc-review/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/jamestexas/agents/design-doc-review"><img src="https://agentmods.dev/badge/skills/jamestexas/agents/design-doc-review.svg" alt="Reviewed on agentmods" width="80" height="20"></a>What 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.1 | $0.00144 | $0.03230 |
| Opus 5.5 | $0.00058 | $0.01292 |
| Sonnet 5.5 | $0.00029 | $0.00646 |
| Haiku 4.5 | $0.00014 | $0.00323 |
Grade A, and why
design-doc-review 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 1mo 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 — 243 lines — stays where its author put it; the contents beside it link to each section on GitHub.
design-doc-review — review the decision, while it is still cheap to change
The spine, one question:
What decision am I being asked to ratify, how expensive is it to unmake, and what is the most load-bearing thing this doc does not say?
A design doc is the last point where a mistake costs words instead of quarters. Code review asks is this built right; design review asks is this the right thing to build, and will this shape survive contact with reality — while the answer is still a paragraph, not a schema, a wire format, a public API, or an org dependency. Your job is to find the expensive-to-reverse errors before they calcify. A doc can be beautifully written and still be the wrong call; fluency is not soundness.
This skill audits whether the decision holds. It is not a copy-edit, not a "do I like this" reaction, and not a code review of the eventual implementation. A good design-review comment is not "this sentence is unclear" — it is "what would have to be true for the rejected alternative to win?" or "this locks in a data model we can't migrate — is that intentional?"
When to use
- Before a design-review meeting or before you approve/+1 an RFC/ADR/one-pager.
- When a doc reads well but you can't articulate why you trust (or distrust) it.
- When you are the author and want to pre-empt the review — run it on your own doc and answer the unasked question before someone else asks it.
- Upstream of
problem-decomposer/work-scope: review the decision before you break it into shippable units, not after.
The weighting rule (this is also the calibration)
Match scrutiny to reversibility × blast radius. Spend your review budget on the one-way doors — the choices that are expensive or impossible to undo (persisted data models, published wire formats and APIs, a vendor or framework lock-in, an org/ownership boundary, anything a customer will depend on). Skim the two-way doors — choices a later PR can reverse cheaply. Most weak reviews spend their energy inversely: bikeshedding the reversible, waving through the irreversible. The severity ladder below is this rule made mechanical.
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.
- 1mo ago First seen · 243 lines · 144 tokens per session scan A 2d9861c75f8f
design-doc-review is a skill published in the GitHub repository jamestexas/agents (2 stars, last pushed 23d ago), licensed Apache-2.0. It adds 144 tokens to every session and 3,230 once invoked, about $0.0006 per session on Opus 5.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-09-11.
Other skills, from other repositories
soul-grader
Use when grading, reviewing, rewriting, or approving a Hermes Agent SOUL.md. Uses the SOUL.md field-guide research artifacts as the only normative source for what makes a good SOUL.md.
markdown-ui-dsl
Create low-fidelity, text-based wireframes using the Markdown-UI Domain Specific Language (DSL).
research-dspy
Build complex AI systems with declarative programming, optimize prompts automatically, create modular RAG systems and agents with DSPy - Stanford NLP's framework for systematic LM programming.
research-instructor
Extract structured data from LLM responses with Pydantic validation, retry failed extractions automatically, parse complex JSON with type safety, and stream partial results with Instructor - battle...
research-guidance
Control LLM output with regex and grammars, guarantee valid JSON/XML/code generation, enforce structured formats, and build multi-step workflows with Guidance - Microsoft Research's constrained gen...
happiness-skill
A Chinese-language guide to happiness based on reducing unmet wants, focusing on the present, and treating happiness as a trainable skill.