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 placeholder with no substantive content. It repeats the skill name as its own trigger term, provides no concrete actions or capabilities, and lacks any 'Use when...' guidance. It would be nearly impossible for Claude to correctly select this skill from a pool of alternatives.
Suggestions
Add specific concrete actions the skill performs, e.g., 'Generates architecture documentation including system diagrams, component descriptions, data flow diagrams, and architecture decision records (ADRs).'
Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks to document system architecture, create architecture diagrams, write ADRs, describe system components, or produce technical design documents.'
Remove the duplicate trigger term and replace with diverse natural keywords users would actually say, such as 'system design doc', 'architecture overview', 'technical design', 'component diagram', 'infrastructure documentation'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description provides no concrete actions. It only names itself ('Architecture Doc Creator') and its category ('Technical Documentation') without describing what it actually does—no mention of specific actions like generating diagrams, documenting system components, creating architecture decision records, etc. | 1 / 3 |
Completeness | Neither 'what does this do' nor 'when should Claude use it' is meaningfully answered. There is no 'Use when...' clause, no explicit triggers, and no description of capabilities beyond the generic category label. | 1 / 3 |
Trigger Term Quality | The trigger terms are just the skill name repeated twice ('architecture doc creator, architecture doc creator'). There are no natural user keywords like 'system design', 'architecture diagram', 'technical documentation', 'ADR', 'component diagram', or other terms a user would naturally say. | 1 / 3 |
Distinctiveness Conflict Risk | The description is extremely generic—'Technical Documentation' could overlap with any documentation-related skill. There is nothing distinguishing this from other documentation skills, and the lack of specific triggers means it could easily conflict with or be confused for other skills. | 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 placeholder with no substantive content. It repeatedly names the skill topic ('architecture doc creator') without ever providing actionable guidance, templates, examples, or workflows for actually creating architecture documentation. It reads as auto-generated boilerplate that would provide zero value to Claude beyond what it already knows.
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.
Provide a step-by-step workflow: 1) Gather system context, 2) Identify components and boundaries, 3) Document interactions, 4) Validate completeness against a checklist — with explicit validation steps.
Include at least one complete, copy-paste-ready example of a generated architecture document for a sample system.
Remove all generic filler text ('This skill provides automated assistance...', 'Follows industry best practices...') and replace with specific, actionable instructions that Claude doesn't already know.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is entirely filler and boilerplate. It explains nothing Claude doesn't already know, repeats 'architecture doc creator' excessively, and provides zero domain-specific information. Every section restates the same vague idea without adding value. | 1 / 3 |
Actionability | There are no concrete steps, code examples, commands, templates, or executable guidance of any kind. The skill describes what it could do in abstract terms but never actually instructs Claude how to create an architecture document. | 1 / 3 |
Workflow Clarity | No workflow is defined. There are no sequenced steps, no validation checkpoints, and no process for creating architecture documentation. The 'Capabilities' section lists vague promises rather than actionable procedures. | 1 / 3 |
Progressive Disclosure | The content is a monolithic block of generic text with no references to supporting files, no structured navigation, and no separation of overview from detail. There are no bundle files to reference either, but the content itself lacks any organizational depth. | 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
3a2d27d
- 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.