documentation-and-adrs
Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.
50
54%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/documentation-and-adrs/SKILL.mdQuality
Discovery
67%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description has a solid structure with an explicit 'Use when...' clause that covers multiple trigger scenarios, which is its strongest aspect. However, the core capability statement 'records decisions and documentation' is somewhat vague and could be more specific about the concrete outputs (e.g., ADRs, decision logs). The trigger terms could be expanded to include more natural variations users might use.
Suggestions
Make the capability statement more specific by listing concrete outputs, e.g., 'Creates Architecture Decision Records (ADRs), API changelogs, and feature documentation'.
Add more natural trigger terms users might say, such as 'ADR', 'decision record', 'design doc', 'RFC', 'changelog', or 'migration guide'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (decisions and documentation) and lists some actions (architectural decisions, changing public APIs, shipping features, recording context), but the core action 'records decisions and documentation' is somewhat generic and doesn't specify concrete formats or outputs like 'creates ADRs, writes changelogs, generates API migration guides'. | 2 / 3 |
Completeness | Clearly answers both 'what' (records decisions and documentation) and 'when' with an explicit 'Use when...' clause listing four specific trigger scenarios: architectural decisions, changing public APIs, shipping features, and recording context for future engineers. | 3 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'architectural decisions', 'public APIs', 'shipping features', and 'record context', but misses common natural terms users might say such as 'ADR', 'decision record', 'changelog', 'design doc', 'RFC', or 'documentation update'. | 2 / 3 |
Distinctiveness Conflict Risk | The term 'documentation' is quite broad and could overlap with other documentation-related skills (e.g., API docs, README generation, code comments). However, the focus on 'decisions' and 'architectural' context provides some distinctiveness that narrows the scope. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
42%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill provides excellent concrete examples and templates (ADR template, code commenting examples, README structure) that are immediately actionable. However, it is far too verbose for a skill file — it explains many concepts Claude already understands (commenting best practices, README conventions, changelog format) and packs everything into a single monolithic document that would benefit greatly from being split into focused sub-files.
Suggestions
Reduce content by 50-60%: remove the 'Common Rationalizations' table, the 'Red Flags' list, the 'When NOT to Comment' section, and explanations of basic concepts like changelog format and README structure that Claude already knows.
Split into focused sub-files: keep SKILL.md as a concise overview with links to separate files like ADR_TEMPLATE.md, API_DOCS.md, and README_TEMPLATE.md for the detailed templates and examples.
Add a brief workflow sequence at the top: e.g., '1. Identify decision type → 2. Choose template → 3. Write doc → 4. Verify with checklist' to give a clear process rather than a reference dump.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~200+ lines, explaining many concepts Claude already knows well (what ADRs are, when to comment code, README structure, changelog format, what a TODO comment is). The 'Common Rationalizations' table and much of the inline documentation section teach basic software engineering practices rather than providing novel, actionable guidance. | 1 / 3 |
Actionability | The skill provides fully concrete, copy-paste-ready templates and examples: a complete ADR template with realistic content, TypeScript code examples showing good vs bad commenting, OpenAPI YAML, README structure, and changelog format. Every section includes executable or directly usable artifacts. | 3 / 3 |
Workflow Clarity | The ADR lifecycle (PROPOSED → ACCEPTED → SUPERSEDED/DEPRECATED) is clearly stated, and the verification checklist at the end provides validation. However, the overall workflow for when and how to create documentation is more of a reference guide than a sequenced process — there's no clear step-by-step workflow with checkpoints for the documentation creation process itself. | 2 / 3 |
Progressive Disclosure | The entire skill is a monolithic wall of text with no references to external files and no bundle files. Content covering ADRs, inline docs, API docs, READMEs, changelogs, and agent documentation could easily be split into separate referenced files. Everything is inlined in one long document with no progressive disclosure structure. | 1 / 3 |
Total | 7 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- addyosmani/agent-skills
- Commit
f17c6e8
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.