A Claude Code skill is an extension mechanism that bundles a repeated procedure or piece of expertise into a single SKILL.md file, adding it to Claude’s toolbox.

Background reference

This page is background material on Claude Code itself, the platform MoAI-ADK runs on. How to use MoAI-ADK is covered in Skill Guide, and the procedure for auto-generating skills with builder agents continues in Builder Agents Guide.

Info

One-line summary: Turn the checklist or procedure you kept pasting into chat into one SKILL.md, and it becomes an “expert in your pocket” whose contents Claude pulls out only when needed.

A skill is a SKILL.md file holding instructions for Claude to follow. Create the file once, and Claude either loads it automatically in relevant situations or you invoke it directly as /skill-name.

These situations are signals to create a skill:

• You keep pasting the same instructions or checklist into chat
• A section of CLAUDE.md has grown from “factual information” into a “multi-step procedure”

CLAUDE.md content resides in context at all times, but a skill’s body loads only when actually used. So you can keep long, detailed reference material with almost no token cost until it is needed.

Before skills, custom commands lived in the .claude/commands/ directory. Today skills subsume the command feature: if both .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md exist, the skill wins. Existing command files still work, but writing new extensions as skills is recommended.

Each skill is a directory with SKILL.md as its entry point. The body consists of YAML frontmatter plus markdown instructions, and supporting files can sit alongside.

my-skill/
├── SKILL.md       # required: instructions + frontmatter
├── reference.md   # optional: detailed reference (loaded when needed)
├── examples.md    # optional: example output
└── scripts/
    └── helper.py  # optional: a script Claude runs

Most frontmatter fields are optional, but description — what Claude uses to decide when to apply the skill — is effectively required.

---
name: api-conventions
description: API design patterns for this codebase. Use when writing or reviewing endpoints.
allowed-tools: Read Grep
---

When writing API endpoints:
- Follow RESTful naming conventions
- Return a consistent error format
- Include request validation

The main frontmatter fields:

The core design of skills is Progressive Disclosure — revealing content in stages, only as much as needed. It conserves the context window while storing deep knowledge.

flowchart TD
    A[Metadata
only the description always loaded] --> B{Relevant situation
arises?}
    B -->|Yes| C[Body
full SKILL.md loaded]
    C --> D{Detailed material
needed?}
    D -->|Yes| E[Bundled files
reference.md and scripts loaded]
    D -->|No| F[Work with the body alone]
    B -->|No| G[Not loaded
zero token cost]

In a normal session only every skill’s description is always loaded — Claude knows “what exists” — and the actual body enters only at the moment of invocation. Point to supporting files with links inside SKILL.md, and Claude reads them only when needed.

Claude loads a skill automatically when your request lines up with the skill’s description (and the optional when_to_use). In other words, the trigger is not a separate setting but keyword matching against the description text.

• The more your description carries keywords users would naturally type, the better it triggers.
• If it triggers too often regardless of intent, narrow the description further or allow manual invocation only with disable-model-invocation: true.
• To invoke directly, call it explicitly as /skill-name.

Where a skill is stored determines its reach.

On name collisions, priority runs enterprise > personal > project. Plugin skills use the plugin-name:skill-name namespace, so they never collide.

The following skill summarizes uncommitted changes. The !`git diff HEAD` syntax is dynamic context injection — the command runs before Claude sees the content, and its output is spliced into the body.

---
description: Summarize uncommitted changes and flag risks. Use when asked what has changed.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullets, then list risks such as missing error handling or hardcoding.

This skill triggers automatically when the user asks “what did I change?”, or directly via /summarize-changes.

MoAI-ADK operates on top of this skill mechanism. General-purpose skills like moai-foundation-core and moai-workflow-spec carry SPEC-workflow and quality-gate knowledge, and skills tailored to your project domain are auto-generated by builder agents.

From the MoAI-ADK perspective, skills span two core concerns at once. On the Tokenomics side, progressive disclosure is token-budget design — you carry only the one-line description (~100 tokens) at all times and pay for the body (~5K tokens) only at use time, which is far more economical than parking knowledge in CLAUDE.md. On the recursive self-learning side, skills are the edit target of harness evolution — the harness upgrading skill instructions based on observations the loop has accumulated is the core path of MoAI-ADK’s self-evolution. For hands-on details like authoring rules, namespaces, and the progressive-disclosure token budget, see the MoAI-ADK advanced documents below.

• Skill Guide
• Builder Agents Guide

• Claude Code official docs — Extend Claude with skills

Tip

If a skill does not trigger as expected, check with /doctor whether the description budget was exceeded, and verify the description contains keywords users would actually type.