Frank
651924a4bc
Three parallel trees documented the same ecosystem: omp-docs/skills/
(two overview pages), tools/npx-skills/ (10 pi-era npm pages), and
tools/vercel-labs-skills/ (11 CLI pages), plus a fourth leaderboard page
at engineering/skills-ecosystem.md. Verbatim overlap (identical SKILL.md
field tables in skills-spec.md vs skill-format.md; 13-agent vs 68-agent
copies of the same upstream table). Consolidated to four concept pages:
- skills/agent-skills.md: standard, format, loading, authoring (merges
skills-spec, skill-format, skill-file-structure, skill-loading,
best-practices, skills-vs-extensions)
- skills/skills-cli.md: CLI reference (merges commands, source-formats,
installation-scope, skill-discovery, lock-file, env-variables,
agent-support, related-links)
- skills/store-wiring.md: moved, fleet ops, links retargeted
- skills/ecosystem.md: replaces skills-ecosystem.md; stale 2026-08-12
top-50 table dropped, replaced with a live top-10 re-queried from the
skills.sh API tonight and the API contract re-verified (zero-based,
200/page, {skills,total,hasMore,page}, total 9909)
All facts re-verified 2026-10-19 against primary sources:
agentskills.io, vercel-labs/skills README + src/cli.ts (command set,
--full-depth) + src/skill-lock.ts (v3 lock, XDG path, wipe-on-old),
live skills.sh API. Deleted superseded core/index-doc.md (old pi-era
docs index). Retargeted all inbound links (tools/index, engineering x3,
packages x3, pi/skills, core/index). Pi-era npm skill packaging is
listed as archived under /pi/.
Refs #29
101 lines
4.0 KiB
Markdown
101 lines
4.0 KiB
Markdown
---
|
|
type: reference
|
|
title: Agent Instruction Files and Agent Skills
|
|
description: Best practices for AGENTS.md, CLAUDE.md, SYSTEM.md, and the Agent Skills SKILL.md standard.
|
|
tags:
|
|
- agents-md
|
|
- claude-md
|
|
- system-md
|
|
- agent-skills
|
|
- unverified
|
|
timestamp: 2026-08-11
|
|
---
|
|
verified: 2026-08-28
|
|
|
|
# Agent Instruction Files and Agent Skills
|
|
|
|
This page explains the files that control how an AI coding agent works in a project. Use it when you create or review agent behavior configuration.
|
|
|
|
## AGENTS.md
|
|
|
|
`AGENTS.md` is the open, cross-tool format for coding-agent instructions. The Agentic AI Foundation (under the Linux Foundation) stewards it. Over 20 coding agents support it, including Cursor, Codex, and Claude Code.
|
|
|
|
The format is plain Markdown. It has no required fields. Any heading structure works. Agents read the nearest `AGENTS.md` in the directory tree. In a monorepo, the agent uses a nested `AGENTS.md` per package.
|
|
|
|
Include these sections in an `AGENTS.md`:
|
|
|
|
* Project overview.
|
|
* Setup and build commands.
|
|
* Code style guidelines.
|
|
* Testing instructions.
|
|
* Pull request instructions.
|
|
* Security considerations.
|
|
* Deployment steps.
|
|
* Commit message conventions.
|
|
|
|
Agents load content progressively. Put a short summary at the top. Put detailed instructions in later sections.
|
|
|
|
## CLAUDE.md
|
|
|
|
`CLAUDE.md` is Anthropic's tool-specific instruction file. Claude Code reads `CLAUDE.md` by default, not `AGENTS.md`. Files load in this order:
|
|
|
|
1. Managed policy (`/etc/claude-code/CLAUDE.md`).
|
|
2. User scope (`~/.claude/CLAUDE.md`).
|
|
3. Project scope (`./CLAUDE.md`).
|
|
4. Local scope (`./CLAUDE.local.md`).
|
|
|
|
Keep each file under 200 lines. Use the `@path/to/file` syntax to import other files. Use path-scoped rules in `.claude/rules/*.md` with `paths` frontmatter for directory-specific rules.
|
|
|
|
To make a repository work in both AGENTS.md and CLAUDE.md workflows, create a `CLAUDE.md` that imports `AGENTS.md` with the `@AGENTS.md` syntax, or use a symlink.
|
|
|
|
## SYSTEM.md
|
|
|
|
`SYSTEM.md` sets the system-level role and behavior for an agent. It establishes the persona, the prime directive, and the binding rules. In the pi-era setup, `/home/dank/.pi/agent/SYSTEM.md` defined the Comrade Chief Designer persona and the ASD-STE100 voice rules; the live equivalent is `~/.omp/agent/APPEND_SYSTEM.md`.
|
|
|
|
Use `SYSTEM.md` for stable, cross-project rules. Use `AGENTS.md` for project-specific context. Do not duplicate content between them. Keep the division of labor clear.
|
|
|
|
## Agent Skills Standard
|
|
|
|
An agent skill is a directory that contains a `SKILL.md` file. Skills extend an agent's capabilities. The open standard lives at [agentskills.io](https://agentskills.io). Over 50 agents support it.
|
|
|
|
The `SKILL.md` frontmatter includes these fields:
|
|
|
|
```yaml
|
|
---
|
|
name: my-skill
|
|
description: What this skill does
|
|
license: MIT
|
|
compatibility: node>=18
|
|
metadata:
|
|
internal: false
|
|
---
|
|
```
|
|
|
|
The `name` field is required and must use lowercase alphanumeric plus hyphens. The `description` field is required. Keep the name under 64 characters. Keep the description under 1024 characters.
|
|
|
|
Skills use progressive disclosure in three stages:
|
|
|
|
* Discovery: the agent loads only the name and description at startup.
|
|
* Activation: the agent reads the full `SKILL.md` when a task matches.
|
|
* Execution: the agent follows the instructions and reads resources on demand.
|
|
|
|
This keeps the context footprint small.
|
|
|
|
## Distribution
|
|
|
|
Distribute skills through npm packages with a `pi` manifest, or through the `skills` CLI from Vercel Labs. See the [Skills Documentation](../skills/index.md) pages for details.
|
|
|
|
## Citations
|
|
|
|
* [agents.md](https://agents.md/)
|
|
* [OpenAI Agentic AI Foundation](https://openai.com/index/agentic-ai-foundation/) (unverified — returned 403)
|
|
* [Claude Code memory documentation](https://code.claude.com/docs/en/memory)
|
|
* [Agent Skills standard](https://agentskills.io/)
|
|
* [agentskills/agentskills](https://github.com/agentskills/agentskills)
|
|
* [vercel-labs/skills](https://github.com/vercel-labs/skills)
|
|
|
|
## See Also
|
|
|
|
* [SDLC and Tooling](sdlc.md)
|
|
* [Skills Ecosystem](/skills/ecosystem.md)
|