> ## Documentation Index
> Fetch the complete documentation index at: https://docs.actionllama.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Docs

> SKILL.md, AGENTS.md, and CLAUDE.md — what they do and how to write them

Action Llama uses three markdown files with distinct purposes. Only `SKILL.md` is required.

## SKILL.md

The portable part of an agent. YAML frontmatter at the top contains portable metadata (name, description, license, compatibility), and the markdown body is the system prompt that drives the agent's behavior. Runtime configuration (credentials, schedule, models, webhooks, hooks, params) lives in the separate `config.toml` file.

### What it is

`SKILL.md` lives inside each agent's directory (e.g. `agents/dev/SKILL.md`). The frontmatter is parsed for portable metadata, and the markdown body is injected as the LLM's system prompt at runtime. Everything the agent does is driven by these instructions.

### How it's used

The scheduler reads `SKILL.md` and sends the markdown body as the system prompt. Runtime configuration is loaded from `config.toml`. A preamble is prepended that teaches the agent behavioral guidelines for its [available tools](/reference/agent-tools) (locks, calls, status). The LLM then receives a user-message prompt with:

1. **`<skill-config>`** — JSON of the `params` table from the agent's `config.toml`
2. **`<credential-context>`** — describes available environment variables and tools
3. **`<environment>`** — filesystem constraints (read-only root, `/tmp` for work)
4. **Trigger context** — schedule, webhook payload, manual, or subagent call context

### Writing tips

* **Write as direct instructions to an LLM.** "You are an automation agent. Your job is to..."
* **Be specific about workflow.** Numbered steps are better than vague descriptions.
* **Reference `<skill-config>` for parameter values.** Don't hardcode repo names or labels — put them in `params` and reference them.
* **Handle both trigger types** if the agent uses both schedule and webhooks.
* **Use the `set_status` tool** to report progress updates to the TUI.
* **Keep it concise.** The system prompt consumes tokens every run. Avoid lengthy explanations of things the LLM already knows.

### Example

```markdown theme={null}
# Dev Agent

You are an automation agent. Your job is to pick up GitHub issues and implement the requested changes.

Your configuration is in the `<skill-config>` block at the start of your prompt.
`GITHUB_TOKEN` is already set in your environment. Use `gh` CLI and `git` directly.

## Workflow

1. **Find work** — If triggered by webhook, work on the issue from the trigger. If scheduled, search for open issues labeled with the label from `<skill-config>`.triggerLabel.
2. **Lock the issue** — `acquire_lock` with resource `"github://owner/repo/issues/N"`. If locked, skip it.
3. **Implement** — Clone the repo, create a branch, make changes, run tests.
4. **Open a PR** — Push and open a PR linking to the issue.
5. **Unlock** — `release_lock` with the same resource.

## Rules

- Never force-push
- Run tests before opening a PR
- If tests fail after 3 attempts, comment on the issue and move on
```

### Handling trigger context

Your `SKILL.md` should handle different trigger types if the agent uses both:

```markdown theme={null}
## Trigger handling

- **Webhook trigger**: The `<webhook-trigger>` block contains the full event payload. Work on the specific issue/PR from the event.
- **Scheduled trigger**: Search for open work matching your configured filters.
- **Subagent call**: The `<skill-subagent>` block contains context from the calling agent. Do what was requested and use the `return_value` tool to send back results.
```

## AGENTS.md

Project-level shared instructions that are loaded by `al chat`.

### What it is

`AGENTS.md` lives at the project root (e.g. `my-project/AGENTS.md`). It provides shared context about the project that is relevant when interacting with agents via the chat console.

### How it's used

When you run `al chat` (project-level console), the contents of `AGENTS.md` are loaded as reference context. It is **not** injected into automated agent runs — only into the interactive chat session.

### When to use it

Use `AGENTS.md` to document:

* Project conventions that are relevant when working with agents interactively
* How agents in the project relate to each other
* Common tasks and how to accomplish them via chat

## CLAUDE.md

Instructions for AI development tools (like Claude Code). Not used by Action Llama at runtime.

### What it is

`CLAUDE.md` lives at the project root and provides instructions to AI coding assistants that may be editing the project's source code. Do not confuse it with `SKILL.md`, which is the agent instructions file.

### How it's used

`CLAUDE.md` is **not** read by Action Llama. It has no effect on agent runs, the scheduler, or the chat console. It exists purely for developer tooling context.

### When to use it

If you use Claude Code or similar AI development tools to work on your Action Llama project, put project conventions, build commands, and coding guidelines in `CLAUDE.md`. See [Claude Integration](/integrations/claude) for how Claude Code uses this file alongside the MCP server.