update-codemaps
Analyzes codebase structure and updates architecture documentation with diff tracking
47
33%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.claude/skills/update-codemaps/SKILL.mdQuality
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 conveys a reasonable sense of what the skill does—analyzing code structure and updating architecture docs with diff tracking—but it lacks a 'Use when...' clause, which is critical for Claude to know when to select it. The trigger terms are somewhat relevant but not comprehensive, and the actions described could be more concrete and detailed.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to update architecture docs, review codebase structure changes, or generate documentation diffs.'
List more specific concrete actions, e.g., 'Scans directory layouts, maps module dependencies, generates architecture markdown files, and tracks documentation changes via diffs.'
Include natural trigger term variations such as 'architecture docs', 'project structure', 'code organization', 'doc refresh', or 'structural changes'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (codebase/architecture documentation) and mentions two actions (analyzes structure, updates documentation with diff tracking), but doesn't list multiple concrete actions comprehensively—e.g., what specific analyses, what format of documentation, what diff tracking entails. | 2 / 3 |
Completeness | Describes what the skill does 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 since the 'when' is entirely absent, this scores at the lower end. | 1 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'codebase structure', 'architecture documentation', and 'diff tracking', but misses common user-facing variations such as 'architecture docs', 'code architecture', 'project structure', 'doc updates', or 'architecture diagram'. | 2 / 3 |
Distinctiveness Conflict Risk | The combination of 'architecture documentation' and 'diff tracking' provides some specificity, but 'analyzes codebase structure' is broad enough to overlap with general code analysis or documentation skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
35%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a reasonable high-level outline of the codemap update workflow but lacks the concrete, executable guidance needed to be truly actionable. The absence of code examples, specific tool usage, output format templates, and error handling makes it more of a task description than an instructional skill. The workflow has a useful approval gate at 30% diff but misses validation and recovery steps.
Suggestions
Add concrete TypeScript/Node.js code snippets showing how to scan files for imports/exports and generate the codemap structure
Provide an example of the expected codemap output format (e.g., a sample architecture.md) so Claude knows exactly what to generate
Include a concrete method or code for calculating the diff percentage between previous and current versions
Add validation steps: e.g., verify generated codemaps are valid markdown, check that all source files were scanned, and include error recovery if scanning fails
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Reasonably lean with no excessive explanation of concepts Claude already knows, but some phrases like 'Analyze the codebase structure and update architecture documentation' are somewhat redundant given the title. Could be tighter. | 2 / 3 |
Actionability | No concrete code, commands, or executable examples are provided. Instructions like 'Scan all source files for imports, exports, and dependencies' are vague—there's no indication of which tools, libraries, or specific approaches to use. 'Use TypeScript/Node.js for analysis' is too abstract without any code snippets. | 1 / 3 |
Workflow Clarity | Steps are listed in a numbered sequence with a validation-like checkpoint (30% diff threshold requiring user approval), but there are no explicit validation steps for the generated codemaps, no error recovery guidance, and the diff calculation step lacks any concrete method or command. | 2 / 3 |
Progressive Disclosure | The skill references output files (codemaps/*.md, .reports/codemap-diff.txt) which implies some structure, but there are no links to example templates, format specifications, or reference files. For a skill that generates multiple output files, examples of expected output format would significantly improve navigation and clarity. | 2 / 3 |
Total | 7 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- sc30gsw/claude-code-customes
- Commit
7aff694
- 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.