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.

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable with concrete templates and a clear verification checklist, but it is a longish single-file monolith whose full boilerplate templates could be factored into reference files to improve token efficiency and navigation.

Suggestions

Move the full README, changelog, and OpenAPI templates into reference files and link to them from the body to reduce inline length and improve progressive disclosure.

Trim the longest templates in-body to minimal skeletons, keeping only the structural essentials and pointing to references for the rest.

Consider a short "Quick start" section up front that points to the most common task before the detailed sections.

Dimension	Reasoning	Score
Conciseness	The body avoids explaining basic concepts and is well-structured, but at ~275 lines it embeds several full copy-paste templates (ADR, README, changelog, OpenAPI) that not every invocation needs and could be trimmed or split out.	2 / 3
Actionability	Concrete, copy-paste-ready templates and code blocks (ADR-001 example, README structure, good/bad comment examples, OpenAPI snippet) give specific executable guidance throughout.	3 / 3
Workflow Clarity	A "Verification" checklist provides explicit checkpoints, the ADR lifecycle is sequenced (PROPOSED → ACCEPTED → SUPERSEDED), and "When NOT to use" guidance bounds the workflow; documentation is low-risk so heavy feedback loops are not required.	3 / 3
Progressive Disclosure	There are no bundle files and the skill is a single well-organized file with no nested references, but its length and the inline full templates (README, changelog, OpenAPI) are content that could be split into reference files for cleaner discovery.	2 / 3
	Total	10 / 12 Passed

Description

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 cleanly answers both what and when with a natural trigger clause, but its capability list and trigger coverage are only moderately specific, leaving some overlap with general coding skills.

Suggestions

Lead with more concrete verbs, e.g. "Writes ADRs, maintains READMEs and changelogs, and documents public APIs," to raise specificity.

Add natural trigger terms users would say (ADRs, decision records, README, changelog) alongside the current triggers.

Tighten the broad triggers ("changing public APIs, shipping features") toward the distinctive decision-and-documentation niche to reduce conflict risk.

Dimension	Reasoning	Score
Specificity	"Records decisions and documentation" names the domain and a couple of actions but does not enumerate multiple concrete actions (e.g. writes ADRs, documents APIs, maintains changelogs) at the level of the top anchor.	2 / 3
Completeness	It states what the skill does ("Records decisions and documentation") and gives an explicit "Use when..." clause covering several triggers, satisfying both what and when.	3 / 3
Trigger Term Quality	Triggers like "making architectural decisions, changing public APIs, shipping features" are natural phrases users would say, but coverage misses common variations such as ADRs, READMEs, or changelogs that round out the niche.	2 / 3
Distinctiveness Conflict Risk	The architectural-decisions/ADR niche is reasonably distinct, but "changing public APIs, shipping features" is broad enough to overlap with general coding or feature-development skills.	2 / 3
	Total	9 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: addyosmani/agent-skills
Commit: 8c65303

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

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.