agent-code Documentation

Skills are reusable prompt templates that define multi-step workflows. They're markdown files with YAML frontmatter, loaded from .agent/skills/ or ~/.config/agent-code/skills/.

Creating a skill

Create a file in .agent/skills/test-and-fix.md:

---
description: Run tests and fix failures
whenToUse: When the user asks to test or fix failing tests
userInvocable: true
---

Run the test suite with the project's test command. If any tests fail:

1. Read the failing test file
2. Read the source code being tested
3. Identify the root cause
4. Fix the issue
5. Re-run tests to verify

Repeat until all tests pass. Do not skip or delete failing tests.

Frontmatter options

Invoking skills

As a slash command

If userInvocable: true, invoke with the filename (minus .md):

> /test-and-fix

With arguments

Use {{arg}} in the template for argument substitution:

---
description: Review a specific file
userInvocable: true
---

Review {{arg}} for bugs, security issues, and code quality problems.
Focus on edge cases and error handling.

> /review src/auth.rs

Programmatically via the Skill tool

The LLM can invoke skills when it determines one is appropriate:

{
  "name": "Skill",
  "input": {
    "skill": "test-and-fix",
    "args": null
  }
}

Directory skills

For complex skills with supporting files, use a directory:

.agent/skills/
  deploy/
    SKILL.md      ← the skill definition
    checklist.md  ← referenced by the skill

Skill locations

Bundled skills

agent-code ships with 12 built-in skills. These are always available and can be overridden by placing a skill with the same name in your project or user skills directory.

Commands

> /skills
Loaded 15 skills:
  commit [invocable] — Create a well-crafted git commit
  review [invocable] — Review code changes for bugs and issues
  test-and-fix [invocable] — Run tests and fix failures
  deploy — Production deployment checklist