CtrlK
BlogDocsLog inGet started
Tessl Logo

recipe-update-doc

Update existing design documents (Design Doc / PRD / ADR) with review

45

Quality

47%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/recipe-update-doc/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Discovery

32%

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 identifies a reasonable niche—updating specific types of design documents—but is too terse and lacks explicit trigger guidance. It doesn't explain what 'update with review' means concretely, and the absence of a 'Use when...' clause makes it difficult for Claude to reliably select this skill over similar document-related skills.

Suggestions

Add a 'Use when...' clause with explicit triggers, e.g., 'Use when the user asks to revise, update, or incorporate feedback into an existing Design Doc, PRD, or ADR.'

Expand the capability description with concrete actions, e.g., 'Incorporates review feedback, updates sections, resolves comments, and tracks changes in existing design documents.'

Include common term variations such as 'product requirements document', 'architecture decision record', 'revise', 'edit design doc' to improve trigger term coverage.

DimensionReasoningScore

Specificity

Names the domain (design documents) and a single action (update with review), and lists specific document types (Design Doc, PRD, ADR), but doesn't describe what 'update with review' concretely entails—e.g., incorporating feedback, revising sections, tracking changes.

2 / 3

Completeness

It partially answers 'what' (update design documents with review) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'what' is also weak, so this scores a 1.

1 / 3

Trigger Term Quality

Includes useful trigger terms like 'Design Doc', 'PRD', 'ADR', and 'review', which users might naturally say. However, it misses common variations such as 'product requirements document', 'architecture decision record', 'revise', 'edit', or 'update document'.

2 / 3

Distinctiveness Conflict Risk

The mention of specific document types (Design Doc, PRD, ADR) and the 'update' action provides some distinctiveness, but it could easily overlap with a skill for creating these documents or a general document editing skill. The lack of explicit triggers increases conflict risk.

2 / 3

Total

7

/

12

Passed

Implementation

62%

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

This is a well-structured orchestration skill with excellent workflow clarity, featuring explicit stop points, feedback loops with iteration limits, and comprehensive error handling. Its main weaknesses are moderate verbosity (some redundancy between the overview and execution flow) and the fact that actionability depends heavily on external sub-agents that aren't provided in the bundle. The progressive disclosure is adequate but could be improved with supporting bundle files for the referenced agents.

Suggestions

Trim redundancy between the 'Workflow Overview' diagram and the detailed 'Execution Flow' section—consider removing the overview or making it a one-line summary.

Provide bundle files or clearer references for the sub-agents (technical-designer, document-reviewer, code-verifier, design-sync) so the skill is self-contained or at least navigable.

DimensionReasoningScore

Conciseness

The skill is reasonably structured but includes some redundancy—the workflow overview diagram partially duplicates the execution flow, and some explanations (like scope boundaries and responsibility boundary) could be tightened. The tables and decision flows are efficient, but the overall document could be more compact.

2 / 3

Actionability

The skill provides structured sub-agent invocation templates with specific prompts and clear decision tables, which is good. However, the guidance is largely procedural/orchestration-level rather than executable code—the sub-agent prompts are templates with placeholders, and the actual work is delegated to other agents whose behavior isn't defined here. The bash command in Step 1 is concrete and executable.

2 / 3

Workflow Clarity

The workflow is clearly sequenced with explicit [Stop] markers at Steps 3, 5, and 6 serving as validation checkpoints. There are well-defined feedback loops (review → revise → re-review with max 2 iterations), error handling for each failure mode, and clear decision flows for branching logic. The completion criteria checklist reinforces the workflow.

3 / 3

Progressive Disclosure

The skill references multiple sub-agents (technical-designer, document-reviewer, code-verifier, design-sync, prd-creator) and a subagents-orchestration-guide skill, but no bundle files are provided to support these references. The content is well-organized with clear sections, but it's a moderately long single file that could benefit from separating the sub-agent prompt templates or error handling into referenced files.

2 / 3

Total

9

/

12

Passed

Validation

90%

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

Validation10 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

10

/

11

Passed

Repository
shinpr/claude-code-workflows
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.