031-architecture-adr-functional-requirements

Facilitates conversational discovery to create Architectural Decision Records (ADRs) for functional requirements covering CLI, REST/HTTP APIs, or both. Use when the user wants to document command-line or HTTP service architecture, capture functional requirements, create ADRs for CLI or API projects, or design interfaces with documented decisions. This should trigger for requests such as Create ADR for functional requirements; Document functional requirements; Capture functional requirements; Generate functional requirements in an ADR; Decide CLI versus REST functional requirements for an ADR. Part of Plinth Toolkit

Quality

77%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/031-architecture-adr-functional-requirements/SKILL.md

Quality

Content

71%Weight 40%Scale 1-5

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

The body is a well-structured overview with clean progressive disclosure and actionable, conversational guidance anchored by concrete commands, file paths, and validation gates. The chief weakness is redundancy between the 'When to use'/'Constraints' sections and the description/workflow steps, which inflates the token budget without adding information.

Suggestions

Remove the 'When to use this skill' section — its five bullets duplicate the trigger phrases already in the frontmatter description.

Consolidate the 'Constraints' bullets into the corresponding Workflow steps (e.g. move 'Never ask all discovery questions at once' and 'Validate summary with user' into Step 2) to eliminate repetition.

Add an explicit recovery loop for Step 2: when the user's validation of the summary fails, state that you should revise based on their corrections and re-validate before proposing ADR generation.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient and avoids explaining concepts Claude already knows, but it carries noticeable redundancy: the 'When to use this skill' list duplicates the description's triggers and the 'Constraints' section repeats the Workflow step constraints ('Never ask all discovery questions at once', 'Validate summary with user').	3 / 5
Actionability	Provides concrete, executable guidance for an instruction-only skill: a specific command ('Use the local shell `date` command'), an explicit file path ('Load references/031-architecture-adr-functional-requirements.md'), and exact dialogue ('Does this accurately capture your requirements?'), with the detailed discovery content correctly deferred to the reference.	4 / 5
Workflow Clarity	The 0–3 workflow is clearly sequenced with an explicit validation checkpoint ('Validate summary with user') and a confirmation gate before ADR generation ('Only after user confirms proceed'), but it lacks an explicit error-recovery loop for when the summary is rejected.	4 / 5
Progressive Disclosure	The body is a concise overview that points to a single well-signaled, one-level-deep reference (references/031-architecture-adr-functional-requirements.md, verified to exist) linked both inline in the workflow and in a dedicated Reference section, keeping content appropriately split and easy to navigate.	5 / 5
	Total	16 / 20 Passed

Description

83%Weight 40%Scale 1-5

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 is strong: it clearly states the skill's purpose and provides explicit, natural trigger phrases covering both 'what' and 'when'. Its main limitation is that the enumerated actions are mostly synonymous variants of a single core task rather than a breadth of distinct capabilities.

Dimension	Reasoning	Score
Specificity	Lists several specific actions ('create Architectural Decision Records', 'document command-line or HTTP service architecture', 'capture functional requirements', 'design interfaces with documented decisions', 'Decide CLI versus REST') but they are largely synonymous variants of one core task rather than distinct concrete operations.	4 / 5
Completeness	Explicitly answers both 'what' ('Facilitates conversational discovery to create Architectural Decision Records (ADRs) for functional requirements covering CLI, REST/HTTP APIs, or both') and 'when' ('Use when...', 'This should trigger for requests such as...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Provides five natural trigger phrases a user would actually say ('Create ADR for functional requirements', 'Document/Capture/Generate functional requirements', 'Decide CLI versus REST functional requirements for an ADR'), giving good keyword coverage though few synonyms beyond these.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (ADRs for functional requirements across CLI/REST, 'Part of Plinth Toolkit') with distinct triggers, though there is minor overlap risk with general architecture or requirements-gathering skills.	4 / 5
	Total	17 / 20 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: jabrena/plinth
Path: skills/031-architecture-adr-functional-requirements/SKILL.md
Commit: 05bf9d1

Reviewed: 12 minutes 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.