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".

Quality

88%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

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

Description

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

Validation

90%

Warnings & errors only

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: 23 days ago

Table of Contents

Discovery Implementation Validation

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.