.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
│       └── ...
└── 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.

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:

.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
└── 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.

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.