Name: docs-architect
Rating: 47.2 (1 reviews)
Author: administrakt0r

docs-architect

Creates comprehensive technical documentation from existing codebases. Analyzes architecture, design patterns, and implementation details to produce long-form technical manuals and ebooks.

Quality

50%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/AI-Agents-Safe-Coding-Skills/skills/docs-architect/SKILL.md

The canonical home for this skill is docs-architect in administrakt0r/AI-Agents-Safe-Coding-Skills

Quality

Content

42%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill body is well-organized but leans on abstract competency lists and generic instructions rather than concrete, executable guidance. It needs real templates/commands, validation steps, and a correctly-signaled reference to lift its scores.

Suggestions

Replace generic instructions ('Apply relevant best practices') with concrete, copy-paste-ready templates such as a documentation outline, a chapter scaffold, or example diagram descriptions.

Add explicit validation checkpoints to the Documentation Process, e.g. 'After structuring, confirm every Key Section is mapped; before finishing, verify cross-references resolve.'

Fix and clearly signal the external reference path (the body says resources/ but the bundle convention is references/), and move the lengthy Key Sections list into that referenced file.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient bullet lists, but generic filler like 'Clarify goals, constraints, and required inputs' and 'Apply relevant best practices and validate outcomes' restates what Claude already knows and could be trimmed.	3 / 5
Actionability	Guidance is largely abstract — 'Apply relevant best practices', 'Provide actionable steps and verification' — with no executable commands, templates, or concrete examples; the sections describe what to include rather than how to execute.	2 / 5
Workflow Clarity	The Documentation Process offers a clear Discovery/Structuring/Writing sequence with sub-steps, but validation checkpoints are absent or only implicit.	3 / 5
Progressive Disclosure	Section headers provide some structure and a single external reference exists, but it is vaguely signaled ('If detailed examples are required, open resources/implementation-playbook.md') with a path that does not match a real bundle directory, and content that could live in separate files is inlined.	3 / 5
	Total	11 / 20 Passed

Description

58%Weight 40%Scale 1-5

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 conveys a clear, specific purpose with concrete actions but omits any explicit trigger guidance for when Claude should invoke it. Adding a 'Use when...' clause would raise completeness and trigger-term quality.

Suggestions

Append an explicit trigger clause, e.g. 'Use when the user asks to document a codebase, write a technical manual or ebook, or produce architecture documentation.'

Add natural user phrasings and synonyms such as 'write docs', 'document this code', or 'create a technical guide' to broaden trigger-term coverage.

Tighten distinctiveness by contrasting with general writing skills, e.g. specify 'from existing source code' rather than 'from existing codebases'.

Dimension	Reasoning	Score
Specificity	Names the domain and several concrete actions ('Analyzes architecture, design patterns, and implementation details', 'produce long-form technical manuals and ebooks'), with only minor coverage gaps.	4 / 5
Completeness	It clearly states what the skill does but provides no 'when to use it' trigger clause; per the rubric a missing 'Use when...' clause caps completeness at 3.	3 / 5
Trigger Term Quality	Relevant keywords like 'technical documentation', 'codebases', and 'architecture' are present, but natural user phrasings ('write docs', 'document this code') and synonyms are missing.	3 / 5
Distinctiveness Conflict Risk	The long-form technical documentation-from-codebases niche is mostly distinct with only minor overlap risk against closely related writing skills.	4 / 5
	Total	14 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: plugins/AI-Agents-Safe-Coding-Skills/skills/docs-architect/SKILL.md
Commit: 57c135b

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.