AGENTS.md and Skills

Use AGENTS.md to teach Anode how this repo works. Use skills when a workflow is repeatable enough to package as a named procedure.

AGENTS.md

AGENTS.md files give Anode standing instructions for your project. The agent loads these files automatically and treats their content as system-level guidance.

Filenames

Anode looks for these files in precedence order:

1. AGENTS.md (highest priority)
2. AGENT.md
3. CLAUDE.md (Claude Code compatible)

The first match in each directory wins. Place them at your workspace root or in subdirectories.

Directory Scope

AGENTS.md files are directory-scoped. A file in src/api/AGENTS.md applies when the agent works on files under src/api/. More specific paths override broader ones.

project/
+-- AGENTS.md              # project-wide rules
+-- src/
    +-- AGENTS.md          # src-specific overrides
    +-- api/
        +-- AGENTS.md      # api-specific overrides

When editing src/api/handler.go, Anode loads all three files. The most specific file takes precedence on conflicting instructions.

Discovery skips symlinked instruction files and ignored directories such as .git, .anode-harness, .agents, .claude, node_modules, vendor, dist, build, target, .next, coverage, .cache, .venv, and venv. The runtime loads at most 8 instruction files and 32 KiB of instruction text per context build.

User-Level Guidance

The current AGENTS.md loader scans the workspace, not a user-level AGENTS file. For guidance that applies across projects, use a custom profile systemPrompt or keep a template AGENTS.md that you copy into each workspace.

File Includes

Reference external files with @file directives outside fenced code blocks:

# Project Guidelines

Follow our coding standards:
@coding-standards.md

API conventions are documented here:
@manual/api-conventions.md

Each included file is bounded at 8KB. The @file path resolves relative to the AGENTS.md location. Includes cannot cross outside the workspace or read files from ignored guidance directories such as .anode-harness/, node_modules/, or .git/.

Glob Includes

Reference multiple files with glob patterns:

@manual/*.md
@configs/**/*.yaml

Glob rules:

• Maximum 10 file expansions per pattern.
• Paths resolve relative to the AGENTS.md file’s directory.
• All resolved paths must stay within the workspace root.

Example

# Project: payments-api

This is a Go microservice handling payment processing.

## Conventions
- Use table-driven tests for all new test files.
- Never commit code with TODO comments.
- All HTTP handlers go in `internal/handlers/`.
- Use `slog` for logging. Never use `fmt.Println` in production code.

## Architecture
@manual/architecture.md

## API specs
@manual/api/*.md

Skills

Skills are reusable, self-contained procedures. The agent sees skill descriptions but loads full content only when it invokes the skill via the skill tool.

Directory Structure

Anode discovers skills from multiple locations:

Location	Scope	Example path
~/.config/anode/skills/<name>/	User (all projects)	~/.config/anode/skills/deploy/SKILL.md
.agents/skills/<name>/	Project	.agents/skills/lint-fix/SKILL.md
.claude/skills/<name>/	Project (Claude-compatible)	.claude/skills/migrate/SKILL.md
skills.dirs[]/<name>/	Configured extra roots	/opt/anode-skills/release/SKILL.md

Each skill is a directory containing a SKILL.md file and optional resources.

Inspect built-in and installed skills, then install a user skill from a local SKILL.md file or skill directory:

anode skills list
anode skills info code_review
anode skills add ./release-skill --name release
anode skills remove release

By default, installed skills go under ~/.config/anode/skills/. Use --target <dir> to install into a different skill root and --overwrite to replace an existing skill with the same name.

SKILL.md Format

Every skill may start with YAML-like frontmatter. The current parser supports simple key: value scalar lines; list fields should be comma-separated or bracketed on one line.

---
name: lint-fix
description: Run linters and auto-fix all reported issues
trigger: lint, fix lint errors, clean up code style
resources: config.yaml, templates/fix-report.md
---

## Steps

1. Run `golangci-lint run ./...` to identify issues.
2. For each fixable issue, apply the suggested fix with `edit_file`.
3. Re-run the linter to confirm all issues resolved.
4. Report unfixable issues to the user.

Frontmatter Fields

Field	Type	Required	Description
name	string	no	Skill identifier. Defaults to the skill directory name.
description	string	no	One-line summary shown to the model. Defaults to the first heading or non-empty body line.
trigger	string	no	Comma-separated trigger keywords
triggers	string	no	Comma-separated or bracketed trigger keywords (alternative to trigger)
resources	string	no	Comma-separated or bracketed resource names for metadata

Lazy loading

Anode shows only skill names, descriptions, and triggers to the model during normal operation. The full SKILL.md body loads only when the agent invokes the skill via the skill tool. Resource filenames are parsed as metadata but resource file contents are not loaded automatically.

Triggers

Trigger keywords help the model decide when to invoke a skill. When the user’s request matches a trigger, the model is more likely to call the skill.

trigger: deploy, push to production, ship it

Resources

Declare files that live alongside the SKILL.md:

resources: checklist.md, templates/pr-template.md

Resource paths are relative to the skill directory. They are parsed as metadata but are not automatically read into the model context by the current runtime. If a skill needs a resource, mention it in the SKILL.md body so the agent can read it with normal tools.

Built-in skills

Anode ships with these built-in skills:

Skill	Description
code_review	Review code changes for issues
bug_hunt	Systematically search for bugs
repo_summary	Generate repository overview
test_failure_analysis	Diagnose test failures
docs_writer	Draft manual-style documentation
commit_message	Write commit messages from diffs
ui_consistency_review	Check UI for consistency issues
security_review	STRIDE + OWASP Top 10 + LLM Top 10 + supply-chain review
simplify	Reuse, quality, and efficiency cleanup pass
browse_wiki	Search and read project docs/manual locally
full_output_enforcement	Generate complete code without placeholders/truncation
incident	Alert-link RCA runbook

Invoke any built-in skill:

TOOL: {"name": "skill", "args": {"name": "code_review", "input": "Review the latest changes"}}

Skill-Local MCP Servers

A skill can bundle its own MCP server configuration. Place an mcp.json file in the skill directory:

.agents/skills/database/
+-- SKILL.md
+-- mcp.json

Example mcp.json

{
  "mcpServers": {
    "db-tools": {
      "command": "npx",
      "args": ["-y", "@myorg/db-mcp-server"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

When the skill is invoked, Anode starts the declared MCP servers and registers their tools into the current run. The tools follow the standard mcp__<server>__<tool> naming convention.

Rules for skill-local MCP:

• Set skills.allowMCP: true, or set ANODE_ENABLE_WORKSPACE_MCP=true when skills.allowMCP is not configured.
• MCP tools obey the same permission policy as any other tool.
• Tool names must not shadow existing built-in or previously registered tools.
• Servers shut down when the Anode run ends.

Skill Precedence

When multiple skills share the same name, Anode uses this precedence order:

1. Claude-compatible project skills (.claude/skills/) - highest priority
2. Project skills (.agents/skills/)
3. Configured extra roots (skills.dirs)
4. User skills (~/.config/anode/skills/)
5. Built-in skills - lowest priority

Later discovery roots override earlier ones, so a project skill named code_review overrides configured, user, and built-in code_review, and .claude/skills/code_review overrides .agents/skills/code_review.

Skill Configuration

These config keys tune skill discovery:

{
  "skills": {
    "dirs": ["/path/to/extra/skills"],
    "maxSize": 65536,
    "allowMCP": false
  }
}

dirs entries are additional skill roots. Relative entries resolve from the workspace root. maxSize reads up to 65,536 bytes of SKILL.md content by default; when a skill is longer, Anode appends ...[truncated] after that prefix. allowMCP enables skill-local MCP activation; profile and tool policy still apply.

Key	Type	Default	Description
dirs	[]string	[]	Additional skill roots to scan
maxSize	int	65536	Read-byte limit per SKILL.md before appending ...[truncated]
allowMCP	bool	false	Enable skill-local MCP activation

Keep Going

• Tools - the full built-in tool reference
• MCP - connect external tool servers
• Profiles - configure agent behavior and tool access
• Configuration - all config options