jbvc/docs-architect
Creates comprehensive technical documentation from existing codebases. Analyzes architecture, design patterns, and implementation details to produce long-form technical manuals and ebooks. Use PROACTIVELY for system documentation, architecture guides, or technical deep-dives.
57
57%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
77%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 solid description that clearly communicates both what the skill does and when to use it. Its main strengths are the specific output types (technical manuals, ebooks) and explicit trigger clause. Weaknesses include moderate overlap risk with other documentation skills and missing some natural user trigger terms like 'document my code' or 'generate docs'.
Suggestions
Add more natural trigger terms users would say, such as 'document my code', 'generate docs', 'codebase documentation', 'API docs', or 'code walkthrough'.
Strengthen distinctiveness by emphasizing what differentiates this from simpler documentation tools—e.g., explicitly mention the long-form/comprehensive nature as a distinguishing factor and contrast with quick README or inline doc generation.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Analyzes architecture, design patterns, and implementation details' and 'produce long-form technical manuals and ebooks'. Also specifies the input ('existing codebases') and output types clearly. | 3 / 3 |
Completeness | Clearly answers both 'what' (creates technical documentation by analyzing codebases, architecture, design patterns) and 'when' ('Use PROACTIVELY for system documentation, architecture guides, or technical deep-dives'). The explicit 'Use ... for' clause provides clear trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes some relevant terms like 'technical documentation', 'architecture guides', 'technical deep-dives', 'ebooks', and 'technical manuals', but misses common user phrases like 'document my code', 'generate docs', 'API documentation', 'README', or 'codebase overview'. The term 'PROACTIVELY' is unusual and not a natural user trigger. | 2 / 3 |
Distinctiveness Conflict Risk | While it specifies long-form documentation from codebases, it could overlap with general code documentation skills, README generators, or API documentation tools. The focus on 'long-form technical manuals and ebooks' helps distinguish it somewhat, but 'technical documentation' is a broad category that could conflict with simpler doc-generation skills. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
20%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads more like a role description or persona prompt than actionable skill instructions. It is overwhelmingly verbose, explaining general documentation concepts Claude already understands, while providing zero concrete examples, commands, or executable guidance. The workflow has some structure but lacks validation steps and specificity needed for a complex multi-step documentation task.
Suggestions
Replace the abstract 'Core Competencies' and 'Best Practices' sections with concrete, executable steps—e.g., specific commands to analyze a codebase, a template with actual markdown structure, or example output snippets showing what a generated architecture section looks like.
Add validation checkpoints to the Documentation Process—e.g., 'After Discovery Phase, list all identified components and confirm with user before proceeding to Structuring Phase.'
Remove descriptions of concepts Claude already knows (what an executive summary is, what technical writing means, what system thinking is) and replace with project-specific patterns or templates.
Provide at least one concrete example showing input (e.g., a small codebase structure) and expected output (e.g., a sample architecture overview section) to make the skill actionable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Heavily verbose with extensive explanations of concepts Claude already knows (what technical writing is, what system thinking means, what an executive summary is). The 'Core Competencies' section is entirely self-descriptive fluff. Lists like 'Key Sections to Include' and 'Best Practices' describe general documentation knowledge that adds no novel value. | 1 / 3 |
Actionability | No concrete code, commands, or executable examples anywhere. The entire skill reads as an abstract description of what good documentation looks like rather than specific instructions for how to produce it. Phrases like 'Analyze codebase structure and dependencies' and 'Apply relevant best practices' are vague directives with no concrete implementation. | 1 / 3 |
Workflow Clarity | There is a three-phase process (Discovery, Structuring, Writing) with sub-steps listed, providing some sequential structure. However, there are no validation checkpoints, no feedback loops, no concrete verification steps, and no guidance on what to do when analysis reveals ambiguity or incomplete information. | 2 / 3 |
Progressive Disclosure | There is one reference to an external file (`resources/implementation-playbook.md`) which is good, but the main content is a monolithic wall of lists and descriptions that could be significantly trimmed or split. The reference is buried in the instructions rather than clearly signaled in a navigation section. | 2 / 3 |
Total | 6 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata.version' is missing | Warning |
Total | 10 / 11 Passed | |
Reviewed
Table of Contents