Skip to content

.agents Guidelines

Guidelines specific to the .agents standard, extending the general guidelines.

Content

  • Optimize for LLM context windows. Content in .agents is primarily consumed by AI agents. Write with token efficiency in mind — be direct, avoid redundancy across files, and structure content so it can be injected into context windows effectively.
  • Be factual and current. Profile and organization data should reflect the present state. Remove or update outdated information promptly rather than accumulating stale entries.
  • Keep organization files user-scoped. Files in profile/organizations/ describe your relationship to an organization — your role, responsibilities, and current work. They are not canonical organization profiles; those live elsewhere (e.g., in the system-wide AgentFinger directory or the organization’s own documentation).
  • Scope techdocs to cross-project concerns. Techdocs cover tooling preferences, deployment strategies, language conventions, and other knowledge that spans multiple projects. Project-specific documentation belongs in the project repository (e.g., in a CLAUDE.md, README.md, or .forge/).

Structure

  • Keep profile/ flat. The profile directory has a fixed structure: user.md at the top level and organization files in organizations/. Do not create additional subdirectories.
  • Limit techdocs/ nesting. Use at most one level of subdirectories for categorization (e.g., techdocs/languages/go.md). Deeper nesting makes discovery harder for tools scanning the directory.
  • Use descriptive file names. File names should clearly indicate their content: containerization.md, not doc1.md. The file name is often the only context a tool has before deciding whether to read the file.

Security

  • Never store secrets. No API keys, tokens, passwords, or credentials. .agents directories can be served over the network via the AgentFinger protocol, so treat every file as potentially public.
  • Be deliberate about personal information. profile/user.md should contain what’s useful for AI agents to personalize their assistance, not a full biography. Consider what you’d be comfortable with any tool on your machine — or on the network — reading.

Tool integration

Most AI coding assistants support instruction files (e.g., CLAUDE.md, .cursorrules, .windsurfrules). Use these to point tools at your .agents directory:

## Additional context

Read the following files before starting work:

- `~/.agents/profile/user.md` — user profile and preferences
- `~/.agents/techdocs/` — cross-project technical documentation

This ensures tools discover your .agents data without requiring built-in support for the convention.