architecture-doc-creator
Architecture Doc Creator - Auto-activating skill for Technical Documentation. Triggers on: architecture doc creator, architecture doc creator Part of the Technical Documentation skill category.
33
0%
Does it follow best practices?
Impact
93%
1.01xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./planned-skills/generated/17-technical-docs/architecture-doc-creator/SKILL.mdQuality
Discovery
0%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 description is essentially a title and category label with no substantive content. It lacks concrete actions, natural trigger terms, explicit usage guidance, and any distinguishing detail that would help Claude select it appropriately from a pool of skills. It scores at the lowest level across all dimensions.
Suggestions
Add specific concrete actions the skill performs, e.g., 'Generates architecture documentation including system diagrams, component descriptions, data flow overviews, and design decision records.'
Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks to create architecture docs, system design documentation, technical architecture overviews, component diagrams, or C4 model documents.'
Remove the duplicate trigger term and expand with natural variations users would actually say, such as 'architecture document', 'system design doc', 'technical architecture', 'design documentation', '.md architecture file'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names a domain ('Technical Documentation') and a label ('Architecture Doc Creator') but does not describe any concrete actions like 'generates architecture diagrams', 'documents system components', or 'creates design decision records'. It is essentially a title repeated with no actionable detail. | 1 / 3 |
Completeness | The description fails to answer 'what does this do' beyond the vague label and completely lacks an explicit 'when should Claude use it' clause. There is no 'Use when...' guidance, which per the rubric should cap completeness at 2 at best, but here even the 'what' is missing, warranting a 1. | 1 / 3 |
Trigger Term Quality | The only trigger terms listed are 'architecture doc creator' repeated twice. These are not natural phrases a user would say; users are more likely to say 'create architecture document', 'system design doc', 'technical architecture', 'design documentation', etc. Coverage of natural variations is essentially zero. | 1 / 3 |
Distinctiveness Conflict Risk | The description is extremely generic — 'Technical Documentation' could overlap with any documentation-related skill. There is nothing that carves out a clear niche distinguishing this from other documentation skills (e.g., API docs, README generators, design docs). | 1 / 3 |
Total | 4 / 12 Passed |
Implementation
0%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is an empty shell with no substantive content. It consists entirely of auto-generated boilerplate that describes what the skill would do without actually providing any instructions, examples, templates, or concrete guidance for creating architecture documentation. It fails on every dimension of the rubric.
Suggestions
Add a concrete architecture document template (e.g., sections like System Overview, Component Diagram, Data Flow, Technology Stack, Deployment Architecture) with example content for each section.
Include executable examples such as a Mermaid diagram code block for architecture diagrams, or a complete sample architecture doc for a reference application.
Define a clear workflow: 1) Gather system context, 2) Identify components and boundaries, 3) Draft sections with specific templates, 4) Validate completeness against a checklist.
Remove all meta-description sections (When to Use, Example Triggers, Capabilities) and replace with actual actionable content that teaches how to create architecture documentation.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is entirely filler and meta-description. It explains what the skill does in abstract terms without providing any actual instructions, code, or concrete guidance. Every section restates the same vague information about 'architecture doc creator' without adding substance. | 1 / 3 |
Actionability | There is zero actionable content—no concrete steps, no code examples, no templates, no commands. The skill describes itself rather than instructing Claude on how to actually create architecture documentation. | 1 / 3 |
Workflow Clarity | No workflow is defined. There are no steps, no sequence, no validation checkpoints. The 'Capabilities' section vaguely mentions 'step-by-step guidance' but none is actually provided. | 1 / 3 |
Progressive Disclosure | The content is a flat, repetitive structure with no references to detailed materials, no linked resources, and no meaningful organization of content across sections. The sections that exist are boilerplate with no real information hierarchy. | 1 / 3 |
Total | 4 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Commit
c8a915c
- 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.