██████╗██╗      █████╗ ██╗   ██╗██████╗ ███████╗    ███████╗██╗  ██╗██╗██╗     ██╗     ███████╗
██╔════╝██║     ██╔══██╗██║   ██║██╔══██╗██╔════╝    ██╔════╝██║ ██╔╝██║██║     ██║     ██╔════╝
██║     ██║     ███████║██║   ██║██║  ██║█████╗      ███████╗█████╔╝ ██║██║     ██║     ███████╗
██║     ██║     ██╔══██║██║   ██║██║  ██║██╔══╝      ╚════██║██╔═██╗ ██║██║     ██║     ╚════██║
╚██████╗███████╗██║  ██║╚██████╔╝██████╔╝███████╗    ███████║██║  ██╗██║███████╗███████╗███████║
 ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝    ╚══════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝╚══════╝

Claude Skills Integration Guide

Focus: how to author an Agent Skill — a SKILL.md folder Claude loads on demand. The whole system is one idea: a tiny always-loaded description advertises the skill, and the full instructions (plus any scripts and reference files) load only when a request matches. This is the Agent Skills format, distinct from building an agent loop — here you are packaging reusable expertise, not wiring tools into a runtime.

Overview

A Skill is a folder containing a SKILL.md file: YAML frontmatter (name + description) followed by markdown instructions. Optionally it bundles extra markdown reference files and executable scripts. Claude discovers skills automatically and pulls each one into context only when relevant — so you can install dozens of skills for roughly 100 tokens each until one actually fires.

The mechanism that makes this cheap is progressive disclosure, three levels of loading:

1. Metadata (always loaded) — the name and description from every skill's frontmatter sit in the system prompt. This is all Claude knows by default: that the skill exists and when to use it.
2. Instructions (loaded when triggered) — when a request matches a skill's description, Claude reads the SKILL.md body off the filesystem (via bash). Only now do the procedures enter context. Keep this under ~500 lines.
3. Resources (loaded as needed) — bundled reference files (REFERENCE.md, EXAMPLES.md) are read only when the body points to them; bundled scripts are executed, never read into context (only their output costs tokens). There is no practical limit on bundled content because it costs zero until accessed.

The single highest-leverage thing you write is the description. Claude uses it to choose among potentially 100+ skills, so it must say both what the skill does and when to reach for it — phrased in the third person with the trigger words a user would actually type.

Official Documentation

No package to install. Agent Skills are a file format, not a library — there is nothing to npm install to author one. Claude Code, the Claude Agent SDK, claude.ai, and the Claude API each read SKILL.md natively, and the format is now an open cross-tool standard (agentskills.io). In Claude Code, custom /commands have merged into skills: a legacy .claude/commands/deploy.md and a .claude/skills/deploy/SKILL.md both create /deploy and behave the same way (skills just add a folder for supporting files, richer frontmatter, and automatic model invocation). Loading skills from your own agent runtime is the Claude Agent SDK — see How the Agent SDK loads skills below and the ai-agents guide.

Frontmatter fields

Every SKILL.md opens with YAML between --- markers. Only description is strictly needed for Claude to know when to use a skill; every other field is optional. Six fields are part of the portable Agent Skills standard and work everywhere; the rest are Claude Code extensions.

Portable six. Outside Claude Code — claude.ai uploads, the Skills API, and package_skill.py from anthropics/skills — only name, description, license, compatibility, metadata, and allowed-tools are accepted; any Claude Code-only field makes packaging/upload hard-fail with an "unexpected key" error. Keep a skill you intend to publish to those surfaces on the portable six.

The reserved-word rule matters here: a skill about Claude Skills themselves cannot be named claude-skills. Name it after the activity instead — see the worked example below.

Build your first skill — a worked example

We'll build a real codeAmani-relevant skill: normalising Kenyan phone numbers to the 2547XXXXXXXX format Daraja requires. This is a perfect skill candidate — it's a fiddly, deterministic rule you'd otherwise paste into chat every time, and it has a clear "when to use" trigger.

(a) Directory layout

A skill is a directory; SKILL.md is the entrypoint. We bundle one helper script and one reference file to demonstrate progressive disclosure:

.claude/skills/normalising-mpesa-phones/
├── SKILL.md                 # always-discoverable metadata + concise instructions
├── REFERENCE.md             # the full edge-case table (loaded only when needed)
└── scripts/
    └── normalise.py         # deterministic normaliser (executed, never read)

Use gerund-form names (normalising-mpesa-phones), forward slashes always, and descriptive filenames — never doc2.md.

(b) SKILL.md frontmatter — the description is the trigger

The description is the only thing loaded until the skill fires, so phrase it with when-to-use cues (the words a teammate would actually say):

---
name: normalising-mpesa-phones
description: >-
  Normalises Kenyan phone numbers to the 2547XXXXXXXX / 2541XXXXXXXX format the
  Daraja (M-Pesa) API requires. Use when formatting a phone number for an STK Push,
  a B2C payout, an SMS, or whenever a number arrives as 07.., +2547.., or 2547...
allowed-tools: Bash(python3 *)
---

Compare a bad description — description: Helps with phone numbers — which gives Claude no trigger to match on and no idea what "help" means. Be specific; include key terms (Daraja, STK Push, 07.., +254).

(c) The body — concise instructions

Assume Claude is already smart. State the rule and the canonical path; don't explain what a phone number is:

# Normalising M-Pesa phone numbers

Daraja rejects anything that is not `254` followed by 9 digits (e.g. `254712345678`).
Normalise every number to that shape **before** calling any Daraja endpoint.

## Rules
- Strip spaces, hyphens, and a leading `+`.
- `07XXXXXXXX` or `01XXXXXXXX` → replace the leading `0` with `254`.
- `7XXXXXXXX` / `1XXXXXXXX` (9 digits, no prefix) → prepend `254`.
- Already `2547…` / `2541…` (12 digits) → leave as-is.
- Anything else → reject; do not guess.

## Use the bundled script (preferred — deterministic)
Run it rather than reimplementing the rule:

    python3 ${CLAUDE_SKILL_DIR}/scripts/normalise.py "0712 345 678"
    # → 254712345678

For the full edge-case table (Safaricom vs Airtel prefixes, invalid lengths),
see [REFERENCE.md](REFERENCE.md).

Note the two progressive-disclosure links: REFERENCE.md is read only if Claude needs the edge cases, and normalise.py is executed (its source never enters context). Keep references one level deep — link every supporting file directly from SKILL.md, never a chain of a.md → b.md → c.md.

(d) The bundled script — deterministic, self-contained

A pre-made script is more reliable than asking Claude to regenerate the regex each time, and it costs zero context until run:

#!/usr/bin/env python3
"""Normalise a Kenyan phone number to Daraja's 2547XXXXXXXX format."""
import re, sys

def normalise(raw: str) -> str:
    s = re.sub(r"[\s\-]", "", raw).lstrip("+")
    if re.fullmatch(r"0[17]\d{8}", s):      # 07.. / 01..
        return "254" + s[1:]
    if re.fullmatch(r"[17]\d{8}", s):       # bare 9-digit
        return "254" + s
    if re.fullmatch(r"254[17]\d{8}", s):    # already canonical
        return s
    raise ValueError(f"Not a valid Kenyan mobile number: {raw!r}")

if __name__ == "__main__":
    print(normalise(sys.argv[1]))

(e) allowed-tools — pre-approve just enough

The frontmatter line allowed-tools: Bash(python3 *) lets Claude run the helper without a permission prompt during the turn that fires the skill, while leaving every other tool governed by your normal permission settings. The grant is turn-scoped — it clears when you send your next message, then re-applies each time the skill is invoked again. Grant narrowly — Bash(python3 *), not bare Bash — and use disallowed-tools to remove a tool from the pool for a locked-down skill. For a side-effecting skill (deploy, send money) add disable-model-invocation: true so only a human can fire it. (In an Agent SDK session this frontmatter field is ignored for project/personal skills — pre-approve via the SDK's allowedTools option instead.)

(f) Where it lives and how it's discovered

The same SKILL.md works across every surface; only the install path changes:

In Claude Code the directory name becomes the slash command (/normalising-mpesa-phones) and the project skill is picked up automatically from .claude/skills/ in the cwd and every parent up to the repo root. A same-named skill at a higher level wins (enterprise > personal > project) and also overrides a bundled skill of that name. Note that a project skill's allowed-tools grant is not gated by workspace trust — Claude Code applies it even in an untrusted -p run — so review the allowed-tools of any skill checked into a repo before running Claude Code there. (Adding a .claude-plugin/plugin.json to a skill folder does require accepting the workspace-trust dialog first.) Custom Skills do not sync across surfaces — a skill uploaded to the API is not on claude.ai, and Claude Code skills are filesystem-only; you can optionally pull skills you enabled on claude.ai into ~/.claude/skills/synced/ with CLAUDE_CODE_SYNC_SKILLS=1.

How progressive disclosure loads a skill

The cost ladder is the whole point: thousands of words of edge-case docs and a dozen scripts sit on disk at zero token cost until the one file a task needs is actually opened. One nuance to design around: once the body loads it stays in context for the rest of the session (Claude Code doesn't re-read the file each turn), so write it as standing guidance, keep it lean, and expect a large skill to be trimmed by auto-compaction. The allowed-tools grant is the exception — that resets every message.

How Claude decides to load a skill

If a skill never triggers, the fix is almost always the description: add the keywords users actually say. If it triggers too eagerly, make the description more specific or set disable-model-invocation: true.

How the Agent SDK loads skills

The Claude Agent SDK reads the same filesystem skills as the CLI — there is no programmatic registration API for skills (unlike subagents, which you can define inline via the agents option). Two knobs govern them:

• settingSources / setting_sources must include 'user' and/or 'project' for skills to load at all. With default query() options both are loaded, so ~/.claude/skills/, <cwd>/.claude/skills/, and every parent .claude/skills/ up to the repo root are discovered. If you set settingSources explicitly and omit those sources, no skills load — a common gotcha.
• skills scopes which discovered skills Claude may auto-invoke: "all" (default when omitted) enables everything, a list of exact names allows only those, and [] disables auto-invocation. Setting it auto-adds the Skill tool to allowedTools; if you pass an explicit tools list, include "Skill" yourself.

const options = {
  cwd: process.cwd(),                    // .claude/skills/ here or in a parent
  settingSources: ["user", "project"],   // required — load skills from disk
  skills: "all",                         // or ["formatting-kes", "normalising-mpesa-phones"]
  allowedTools: ["Read", "Write", "Bash"],
};

Dispatch a skill directly by putting /<name> in the prompt string — this works even if the name is not in your skills allowlist. Confirm what loaded by reading the init system message: its skills array lists user-invocable skills, and slash_commands lists every dispatchable command (built-ins, bundled skills, your skills, .claude/commands/ files). One SDK-only caveat: for project/personal skills the allowed-tools frontmatter field is ignored — grant those tools through the SDK's allowedTools / allowed_tools option instead. In non-interactive (-p / SDK) runs a context: fork skill always blocks for its result rather than backgrounding.

Authoring checklist

• description is third-person and states what it does + when to use it, with real trigger keywords.
• name is lowercase-hyphen, ≤64 chars, and avoids the reserved words anthropic/claude and XML tags (or is omitted in Claude Code to inherit the directory name).
• SKILL.md body is under ~500 lines; long material is split into bundled files.
• Supporting files are referenced one level deep from SKILL.md.
• Reference files >100 lines start with a table of contents.
• Scripts handle their own errors (don't punt back to Claude) and document any constants.
• File paths use forward slashes; no time-sensitive "before August 2025" text.
• allowed-tools grants narrowly; side-effecting skills set disable-model-invocation: true.
• Tested with the models you'll run it on (Haiku needs more guidance than Opus).

codeAmani notes

• Secrets stay server-side. A skill bundles instructions and scripts, never credentials. The phone-normaliser script takes a number, not a key. If a skill must call Daraja or Supabase, it reads DARAJA_CONSUMER_SECRET / SUPABASE_SERVICE_ROLE_KEY from the environment at runtime — the SKILL.md and its scripts go in git, so they must contain zero secrets. Audit any third-party skill before trusting it; a malicious one can run code with your permissions.
• AI routing stays Claude-primary. Skills are an Anthropic-native capability — there's no provider choice to make. They make Claude a specialist for a repeated task, complementing (not replacing) the house routing: Claude for reasoning/coding, OpenAI for structured output, HuggingFace for open models.
• High-leverage codeAmani skills to build first: the normalising-mpesa-phones skill above; a formatting-kes skill (integer KES, Ksh 1,234 display, no decimals to Daraja); a verifying-mpesa-callbacks skill that encodes the idempotency-on-CheckoutRequestID + reconciliation rule (see daraja-api and webhooks); and a Swahili-tone copy skill for support replies. Each is a fiddly house convention you currently re-explain — exactly what a skill is for.
• Ship them as a project skill. Commit .claude/skills/<name>/ to the repo so every teammate (and every agent in the repo) inherits the convention. For org-wide reuse, package them into a Claude Code plugin's skills/ directory — the same pattern this very tech-stack repo uses to publish its guides.