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

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

100%

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

A lean, action-dense best-practices reference: it supplies executable commands, exact paths, a validation gate checklist, feedback loops, and one-level-deep signaled references without padding. It earns the top anchor on every content dimension.

Dimension	Reasoning	Score
Conciseness	The body is dense and assumes Claude's competence — it explains only non-obvious project gotchas (the macOS filepath.Join pitfall, the OTEL global-state race) rather than general concepts, so nearly every token earns its place and matches the lean/efficient anchor at 3.	3 / 3
Actionability	It provides concrete executable commands ("go test ./...", "golangci-lint run", "-count=1", "-race"), exact file paths ("internal/config/envkeys.go", "internal/config/defaults.go"), and a copy-pasteable retained-agents code block plus the per-spawn Agent() pattern, matching the fully-executable anchor at 3 rather than the pseudocode anchor at 2.	3 / 3
Workflow Clarity	The TRUST 5 table is an explicit gate checklist with per-pillar "Failure action" validation steps, and Test Isolation includes a feedback loop ("After fixing any test, run the FULL suite (go test ./...)") with error-recovery guidance, matching the clear-sequence-with-validation anchor at 3.	3 / 3
Progressive Disclosure	The body is a well-organized overview that defers detail to clearly signaled one-level-deep references ("See .claude/rules/moai/workflow/archived-agent-rejection.md §C for the full migration table") and deliberately avoids repeating suppressed content, matching the clear-overview-with-well-signaled-references anchor at 3.	3 / 3
	Total	12 / 12 Passed

Description

85%

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, third-person description that concretely enumerates the domains covered and gives an explicit when-trigger, with only the keyword phrasing being more jargon-heavy than natural. Its main weakness is trigger-term naturalness rather than coverage.

Suggestions

Soften the jargon in the description by pairing each technical token with a natural phrase a user might say (e.g., add "Go test setup and isolation" alongside "t.TempDir"), so trigger matching works on plain-language queries too.

Consider leading the description with the natural-language trigger ("Use when authoring or reviewing moai-adk-go harness code") before the enumerated jargon, mirroring the 'Use when...' pattern the rubric rewards.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete subjects with named mechanisms and files — "TRUST 5 gates", "Go test isolation (t.TempDir, no OTEL env in parallel tests)", "env constants in envkeys.go, thresholds in defaults.go" — matching the multiple-specific-concrete-actions anchor rather than the vague single-domain anchor at 2.	3 / 3
Completeness	It answers both what ("Covers TRUST 5 gates ... verification-claim integrity") and when via an explicit trigger clause ("Loaded by the specialists when authoring or reviewing moai-adk-go code"), satisfying the explicit-trigger requirement that would otherwise cap completeness at 2.	3 / 3
Trigger Term Quality	Relevant keywords are present but they lean heavily toward project jargon ("t.TempDir", "envkeys.go", "deferred-tool preload rule") rather than natural terms a user would say, matching the anchor of some-relevant-keywords-but-missing-common-variations rather than the natural-term coverage at 3.	2 / 3
Distinctiveness Conflict Risk	It carves a clear niche scoped to four named moai-adk-go harness specialists with project-specific triggers, making conflict with unrelated skills unlikely and matching the clear-niche anchor at 3.	3 / 3
	Total	11 / 12 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
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
Commit: 05117b6

Reviewed: 1 day 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.