Lab Architecture

Lab: Skill Architecture

Track: Skills | Level: Beginner-Intermediate | Time: 30 minutes

This page is a deep dive into the anatomy of a SKILL.md file -- the two-part structure (frontmatter + body), every field explained, and best practices for keeping skills lean and effective. Based on skills/02-skill-anatomy.ipynb.

---

SKILL.md: Two Parts

Every SKILL.md has exactly two sections separated by --- delimiters:

---
[FRONTMATTER: YAML configuration]
---

[BODY: Markdown instructions]

The frontmatter tells Claude what the skill is and when to use it. The body tells Claude how to execute it.

---

Part 1: Frontmatter (YAML)

Required Fields (6)

Every SKILL.md must include these six fields:

1. name (String)

• Format: kebab-case (lowercase, hyphens only)
• Pattern: ^[a-z0-9-]+$
• Max length: 64 characters
• Cannot contain "claude" or "anthropic"

name: bigquery-migrations      # correct
name: BigQueryMigrations       # wrong (camelCase)
name: bigquery_migrations      # wrong (snake_case)

2. description (String, Multiline)

Must include: (a) what the skill does, (b) a "Use when..." phrase, and (c) 2-6 trigger phrases.

description: |
  Generate BigQuery schema migrations with validation.
  Use when: migrating schemas, adding fields, changing types.
  Triggers: migration, schema change, add field, alter table.

The trigger phrases are what allow Claude to auto-activate the skill based on user intent.

3. allowed-tools (String, CSV)

Must be a quoted CSV string -- not a YAML array. Bash must always be scoped.

allowed-tools: "Read,Write,Grep,Bash(git:*)"   # correct
allowed-tools: [Read, Write, Grep]              # wrong (array)
allowed-tools: "Bash"                           # wrong (unscoped)

4. version (String, SemVer)

Three-part semantic versioning: MAJOR.MINOR.PATCH.

version: 1.0.0    # correct
version: 1.0      # wrong (only 2 parts)

5. author (String)

Format: Name <email>.

author: Jane Developer <jane@example.com>

6. license (String, SPDX)

license: MIT
license: Apache-2.0

Optional Fields

Field	Type	Purpose
model	String	Override the default model (sonnet, haiku, or opus)
context	String	Set to fork to run in a subagent
agent	String	Subagent type (e.g., Explore)
user-invocable	Boolean	Set false to hide from the slash menu
argument-hint	String	Autocomplete hint (e.g., "<file-path>")
hooks	Object	Lifecycle hooks (e.g., pre-tool-call)
compatibility	String	Environment requirements (e.g., "Node.js >= 18")
compatible-with	String	Platform targets: claude-code, cursor, windsurf, cline
tags	Array	Discovery tags for categorization

Common Tool Authorization Patterns

Use Case	Tools
Read-only analysis	Read,Grep,Glob
File manipulation	Read,Write,Edit,Grep,Glob
Git operations	Read,Write,Bash(git:*)
Package management	Read,Bash(npm:*),Bash(pip:*)
Web research	Read,WebFetch,WebSearch

Principle: grant the minimum tools needed. Read-only skills should not have Write or Edit. Bash must always be scoped to a namespace.

---

Part 2: Body (Markdown)

Size Limits

Metric	Target	Hard Maximum
Lines	150	500
Words	--	2,000
Tokens (est.)	--	3,000

If your skill exceeds 150 lines, use Progressive Disclosure Architecture (PDA): move detailed implementation into references/implementation.md and reference it as ${CLAUDE_SKILL_DIR}/references/implementation.md. The SKILL.md stays lean; the agent reads references on demand.

Purpose Statement

The first paragraph after # Title or content in ## Overview serves as the purpose statement:

• Must be 1-2 sentences
• Must be 400 characters or fewer
• Explains what the skill does and when to use it

The 7 Required Sections

# Skill Name

## Overview
Brief purpose statement (1-2 sentences, max 400 chars).

## Prerequisites
What must exist before running (files, env vars, tools).

## Instructions
### Step 1: [Action]
### Step 2: [Action]

## Output
What the skill produces (JSON, files, reports).

## Error Handling
How to handle common errors and edge cases.

## Examples
Working examples of skill execution.

## Resources
Related docs, links to ${CLAUDE_SKILL_DIR}/references/ files.

Code Block Rules

Bash blocks containing dangerous commands (rm, curl, pip, etc.) must include set -euo pipefail:

```bash
set -euo pipefail
curl -sSL https://example.com/install.sh | bash
```

Magic numbers (values >= 200) must have an inline comment explaining their meaning:

timeout = 300  # 300 second timeout for large repos

The ${CLAUDE_SKILL_DIR} Variable

Always use ${CLAUDE_SKILL_DIR} for paths relative to the skill directory. Never use absolute paths or ${CLAUDE_PLUGIN_ROOT}.

See `${CLAUDE_SKILL_DIR}/references/implementation.md` for details.

---

Real Example: Putting It Together

---
name: git-commit-helper
description: |
  Generate conventional commit messages.
  Use when: creating commits, writing commit messages.
  Triggers: commit message, generate commit, conventional commits.
allowed-tools: "Read,Bash(git:*)"
version: 1.0.0
author: Dev Team <dev@example.com>
license: MIT
model: haiku
tags: [git, commits, productivity]
---

# Git Commit Message Generator

## Overview
Generates conventional commit messages following team standards.
Use when creating commits or writing commit messages.

## Prerequisites
- Git repository initialized
- Staged changes exist

## Instructions
### Step 1: Analyze Changes
Use `git diff --staged` to see what changed.

### Step 2: Determine Type
feat, fix, docs, refactor, test, chore.

### Step 3: Write Message
Format: `type(scope): description`

## Output
Return the commit message as plain text.

## Error Handling
If no staged changes, prompt user to stage files first.

## Examples
Input: staged change adds a login endpoint
Output: `feat(auth): add login endpoint with JWT validation`

## Resources
- [Conventional Commits](https://conventionalcommits.org)

---

Key Takeaways

1. 6 required frontmatter fields: name, description, allowed-tools, version, author, license
2. 7 required body sections: Overview, Prerequisites, Instructions, Output, Error Handling, Examples, Resources
3. Bash must be scoped: Bash(git:*) or Bash(npm:*), never bare Bash
4. CSV for tools: quoted string, not YAML array
5. Keep it lean: target 150 lines, overflow to references/ (PDA pattern)
6. Portable paths: always ${CLAUDE_SKILL_DIR}, never absolute paths

See Also

• SKILL-md-Specification -- full specification reference
• Skill-Template -- starter template
• Lab-Build-Your-Own -- build a skill from scratch
• Lab-Mental-Model -- the big picture
• Open the notebook in Colab