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/
  implement/
    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 "ship this as a pull request," 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 7 focused skills covering implementation, PR lifecycle, auditing, and autonomous delivery — available when the workflow bundle is installed through the wizard and refreshed through upgrade flows for repos that already have it.
• Client projection — User-managed .agent-layer/skills/ and Git-managed .agent-layer/skills-imported/ are canonical. al sync merges them into one immutable source snapshot, then projects that snapshot 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, DECISIONS.md, COMMANDS.md, CONTEXT.md), keeping project context durable across sessions.
• Artifact conventions — Skills keep agent-only plans, reports, and trackers under .agent-layer/tmp/, where another agent can pick them up without mixing transient state into product files.
• 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 plans and requirements documentation collaboratively with the agent. Use the project memory files (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:

• implement — Give it a code change or specification and it selects a proportional direct or planned workflow, with independent review only when warranted.
• 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.
• 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:

• "Implement Phase 3" → implement
• "Ship this as a PR" → ship-pr
• "Check whether the docs still match the code" → audit-documentation

Explicit — Name the skill directly:

• "Use implement to complete Phase 3"
• "Run interface-audit on the auth module"

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

Built-in skill library

The Agent Layer workflow bundle includes 7 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
implement	Implements a requested change directly or through a planned Agent Dispatch workflow, adding independent plan or code review only when warranted.
auto-skill-loop	Repeatedly selects, implements, ships, and—under standing authorization—merges one pull request at a time for a named mode.
ship-pr	Owns commits, pushes, PR creation, hosted continuous integration and review monitoring, repair dispatches, replies, and the merge-authorization gate.

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.

Auditing

Skill	What it does
audit-documentation	Audits Markdown documentation for static accuracy and cross-document consistency, fixing safe findings.
audit-tests	Audits the existing test suite for redundancy, misleading coverage, organization problems, and material behavioral gaps, fixing safe findings.
audit-memory	Audits agent memory files for structure, staleness, placement, consistency, and decision-log bloat, fixing accepted findings.
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 optional tool integrations. Most require the corresponding command to be available on PATH; dispatch-agent uses the built-in Agent Dispatch MCP tools and has no external binary requirement.

Skill	What it does
dispatch-agent	Uses the Agent Dispatch MCP tools only when the user names an external dispatch target or another skill explicitly requires dispatch; it has no external binary requirement.
find-docs	Uses Context7 for current API and library documentation when local docs or CLI help are insufficient.
playwright	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.

The two client skill roots are Agent Layer-owned disposable output. Do not edit or install skills directly in .agents/skills/ or .claude/skills/; sync replaces each enabled root wholesale and removes all extra content. SKILL.md bytes, unknown/provider-specific frontmatter, nested resources, and executable bits are preserved exactly. Lowercase skill.md is rejected. Every source-tree node must be a real directory or regular file; symlinks and all other node types are rejected, including symlinked skill directories and SKILL.md files.

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.

Importing skills from Git

Agent Layer can import known Agent Skills from any Git repository your existing Git authentication can reach, keep them editable locally, pull upstream changes without losing your edits, and contribute changes back.

al skills add https://github.com/example/skills.git skills/reviewer
al skills status
al skills pull

Imported skills land in .agent-layer/skills-imported/<skill-name>/ and are projected through ordinary al sync exactly like the skills you write in .agent-layer/skills/. Edit them in place: al skills pull merges upstream updates against the version you originally imported, so your local changes survive. When a change genuinely conflicts, or an upstream skill stops being valid, that one skill fails and its content is left untouched — the rest of the repository still imports. If a run is interrupted part way through, the next al skills or al sync command rolls it back, so you never end up with a half-replaced skill.

The generated .agent-layer/.gitignore ignores both the machine-managed .agent-layer/skills-imported/ directory and its .agent-layer/skills.lock.json upstream state by default.

If you want to discard one skill's edits instead, reset it explicitly. This is permanent: Agent Layer creates no commit, stash, copy, or backup for you.

al skills reset reviewer

Reset accepts the current configured upstream version for that skill only. It does not add new wildcard matches, retire other skills, or otherwise reconcile membership. Preserve edits yourself before running it if you may want to reapply them. Reset prompts before discarding edits; non-interactive callers must pass --yes.

Import several skills at once with a wildcard, and exclude the ones you do not want:

al skills add https://github.com/example/skills.git "skills/*" "!skills/internal-only"

Pin an import to a tag or commit when you want it to hold still:

al skills add https://github.com/example/skills.git skills/reviewer --ref v1.4.0

To contribute your local edits back, give the import a write policy. Push to an explicit branch, or through your own fork:

al skills add https://github.com/example/skills.git skills/reviewer \
  --write branch --push-branch skill-updates
al skills push

Agent Layer never force-pushes, never invents a branch name, and never opens a pull request for you. al skills push uses your current files whether or not you committed them in your own project, and it never pulls first. Push prompts before publication; non-interactive callers must pass --yes. The add and remove commands likewise prompt before changing import configuration and accept --yes for automation.

A missing configured contribution branch starts from the destination's current default branch. Pushes use Git objects directly rather than checking out remote content, and accept only HTTPS, SSH, Git, file, scp-style SSH, and local-path repository transports. Plain HTTP is refused; use HTTPS or SSH instead. If a destination skill contains an ignored artifact, symbolic link, submodule, or another unsupported node, Agent Layer names it and requires you to remove it from the destination before retrying.

Changes are reconciled against the destination the same way al skills pull reconciles upstream changes, so a change made on the destination branch is preserved rather than overwritten. If the destination branch removed a skill entirely, that removal is preserved too: the push reports the skill as unchanged when your copy still matches what you imported, and reports a conflict when you had also edited it.

To stop managing an imported skill, remove its selector. A clean copy is deleted; a copy you edited is preserved and reported so you can move it into .agent-layer/skills/ and own it yourself.

al skills remove https://github.com/example/skills.git skills/reviewer

See the CLI reference for the full command contract and configuration reference for every [[skills.imports]] field.

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.