Skill Guide

Detailed guide to MoAI-ADK’s skill system.

What is a Skill?

A skill is a knowledge module that provides Claude Code with specialized knowledge in a specific domain.

To use a school analogy: Claude Code is the student and skills are textbooks. Just as you open a math textbook for math class and a science textbook for science class, Claude Code loads the Python skill when writing Python code and the Frontend skill when creating React UIs.

Without skills: Claude Code responds with only general knowledge. With skills: Applies MoAI-ADK’s rules, patterns, and best practices to respond.

Skill Categories

MoAI-ADK has a total of 52 skills classified into 9 categories.

Foundation (Core Philosophy) - 5 skills

Workflow (Automation Workflows) - 11 skills

Domain (Domain Expertise) - 4 skills

Language (Programming Languages) - 16 skills

Platform (Cloud/BaaS) - 4 skills

Library (Special Libraries) - 4 skills

Tool (Development Tools) - 2 skills

Framework (App Frameworks) - 1 skill

Design Tools - 1 skill

Progressive Disclosure System

MoAI-ADK’s skills use a 3-level progressive disclosure system. Loading all skills at once would waste tokens, so only the necessary amount is loaded incrementally.

Role of Each Level

Token Savings

• Old method: Load all 52 skills = ~260,000 tokens (impossible)
• Progressive disclosure: Load only metadata = ~5,200 tokens (97% savings)
• On-demand load: Only 2-3 skills needed for task = ~15,000 additional tokens

Skill Trigger Mechanism

Skills are automatically loaded via 4 trigger conditions.

Trigger Configuration Example

# Define triggers in skill frontmatter
triggers:
  keywords: ["api", "database", "authentication"] # Keyword matching
  agents: ["manager-spec", "expert-backend"] # On agent invocation
  phases: ["plan", "run"] # Workflow phases
  languages: ["python", "typescript"] # Programming languages

Trigger Priority:

1. Keywords: Load immediately when keyword detected in user message
2. Agents: Auto-load when specific agent is invoked
3. Phases: Load according to Plan/Run/Sync phase
4. Languages: Load based on programming language of files being worked on

Skill Usage

Explicit Invocation

You can directly invoke skills in Claude Code conversations.

# Invoke skills in Claude Code
> Skill("moai-lang-python")
> Skill("moai-domain-backend")
> Skill("moai-library-mermaid")

Auto Load

In most cases, skills are automatically loaded via the trigger mechanism. Users don’t need to invoke them directly; the conversation context is analyzed to activate appropriate skills.

Skill Directory Structure

Skill files are located in the .claude/skills/ directory.

.claude/skills/
├── moai-foundation-core/       # Foundation category
│   ├── skill.md                # Main skill document (under 500 lines)
│   ├── modules/                # Deep documentation (unlimited)
│   │   ├── trust-5-framework.md
│   │   ├── spec-first-ddd.md
│   │   └── delegation-patterns.md
│   ├── examples.md             # Real-world examples
│   └── reference.md            # External reference links
│
├── moai-lang-python/           # Language category
│   ├── skill.md
│   └── modules/
│       ├── fastapi-patterns.md
│       └── testing-pytest.md
│
└── my-skills/                  # User custom skills (excluded from updates)
    └── my-custom-skill/
        └── skill.md

Skill File Structure

Each skill’s skill.md follows this structure.

---
name: moai-lang-python
description: >
  Python 3.13+ development expert. FastAPI, Django, pytest patterns provided.
  Use for Python API, web app, data pipeline development.
version: 3.0.0
category: language
status: active
triggers:
  keywords: ["python", "fastapi", "django", "pytest"]
  languages: ["python"]
allowed-tools: ["Read", "Grep", "Glob", "Bash", "Context7 MCP"]
---
 
# Python Development Expert
 
## Quick Reference
 
(Quick reference - 30 seconds)
 
## Implementation Guide
 
(Implementation guide - 5 minutes)
 
## Advanced Patterns
 
(Advanced patterns - 10 minutes+)
 
## Works Well With
 
(Related skills/agents)

Real-World Examples

Auto Skill Load in Python Project

Scenario where user is working on a Python FastAPI project.

# 1. User requests API development
> Create a user authentication API with FastAPI
 
# 2. Keywords automatically detected by MoAI-ADK
# "FastAPI" → moai-lang-python trigger
# "authentication" → moai-domain-backend trigger
# "API" → moai-domain-backend trigger
 
# 3. Auto-loaded skills
# - moai-lang-python (Level 2): FastAPI patterns, pytest tests
# - moai-domain-backend (Level 2): API design patterns, auth strategy
# - moai-foundation-core (Level 1): TRUST 5 quality standards
 
# 4. Agent uses skill knowledge for implementation
# - Apply FastAPI router patterns
# - Apply JWT authentication best practices
# - Auto-generate pytest tests
# - Meet TRUST 5 quality standards

Skill Collaboration

Process where multiple skills collaborate on a single task.

Related Documentation

• Agent Guide - Agent system that uses skills
• Builder Agents Guide - Custom skill creation
• CLAUDE.md Guide - Skill configuration and rules