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-and-fix-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. For skills that route agents to installed command-line tools, use the CLI Skill Design Guide. For Agent Layer's root-skill model and current-to-target skill mapping, see Skills approach.

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 workflow-bundle library of 23 skills covering planning, implementation, review, debugging, PR lifecycle, auditing, and codebase improvement — available when the workflow bundle is installed through the wizard and refreshed through upgrade flows for repos that already have it.
• 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:

• full-workflow — Give it a feature or roadmap phase and it aligns the contract, plans, implements, verifies, and ships the pull request.
• 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 — Runs one evidence-led quality sweep over the repository or a named scope, repairing and verifying material findings.
• auto-skill-loop — Runs fix-issue-log, implement-backlog, improve-interfaces, improve-codebase, or a repository-added mode continuously, preserving blocked work and centrally shipping independent ready deliveries until substantive work is exhausted or the user stops it.

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" → full-workflow
• "Ship this as a PR" → ship-pr
• "Debug why the test is flaking" → debug-and-fix-issue

Explicit — Name the skill directly:

• "Use full-workflow to complete 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

The Agent Layer workflow bundle includes 23 skills. They are organized here by how you typically use them. Agent Layer also ships optional CLI catalog skills for installed tools; those are listed separately below.

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
full-workflow	Orchestrates a feature or roadmap phase from specification alignment through planning, review, implementation, verification, and PR shipping.
fully-implement-plan	Implements a provided plan through cleanup, verification, and full local checks without opening or shipping a PR.
auto-skill-loop	Runs fix-issue-log, implement-backlog, improve-interfaces, improve-codebase, or a repository-added mode until substantive autonomous work is exhausted or the user stops it.
ship-pr	Owns commits, pushes, PR creation, concurrent local checks and remote monitoring, batched repairs, audited replies, and the merge-authorization gate.
improve-codebase	Runs one broad evidence-led sweep, repairs validated local and cross-cutting findings, reviews the combined work once, and verifies the result.

Primary skills

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

Skill	What it does
write-plan	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, running task-local checks and recording deviations or follow-up.
debug-and-fix-issue	Investigation-first debugging and fixing: reproduces the bug, narrows the cause systematically, writes a failing test, then delegates planning, implementation, cleanup, and verification. 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-uncommitted-code	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-work	Post-implementation completeness check. Compares what was actually built against the plan or request, reporting gaps, regressions, missing verification or docs, working-code evidence, and scope drift.

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.
clean-and-fix-code	Single working-tree cleanup/fix pass. Runs diff-scoped test pruning and new-code simplification as internal assets, reviews the current uncommitted diff, and fixes accepted findings once.
boost-coverage	Raises coverage to an explicit or repository target with one coherent behavior-focused test batch and one final measurement.
run-and-fix-all-checks	Runs the repository's complete documented check lane, repairs observed root causes directly, and repeats only on concrete failure evidence.

PR and CI lifecycle

Skill	What it does
fix-ci	Diagnoses an observed PR check failure, reproduces and repairs it locally, and returns uncommitted changes and evidence to the shipping caller.
address-pr-comments	Evaluates PR feedback, implements accepted fixes locally, and prepares evidence-backed reply drafts without committing, pushing, or posting.

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.
interface-audit	Audits product interfaces as component boundaries, scores complexity and debt, and produces interface cleanup recommendations without implementing changes.

Optional CLI catalog skills

These skills are installed only when selected through the CLI catalog. They route agents to installed local tools and require the corresponding command to be available on PATH.

Skill	What it does
agent-dispatch	Uses al dispatch only when the user names an external dispatch target or another skill explicitly requires dispatch.
find-docs	Uses Context7 for current API and library documentation when local docs or CLI help are insufficient.
playwright-cli	Uses playwright-cli for browser automation, screenshots, user interface inspection, and Playwright test work.
tavily-web	Uses Tavily CLI for web search, URL extraction, site mapping, and cited research.

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. For command-line tool workflows, use CLI Skill Design Guide so live --help stays the source of truth for syntax.

Skills approach

The built-in skills follow an Agent Layer-specific model: deterministic root skills with stable input/output contracts, composed by workflow skills that own loops and orchestration. See Skills approach for the canonical ethos, target root modules, and mapping to the current bundled skill names.