CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

moai-codemaps

Scan codebase and generate architecture documentation in codemaps/

Quality

67%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/moai-codemaps/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

68%Weight 40%Scale 1-5

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

An extremely lean delegation stub: maximally token-efficient, but it forwards an unsubstituted $ARGUMENTS placeholder to an external skill ('moai') that is not part of this bundle, with no description of accepted arguments, expected behavior, or failure handling. As a wrapper it works only if the template is rendered and the target skill exists.

Suggestions

Replace the raw $ARGUMENTS placeholder with concrete guidance on what arguments the codemaps command accepts (e.g., target paths, output options) or an example invocation.

Add one line stating what the delegation produces (e.g., expected files created under codemaps/) so execution is not blind.

Add a brief fallback or validation step for when the referenced Skill("moai") is unavailable, so the single-action workflow has a checkpoint.

DimensionReasoningScore

Conciseness

The body is a single line ('Use Skill("moai") with arguments: codemaps $ARGUMENTS') with zero padding and no explanation of concepts Claude already knows; every token is a directive. This clearly matches the 'lean and efficient' anchor.

5 / 5

Actionability

The directive is concrete in form ('Use Skill("moai") with arguments: codemaps $ARGUMENTS') but contains an unresolved template placeholder ($ARGUMENTS) and gives no detail on valid arguments, expected output, or what the codemaps command produces — matching 'some concrete guidance but incomplete'. Not 4 because the placeholder and undefined delegation behavior are more than minor gaps; not 2 because a specific, literal instruction is present.

3 / 5

Workflow Clarity

Although it is a single-action skill (which can score 5 if unambiguous), the action is not unambiguous: $ARGUMENTS is unsubstituted, there is no indication of what arguments are accepted, and no validation or fallback if the referenced 'moai' skill is unavailable. This lands at 'sequence present but checkpoints missing or implicit'. Not 4 because the gaps are central, not minor.

3 / 5

Progressive Disclosure

The body is under 50 lines with no inline content that belongs in separate files, and the single external reference (the 'moai' skill) is one level deep and explicitly signaled. Not 5 because no bundle files exist (no references/, scripts/, or assets/), so the delegation target is unverifiable and no overview of what the referenced skill covers is provided — a minor organization gap matching 'good structure... minor organization gaps'.

4 / 5

Total

15

/

20

Passed

Description

50%Weight 40%Scale 1-5

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 is a concise, third-person statement of what the skill does, naming a domain and two actions with an output location. However, it completely lacks any 'use when' trigger guidance and offers no synonyms or natural trigger phrases, capping both completeness and trigger-term quality at the midpoint.

Suggestions

Append a 'Use when...' clause, e.g. 'Use when the user asks for architecture documentation, a code map, or an overview of the codebase or repository structure.'

Add natural trigger synonyms such as 'code map', 'architecture diagram', 'document the repo', and 'codebase overview' to improve trigger-term coverage.

Specify what the generated documentation includes (e.g., modules, dependencies, data flow) rather than the generic 'architecture documentation'.

DimensionReasoningScore

Specificity

'Scan codebase and generate architecture documentation in codemaps/' names the domain and two actions (scan, generate architecture documentation) plus an output location — matching 'names domain and 1-2 concrete actions, but not comprehensive'. Not 4 because 'scan' is generic and there is no detail on what the documentation contains or covers.

3 / 5

Completeness

The 'what' is stated (scan codebase, generate architecture documentation in codemaps/) but the 'when' is entirely absent — there is no 'Use when...' clause or equivalent trigger guidance, which per the judging guidelines caps completeness at 3. This matches the anchor 'has a clear what but when is missing or only weakly implied'.

3 / 5

Trigger Term Quality

'Scan codebase' and 'architecture documentation' are relevant keywords a user might plausibly say, but common variations and synonyms are missing (e.g., 'repo', 'code map', 'architecture diagram', 'document the code', 'overview of the codebase') — matching 'some relevant keywords but missing common variations or synonyms'. Not 4 because coverage is thin, with only two keyword phrases.

3 / 5

Distinctiveness Conflict Risk

'generate architecture documentation in codemaps/' carves out a niche, but 'Scan codebase' is broad and the description would plausibly fire for general codebase-documentation, repo-onboarding, or init-style skills — matching 'somewhat specific but could still overlap with similar skills'. Not 4 because no trigger phrases distinguish it from closely related documentation skills.

3 / 5

Total

12

/

20

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

modu-ai/moai-adk

Path

.agents/skills/moai-codemaps/SKILL.md

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.