Skill Guide

A detailed guide to MoAI-ADK’s skill system. Skills are the knowledge layer of the agentic harness — and, in that they “load only the needed knowledge at the needed moment,” they are also where tokenomics is most concretely implemented.

Platform basics

Background on the platform layer is in Skills. This page is the MoAI-ADK account of it.

Info

What is a skill?

Remember the helicopter scene from the 1999 film The Matrix? When Neo asks Trinity whether she can fly a helicopter, Trinity calls headquarters, names the helicopter model, and asks for the operating program to be uploaded.

Claude Code’s skills are exactly that operating manual. They load only the needed knowledge at the needed moment, letting the AI instantly act like an expert.

A skill is a knowledge module that provides Claude Code with specialized expertise in a particular field.

In a school analogy, Claude Code is the student and skills are the textbooks. Just as you open the math textbook in math class and the science textbook in science class, Claude Code loads the Python skill when writing Python code and the Frontend skill when building a React UI.

flowchart TD
    USER[User request] --> DETECT[Keyword detection]
    DETECT --> TRIGGER{Trigger matching}
    TRIGGER -->|Python-related| PY["moai-domain-backend
Backend expertise"]
    TRIGGER -->|React-related| FE["moai-domain-frontend
Frontend expertise"]
    TRIGGER -->|Security-related| SEC["moai-foundation-core
TRUST 5 security principles"]
    TRIGGER -->|DB-related| DB["moai-domain-database
Database expertise"]

    PY --> AGENT[Knowledge injected into agent]
    FE --> AGENT
    SEC --> AGENT
    DB --> AGENT

Without skills: Claude Code responds with general knowledge only. With skills: it responds by applying MoAI-ADK’s rules, patterns, and best practices.

The MoAI-ADK template ships 34 skills in total. The catalog splits them by installation scope into 21 core skills, deployed with every project, and 13 optional-pack skills (backend 3, design 1, devops 5, frontend 4), deployed on demand. By function they group as Foundation 4 + Workflow 8 + Domain 7 + Reference 11 + Meta/Harness 3 = 33 specialized skills, plus the 1 moai umbrella skill that routes requests to them. In user projects, you can additionally author custom hns-* harness skills. Programming-language support is provided by rules under rules/moai/languages/ and is not a separate skill.

This count is also a result of dieting — the skill catalog was refined from 48 → 38 over the v3 period, and now stands at 34 with the optional packs included. The current prefix for custom harness skills is hns-* (the legacy harness-* is also recognized).

Which diagram kinds moai-domain-svg-infographic can produce was measured, not assumed. All nine forms of an external catalog (the SkillStead TypePack) were run as identical generation briefs and checked against the skill’s own delivery gates — the deterministic source lint and the dimension-verified 2x PNG render — and every one of them reproduced successfully.

Each form is expressed on top of the four base layouts (stack, left-to-right flow, side-by-side comparison, hierarchy tree) in a way that preserves the information structure. The per-form verdict table and gate logs live in .moai/reports/t272/verdict.md.

The 34 skills ship with the MoAI-ADK template (21 core immediately, 13 via optional packs), and each skill loads independently to save tokens. Users can additionally author per-project custom hns-* harness skills (the legacy harness-* prefix is also recognized).

MoAI-ADK skills use a 3-level Progressive Disclosure system. Loading every skill at once wastes tokens, so they load incrementally, only as needed. Think of it as the skill-layer implementation of the context diet.

flowchart TD
    subgraph L1["Level 1: Metadata (~100 tokens)"]
        M1["Name, description, trigger keywords"]
        M2["Always loaded"]
    end

    subgraph L2["Level 2: Body (~5,000 tokens)"]
        B1["Full skill document"]
        B2["Code examples, patterns"]
    end

    subgraph L3["Level 3: Bundle (unlimited)"]
        R1["modules/ directory"]
        R2["reference.md, examples.md"]
    end

    L1 -->|"On trigger match"| L2
    L2 -->|"When deep information is needed"| L3

• Naive approach: loading all 34 skills = about 170,000 tokens (infeasible)
• Progressive disclosure: metadata only = about 3,400 tokens (98% savings)
• Load on demand: only the 2-3 skills the task needs = about 15,000 additional tokens

Skills load automatically via 4 trigger conditions.

flowchart TD
    REQ[Analyze user request] --> KW{Keyword detection}
    REQ --> AG{Agent invocation}
    REQ --> PH{Workflow phase}
    REQ --> LN{Language detection}

    KW -->|"api, database"| SKILL1[moai-domain-backend]
    AG -->|"manager-develop"| SKILL1
    PH -->|"run phase"| SKILL2[moai-workflow-ddd]
    LN -->|"Python file"| SKILL3[moai-domain-backend]

    SKILL1 --> LOAD[Skill loaded]
    SKILL2 --> LOAD
    SKILL3 --> LOAD

# The actual SKILL.md frontmatter (auto-discovery is driven by the description/when_to_use prose)
name: moai-domain-backend
description: >
  Backend development specialist ... Use when designing APIs,
  implementing server logic, authentication, or authorization.
when_to_use: >
  Use for backend work: API design (REST, GraphQL, gRPC) ...
allowed-tools: Read, Write, Edit, Bash(go:*), Grep, Glob   # CSV string (not a YAML array)
user-invocable: false
metadata:
  version: "1.0.0"
  category: "domain"

Auto-load mechanism:

• Claude Code reads the description / when_to_use prose and discovers a skill by matching it against the domain of the user request (there is no separate triggers: block).
• allowed-tools is written as a CSV string (not space-separated, not a YAML array).
• The orchestrator routes domain skills by injecting an At start, invoke Skill("<name>") instruction on agent spawn (skill-routing.md).

You can invoke a skill directly in a Claude Code conversation.

# Invoke a skill in Claude Code
> Skill("moai-domain-backend")
> Skill("moai-domain-frontend")
> Skill("moai-ref-api-patterns")

In most cases skills are loaded automatically by the trigger mechanism. The conversation context is analyzed and the appropriate skills are activated without the user invoking anything.

Skill files live in the .claude/skills/ directory.

.claude/skills/
├── moai-foundation-core/       # Foundation category
│   ├── skill.md                # main skill document (500 lines or fewer)
│   ├── modules/                # in-depth documents (unlimited)
│   │   ├── trust-5-framework.md
│   │   ├── spec-first-ddd.md
│   │   └── delegation-patterns.md
│   ├── examples.md             # real-world examples
│   └── reference.md            # external reference links
│
├── moai-domain-backend/        # Domain category
│   ├── skill.md
│   └── modules/
│       ├── api-patterns.md
│       └── microservices.md
│
└── my-skills/                  # user custom skills (excluded from updates)
    └── my-custom-skill/
        └── skill.md

Warning

Warning: Skills with the moai-* prefix are overwritten on MoAI-ADK updates. Always create personal skills in the .claude/skills/my-skills/ directory.

A skill prefix distinguishes the distribution owner, and moai update behaves differently.

The hns-* prefix means a user-created harness skill, which moai update never overwrites or deletes. You must not mirror hns-* skills in the template (a CI guard detects it).

Warning

Note: Skills with the moai-* prefix are overwritten on a MoAI-ADK update. Create personal skills and harness skills in a hns-*-prefixed or prefix-less directory.

Each skill’s skill.md follows this structure.

---
name: moai-domain-backend
description: >
  Backend development specialist. Provides API design, microservices, and database integration patterns.
  Use when developing APIs, web apps, or data pipelines.
version: 3.0.0
category: domain
status: active
triggers:
  keywords: ["api", "database", "microservices", "authentication"]
allowed-tools: ["Read", "Grep", "Glob", "Bash"]
---

# Backend Development Specialist

## Quick Reference

(quick reference - 30 seconds)

## Implementation Guide

(implementation guide - 5 minutes)

## Advanced Patterns

(advanced patterns - 10 minutes+)

## Works Well With

(related skills/agents)

A scenario where the user is working in a Python FastAPI project.

# 1. The user requests API development
> Build a user authentication API with FastAPI

# 2. Keywords MoAI-ADK detects automatically
# "FastAPI" → moai-domain-backend trigger (Python patterns come from rules/moai/languages/)
# "authentication" → moai-domain-backend trigger
# "API"     → moai-domain-backend trigger

# 3. Skills loaded automatically
# - moai-domain-backend (Level 2): API design patterns, authentication strategies
# - moai-foundation-core (Level 1): TRUST 5 quality standards

# 4. The agent implements using skill knowledge
# - Applies FastAPI router patterns
# - Applies JWT authentication best practices
# - Auto-generates pytest tests
# - Meets TRUST 5 quality standards

How multiple skills cooperate on a single task.

flowchart TD
    REQ["User: Build a full-stack app
with Supabase + Next.js"] --> ANALYZE[Analyze request]

    ANALYZE --> S1["moai-domain-frontend
React/Next.js patterns"]
    ANALYZE --> S2["moai-domain-backend
API design patterns"]
    ANALYZE --> S3["moai-domain-database
Database integration"]
    ANALYZE --> S4["moai-foundation-core
TRUST 5 quality"]

    S1 --> IMPL[Integrated implementation]
    S2 --> IMPL
    S3 --> IMPL
    S4 --> IMPL

    IMPL --> RESULT["Type-safe
full-stack app"]

Claude Code discovers .claude/skills/ not only at the project root but also in nested subdirectories (parent-walk). Monorepos can therefore place package-local skills in each package’s own .claude/skills/ directory. When working inside a nested directory containing its own .claude/skills/, that nested directory’s skills are loaded alongside the root-level skills while working within that subtree.

When the same skill name appears in more than one .claude/skills/ directory along the nesting chain, the closest-directory-wins rule resolves the conflict: the .claude/skills/ closest to the current working directory shadows the one higher up the tree. This is the same precedent rule already applied to agents, workflows, and output-styles under nested .claude/ directories — the innermost .claude/ wins. A package-local skill that deliberately overrides a root skill must keep the same name. Renaming it creates a second skill, not an override.

disableBundledSkills (a settings.json boolean, or its environment-variable form) hides Claude Code’s bundled skills and workflows — e.g. /deep-research, built-in slash-command skills — from discovery, exposing only enterprise + personal + project + plugin skills. Use it when providing a curated, bundle-free skill surface. MoAI-ADK does not generate this toggle in its own generators. It is documented here as an available option. The companion --safe-mode launch flag is documented in the Settings JSON Guide.

• Agent Guide - the agent system that uses skills
• Builder Agents Guide - how to create custom skills
• CLAUDE.md Guide - skill configuration and the rules system

Info

Tip: The key to using skills well is using the right keywords. Ask “build a REST API in Python” and the moai-domain-backend skill activates automatically (Python patterns are provided via rules/moai/languages/) to generate optimal code.