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 vinvcn/addyosmani-agent-skills-zh --skill documentation-and-adrsgit clone --depth 1 https://github.com/vinvcn/addyosmani-agent-skills-zhWrote 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/vinvcn/addyosmani-agent-skills-zh/documentation-and-adrs)<a href="https://agentmods.dev/skills/vinvcn/addyosmani-agent-skills-zh/documentation-and-adrs"><img src="https://agentmods.dev/badge/skills/vinvcn/addyosmani-agent-skills-zh/documentation-and-adrs/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/vinvcn/addyosmani-agent-skills-zh/documentation-and-adrs"><img src="https://agentmods.dev/badge/skills/vinvcn/addyosmani-agent-skills-zh/documentation-and-adrs.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.00046 | $0.02107 |
| Opus 5 | $0.00023 | $0.01053 |
| Sonnet 5 | $0.00009 | $0.00421 |
| Haiku 4.5 | $0.00005 | $0.00211 |
Grade A, and why
documentation-and-adrs 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 12d 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 — 279 lines — stays where its author put it; the contents beside it link to each section on GitHub.
文档和 ADR
概览
记录决策，而不只是记录代码。最有价值的文档会捕捉 why：促成某个决策的上下文、约束和权衡。代码展示构建了 what；文档解释 why it was built this way，以及 what alternatives were considered。这些上下文对未来在代码库中工作的工程师和 agent 都很重要。
何时使用
- 做出重要架构决策
- 在多个竞争方案之间做选择
- 添加或变更公开 API
- 发布会改变用户可见行为的功能
- 让新的团队成员（或 agent）熟悉项目
- 当你发现自己反复解释同一件事时
不应使用的情况： 不要记录显而易见的代码。不要添加只是复述代码本身的注释。不要为一次性原型编写文档。
Architecture Decision Records (ADRs，架构决策记录)
ADR 捕捉重大技术决策背后的推理。它们是你能写出的最高价值文档。
何时编写 ADR
- 选择框架、库或主要依赖
- 设计数据模型或数据库 schema
- 选择认证策略
- 决定 API 架构（REST vs. GraphQL vs. tRPC）
- 在构建工具、托管平台或基础设施之间做选择
- 任何逆转成本高的决策
ADR 模板
将 ADR 存放在 docs/decisions/，并使用连续编号：
# ADR-001: Use PostgreSQL for primary database
## Status
Accepted | Superseded by ADR-XXX | Deprecated
## Date
2025-01-15
## Context
We need a primary database for the task management application. Key requirements:
- Relational data model (users, tasks, teams with relationships)
- ACID transactions for task state changes
- Support for full-text search on task content
- Managed hosting available (for small team, limited ops capacity)
## Decision
Use PostgreSQL with Prisma ORM.
## Alternatives Considered
### MongoDB
- Pros: Flexible schema, easy to start with
- Cons: Our data is inherently relational; would need to manage relationships manually
- Rejected: Relational data in a document store leads to complex joins or data duplication
### SQLite
- Pros: Zero configuration, embedded, fast for reads
- Cons: Limited concurrent write support, no managed hosting for production
- Rejected: Not suitable for multi-user web application in production
### MySQL
- Pros: Mature, widely supported
- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling
- Rejected: PostgreSQL is the better fit for our feature requirements
## Consequences
- Prisma provides type-safe database access and migration management
- We can use PostgreSQL's full-text search instead of adding Elasticsearch
- Team needs PostgreSQL knowledge (standard skill, low risk)
- Hosting on managed service (Supabase, Neon, or RDS)
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.
- 12d ago First seen · 279 lines · 46 tokens per session scan A 200721f1da60
documentation-and-adrs is a skill published in the GitHub repository vinvcn/addyosmani-agent-skills-zh (31 stars, last pushed 4mo ago), licensed MIT. It adds 46 tokens to every session and 2,107 once invoked, about $0.0002 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-30.
Other skills, from other repositories
test-driven-development
Drives development with tests via Red-Green-Refactor and the Prove-It pattern, with hard rules against weakening assertions or faking green suites. Use when implementing any logic, fixing any bug, or changing any behavior. Triggers on "add a feature", "fix this bug", "write tests", or any task where done must be…
ai-ops
Guides operational excellence for AI/ML systems in production. Use when deploying models, managing inference infrastructure, monitoring model drift, or maintaining AI-powered features. Use when you need reliable, observable, and governable machine learning systems.
ci-cd-and-automation
Automates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies.
context-engineering
Optimizes agent context setup. Use when starting a new session, when agent output quality degrades, when switching between tasks, or when you need to configure rules files and context for a project.
data-engineering
Guides data pipeline design, ETL/ELT workflows, schema evolution, and data quality assurance. Use when building data pipelines, designing data warehouses, migrating schemas, or ensuring data integrity across systems. Use when you need reliable, testable, and observable data flows.
debugging-and-error-recovery
Guides systematic root-cause debugging with hard rules against guess-fixes and symptom suppression. Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error. Triggers on "this is broken", "tests are failing", "why doesn't this work", or any error output.