Customizing the Agent: AGENTS.md & Skills

You can shape how the Abacus AI agent behaves in your codebase with two complementary mechanisms:

Mechanism	What it is	When it applies
AGENTS.md	An always-on instructions file that describes your project — conventions, structure, and how to build/test it.	Loaded automatically for every request in the workspace.
Skills	Reusable, packaged instruction sets (SKILL.md) for specific tasks — optionally bundled with helper scripts and reference files.	Pulled in on demand, only when a task matches the skill.

A simple way to think about it: AGENTS.md is the agent's persistent memory of your project, while Skills are specialized playbooks it reaches for when a particular kind of task comes up. Both work identically across the CLI, the VS Code extension, and the Desktop App.

---

AGENTS.md

AGENTS.md is a plain Markdown file that gives the agent standing instructions for working in your repository. It is the open AGENTS.md convention — the same idea as Claude Code's CLAUDE.md or a project-level system prompt — and it is the first thing the agent reads when it starts working in your project.

Use it for things you'd otherwise have to repeat in every prompt:

• Coding conventions — style, naming, formatting, preferred libraries.
• Project layout — where things live and how the codebase is organized.
• Build / test / lint commands — how to compile, run tests, typecheck, and lint.
• Do's and don'ts — guardrails such as "never edit generated files" or "always run npm run lint before finishing."

Where to put it

Create a file named AGENTS.md in the root of your project. The agent picks it up automatically — no configuration or restart required.

my-project/
├── AGENTS.md          ← loaded automatically
├── src/
└── package.json

Example

# Project: Acme Web App

## Stack
- TypeScript + React (Vite), Tailwind for styling.
- Backend: Python (FastAPI) under `server/`.

## Conventions
- Use functional components and hooks; no class components.
- Prefer named exports.
- 2-space indentation. Single quotes.

## Build & Test
- Install: `npm install`
- Dev server: `npm run dev`
- Lint + typecheck (run before finishing any task): `npm run lint && npm run typecheck`
- Tests: `npm test`

## Don'ts
- Never edit files under `src/generated/` — they are auto-generated.
- Don't commit changes to `package-lock.json` unless dependencies actually changed.

Tips for an effective AGENTS.md

• Be concise and structured. Use headings, short bullet points, and numbered steps. Long prose gets diluted.
• Lead with the rules that matter most — conventions and guardrails the agent must not miss.
• Include exact commands. Spelling out the build/test/lint commands lets the agent verify its own work.
• Keep it current. Treat it like code: update it when conventions change.

---

Skills

A Skill is a self-contained packet of instructions for a specific kind of task, defined in a SKILL.md file. Skills give the agent reusable, on-demand expertise for tasks that have their own procedure — so you don't have to spell those steps out in every prompt.

A skill can be as simple as a single instructions file, or a folder that also ships helper scripts and reference documents alongside it.

The SKILL.md format

A skill is defined by YAML frontmatter followed by Markdown instructions:

---
name: pdf-forms
description: Use when filling, extracting, or generating PDF forms. Triggers on requests involving .pdf files, form fields, or AcroForms.
---

# Filling PDF Forms

1. Inspect the form fields with `python scripts/inspect.py <file.pdf>`.
2. Map the user's data to the field names.
3. Fill and flatten using the helper script.
...

Frontmatter fields:

Field	Required	Description
name	Yes	Display name of the skill.
description	Yes	The most important field — explains when the skill should be used. Be specific and trigger-oriented.
argument-hint	No	Hint shown for arguments when the skill is invoked with /.

Everything after the frontmatter is free-form Markdown — the actual instructions the agent follows.

Two layouts

A skill can be either:

1. A single Markdown file — my-skill.md placed directly in a skills folder.

2. A directory with a SKILL.md — preferred when the skill ships supporting files:

   pdf-forms/
   ├── SKILL.md          ← required
   ├── scripts/
   │   └── inspect.py    ← helper script
   └── reference/
       └── acroforms.md  ← extra reference docs

Where to put skills

The agent scans several locations. Skills are merged across all of them, so you can mix shared, personal, and project-specific skills.

Level	Locations	Scope
Global (user-level)	~/.abacusai/skills/ ~/.agents/skills/	Available in all your projects, on this machine.
Project-level	<project>/.abacusai/skills/ <project>/.agents/skills/	Scoped to that project. Commit them to share with your team.

Two folder conventions

Both .abacusai/skills/ (Abacus.AI's native folder) and .agents/skills/ (the shared, cross-tool agent convention) are scanned at each level. Use whichever you prefer — .agents/ is handy if you want the same skills to be picked up by other agent tools too. When a skill with the same name exists in both, the .abacusai/ copy wins. Project-level skills take precedence over global ones.

So, for example:

# Personal skills, available everywhere
~/.abacusai/skills/commit-style/SKILL.md

# Project skill, shared with the team via git
my-project/.abacusai/skills/deploy-runbook/SKILL.md

Creating your own skill

1. Choose a location — ~/.abacusai/skills/ for a personal skill, or <project>/.abacusai/skills/ to share it with your team.
2. Create a folder (e.g. my-skill/) and add a SKILL.md with name and description frontmatter plus your instructions.
3. (Optional) Add helper scripts and reference files alongside SKILL.md.

Sharing skills via GitHub

Skills are just files in a folder, so any folder in a public GitHub repository can be used as a skill. This makes them easy to version, review, and share across a team.

---

AGENTS.md vs. Skills — which should I use?

• Reach for AGENTS.md for context that applies to most work in the repo: conventions, structure, build/test commands, and guardrails.
• Reach for a Skill for a specific, repeatable task that has its own multi-step procedure — especially if it benefits from helper scripts or reference material — and that you don't want loaded into every conversation.

Used together, AGENTS.md keeps the agent aligned with your project at all times, while Skills give it on-demand expertise exactly when each task calls for it.

For further help, reach out at support@abacus.ai.