The problem

Agents are powerful — but without structure they are unpredictable.

• You repeat the same instructions across conversations
• Different team members get different results for the same task
• Heavy context is loaded even when it is irrelevant
• There is no reviewable, auditable record of how work gets done

Skills give agents procedural memory — repeatable playbooks they can activate on demand.

What is a skill?

A skill is a reusable capability package that helps an agent perform a recurring class of tasks more reliably.

It bundles three things:

A skill is not just context — it is a task-specific operating procedure.

Where skills fit

Use a skill when correctness depends on following a repeatable process, not just having access to a tool.

Anatomy on disk

A skill is a folder with a SKILL.md file and optional resources.

my-skill/
├── SKILL.md            # required — instructions and metadata
├── scripts/            # optional — executable helpers
│   └── validate.sh
├── references/         # optional — deep docs, supporting context
└── assets/             # optional — templates, schemas, examples

The folder name becomes the skill's identity if no name is specified in frontmatter.

Inside SKILL.md — frontmatter

The YAML frontmatter controls how the skill behaves at runtime.

---
name: test-workflow
description: Submit a triage incident and monitor the 7-step workflow
argument-hint: [payment|auth|checkout|api-gateway]
disable-model-invocation: true    # only manual /slash invocation
user-invocable: true              # appears in the / menu
allowed-tools: Bash, Read         # tools the agent can use
context: fork                     # run in isolated subagent context
---

Every field except name is optional — but description is critical for activation.

Inside SKILL.md — body

A good SKILL.md body defines six things:

1. What the skill does — one sentence
2. When to use it — triggering conditions
3. What inputs it expects — arguments, prerequisites
4. The steps to follow — numbered, explicit
5. The required output format — tables, JSON, status codes
6. Final checks — validation before responding

The body is where the agent's operating procedure lives.

Script integration

Skills become powerful when they can execute code. Two mechanisms:

Preprocessing — inject data before the agent sees the prompt

Current git status: !`git status --short`
Test results: !`mvn test 2>&1 | tail -20`

Runtime execution — let the agent run scripts

allowed-tools: Bash(bash ${CLAUDE_SKILL_DIR}/scripts/*.sh)

${CLAUDE_SKILL_DIR} resolves to the skill's folder — bundle scripts alongside SKILL.md.

Skill scoping

Skills can live at different levels of the system.

Project skills are version-controlled with the codebase. Personal skills follow the developer. Enterprise skills enforce organisational standards.

Progressive disclosure

Skills solve the too-much-context-too-early problem.

Tier 1 — Catalog     → load only name + description for all skills
Tier 2 — Instructions → load full SKILL.md when the skill is relevant
Tier 3 — Resources    → load scripts / references / assets only as needed

This makes skills a form of lazy-loaded procedural memory — the agent knows what it can do without carrying the weight of how until it needs to.

Activation is a routing problem

The description field is the main surface the agent uses to decide whether to activate a skill.

User request
  → Compare against skill catalog (name + description)
    → Pick relevant skill
      → Load SKILL.md
        → Load resources if needed

A bad description causes missed activations, wrong activations, and unreliable behaviour.

A good description says both what the skill does and when it should be used.

What is a constitution?

A constitution is a foundational, non-user-invocable skill that defines the rules, constraints, and shared knowledge that all other skills must follow.

---
name: constitution
description: Foundational principles for all project skills.
user-invocable: false     # not a /slash command
---

It is auto-loaded as background context whenever other skills run — ensuring every skill operates from the same source of truth.

Why a constitution matters

Without a constitution, each skill is an island — it makes its own assumptions about ports, service names, safety rules, and output formats.

A constitution turns a collection of skills into a coherent skill system.

What goes in a constitution

A constitution typically defines:

• Service architecture — names, ports, dependencies, startup order
• Safety rules — what skills must never do, what they must always check
• Build conventions — standard commands, module structure
• Domain knowledge — workflow steps, API contracts, configuration rules
• Output standards — formatting, status indicators, error reporting

It is the project's institutional knowledge encoded for agent consumption.

Constitution — real example

An incident triage system with three microservices and a 7-step AI workflow:

## Safety Rules
### NEVER:
- Kill processes on ports outside {9100, 9200, 9300}
- Modify application.conf without user confirmation
- Commit or echo API keys

### ALWAYS:
- Check OPENAI_API_KEY before starting the triage system
- Check port availability before starting a service
- Report errors with service name, port, and next steps

The constitution encodes what every skill needs to know but no single skill should own.

Constitution — architecture table

The constitution provides a single reference that all skills share:

## Service Architecture

| Service                  | Port | Service Name (exact)       |
|--------------------------|------|----------------------------|
| Agentic Triage System    | 9100 | triage-service             |
| Evidence MCP Server      | 9200 | evidence-mcp-server        |
| Knowledge Base MCP Server| 9300 | knowledge-base-mcp-server  |

Startup order: Evidence (9200) → Knowledge Base (9300) → Triage (9100)

When a /start-services skill checks ports and a /test-workflow skill sends requests, they both read from the same truth.

How skills reference the constitution

The constitution is auto-loaded — skills do not need to explicitly import it.

.claude/skills/
├── constitution/           ← user-invocable: false (auto-loaded)
│   └── SKILL.md
├── start-services/         ← reads constitution context automatically
│   ├── SKILL.md
│   └── scripts/
│       ├── preflight.sh
│       └── healthcheck.sh
├── test-workflow/          ← reads constitution context automatically
│   ├── SKILL.md
│   └── scripts/
│       ├── submit-incident.sh
│       └── poll-status.sh
└── check-config/           ← reads constitution context automatically
    ├── SKILL.md
    └── scripts/
        └── validate.sh

Who defines skills?

Skills are not just a developer tool — they are an organisational capability.

Skills encode how the team has agreed to work — not just what the agent can do.

Rules vs processes — where to put standards

Not everything belongs in a skill. The right home depends on the type of standard.

Git workflow as skills

A tech lead defines how the team works with git — as executable, reviewable skills.

---
name: commit
description: Create a git commit following conventional commit format
disable-model-invocation: true   # user-only — commits are side effects
allowed-tools: Bash, Read, Grep
---

These skills replace a wiki page that nobody reads with enforceable process at the point of action.

Git commit skill — inside the body

The skill defines the exact format, valid types, and module-based scopes:

## Commit message format
<type>(<scope>): <short description>

### Types
feat | fix | refactor | docs | test | chore | style

### Scopes (module-based)
evidence | kb | triage | root | all

## Rules
- Never use `git add -A` — stage specific files
- Never stage .env files or credentials
- Short description: lowercase, imperative, under 72 chars

A new team member runs /commit and the agent follows the team's conventions — without reading a contributing guide.

Coding standards as skills

Static rules go in CLAUDE.md. But template-based standards become skills.

---
name: new-agent
description: Scaffold a new Akka agent following project patterns
disable-model-invocation: true
allowed-tools: Bash, Read, Write, Edit
---

The skill encodes the team's established patterns:

An architect defines this once. Every new agent follows the pattern.

The organisational skill stack

A mature team layers skills across scopes:

Enterprise (managed settings)
├── security-review       ← Platform team: mandatory before deploy
├── compliance-check      ← Legal/compliance: data handling rules
└── incident-response     ← SRE: runbook-driven response process

Project (.claude/skills/ in repo)
├── constitution          ← Architect: project truth
├── commit, branch, pr    ← Tech lead: git workflow
├── new-agent             ← Architect: component templates
├── start-services        ← Team: operational skills
└── test-guardrails       ← Team: quality gates

Personal (~/.claude/skills/)
├── quick-debug           ← Developer: personal shortcuts
└── my-review-style       ← Developer: personal preferences

Higher scopes set the floor. Lower scopes add specificity.

Building a skill system

A well-designed skill system covers the full development lifecycle:

Each skill is focused. The constitution keeps them aligned. The organisational hierarchy keeps them governed.

Invocation control

Skills support two dimensions of control:

Runtime architecture

A skill-enabled host system has to:

1. Discover skills from configured directories
2. Parse metadata from SKILL.md frontmatter
3. Expose a catalog of available skills to the model
4. Activate a skill by injecting its full instructions
5. Resolve resources — scripts, references, templates
6. Auto-load constitutions as persistent background context
7. Mediate execution safely — sandbox scripts, enforce allowed-tools

Skills are a model-facing abstraction backed by runtime orchestration.

Security and governance

A skill can influence behaviour. Scripts can create side effects.

Risk surface:

• Prompt injection flowing through skill instructions into tool calls
• Unsafe bundled scripts with broad shell access
• Over-broad allowed-tools grants
• Silent loss of skill instructions after context compaction

Defensive posture:

• Sandbox execution — restrict with allowed-tools: Bash(pattern)
• Require user approval for destructive operations
• Validate structured inputs and outputs in scripts
• Log skill activation and script execution
• Protect constitution from being compacted away

What makes a good skill

Authoring checklist

When writing a new skill, verify:

• [ ] Can the agent tell when to use this from the description alone?
• [ ] Are inputs, steps, and output shape explicit?
• [ ] Does the skill define its own final checks?
• [ ] Are safety boundaries respected (or deferred to the constitution)?
• [ ] Are scripts executable and idempotent where possible?
• [ ] Is the skill narrow enough to do one thing well?

---
name: pdf-exec-brief
description: Use when the user wants PDFs summarised into a
  concise executive brief with risks, actions, and citations.
---

Takeaway

A skill is best understood as a:

portable, lazy-loaded packet of procedural memory for an agent

Skills are stronger than saved prompts and lighter than building a separate agent for every task.