update-codemaps
Analyzes codebase structure and updates architecture documentation with diff tracking
Install with Tessl CLI
npx tessl i github:sc30gsw/claude-code-customes --skill update-codemaps54
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
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 provides a basic understanding of the skill's purpose but lacks the explicit trigger guidance essential for Claude to know when to select it from a large skill library. The actions mentioned are somewhat vague ('analyzes', 'updates') without specifying concrete operations, and natural user trigger terms are limited.
Suggestions
Add an explicit 'Use when...' clause with trigger scenarios like 'Use when the user asks to update architecture docs, document code structure, track documentation changes, or sync docs with code changes'
Expand specific actions to be more concrete, e.g., 'Generates architecture diagrams, updates README files, tracks changes between documentation versions, maps module dependencies'
Include natural keyword variations users might say: 'architecture docs', 'code documentation', 'update docs', 'document the codebase', 'sync documentation'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (codebase/architecture documentation) and mentions two actions (analyzes structure, updates documentation with diff tracking), but lacks comprehensive detail on what specific analysis or documentation tasks are performed. | 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 rubric guidelines, missing explicit trigger guidance caps this at 2, but the 'what' is also weak, warranting a 1. | 1 / 3 |
Trigger Term Quality | Contains some relevant keywords like 'codebase', 'architecture', 'documentation', and 'diff tracking', but misses common variations users might say such as 'code structure', 'docs', 'architecture docs', 'update docs', or 'document changes'. | 2 / 3 |
Distinctiveness Conflict Risk | The combination of 'architecture documentation' and 'diff tracking' provides some specificity, but 'analyzes codebase structure' is generic enough to potentially overlap with code analysis or general documentation skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill is concise and outlines a clear high-level workflow for updating architecture documentation, but lacks the concrete, executable guidance needed for Claude to implement it. The absence of code examples, specific analysis techniques, or output format templates makes this more of a task description than an actionable skill.
Suggestions
Add executable TypeScript/Node.js code showing how to scan files for imports/exports (e.g., using ts-morph or the TypeScript compiler API)
Provide a concrete example of the expected codemap format for at least one output file (e.g., architecture.md)
Include specific logic or pseudocode for calculating the diff percentage between codemap versions
Add an example of the .reports/codemap-diff.txt output format
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient, with no unnecessary explanations of concepts Claude already knows. Every line serves a purpose and the instructions are direct. | 3 / 3 |
Actionability | The skill describes what to do at a high level but provides no concrete code, commands, or examples. 'Scan all source files' and 'Generate token-lean codemaps' are vague without executable guidance on how to accomplish these tasks. | 1 / 3 |
Workflow Clarity | Steps are numbered and sequenced, and there's a validation checkpoint (30% threshold requiring approval). However, there's no guidance on error handling, no validation of the generated codemaps, and the diff calculation process is unspecified. | 2 / 3 |
Progressive Disclosure | The skill references output files (codemaps/*.md, .reports/codemap-diff.txt) but doesn't provide examples of expected formats or link to templates. For a skill generating multiple documentation files, examples of the expected output format would improve navigation. | 2 / 3 |
Total | 8 / 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.
- 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.