CtrlK
BlogDocsLog inGet started
Tessl Logo

project-documentation-workflow

Wave-based comprehensive project documentation generator with dynamic task decomposition. Analyzes project structure and generates appropriate documentation tasks, computes optimal execution waves via topological sort, produces complete documentation suite including architecture, methods, theory, features, usage, and design philosophy.

36

Quality

35%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Risky

Do not use without reviewing

Fix and improve this skill with Tessl

tessl review fix ./.codex/skills/project-documentation-workflow/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

27%

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 ambitious documentation workflow system but suffers from extreme verbosity — it dumps the entire implementation inline rather than providing a concise overview with references to supporting files. The code is illustrative but not truly executable due to undefined functions and tools. The workflow structure is reasonable but lacks proper validation checkpoints and error recovery paths for a system involving batch operations and multi-agent coordination.

Suggestions

Extract the implementation code (topological sort, wave summary generation, instruction template, aggregation logic) into separate bundle files and reference them from SKILL.md, keeping only the workflow overview, usage, and CSV schema inline.

Define or document all referenced functions and tools (parseCsv, toCsv, spawn_agents_on_csv, ccw cli, $ARGUMENTS) so the code becomes truly executable rather than illustrative pseudocode.

Add explicit validation checkpoints: verify generated documents contain all required doc_sections, validate CSV integrity after merges, and add a retry/recovery path for failed tasks beyond just skipping dependents.

Remove the optimization comparison table and bilingual labels — focus on instructing Claude what to do rather than explaining design decisions or providing marketing-style before/after comparisons.

DimensionReasoningScore

Conciseness

Extremely verbose at ~500+ lines with extensive inline code that could be in separate files. Includes unnecessary UI formatting (box-drawing characters), bilingual labels (Chinese + English) that add noise, and an optimization comparison table that explains design rationale rather than instructing. Much of the implementation detail (topological sort algorithm, wave summary generation) is standard CS that Claude knows.

1 / 3

Actionability

Contains substantial executable-looking JavaScript code with concrete commands and CSV schemas, but the code references undefined functions (parseCsv, toCsv, fileExists, spawn_agents_on_csv, functions.request_user_input) and uses pseudo-variables ($ARGUMENTS, $project-documentation-workflow) without defining them. The Bash command in Phase 0 Step 1 calls an undefined 'ccw cli' tool. Code is illustrative rather than truly copy-paste ready.

2 / 3

Workflow Clarity

The three-phase workflow (Decomposition → Wave Execution → Aggregation) is clearly sequenced with dependency checking and skip-on-failure logic. However, validation checkpoints are weak — there's no explicit verification that generated documents are valid/complete, no error recovery beyond skipping dependents, and no feedback loop for failed tasks. The cycle detection in topological sort throws an error but there's no recovery path.

2 / 3

Progressive Disclosure

This is a monolithic wall of text with all implementation details inline — the topological sort algorithm, wave summary generation, instruction templates, results aggregation, and CSV schema are all in one massive file. No bundle files are provided despite the content clearly warranting separation (e.g., instruction template, utility functions, CSV schema reference). There are no references to external files for detailed content.

1 / 3

Total

6

/

12

Passed

Description

42%

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 is technically detailed about its capabilities but reads more like an implementation summary than a skill selection guide. It lacks a 'Use when...' clause entirely, making it difficult for Claude to know when to select this skill. The heavy use of technical jargon ('topological sort', 'wave-based', 'dynamic task decomposition') reduces its effectiveness as a trigger for natural user requests.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to document a project, generate project docs, create a documentation suite, or needs comprehensive technical documentation for a codebase.'

Include natural trigger terms users would actually say, such as 'generate docs', 'document my project', 'create README', 'technical documentation', 'API docs'.

Reduce implementation jargon like 'topological sort' and 'wave-based' which describe internal mechanics rather than helping with skill selection.

DimensionReasoningScore

Specificity

Lists multiple specific concrete actions: analyzes project structure, generates documentation tasks, computes execution waves via topological sort, produces documentation suite including architecture, methods, theory, features, usage, and design philosophy.

3 / 3

Completeness

Describes what the skill does reasonably well, but completely lacks any 'Use when...' clause or equivalent explicit trigger guidance. Per the rubric, a missing 'Use when...' clause should cap completeness at 2, and since the 'when' is entirely absent, this scores a 1.

1 / 3

Trigger Term Quality

Contains relevant terms like 'documentation', 'project structure', 'architecture', but uses technical jargon like 'topological sort', 'wave-based', 'dynamic task decomposition' that users wouldn't naturally say. Missing common user phrases like 'document my project', 'generate docs', 'README'.

2 / 3

Distinctiveness Conflict Risk

The wave-based approach and topological sort give it some distinctiveness, but 'project documentation generator' is broad enough to overlap with simpler documentation skills. The specific mention of documentation types (architecture, methods, theory) helps but doesn't fully disambiguate.

2 / 3

Total

8

/

12

Passed

Validation

72%

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

Validation8 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (809 lines); consider splitting into references/ and linking

Warning

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

8

/

11

Passed

Repository
catlog22/Claude-Code-Workflow
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.