reverse-document

Generate missing design or architecture docs from existing implementation — works backwards from code and prototypes.

Quality

69%

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 ./.claude/skills/reverse-document/SKILL.md

Quality

Content

73%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 body is a strong, validation-rich workflow with an exemplary sufficiency gate, intent-clarification checkpoint, and provenance-stamping requirements that guard against fabrication. Its weaknesses are verbosity from triple-stating the workflow (phases, example session, protocol summary) and references to template files that are not part of the bundle.

Suggestions

Cut or merge the "Example Session" and "Collaborative Protocol" sections — both restate the eight phases already detailed in the Workflow; keeping just one condensed illustration would save ~50 lines.

Tighten the multi-paragraph blockquote rationales (e.g., the provenance and tier-resolution justifications) to one or two lines each; the rules are sound but repeated across phases.

Either include the `templates/*.md` files in the skill bundle (references/ directory) or inline the key template structure, since the skill's core output format currently depends on files not shipped with it.

Dimension	Reasoning	Score
Conciseness	The core phase guidance is dense and operational, but the "Example Session" (~35 lines) and "Collaborative Protocol" (~15 lines) sections restate the eight phases already detailed above them, and several multi-paragraph blockquotes repeat the same intent-inference rationale. This fits "mostly efficient but includes some unnecessary explanation or could be tightened" better than level 2, since no section explains concepts Claude already doesn't know and the padding is duplication rather than tutelage.	3 / 5
Actionability	Concrete argument format, per-engine path examples, an executable `!`bash` config-resolution command, template/output-path tables, copy-paste-ready provenance banner and metadata frontmatter, and full message templates. Minor gaps keep it below level 5: the referenced `templates/*.md` files are not present in the bundle, and most guidance is bracket-placeholder fill-in patterns rather than fully concrete examples.	4 / 5
Workflow Clarity	Eight explicitly sequenced phases with a hard sufficiency gate (Phase 3b: "Run this before Phase 4, and stop here if it fails"), a findings checkpoint requiring user clarification before drafting, mode-aware approval gates before any file write, explicit handling of unanswered questions, and defined follow-up. This matches the level-5 anchor: clear sequence, explicit validation steps, and feedback loops for error recovery.	5 / 5
Progressive Disclosure	A single-file skill with well-organized phase sections; all external references (`.claude/docs/workflow-modes.md`, `.claude/docs/automation-modes.md`, `.claude/docs/code-root-resolution.md`, `templates/*.md`) are one level deep and clearly signaled with explicit paths. Minor gaps: the redundant example-session and protocol sections are inlined where they could be trimmed or split, keeping it below level 5's ideally-split structure.	4 / 5
	Total	16 / 20 Passed

Description

53%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 clearly states what the skill does and occupies a distinctive niche, but it omits any "when to use" trigger guidance and misses the most natural trigger terms users would say. Adding a use-when clause and naming the concrete output types would lift it substantially.

Suggestions

Add an explicit trigger clause, e.g. "Use when a feature was built without a design doc, you inherited an undocumented codebase, or you need to formalize a prototype — the body already lists these triggers, so surface them in the description."

Include natural trigger terms users would actually say: "document existing code", "documentation", "GDD", "ADR", "concept doc".

Name the concrete output types (game design document, architecture decision record, concept document) instead of the generic "design or architecture docs".

Dimension	Reasoning	Score
Specificity	Names the domain ("design or architecture docs" from "existing implementation") and 1-2 concrete actions ("Generate missing... docs", "works backwards from code and prototypes"), but does not enumerate the supported outputs (GDD, ADR, concept doc). It falls short of the level-4 anchor, which requires several listed specific actions, and is well above level 2's generic-domain-only anchor.	3 / 5
Completeness	The "what" is clear and specific ("Generate missing design or architecture docs from existing implementation — works backwards from code and prototypes"), but there is no "Use when..." clause or equivalent explicit trigger guidance, which the judging guidelines cap at 3. It is not level 2 because the "what" is concrete rather than vague.	3 / 5
Trigger Term Quality	Contains relevant keywords ("design", "architecture", "docs", "implementation", "code", "prototypes") but misses common natural variations users would say, notably "document"/"documentation" as a verb, "GDD", "ADR", and "document existing code" — matching the level-3 anchor of relevant keywords missing synonyms rather than level 4's good-but-gapped coverage.	3 / 5
Distinctiveness Conflict Risk	"Works backwards from code and prototypes" carves a distinct reverse-documentation niche with little overlap risk against forward-design or general doc skills. It stops short of level 5 because the description lacks explicit distinct trigger phrases that fully separate it from adjacent documentation-generation skills.	4 / 5
	Total	13 / 20 Passed

Validation

87%

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 — 14 / 16 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	14 / 16 Passed

Repository: Donchitos/Claude-Code-Game-Studios
Path: .claude/skills/reverse-document/SKILL.md
Commit: b21fa0f

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.