Skills

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 — 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.

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 22 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 into each client's native format during al sync (e.g., .agent/skills/ for Claude Code, .codex/skills/ for Codex).
• 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), making work inspectable and auditable.
• 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 22 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	Writes a scoped implementation plan and task list for a requested change. Produces a narrative plan and an ordered task list clear enough for a fresh agent to execute.
implement-plan	Executes a plan/task-list pair without freelancing. Keeps changes aligned to the artifacts and 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/task artifact pair. Identifies scope gaps, sequencing problems, and weak verification before code is written.
verify-against-plan	Post-implementation completeness check comparing what was built against the plan. Reports 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-code	Assesses code complexity, removes dead code, simplifies overly complex functions, and splits files that mix unrelated responsibilities.
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 the changes, 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:

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

Add frontmatter:

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

Follow the 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.

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 for the research basis.