CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

hns-moaiadk-best-practices

moai-adk-go best-practices reference for the 4 harness specialists (cli-template-specialist, quality-specialist, workflow-specialist, hook-ci-specialist). Covers TRUST 5 gates, Go test isolation (t.TempDir, no OTEL env in parallel tests), hardcoding-prevention rules (env constants in envkeys.go, thresholds in defaults.go), the AskUserQuestion orchestrator-only boundary, the deferred-tool preload rule, the archived-agent rejection contract, and verification-claim integrity. Loaded by the specialists when authoring or reviewing moai-adk-go code.

Quality

88%

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

SKILL.md
Quality
Evals
Security

Quality

Content

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

A strong reference skill: it delivers concrete, executable project-specific rules with genuine validation checkpoints and defers bulk detail to canonical SSOT files. Weaknesses are mild — a dated incident anecdote, cross-reference noise, and reliance on external repo files that are not part of the skill bundle for critical details like the archived-agent list and blocker report format.

Suggestions

Move the 2026-06-17 incident anecdote into a brief 'canonical failure example' note without the raw date, or into a deprecated/old-patterns section, to avoid time-sensitive detail in the main body.

Ship the archived-agent names list and migration table (or at least the blocker report format) as files in a references/ directory inside the skill bundle, so the skill is self-contained instead of depending on unverifiable external repo paths.

Expand the TRUST 5 failure actions into a short recovery loop (e.g., 'if golangci-lint fails: fix, re-run, then re-run the full test suite') so each gate has an explicit fix-and-revalidate step.

DimensionReasoningScore

Conciseness

The body is dense, non-obvious project policy with no basic-concept padding — every section states rules Claude could not infer. Minor trimmable material keeps it below the lean anchor: the dated "2026-06-17 incident (29 SPECs wrongly flagged...)" anecdote and parenthetical cross-reference chatter like "(CLAUDE.local.md §WARN)" are padding-adjacent, and the time-sensitive date is not placed in a deprecated/old-patterns section.

4 / 5

Actionability

Guidance is fully concrete and executable: exact commands ("go test ./...", "-count=1", "-race", "golangci-lint run"), exact file paths ("internal/config/envkeys.go", "internal/config/defaults.go"), a copy-paste "ToolSearch(query: \"select:AskUserQuestion,TaskCreate,...\")" pattern, the retained-agent whitelist, and a concrete per-spawn "Agent(subagent_type: \"general-purpose\", tools: ..., prompt: ...)" template covering the common delegation case.

5 / 5

Workflow Clarity

The TRUST 5 gates table functions as an explicit validation checklist ("Every change must pass all five dimensions before completion" with per-pillar failure actions), and "After fixing any test, run the FULL suite" is a real feedback loop. However, the skill is a multi-topic reference rather than a sequenced process, and error-recovery loops (what to do when a gate fails beyond the one-word failure action) are only implicit, so the full sequence-with-recovery anchor is not met.

4 / 5

Progressive Disclosure

The body is a well-sectioned overview that appropriately defers bulk detail (archived agent names, the migration table, the blocker report format) to one-level-deep referenced paths, with a Cross-References section for navigation. But the bundle ships no references/ files at all — the deferred content lives in external repo paths (".claude/rules/moai/...") that cannot be verified as part of the skill, leaving organization gaps against the clear-well-signaled-references anchor.

4 / 5

Total

17

/

20

Passed

Description

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

A strong description: it explicitly scopes what the skill covers via a concrete enumerated list, names its audience and trigger condition in third person, and is tightly niche-bound. The only soft spot is trigger-term naturalness — keywords are project jargon rather than phrases a user would naturally say.

Suggestions

Add one or two natural-language trigger phrases (e.g., 'use when writing or reviewing Go code in the moai-adk-go repo') alongside the jargon keywords so the skill also triggers on plain-English requests.

Include common keyword variations or file extensions (e.g., '.go files', 'golangci-lint') to broaden natural term coverage.

DimensionReasoningScore

Specificity

The description enumerates concrete, specific coverage areas — "Covers TRUST 5 gates, Go test isolation (t.TempDir, no OTEL env in parallel tests), hardcoding-prevention rules (env constants in envkeys.go, thresholds in defaults.go), the AskUserQuestion orchestrator-only boundary, the deferred-tool preload rule, the archived-agent rejection contract, and verification-claim integrity" — leaving little ambiguity about scope. This matches the comprehensive-coverage anchor, exceeding the 'several specific actions; minor gaps' level below.

5 / 5

Completeness

Both what and when are explicit: the what is the enumerated best-practices coverage list, and the when is "Loaded by the specialists when authoring or reviewing moai-adk-go code" — concrete, third-person trigger guidance with named agents. This clears the missing-'Use when' cap and matches the explicit what-and-when-with-triggers anchor.

5 / 5

Trigger Term Quality

Keywords like "moai-adk-go", "TRUST 5", "t.TempDir", "envkeys.go", "AskUserQuestion", "archived-agent", "verification-claim" give good domain-keyword coverage for the target audience. They are jargon tokens rather than natural user phrasings and lack synonyms or common variations, so the comprehensive-synonyms anchor (5) is not met but the good-coverage-with-few-missing anchor fits.

4 / 5

Distinctiveness Conflict Risk

The description is anchored to a highly specific niche — "moai-adk-go best-practices reference for the 4 harness specialists (cli-template-specialist, quality-specialist, workflow-specialist, hook-ci-specialist)" — with distinct triggers unlikely to fire for unrelated skills. Minimal conflict risk with any other skill.

5 / 5

Total

19

/

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/hns-moaiadk-best-practices/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.