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. Part of cursor-rules-java project
80
75%
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/031-architecture-adr-functional-requirements/SKILL.mdQuality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong skill description that clearly defines its niche at the intersection of ADR creation and functional requirements for CLI/API projects. It provides explicit 'Use when' guidance with multiple trigger scenarios and example phrases, making it easy for Claude to select appropriately. The description is specific, well-structured, and distinctive enough to avoid conflicts with other skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'conversational discovery to create Architectural Decision Records (ADRs)', 'functional requirements covering CLI, REST/HTTP APIs', 'document command-line or HTTP service architecture', 'capture functional requirements', 'design interfaces with documented decisions'. These are concrete and domain-specific. | 3 / 3 |
Completeness | Clearly answers both 'what' (facilitates conversational discovery to create ADRs for functional requirements covering CLI, REST/HTTP APIs) and 'when' (explicit 'Use when' clause with multiple trigger scenarios, plus a 'This should trigger for' section with example phrases). | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'ADR', 'Architectural Decision Records', 'functional requirements', 'CLI', 'REST/HTTP APIs', 'command-line', 'HTTP service architecture', 'API projects'. Also provides explicit trigger phrases like 'Create ADR for functional requirements', 'Document functional requirements', 'Capture functional requirements'. Good coverage of natural variations. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive niche combining ADRs specifically for functional requirements of CLI and REST/HTTP APIs. The combination of 'ADR' + 'functional requirements' + 'CLI/API' creates a very specific trigger profile unlikely to conflict with general documentation or coding skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a reasonable high-level framework for interactive ADR creation with appropriate constraints around conversational pacing and user confirmation. However, it lacks concrete examples (sample questions, sample ADR output snippets, or interaction patterns) that would make it truly actionable, and it contains some redundancy between the description, 'What is covered,' and 'When to use' sections. The heavy reliance on an external reference file without providing substantive quick-start content in the SKILL.md itself limits its standalone usefulness.
Suggestions
Add 1-2 concrete example discovery questions and a brief sample ADR output snippet to make the skill actionable without requiring the reference file for basic usage.
Remove the 'What is covered in this Skill?' bullet list and 'When to use this skill' section, as they largely duplicate the opening paragraph and YAML description—use that space for examples instead.
Add an explicit feedback loop in the workflow for when the user rejects the summary (e.g., 'If user requests changes: revisit specific discovery areas, update summary, re-validate').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill includes some unnecessary explanation (e.g., 'What is covered in this Skill?' bullet list largely restates the workflow and description). The 'When to use this skill' section repeats the trigger phrases from the description. However, it's not egregiously verbose—mostly functional content with some redundancy. | 2 / 3 |
Actionability | The skill provides a clear workflow structure and specific constraints (run `date`, read a specific reference file), but lacks concrete examples of discovery questions, ADR output format, or sample interactions. The actual actionable content is deferred entirely to the reference file, making the SKILL.md itself more of an abstract process description than executable guidance. | 2 / 3 |
Workflow Clarity | The workflow has a clear sequence (get date → read reference → discover → generate), and includes validation checkpoints (confirm with user before generating). However, the steps are fairly high-level and lack specifics about what to do if the user rejects the summary, how to handle ambiguous scope, or concrete error recovery paths. The validation step is present but the feedback loop is implicit rather than explicit. | 2 / 3 |
Progressive Disclosure | The skill correctly references a single external file for detailed guidance, which is good one-level-deep disclosure. However, no bundle files were provided to verify the reference exists, and the SKILL.md itself is somewhat thin—it defers almost all substantive content to the reference file while also including a redundant 'What is covered' section that could have been used for a more useful quick-start summary. | 2 / 3 |
Total | 8 / 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.
762cb86
Table of Contents
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.