.agents

The .agents directory is the most basic form of AgentFinger — a static, portable data layer for user identity and knowledge. It mirrors the structure of the AgentFinger Daemon’s user data directory and can be served over the network by an AgentFinger daemon, but works equally well as a local convention read directly by AI agents, coding assistants, and other tools.

What it is

A user-level directory convention at ~/.agents/ that stores profile information, organizational context, and technical documentation in a predictable layout. Any tool that knows the convention can discover and consume this data without configuration.

Directory structure

~/.agents/
├── index.md                   # Root document (optional)
├── profile/
│   ├── user.md                # User profile
│   └── organizations/         # Organization references
│       ├── <org-slug>.md
│       └── ...
├── skills/                    # Agent Skills (optional)
│   ├── <skill-name>/
│   │   └── SKILL.md
│   └── ...
└── techdocs/                  # Cross-project documentation
    ├── <topic>.md
    └── <category>/            # Subdirectories allowed
        └── <topic>.md

index.md

Optional root document. When present, it serves as the entry point for tools querying the directory — a summary or table of contents that provides context before diving into subdirectories.

profile/

Identity and organizational information.

profile/user.md : General information about the user — personal details, interests, projects, development activities, and preferences. This is the primary file tools look for.

profile/organizations/<slug>.md : The user’s relationship to a specific organization — their role, responsibilities, and current work. Each file is a compact, user-scoped reference (not the canonical organization profile, which lives in the system-wide AgentFinger directory).

techdocs/

Inter-project technical documentation that applies across repositories. Files here describe the user’s tech stack, tooling preferences, containerization guidelines, deployment strategies, and other cross-cutting concerns.

Unlike profile/, subdirectories are allowed in techdocs/ for organizing topics by category.

skills/

Reusable instruction packages following the Agent Skills specification. Each skill lives in its own subdirectory and contains at minimum a SKILL.md file with YAML frontmatter and Markdown instructions.

~/.agents/skills/
├── pdf-processing/
│   ├── SKILL.md
│   └── scripts/
│       └── extract.py
└── code-review/
    └── SKILL.md

skills/ is supported as a global skill location by Codex, OpenCode, Augment, and other tools implementing the Agent Skills standard. The format and frontmatter schema are defined externally by agentskills.io — .agents provides the standardized home directory location.

SKILL.md frontmatter must include at minimum:

---
name: skill-name
description: What this skill does and when to use it.
---

Structure requirements

A valid .agents directory must contain at least one of:

• index.md
• profile/user.md

Everything else is optional.

File conventions

All shared conventions apply. Additionally:

• Hierarchy: Shallow. profile/ is flat except for the organizations/ subdirectory. techdocs/ may use one level of subdirectories.

See the .agents guidelines for content and structural best practices.

Reserved paths

Dot-prefixed names at the root level are reserved for tool-specific configuration and metadata. Additionally, the following top-level directory name is reserved:

skills/ : Agent Skills — reusable instruction packages following the Agent Skills specification. See the skills/ section above.

Dot-prefixed reserved names:

.config : Configuration file (YAML, no extension). Used by the AgentFinger daemon for user-level settings.

.acl : Access control list (plain text). Defines who can read which paths when served over the network.

.project : Traditional Finger-style file describing the user’s current project. Included as an appendix when served by the AgentFinger daemon.

.plan : Traditional Finger-style file describing the user’s current plans. Included as an appendix when served by the AgentFinger daemon.

Other dot-prefixed names may be used by tools for their own purposes.

Extensibility

Tools and communities can add directories and files beyond the canonical structure without breaking compatibility. Custom additions should use descriptive names and avoid collisions with the reserved paths listed above.

Examples

Minimal setup

~/.agents/
└── profile/
    └── user.md

A single file is enough. The user profile provides the essential identity information that agents need.

Full setup

~/.agents/
├── .config
├── .acl
├── .project
├── .plan
├── index.md
├── profile/
│   ├── user.md
│   └── organizations/
│       ├── stlabs.md
│       └── flamebound.md
├── skills/
│   ├── pdf-processing/
│   │   └── SKILL.md
│   └── code-review/
│       └── SKILL.md
└── techdocs/
    ├── containerization.md
    ├── workflows.md
    └── languages/
        ├── go.md
        └── typescript.md

FAQ

How does .agents relate to AgentFinger?

.agents is the static data layer that AgentFinger serves over the network. The directory structure mirrors what the AgentFinger daemon’s user data directory looks like. You can use .agents purely as a local convention (read directly by tools like Claude Code, Cursor, or custom scripts) without ever running an AgentFinger daemon. If you do run the daemon, it reads from ~/.agents/ and serves the contents over the AgentFinger protocol.

How does .agents relate to the XDG Base Directory Specification?

It does not conflict with it. XDG defines where applications store their own configuration. .agents defines where user identity and knowledge data lives so that any tool can find it. They occupy different conceptual spaces: XDG is about per-application config; .agents is about cross-tool discovery.

How does ~/.agents/skills/ relate to the Agent Skills specification?

The Agent Skills specification (originally developed by Anthropic, now an open standard) defines the SKILL.md format and how agents discover and load skills. It does not mandate a specific home directory path — different tools use different locations (~/.codex/skills/, ~/.claude/skills/, ~/.opencode/skills/, etc.).

~/.agents/skills/ is the tool-neutral home directory location for user-global skills. dotStandards formalizes it as the canonical cross-tool location, while the format itself remains defined by agentskills.io. Tools that scan ~/.agents/skills/ include Codex, OpenCode, and Augment.

Status

Governance

Maintained by secondtruthLabs.

Related specifications

• AgentFinger Protocol Specification — the network protocol that serves .agents data over the wire.
• AgentFinger Daemon Implementation Guide — reference server implementation, directory resolution, ACL, and service discovery.
• Agent Skills Specification — the open standard for the SKILL.md format used in ~/.agents/skills/.