reverse-documentation

Automatically generate comprehensive documentation for Rust and TypeScript codebases by analyzing code structure, patterns, and relationships. Supports trait-based patterns, async operations, React components, and Next.js applications.

Quality

35%

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 ./.github/skills/reverse-documentation/SKILL.md

Quality

Content

20%

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 a long, descriptive overview that restates Claude's existing knowledge and offers little executable guidance, with a clear but vaguely-validated workflow and no progressive disclosure to separate bundle files.

Suggestions

Cut the conceptual restatements (what traits/hooks/useState are) and the redundant 'Core concepts' vs 'Capabilities' vs 'Best practices' overlap; keep only what Claude would not already infer about this specific codebase.

Replace abstract phase descriptions with concrete, executable steps (e.g. actual commands or tool invocations for discovery, parsing, and validation) so the guidance is actionable rather than descriptive.

Move detailed Rust/TypeScript capability catalogs and EdgeQuake-specific patterns into separate reference files (e.g. references/rust-patterns.md, references/ts-patterns.md) and link to them from a lean overview, adding a concrete validation command to the workflow.

Dimension	Reasoning	Score
Conciseness	The ~290-line body re-explains concepts Claude already knows (what traits, generics, lifetimes, useState/useReducer/Context API, and React component lifecycles are) and repeats the same material across 'Core concepts', 'Capabilities', and 'Best practices', with generic platitudes like 'Document all public APIs' padding the token budget.	1 / 3
Actionability	The body is almost entirely descriptive ('the AI assistant will: Discovery Phase ... Analysis Phase ...') with no executable code, commands, or scripts; the only concrete-ish element is an illustrative YAML config block and natural-language example prompts, so it describes rather than instructs.	1 / 3
Workflow Clarity	A clear five-phase sequence is listed (Discovery, Analysis, Understanding, Generation, Validation) and a Validation Phase is named, but the validation checkpoint is vague ('Verify examples compile and documentation is complete') with no concrete command or feedback loop.	2 / 3
Progressive Disclosure	The file is well-organized into sections, but no bundle files exist (references/, scripts/, assets/ are absent) and all detailed capability lists and EdgeQuake-specific patterns are inline in a single monolithic document rather than split into one-level-deep reference files.	2 / 3
	Total	6 / 12 Passed

Description

50%

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 names a specific language/framework niche, but it omits any 'Use when...' trigger guidance and relies on a single main action, leaving it at the middle level across all dimensions.

Suggestions

Add an explicit 'Use when...' clause with natural trigger phrases, e.g. 'Use when the user asks to document Rust crates, React components, custom hooks, or Next.js apps, or wants API/architecture docs generated from code.'

Enumerate several concrete actions (e.g. 'generate API references, architecture diagrams, READMEs, and migration guides') rather than a single 'generate comprehensive documentation' action.

Include common user-facing keyword variations such as 'code docs', 'API docs', and 'document my code' to broaden natural trigger coverage.

Dimension	Reasoning	Score
Specificity	The description names the domain ('Rust and TypeScript codebases') and one main action ('Automatically generate comprehensive documentation ... by analyzing code structure, patterns, and relationships') plus supported patterns, but it does not enumerate multiple distinct concrete actions the way the level-3 anchor does.	2 / 3
Completeness	It clearly answers 'what' (generate documentation by analyzing structure, patterns, relationships) but provides no 'Use when...' clause or equivalent explicit trigger guidance, which per the rubric caps completeness at 2.	2 / 3
Trigger Term Quality	Natural terms a user would say are present ('documentation', 'Rust', 'TypeScript', 'React components', 'Next.js'), but coverage lacks common variations ('API docs', 'code docs', 'document my code') and mixes in technical jargon ('trait-based patterns', 'async operations') without an explicit 'Use when' framing.	2 / 3
Distinctiveness Conflict Risk	The Rust/TypeScript plus named-frameworks niche is somewhat specific, but 'documentation generation' is a broad concept that could overlap with general code-documentation skills, and the absence of explicit distinct triggers keeps it from level 3.	2 / 3
	Total	8 / 12 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
metadata_version	'metadata.version' is missing	Warning
metadata_field	'metadata' should map string keys to string values	Warning

	Total	14 / 16 Passed

Repository: raphaelmansuy/edgequake
Path: .github/skills/reverse-documentation/SKILL.md
Commit: 62e6adb

Reviewed: 1 day 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.