virtualian/pai-autodocs/developer

In this tutorial, you will build a complete PAI skill from scratch. You will create the required directory structure, write a SKILL.md with proper frontmatter, add a workflow, and test that PAI discovers and routes to your skill automatically. By the end, you will understand the full anatomy of a skill and how the pieces connect.

What you will learn

• The required directory structure for a PAI skill
• How to write a SKILL.md with YAML frontmatter and workflow routing
• The TitleCase naming convention and why it matters
• How to create a workflow file
• How PAI discovers and activates skills
• The distinction between skills, workflows, and tools

Prerequisites

Before starting this tutorial, you need:

• PAI installed and working -- you should be able to run pai and see the Algorithm header
• Completed the [getting started tutorial](/user/first-session/) -- you understand the Algorithm phases
• A text editor for creating files (or you can ask PAI to create them for you)
• Basic familiarity with Markdown syntax

What you will build

You will create a QuickNote skill -- a simple skill that captures quick notes and saves them to a file. This is intentionally minimal so you can focus on the skill structure rather than complex logic.

When finished, you will be able to say "take a quick note" in a PAI session and have it automatically route to your skill.

Step 1: Understand the skill directory structure

Every PAI skill follows a mandatory structure. Here is the skeleton:

SkillName/
├── SKILL.md              # Main skill file (always uppercase)
├── Tools/                # CLI tools directory (always present, even if empty)
└── Workflows/            # Workflow files
    └── WorkflowName.md   # Individual workflow

Three things to note:

1. `SKILL.md` is always uppercase. This is a convention -- it is the main entry point for every skill.
2. `Tools/` must always exist, even if you have no tools yet. This is a structural requirement.
3. `Workflows/` contains execution procedures -- step-by-step instructions for doing work.

Skills live in ~/.claude/skills/. Let's create the directory structure now.

Step 2: Create the skill directory

Open your terminal and create the QuickNote skill directories:

mkdir -p ~/.claude/skills/QuickNote/Workflows
mkdir -p ~/.claude/skills/QuickNote/Tools

Verify the structure:

ls -la ~/.claude/skills/QuickNote/

Expected output:

total 0
drwxr-xr-x  4 user  staff  128 Feb 16 10:00 .
drwxr-xr-x  N user  staff  NNN Feb 16 10:00 ..
drwxr-xr-x  2 user  staff   64 Feb 16 10:00 Tools
drwxr-xr-x  2 user  staff   64 Feb 16 10:00 Workflows

Why TitleCase?

Notice that the directory is QuickNote, not quick-note, quicknote, QUICK_NOTE, or quick_note. PAI uses TitleCase (PascalCase) for all naming:

The only exception is SKILL.md itself, which is always uppercase by convention.

Step 3: Write the SKILL.md file

The SKILL.md file has two parts: YAML frontmatter and a Markdown body. Create the file at ~/.claude/skills/QuickNote/SKILL.md with the following content:

---
name: QuickNote
description: Capture and organize quick notes. USE WHEN user wants to take a note, jot something down, capture a thought, save a reminder, OR record a quick idea.
---
 
# QuickNote
 
Capture quick notes and save them to an organized file.
 
## Customization
 
**Before executing, check for user customizations at:**
`~/.claude/skills/PAI/USER/SKILLCUSTOMIZATIONS/QuickNote/`
 
If this directory exists, load and apply:
-`PREFERENCES.md` - User preferences and configuration
 
These define user-specific preferences. If the directory does not exist, proceed with skill defaults.
 
## Workflow Routing
 
| Workflow | Trigger | File |
|----------|---------|------|
| **Capture** | "take a note", "jot this down", "save a thought" | `Workflows/Capture.md` |
 
## Examples
 
**Example 1: Quick thought capture**

User: "Take a quick note: remember to review the API rate limits before launch" -> Invokes Capture workflow -> Saves note with timestamp to ~/Notes/quick-notes.md -> Confirms note was saved

 
**Example 2: Reminder note**

User: "Jot down that the design review is moved to Thursday" -> Invokes Capture workflow -> Appends timestamped note to file -> Confirms with note content

 
## Defaults
 
- **Notes file:** `~/Notes/quick-notes.md`
- **Format:** Timestamped Markdown list items
- **Behavior:** Append only (never overwrite existing notes)

Breaking down the frontmatter

The YAML frontmatter is the most critical part. Let's examine each element:

---
name: QuickNote
description: Capture and organize quick notes. USE WHEN user wants to take a note, jot something down, capture a thought, save a reminder, OR record a quick idea.
---

`name` -- Must use TitleCase. Must match the directory name.

`description` -- This is a single line (not multi-line with |). It has a strict structure:

1. What it does: "Capture and organize quick notes."
2. `USE WHEN` keyword: This is mandatory. Claude Code parses this to determine when to activate the skill.
3. Intent triggers: Natural language descriptions of when this skill should activate, connected with OR.

The USE WHEN clause uses intent matching, not string matching. You do not need to list exact phrases in quotes. Instead, describe the intent: "user wants to take a note" covers "take a note", "I need to note something", "let me write that down", and many other phrasings.

:::caution The description has a hard limit of 1024 characters (Anthropic constraint). Keep it concise. :::

Breaking down the Markdown body

The body contains several key sections:

1. Brief description -- One or two lines explaining the skill
2. Customization block -- Standard block for user overrides (explained in Step 7)
3. Workflow Routing -- Table mapping triggers to workflow files
4. Examples -- 2-3 concrete usage patterns (required for every skill)
5. Defaults -- Default configuration values

The Workflow Routing table has three columns:

The Examples section is not optional decoration. Research shows that examples improve tool selection accuracy significantly. They show Claude the full input-to-behavior-to-output pattern, not just trigger keywords.

Step 4: Create the Capture workflow

Workflows are step-by-step execution procedures. They tell PAI exactly what to do when the workflow is triggered. Create the file at ~/.claude/skills/QuickNote/Workflows/Capture.md:

# Capture Workflow
 
Capture a quick note and append it to the notes file.
 
## Steps
 
1.**Extract the note content** from the user's message
   -Strip any meta-language ("take a note", "jot down that")
   -Keep the actual content to save
 
2.**Ensure the notes directory exists**
   ```bash
   mkdir -p ~/Notes
   ```
 
3.**Append the note** with a timestamp to `~/Notes/quick-notes.md`
   ```
   Format:
   -[YYYY-MM-DD HH:MM] Note content here
   ```
 
4.**Confirm to the user** what was saved
   -Show the note content
   -Show the file path
   -Show the timestamp
 
## Output Format
 

Saved note to ~/Notes/quick-notes.md:

• [2026-02-16 14:30] Your note content here

Workflows vs reference documentation

This is a critical distinction in PAI:

Workflows are actions. Reference docs are context. Never put reference documentation inside the Workflows/ directory.

Step 5: Test the skill

Start a new PAI session to pick up the new skill:

pai

When PAI starts, it scans the YAML frontmatter of every SKILL.md in ~/.claude/skills/. Your QuickNote skill's USE WHEN clause is now part of the routing table.

Try invoking it:

Take a quick note: check the deployment logs for the memory leak issue

What you should observe

1. The Algorithm runs -- you see the full OBSERVE through LEARN phases
2. In the THINK phase, the Skill Check should show:

`` 🔍 SKILL CHECK (validate hook hints against ISC): │ Hook suggested: QuickNote │ ISC requires: note capture and file persistence │ Final skills: QuickNote:Capture ``

1. In BUILD/EXECUTE, PAI follows your workflow steps:

• Creates ~/Notes/ if it does not exist
• Appends the timestamped note to ~/Notes/quick-notes.md

1. In VERIFY, the ISC criteria are checked against actual results

After execution, verify the note was saved:

cat ~/Notes/quick-notes.md

Expected output:

-[2026-02-16 14:30] check the deployment logs for the memory leak issue

Step 6: Understand how skill discovery works

Now that your skill is working, let's understand the full discovery and routing pipeline:

Session startup

When PAI starts (pai command), it reads the YAML frontmatter from every SKILL.md file under ~/.claude/skills/. Only the frontmatter loads at startup -- the full Markdown body is not read until the skill is actually invoked. This keeps startup fast.

Session Start
    │
    ▼
Scan ~/.claude/skills/*/SKILL.md
    │
    ▼
Read YAML frontmatter only (name + description)
    │
    ▼
Build routing table from USE WHEN clauses
    │
    ▼
Ready for user input

Skill activation (two passes)

When you type a prompt, skill activation uses a two-pass system:

Pass 1: Hook hints (before Algorithm starts)

Claude Code matches your raw prompt against skill descriptions and USE WHEN triggers to suggest which skills might be relevant. These are draft suggestions -- starting points, not final decisions.

Pass 2: THINK validation (after OBSERVE completes)

In the THINK phase, with the full context of reverse-engineering and ISC criteria, PAI validates the hook's suggestions. It can:

• Confirm a hook suggestion that matches the ISC
• Add skills the hook missed but the ISC requires
• Remove skills the hook suggested that do not serve the ISC

Pass 2 is authoritative. It overrides Pass 1 based on ISC evidence.

Skill invocation

Once a skill is selected, PAI:

1. Reads the full SKILL.md body (not just frontmatter)
2. Uses the Workflow Routing table to find the right workflow file
3. Reads and follows the workflow file step-by-step

User prompt: "jot down to review the API docs"
    │
    ▼
Pass 1 (Hook): suggests QuickNote
    │
    ▼
OBSERVE: reverse-engineer intent, create ISC
    │
    ▼
Pass 2 (THINK): validates QuickNote against ISC → confirmed
    │
    ▼
Load QuickNote/SKILL.md body
    │
    ▼
Route to Workflows/Capture.md via routing table
    │
    ▼
Follow Capture.md step-by-step

Step 7: Understand skill customization

The Customization section in your SKILL.md points to a user overrides directory. This separates skill logic from personal preferences.

PAI has two categories of skills: