CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

moai

MoAI unified orchestrator for autonomous development. Routes natural language or subcommands (plan, run, sync, project, fix, loop, mx, feedback, review, clean, codemaps, gate, e2e, harness, goal, gtd, todo) to specialized agents.

Quality

62%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/moai/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

52%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.

The router core is genuinely strong — a clear priority ladder, hard validation gates, and executable commands — but the body carries substantial repetition and retired-feature history that bloat token cost, and its progressive-disclosure structure is broken: every referenced path points outside the bundle while the bundle's real reference files are orphaned. Linking the existing references/ files and moving the harness/todo detail out of SKILL.md would fix both weaknesses.

Suggestions

Link the existing bundle references from the body (e.g. mx tag routing → references/mx-tag.md, review/run quality guidance → references/anti-patterns.md, execution patterns → references/reference.md) so they are discoverable, and reconcile or remove the dangling workflows/*.md and .moai/.claude paths that are absent from the bundle.

Move the harness Branch A/A.1/B detail and the todo database-path policy into separate workflow/reference files, keeping only the argument-branching routing rule inline.

Trim historical and duplicated content — the retired --worktree/MODE_TEAM_UNAVAILABLE history, the repeated '(experimental — Agent Teams re-allowed; see Execution Mode Flags)' notes, and the duplicated routing-ledger policy — into a single 'Deprecated / History' section or delete it, and define the undefined placeholders (--tier, --level, --session).

DimensionReasoningScore

Conciseness

The ~400-line body is noticeably verbose: it repeats the routing-ledger privacy policy in two places, restates '(experimental — Agent Teams re-allowed; see Execution Mode Flags)' on at least six workflow entries, and carries historical sediment ('the retired era emitted MODE_TEAM_UNAVAILABLE ... the sentinel is retained as documented history', the retired --worktree era) plus inline Korean error-message templates that belong in a reference file. It avoids a 1 because it never explains concepts Claude already knows — everything is project-specific policy — but much of the rationale and history could be trimmed or moved to a deprecated/legacy section.

2 / 5

Actionability

The body provides copy-paste-ready commands ('echo "<raw request text>" | moai harness ledger record --subcommand <matched> ...', 'moai paths', 'moai todo list --json'), an explicit forbidden flag/subcommand table, exact error-message templates, and a concrete 10-step execution directive. Not a 5 because several placeholders ('--tier <tier>', '--level <harness-level>', '--session <session-id>') are never defined, and the Socratic/AskUserQuestion guidance stays high-level in places.

4 / 5

Workflow Clarity

Routing follows a strictly ordered priority ladder (Priority 1 first-word matching → SPEC-ID detection → semantic classification → AskUserQuestion fallback) with explicit validation (Step 1.5 stops all processing on a forbidden flag/subcommand combination) and error-recovery templates, plus [HARD] markers acting as checkpoints. It falls short of 5 due to minor gaps: no check that 'workflows/<name>.md' exists before reading, and validation for destructive delegated workflows (harness remove, dead-code clean) is only implied via the downstream workflow files.

4 / 5

Progressive Disclosure

The body's navigation is disconnected from the actual bundle: it directs the agent to 'Read workflows/plan.md' (and 17 other workflows/*.md paths) and to .moai/config and .claude/rules files, none of which exist in the bundle, while the four files that DO exist in references/ (reference.md, anti-patterns.md, mx-tag.md, file-reading-optimization.md) are never mentioned or linked from SKILL.md and are therefore undiscoverable. Large inline blocks (the three harness branches, the todo database-path policy) also clearly belong in separate files, matching anchor 2's 'content that clearly belongs in separate files is inlined; or references are buried' more than anchor 3's merely-imperfect organization.

2 / 5

Total

12

/

20

Passed

Description

57%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 clearly states what the skill does and enumerates an impressive list of subcommands, but it omits any 'when to use' guidance and describes only the routing action rather than the underlying capabilities. Adding an explicit trigger clause and one-phrase capability summaries for the main subcommands would lift it substantially.

Suggestions

Add an explicit trigger clause, e.g. 'Use when the user asks to plan, implement, review, fix, or document a development task, or invokes any /moai subcommand.'

Briefly state what the key subcommands do (e.g. 'plan creates SPEC documents, run implements them via DDD/TDD, sync prepares PRs') instead of listing bare tokens.

Include natural-language synonyms users would say ('autonomous development', 'backlog', 'code review my changes') to sharpen trigger matching and distinctiveness.

DimensionReasoningScore

Specificity

The description names its domain ('unified orchestrator for autonomous development') and one concrete action ('Routes natural language or subcommands ... to specialized agents') plus a list of 17 subcommand tokens, but never states what those subcommands actually do (e.g. 'create SPEC documents', 'run DDD/TDD implementation'), so coverage of capabilities is not comprehensive. It sits above anchor 2 (which would name only the domain) but below anchor 4 (which requires several specific actions, not one action plus bare tokens).

3 / 5

Completeness

The 'what' is clearly stated ('Routes natural language or subcommands ... to specialized agents') but there is no 'Use when...' clause or equivalent explicit trigger guidance anywhere in the description, which caps completeness at 3 per the judging guidelines. It is not a 4 because the 'when' is entirely absent rather than merely imprecise.

3 / 5

Trigger Term Quality

The enumerated subcommands — 'plan, run, sync, project, fix, loop, mx, feedback, review, clean, codemaps, gate, e2e, harness, goal, gtd, todo' — are words users naturally say when they need this skill, giving good keyword coverage. Not a 5 because common need-phrases and synonyms ('code review my changes', 'autonomous development pipeline', 'backlog') are missing beyond the bare command names.

4 / 5

Distinctiveness Conflict Risk

The 'MoAI' branding and orchestrator framing give it a distinct identity, but the trigger surface consists of ultra-generic development verbs ('plan', 'run', 'fix', 'review', 'todo') with no 'use when' scoping, so it could still overlap with generic planning/review/fix skills. More overlap-prone than anchor 4's 'minor overlap risk with closely related skills', yet more specific than anchor 2's 'very broad'.

3 / 5

Total

13

/

20

Passed

Validation

87%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

14

/

16

Passed

Repository

modu-ai/moai-adk

Path

.claude/skills/moai/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.