documentation-and-adrs
by addyosmanidocumentation-and-adrs helps agents write decision-focused technical documentation and ADRs. Use it to capture context, constraints, tradeoffs, rejected options, and consequences for architecture, APIs, infrastructure, auth, and feature changes. It is ideal when you need durable rationale for future engineers and agents, not just a polished summary.
This skill scores 78/100, which means it is a solid listing candidate with useful workflow guidance for agents and enough clarity for users to judge install value. It clearly targets decision documentation and ADR creation, giving agents a specific trigger and a better path than a generic prompt when context, trade-offs, and future maintenance matter.
- Clear trigger guidance for architectural decisions, API changes, feature shipping, and repeated explanations.
- Operationally useful ADR guidance that emphasizes context, constraints, trade-offs, and alternatives.
- Strong directory value because it helps agents produce documentation that future engineers can actually use.
- No install command, scripts, or support files, so users must rely on the SKILL.md workflow alone.
- The excerpt shows a truncated section and some placeholder markers, so edge-case completeness is harder to verify.
Overview of documentation-and-adrs skill
What the documentation-and-adrs skill does
The documentation-and-adrs skill helps an agent write decision-focused technical documentation, especially Architecture Decision Records (ADRs). Its real job is not “write more docs,” but “capture why a team chose this approach, what constraints mattered, and what alternatives were rejected.” That makes it useful when code alone will not explain future maintenance decisions.
Best-fit users and jobs-to-be-done
This skill is best for engineers, tech leads, architects, and teams doing Technical Writing around architecture, APIs, infrastructure, auth, data models, or user-facing feature changes. Use documentation-and-adrs when you need durable context for future engineers or agents, not just a polished explanation for today’s task.
What makes it different from a generic prompt
A normal prompt may produce a clean summary, but the documentation-and-adrs skill is oriented around decision records: context, constraints, options, tradeoffs, and consequences. That framing matters because most weak docs fail by describing the implementation while omitting the reasoning that future maintainers actually need.
When not to install it
Skip this skill if you only want inline code comments, lightweight README cleanup, or docs for throwaway prototypes. It is also a poor fit for obvious code paths where the implementation already communicates the intent and there is no meaningful decision history to preserve.
How to Use documentation-and-adrs skill
Install context and where to start reading
For documentation-and-adrs install, add the skill from the addyosmani/agent-skills repository, then read skills/documentation-and-adrs/SKILL.md first. This skill ships as a single guidance file, so there are no helper scripts or reference files to lean on. That means your input quality matters more than with a tool-backed skill.
If your environment supports skill installation, use:
npx skills add addyosmani/agent-skills --skill documentation-and-adrs
Then review:
skills/documentation-and-adrs/SKILL.md
What input the documentation-and-adrs skill needs
The skill works best when you provide the decision surface, not just the desired output format. Strong inputs usually include:
- the change being proposed
- affected systems or APIs
- constraints such as performance, compliance, cost, deadlines, or compatibility
- alternatives considered
- expected consequences and risks
- intended audience and output location, such as
docs/adr/ordocs/architecture/
Weak input: “Write an ADR for moving to GraphQL.”
Stronger input:
- Current state: REST API with versioning pain across mobile clients
- Decision needed: whether to adopt GraphQL for new product surfaces
- Constraints: keep existing REST endpoints for 12 months, small platform team, need field-level client flexibility
- Alternatives: improved REST conventions, tRPC, GraphQL gateway
- Decision owner: platform lead
- Output: ADR with status, context, decision, consequences, and rejected alternatives
How to prompt for better documentation-and-adrs usage
A good documentation-and-adrs usage prompt should ask for both structure and reasoning quality. A reliable pattern is:
- State the decision or doc type.
- Provide project context and constraints.
- Name the options considered.
- Ask the agent to surface tradeoffs, assumptions, and follow-up actions.
- Specify the target format.
Example prompt:
“Use the documentation-and-adrs skill to draft an ADR for choosing an authentication strategy for our B2B SaaS. Compare hosted auth, self-managed OAuth, and passkeys-first. Include context, constraints, decision drivers, rejected options, consequences, migration notes, and open questions. Audience is future backend and security engineers.”
Suggested workflow for real teams
Use this order for a practical documentation-and-adrs guide workflow:
- Gather facts from issues, PRs, architecture notes, and team chat.
- Ask the agent to extract decision drivers before drafting.
- Review the first draft for missing alternatives and unstated constraints.
- Turn the output into a repository doc or ADR with stable naming and location.
- Update the record once the decision is validated in production.
This skill is especially good for Technical Writing when paired with concrete source material. It is much weaker if you ask it to infer business or architectural rationale that has not been provided anywhere.
documentation-and-adrs skill FAQ
Is documentation-and-adrs for Technical Writing beginners?
Yes, if the beginner already has access to the facts behind the decision. The skill gives useful structure for ADRs and decision docs, but it does not replace technical judgment. Beginners often get the best results by supplying meeting notes, issue links, or a rough pros-and-cons list instead of asking for a document from nothing.
How is it different from asking for “write docs”?
Generic documentation prompts usually optimize for readability. documentation-and-adrs optimizes for maintainability of decisions: why this path was chosen, what constraints existed, and what future readers should know before changing it. That difference matters most for architecture, public APIs, and infrastructure choices.
What are the boundaries of this skill?
The skill is not a repo-wide documentation system, style linter, or doc generator with automation. It gives process and structure guidance, not scripts or templates enforced by tooling. If you need automatic doc syncing, standards enforcement, or publishing workflows, you will need other tools around it.
When should I not use documentation-and-adrs skill?
Do not use it for trivial implementation details, obvious refactors, duplicated code comments, or speculative prototypes with no lasting value. If the team has not made a real decision yet, use the skill to compare options, but do not pretend a final ADR exists before the decision is actually made.
How to Improve documentation-and-adrs skill
Give decision-grade inputs, not summary-grade inputs
The fastest way to improve documentation-and-adrs skill output is to provide evidence that supports a decision. Include rejected options, constraints, and expected consequences. Without those, the output will sound polished but generic. If possible, provide snippets from design docs, PR descriptions, RFCs, or incident reviews.
Watch for common failure modes
The most common problems are:
- repeating implementation details instead of documenting rationale
- listing alternatives without explaining why they lost
- omitting risks, migration costs, or operational consequences
- writing for today’s reviewers instead of future maintainers
If you see any of these, ask for a revision focused on “decision drivers, rejected alternatives, and downstream consequences.”
Iterate on structure after the first draft
After the first pass, ask the agent to tighten weak sections rather than rewrite everything. Good follow-ups include:
- “Make the tradeoffs more explicit.”
- “Add assumptions and what would change this decision.”
- “Separate immediate consequences from long-term maintenance impact.”
- “Rewrite for future engineers unfamiliar with this subsystem.”
Adapt the skill to your repo conventions
To make documentation-and-adrs for Technical Writing more useful, tell the agent your file naming, ADR format, and doc locations. For example, specify whether you use sequential ADRs like docs/adrs/0007-auth-strategy.md or topic-based docs under docs/architecture/. The closer your prompt matches your repository’s documentation conventions, the less cleanup you will need after generation.