---
title: Skills
description: Structured workflows that give agents repeatable, multi-phase processes for common development tasks.
sidebar_position: 4
---

Agent skills are structured Markdown workflows that guide AI coding agents through complex, multi-step tasks. Instead of describing what you want step by step, you invoke a skill and the agent follows a tested process with built-in quality gates.

Skills are the difference between "write me a PR" and a repeatable lifecycle that audits changes, runs CI, waits for review comments, addresses every one, and confirms CI passes before finishing. They encode the workflow discipline that makes autonomous agents trustworthy.

## The skill standard

Skills follow the [Agent Skills specification](https://agentskills.io/specification) — an open standard for portable, structured agent workflows. The standard is client-agnostic: skills work across Claude Code, Codex, and any system that supports skill-based workflows.

A skill is a Markdown file (`SKILL.md`) with YAML frontmatter that lives in a named directory:

```
skills/
  debug-issue/
    SKILL.md
  ship-pr/
    SKILL.md
```

Each skill file has:

- **Frontmatter** with a `name` (must match the directory, lowercase alphanumeric and hyphens, 1–64 chars) and a `description` (what it does and when to trigger, max 1,024 chars)
- **A body** containing defaults, constraints, phased workflow steps, quality gates, and a defined handoff

The `description` is the routing signal. When you say "debug why the test is flaking," the agent matches that against skill descriptions and activates the right one. Descriptions are written for routing precision, not marketing.

### Progressive disclosure

Skills use a three-stage model that keeps context costs low:

1. **Catalog time** — The agent sees only skill names and descriptions (~50–100 tokens each). This is the routing signal.
2. **Activation time** — When a skill triggers, the full `SKILL.md` body loads with the complete workflow, constraints, and quality gates.
3. **Execution time** — The agent follows the phased workflow, producing outputs, running checks, and stopping at human checkpoints when needed.

You do not pay the context cost of every skill on every request.

### Skill structure

The recommended section order is informed by research on how language models process instructions (primacy and recency effects). Critical rules go early; guardrails go at the end. For the full research basis, see [Skill Design Guide](/skill-design).

1. **Opening contract** — one sentence stating what the skill does
2. **Defaults** — what happens with no inputs
3. **Inputs** — what the skill accepts
4. **Required artifacts** — file paths for output
5. **Multi-agent pattern** — recommended sub-agent roles (optional)
6. **Global constraints** — hard rules that always apply
7. **Human checkpoints** — exact conditions for asking the user
8. **Workflow phases** — ordered execution steps
9. **Guardrails** — common failure modes to avoid
10. **Final handoff** — what to report when done

## What Agent Layer adds

The skill standard defines the format. Agent Layer builds on it with:

- **A built-in library of 24 skills** covering planning, implementation, review, debugging, PR lifecycle, auditing, and codebase improvement — available after `al init` with no setup.
- **Client projection** — Skills are authored once under `.agent-layer/skills/` and projected during `al sync` to `.agents/skills/` for shared-skill clients and `.claude/skills/` for Claude Code.
- **Memory integration** — Skills read from and write to project memory files (`ISSUES.md`, `BACKLOG.md`, `ROADMAP.md`, `DECISIONS.md`, `COMMANDS.md`, `CONTEXT.md`), keeping project context durable across sessions.
- **Artifact conventions** — Skills produce structured output files under `.agent-layer/tmp/` using a standard naming convention (`<skill-name>.<run-id>.<type>.md`). Planning workflows produce a trio of artifacts — a plan, a task list, and a context file — so that any agent can pick up the work cold without re-discovering what the planner already found.
- **Orchestrator composition** — Top-level skills delegate to supporting skills automatically, enabling complex multi-step workflows from a single invocation.

## Recommended workflow

The highest-leverage way to use Agent Layer skills follows two phases:

### 1. Plan with the agent

Spend time up front writing out your roadmap, phase definitions, and requirements documentation collaboratively with the agent. Use the project memory files (`ROADMAP.md`, `CONTEXT.md`, `BACKLOG.md`) as the working surface. This investment pays for itself — clear plans produce dramatically better autonomous execution.

### 2. Execute with orchestrator skills

Once planning artifacts exist, use the top-level orchestrator skills to drive development. These skills handle the full lifecycle internally, delegating to supporting skills as needed:

- **`complete-current-phase`** — Point it at a roadmap phase and it handles planning, implementation, verification, auditing, and cleanup loops until the phase is complete. This is the primary workflow for roadmap-driven development.
- **`ship-pr`** — Audits uncommitted changes, commits, pushes, creates the PR, monitors CI (fixing failures), waits for review comments, addresses every one, and confirms CI passes.
- **`improve-codebase`** — Deep autonomous codebase audit that decomposes the repo into reviewable chunks, runs parallel multi-lens reviews, fixes findings iteratively, and delegates to complementary skills.
- **`fix-issues`** — Works through `ISSUES.md` by organizing open issues into coherent batches, planning, implementing, auditing, and keeping the issue ledger current.

You rarely need to invoke the supporting skills directly. The orchestrators handle delegation automatically. But the supporting skills are available when you want fine-grained control over a specific step.

### Using skills

Skills activate implicitly or explicitly:

**Implicit** — Describe what you want and the agent matches the right skill:
- "Drive Phase 3 to completion" → `complete-current-phase`
- "Ship this as a PR" → `ship-pr`
- "Debug why the test is flaking" → `debug-issue`

**Explicit** — Name the skill directly:
- "Use `complete-current-phase` for Phase 3"
- "Run `improve-codebase` on the auth module"

Skills accept flexible inputs: plain-language descriptions, file paths, constraints like "diagnosis only," or references to roadmap phases and prior artifacts. Everything has sensible defaults, so you can invoke with just a request.

## Built-in skill library

Agent Layer ships 24 skills. They are organized here by how you typically use them.

### Orchestrator skills

These are the top-level workflows you invoke directly. They delegate to supporting skills internally and handle complex multi-step processes end to end.

| Skill | What it does |
| --- | --- |
| `complete-current-phase` | Drives a roadmap phase through planning, implementation, verification, auditing, and cleanup loops until the phase is complete. The primary orchestrator for roadmap execution. |
| `ship-pr` | Full PR lifecycle: audits uncommitted changes, commits, pushes, creates the PR, monitors CI (fixing failures), waits for review comments, addresses every one, and confirms CI passes. Delegates to `audit-and-fix-uncommitted-changes`, `fix-ci`, and `address-pr-comments`. |
| `improve-codebase` | Deep autonomous codebase audit: decomposes the repo into reviewable chunks, runs parallel multi-lens reviews, fixes findings iteratively, and delegates to complementary skills. |
| `fix-issues` | Works through `ISSUES.md`: organizes open issues into coherent batches, plans, implements, audits, and keeps the issue ledger current. |

### Primary skills

These are commonly invoked directly for specific tasks that do not need a full orchestrator.

| Skill | What it does |
| --- | --- |
| `plan-work` | Produces a plan, task list, and context file for a requested change — scoped tightly enough for a fresh agent to execute without guessing. The context file captures key file paths, current state, and constraints so the implementing agent can orient immediately. |
| `implement-plan` | Picks up a plan/task/context set and executes it. Reads the context file first to orient, then works through the task list while keeping changes aligned to the plan. Verifies code, tests, docs, and memory before closing. |
| `debug-issue` | Investigation-first debugging: reproduces the bug, narrows the cause systematically, writes a failing test, fixes the root cause, and verifies. Refuses to guess — requires evidence at every step. |
| `schedule-backlog` | Proposes reviewable updates by mapping backlog items into roadmap phases, cross-checking impacts, and using human checkpoints before editing memory files. |

### Supporting skills

These are used by orchestrators or available for fine-grained control when you need a specific step. You rarely invoke them directly when following the orchestrator workflow.

**Review and verification**

| Skill | What it does |
| --- | --- |
| `review-scope` | Reviews files, directories, diffs, or uncommitted changes. Produces a findings report covering correctness, gaps, risks, architecture, tests, docs, performance, and maintainability. |
| `review-plan` | Pre-execution review of a plan and its artifacts. Identifies scope gaps, sequencing problems, missing context, and weak verification before code is written. |
| `verify-against-plan` | Post-implementation completeness check. Compares what was actually built against what the plan promised, reporting gaps, regressions, missing tests or docs, and scope drift. |
| `resolve-findings` | Triages review findings, verifies each independently, implements accepted fixes, and records why findings were rejected, deferred, or resolved. |

**Quality and maintenance**

| Skill | What it does |
| --- | --- |
| `simplify-codebase` | Codebase-wide complexity reduction: removes dead code, simplifies overly complex functions, and splits files that mix unrelated responsibilities. Operates on the whole repository or explicit paths, not the uncommitted diff. |
| `simplify-new-code` | Diff-scoped scope-creep removal: scans the current uncommitted diff for agent-added speculative flexibility, premature abstractions, dead branches, impossible-case error handling, defensive scaffolding, clever patterns, and half-finished work, and auto-applies simplifications while preserving requested behavior. Uses a fresh-context reviewer subagent so the implementer's narrative cannot rationalize the cleanup. |
| `prune-new-tests` | Burden-of-proof pruning of tests added in the current uncommitted diff: each added test must defend its existence with a concrete production-code mutation that would flip its assertion or it is auto-deleted. Surviving coverage gaps are reported, never backfilled with false coverage. Uses a fresh-context reviewer subagent. |
| `boost-coverage` | Raises test coverage iteratively by discovering the repo's coverage commands, selecting low-coverage files, and adding tests until thresholds are met. |
| `repair-checks` | Runs the repo's documented checks in order, fixes failures in scope, and repeats until passing or a real blocker emerges. |

**PR and CI lifecycle**

| Skill | What it does |
| --- | --- |
| `fix-ci` | CI failure repair for PRs. Diagnoses failures, fixes issues, audits changes, commits, pushes, and re-checks until CI passes. |
| `address-pr-comments` | Implements fixes for agreed PR feedback, replies to every comment with justification, audits substantive changes when warranted, and commits/pushes. |
| `audit-and-fix-uncommitted-changes` | Working-tree audit and fix orchestrator. Runs iterative review/fix loops until convergence, with round-by-round severity reporting. Used as a pre-commit quality gate. |

**Auditing**

| Skill | What it does |
| --- | --- |
| `audit-documentation` | Audits documentation for static accuracy and cross-document consistency against the repository. Optionally applies fixes for accepted findings. |
| `audit-tests` | Test suite health audit: discovers conventions, classifies tests by tier, identifies redundancy, quality gaps, and coverage gaps — without modifying tests. |
| `audit-memory` | Audits agent memory files for structure compliance, staleness, misplacement, and consistency. |

**Task management**

| Skill | What it does |
| --- | --- |
| `finish-task` | Task closeout: checks plan alignment, updates project memory files, runs verification, and summarizes outcomes after implementation is complete. |

## Writing your own skills

Create a new directory under `.agent-layer/skills/` with a `SKILL.md` file:

```bash
mkdir -p .agent-layer/skills/my-workflow
touch .agent-layer/skills/my-workflow/SKILL.md
```

Add frontmatter:

```yaml
---
name: my-workflow
description: >-
  One-sentence explanation of what this does and when it should trigger.
---
```

Follow the [skill structure](#skill-structure) outlined above. Keep the body focused: aim for 150–300 lines, put critical rules early, and make artifacts and stop conditions explicit.

Run `al sync` to project the new skill into all enabled clients.

For the complete research-backed authoring guide — including empirical studies on instruction-following, context length effects, and constraint composition — see [Skill Design Guide](/skill-design).

## Design philosophy

The built-in skills reflect several deliberate choices:

**Investigation before action** — Skills like `debug-issue` refuse to guess. They require reproduction, evidence, and a failing test before any fix. This mirrors how experienced developers work.

**Autonomous by default, checkpoints for real ambiguity** — Skills run autonomously through their normal workflow. Human checkpoints trigger only for genuine ambiguity — scope decisions, breaking changes, or competing approaches. Vague escalation like "ask when uncertain" is deliberately avoided.

**Composition over monoliths** — Skills delegate to each other. `ship-pr` delegates to `audit-and-fix-uncommitted-changes`, `fix-ci`, and `address-pr-comments`. `complete-current-phase` orchestrates planning, implementation, and verification. This keeps each skill focused while enabling complex workflows.

**Evidence-backed structure** — The skill format is informed by research on how language models process instructions. Critical rules go early (primacy effect), guardrails go at the end (recency effect), and lean bodies minimize reasoning degradation from context length. See [Skill Design Guide](/skill-design) for the research basis.
