map
Generate or update ARCHITECTURE.md — a living map of a project's structure, dependencies, and high-coupling zones. Polyglot-adaptive. Heavyweight (writes ARCHITECTURE.md, dispatches parallel agents); explicit invocation only. Triggers: /map, "generate ARCHITECTURE.md", "map this codebase".
72
88%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong skill description that concisely communicates what the skill does (generates/updates ARCHITECTURE.md with project structure, dependencies, and coupling analysis), when to use it (explicit triggers listed), and important operational characteristics (heavyweight, parallel agents, explicit invocation only). It uses third person voice correctly and avoids vague language or buzzwords.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple concrete actions: 'Generate or update ARCHITECTURE.md', describes it as 'a living map of a project's structure, dependencies, and high-coupling zones', mentions 'polyglot-adaptive', 'writes ARCHITECTURE.md', 'dispatches parallel agents'. These are specific, concrete capabilities. | 3 / 3 |
Completeness | Clearly answers 'what' (generate/update ARCHITECTURE.md with structure, dependencies, high-coupling zones) and 'when' (explicit triggers listed: /map, 'generate ARCHITECTURE.md', 'map this codebase'; also notes 'explicit invocation only'). Both dimensions are well-covered. | 3 / 3 |
Trigger Term Quality | Includes natural trigger terms users would say: '/map', 'generate ARCHITECTURE.md', 'map this codebase', plus 'ARCHITECTURE.md' appears multiple times. These cover the most likely phrasings a user would use when wanting to map a codebase. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive — targets a very specific artifact (ARCHITECTURE.md), a specific task (codebase mapping), and uses unique trigger terms like '/map' and 'map this codebase'. The 'explicit invocation only' note further reduces false positive risk. Unlikely to conflict with other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
77%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 actionability and workflow clarity — every mode is precisely defined with clear steps, error handling, and fallback logic. The main weaknesses are verbosity in agent prompt definitions (which repeat similar patterns for language detection across all three agents) and a monolithic structure that would benefit from extracting agent prompts and scoping logic into separate referenced files. The broken reference to 'Diff-Aware Scoping Logic in spec' is a notable gap.
Suggestions
Extract the three detailed agent prompts into separate files (e.g., prompts/structure-mapper.md) and reference them from the main skill to improve progressive disclosure and reduce the monolithic feel.
Include or create the referenced 'Diff-Aware Scoping Logic' spec — currently it's a broken reference that leaves Mode 2's scoping undefined.
Consolidate the repeated language-detection patterns across agents into a shared reference or note, rather than listing similar file examples in each agent prompt.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is detailed and mostly necessary given the complexity of the orchestration task, but there's significant verbosity in the agent prompts — listing exhaustive examples of file patterns and tools for every language. Some of these lists could be trimmed since Claude can infer language-specific conventions. The repeated 'examples, not exhaustive' pattern adds token overhead. | 2 / 3 |
Actionability | The skill provides highly concrete, executable guidance: specific git commands, exact agent prompts, clear argument parsing logic, precise fallback behaviors, and detailed assembly instructions. Every mode has step-by-step instructions with specific tools and outputs defined. | 3 / 3 |
Workflow Clarity | The multi-step workflows are clearly sequenced across all four modes with explicit validation checkpoints (agent failure retry logic, metadata corruption handling, fallback behaviors). Error handling is a dedicated section with specific recovery actions. The mode selection logic includes clear decision trees with fallbacks. | 3 / 3 |
Progressive Disclosure | The content is a long monolithic document (~150+ lines) with no references to supporting files despite the complexity warranting them. The detailed agent prompts could be extracted to separate files. The 'Diff-Aware Scoping Logic' is referenced but not included ('see Diff-Aware Scoping Logic in spec'), and no bundle files are provided to support this reference, creating a broken reference. | 2 / 3 |
Total | 10 / 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.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- belchman/claude-skills
- Commit
be88d6c
- 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.