cognitive-doc-design
Design docs that reduce cognitive load. Trigger: writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs.
67
81%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
82%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 concise and includes an explicit trigger clause with good coverage of natural document types users would mention. Its main weakness is the lack of specific concrete actions—it says 'Design docs' but doesn't enumerate what that entails (e.g., structuring sections, creating templates, simplifying language). The distinctiveness could also be improved by clarifying what makes this different from general writing assistance.
Suggestions
Add specific concrete actions like 'Structures sections, creates templates, simplifies technical language, and organizes information hierarchy' to improve specificity.
Clarify what distinguishes this from general writing skills—e.g., mention specific techniques like 'progressive disclosure', 'scannable formatting', or 'audience-appropriate abstraction levels'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (docs/documentation) and hints at the approach ('reduce cognitive load'), but doesn't list concrete actions like 'create outlines', 'structure sections', 'add diagrams'. The phrase 'Design docs' is somewhat vague about what specific actions are performed. | 2 / 3 |
Completeness | Answers both 'what' ('Design docs that reduce cognitive load') and 'when' ('Trigger: writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs'). The explicit 'Trigger:' clause serves as a clear 'Use when' equivalent. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would actually say: 'guides', 'READMEs', 'RFCs', 'onboarding', 'architecture', and 'review-facing docs'. These cover a good range of common documentation types users would mention. | 3 / 3 |
Distinctiveness Conflict Risk | While the specific doc types (READMEs, RFCs, architecture docs) help narrow the scope, 'writing guides' and 'onboarding' are broad enough to potentially overlap with general writing or onboarding-specific skills. The 'reduce cognitive load' angle adds some distinctiveness but could still conflict with general technical writing skills. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
79%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-crafted skill that efficiently communicates documentation patterns through tables, templates, and concrete examples. Its strengths are conciseness and actionability—the markdown template and PR guidance are immediately usable. The main weakness is the lack of explicit validation steps (e.g., how to verify a doc meets the cognitive load criteria) and the missed opportunity to provide separate reference files for different doc types.
Suggestions
Add a brief validation checklist or feedback loop step, e.g., 'After drafting, verify: Can a reader find the answer in <10 seconds? Does each section pass the squint test (scannable at arm's length)?'
Consider splitting PR-specific templates and architecture doc examples into separate referenced files to improve progressive disclosure for this multi-context skill.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient. It avoids explaining what documentation is or why it matters in general terms. Every section delivers actionable patterns, structures, or commands without padding. The table format for critical patterns is especially token-efficient. | 3 / 3 |
Actionability | Provides a concrete, copy-paste-ready markdown template for documentation structure, specific PR documentation guidance with explicit reviewer-facing actions, and executable bash commands for checking markdown changes and PR stats. The patterns table gives clear, specific rules rather than vague advice. | 3 / 3 |
Workflow Clarity | The documentation shape template provides a clear sequence (quick path → details → checklist → next step), and the PR section gives ordered guidance. However, there are no explicit validation checkpoints or feedback loops for verifying documentation quality—e.g., no step to validate readability, check link integrity, or confirm the doc meets the patterns before finalizing. | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear sections and headings, but it's entirely self-contained with no references to external files for deeper guidance. For a documentation skill that covers PRs, architecture docs, onboarding, and READMEs, some content could benefit from being split into separate reference files (e.g., PR-specific templates, architecture doc examples). However, at ~70 lines this is borderline acceptable as a single file. | 2 / 3 |
Total | 10 / 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
- sergiodvillegas-art/gentle-ai
- Commit
3bfa934
- 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.