AGENTS.md .uai Linking Specification

Specification for Linking .uai Files in AGENTS.md (UAIX Proposal)#

Executive Summary: We propose an open, practical standard to link informational AI files (.uai extension) from an AGENTS.md context file, enabling multiple AI agents to share structured knowledge. These .uai files are JSON- or YAML-style documents with defined fields (intents, capabilities, context, version, provenance, access controls, etc.). The AGENTS.md file references them using a simple syntax (e.g. @path/to/file.uai or Markdown links), so any agent framework can fetch and parse the same data. This enables seamless handoff: one agent can emit a .uai knowledge file that others later consume. We define required metadata in agents.md (labels, URIs), a detailed .uai schema, layout conventions, and usage examples (including mermaid workflows and ER diagrams). We cover backward compatibility (renaming AGENT.md→AGENTS.md【62†L201-L204】 and incremental adoption), security (signatures/checksums and access roles), and tool support (validators, linters, CLI commands). Finally, we outline UAIX contribution steps (change workflow, PR template, docs updates【59†L175-L184】【59†L120-L123】). Tables compare linking alternatives and file format options. This proposal is written to fit UAIX style, ready for inclusion on UAIX.org with minimal changes.

Goals and Scope#

• Enable multi-agent context sharing: Define a standard way for AGENTS.md (the “README for agents”【1†L7-L15】) to reference external .uai files that contain structured AI knowledge. These files allow teams to pass the same data (intents, capabilities, domain info, etc.) to different agents regardless of vendor. Agents can “read” and “write” .uai files as durable context between tasks (akin to the Agent2Agent “agent card” concept【61†L31-L34】【61†L109-L117】).

• Leverage existing conventions: We align with established patterns. For example, Gemini and Claude already support @file includes in their context files【27†L689-L697】【63†L19-L27】, and OpenAI’s Codex suggests breaking large AGENTS.md into linked files【36†L713-L716】. Our spec uses a similar @path/to/file.uai or Markdown link syntax so any agent tool can fetch the file.

• Structure and interoperability: The .uai file is a formal, machine-readable document (JSON/YAML) with a published schema (we propose “UAI-1.info.v1”). It contains standard metadata (intents, capabilities, version, provenance, etc.) enabling rigorous interpretation. This is analogous to the Agent2Agent “agent card”【61†L109-L117】 and UAIX’s emphasis on typed messages【48†L39-L43】.

• Backward compatibility: We build on current practice rather than break it. Projects without .uai can continue using plain AGENTS.md. To adopt .uai, teams simply add references in AGENTS.md. We document migration steps (rename AGENT.md→AGENTS.md【62†L201-L204】, then add .uai files) and label compatibility changes in the UAIX changelog【59†L175-L184】.

• Scope: This proposal covers the AGENTS.md spec extension on UAIX, including syntax for linking files, the .uai file format/schema, directory/naming conventions, examples, and guidance for UAIX publication (governance, PR template). It does not attempt to standardize the contents of AGENTS.md itself beyond linking, nor replace UAIX’s existing UAI message protocol (UAI-1)【48†L39-L43】. It simply defines “informational files” that live alongside code and AGENTS.md to share AI-context metadata today.

Linking .uai Files from AGENTS.md#

To reference a .uai file in your project’s AGENTS.md, use a consistent syntax. For example, include a list or section in AGENTS.md like:

## AI Information Files
- [Project Glossary](glossary.uai) – Key terms for this project
- [Data Schema](schema.uai) – Structured definitions of core data models
- @docs/architecture.uai – Detailed architecture context

Here, each bullet names an info file. We allow either Markdown links or the “@” include syntax (as used by Gemini/Claude【27†L689-L697】【63†L19-L27】). The important metadata is the file path/URI (relative or absolute); agents should recognize and load the file’s contents. At minimum, an entry must include the file path and a brief label/description. Optionally, one can add more fields, e.g.:

- [Model Capabilities](caps.uai) *(description: available inference features)*

Internally, agent tools will parse AGENTS.md and look for .uai links. We propose adopting the @file.uai pattern (following Claude/Gemini context imports【27†L689-L697】【63†L19-L27】) so that agents may automatically include the file’s content. For example, an agent prompt could say:

> Summarize the requirements from @glossary.uai

which would cause the agent to fetch and ingest the JSON/YAML from glossary.uai.

Table 1. Comparison of context linking methods in AGENTS.md. We compare ways to reference external info:

In practice, teams might start by using Markdown links or @ includes, and then migrate to structured .uai. The table above shows that .uai files bring structure and validation (see schema below), at the cost of being a new convention to learn.

.uai File Schema#

A .uai file is a structured document (JSON or YAML) with a fixed schema. We name the schema version (e.g. "schemaVersion": "UAI.info.v1") to allow evolution. Below are the required and optional fields we recommend; agents and validators should enforce “required” fields and types. Field order is not significant (we follow UAIX’s keyed JSON approach【59†L175-L184】).

• schemaVersion (string, required): The version of the .uai schema (e.g. "UAI.info.v1"). This anchors compatible parsing.
• id (string, optional): A unique identifier or URI for this info file (e.g. urn:project:glossary.v1). Useful for provenance tracking.
• name (string, required): A short title for the info file (e.g. "Project Glossary").
• description (string, optional): Longer human-readable description.
• version (string, optional): File version (semantic or date-based, e.g. "2026-04-22" or "1.2.0").
• intents (array of strings or objects, optional): Key tasks or user intents covered. Example: "code completion", or [{ "name": "resolve-bugs", "description": "Use this to fix reported bugs." }].
• capabilities (array of strings or objects, optional): Agent capabilities or tools relevant to this context. For example:

  "capabilities": [
    { "name": "Python-Linter", "description": "Checks PEP8 style" },
    { "name": "Test Runner", "version": "2.0" }
  ]

This echoes the Agent2Agent agent-card style of listing skills【61†L109-L117】.

• context (object or string, optional): Additional structured context data. Could be an object of key-value data, or a markdown/HTML string. E.g. "context": { "repoSize": 120000, "langs": ["C#", "SQL"] }.
• provenance (object, optional): Information about authorship and history. Fields like "createdBy": "did:web:example.com", "createdDate": "2026-04-22T17:00:00Z", and "modifiedBy". This mirrors UAIX’s use of DIDs and timestamps in messages【18†L508-L514】.
• accessControl (object, optional): Defines who or what can read/modify this file. For example, roles or DIDs authorized:

  "accessControl": {
    "readRoles": ["developers", "integrators"],
    "writeDIDs": ["did:example:alice"]
  }

Agents should respect these controls when retrieving the file.

• links (array of objects, optional): Machine-readable references to related resources. Each link can have "rel", "href", "type". For example:

  "links": [
    { "rel": "cites", "href": "https://example.com/architecture-spec.pdf", "type": "application/pdf" },
    { "rel": "parent", "href": "other.uai" }
  ]

This supports interconnected knowledge.

• signature (string, optional): A digital signature (e.g. JWS) of the file for integrity. If present, clients should verify it against a public key.
• checksum (string, optional): A content hash (e.g. SHA-256) to detect tampering (as UAIX uses for message parts【18†L508-L514】).

Example .uai (JSON):

{
  "schemaVersion": "UAI.info.v1",
  "name": "Project Glossary",
  "description": "Key terms and abbreviations used in this project.",
  "version": "2026-04-22",
  "createdBy": "did:web:example.com",
  "createdDate": "2026-04-22T17:00:00Z",
  "intents": [
    { "name": "define-term", "description": "Provide definition of a term" },
    { "name": "add-term",    "description": "Add a new glossary term" }
  ],
  "capabilities": [
    { "name": "Search", "description": "Full-text search over definitions" }
  ],
  "context": {
    "primaryLanguage": "C#",
    "termsCount": 42
  },
  "links": [
    { "rel": "documentation", "href": "https://docs.example.com/project/glossary" }
  ]
}

This file advertises agent intents and capabilities similar to an Agent2Agent card【61†L109-L117】, but focuses on project-specific information. Agents reading this file know which tasks it supports and can incorporate its data.

We recommend providing a JSON Schema for .uai so tools can validate files in CI. Fields marked required must be present; additional fields should generally be disallowed unless namespaced (per UX).

Directory/Layout and Naming Conventions#

Place .uai files in logical locations alongside your code. Common patterns:

• Project root or subfolders: For example, a top-level ai/ or agents/ directory containing .uai files, or simply place them in the root. Nested projects may have their own AGENTS.md and .uai files (see UAIX style for nested contexts【1†L7-L15】【62†L201-L204】).
• Descriptive names: Use clear, lowercase names (kebab-case or snake_case) matching content. E.g. glossary.uai, schema.uai, architecture.uai. Since UAIX uses hyphenated record names, we prefer kebab-case for consistency. Avoid spaces.
• Versioning in names (if needed): If you keep multiple versions, include a version date or number: e.g. glossary_v1.uai or glossary-2026-04-22.uai.
• Grouping: If many .uai files exist, group them by function. For instance:

  ai/
    glossary.uai
    data_schema.uai
    intent_specs.uai
  docs/
    AGENTS.md
    roadmap.md

• Cross-referencing: In AGENTS.md and other .uai files, refer to .uai by relative or absolute paths (e.g. @ai/glossary.uai). Agents should resolve these paths consistently (similar to how Claude’s @ references file paths【27†L689-L697】).

Examples and Workflows#

AGENTS.md snippet example

A minimal AGENTS.md referencing .uai files:

# AGENTS.md: AI Context for Project X

We organize AI guidance as follows:

- **Project Overview:** High-level summary of the application.
- **Build/Test:** Commands to build and test (run, e.g., `npm test`).
- **Link Info Files:**
  - [Glossary](ai/glossary.uai) – Definitions of key terms.
  - [Data Model](ai/data_model.uai) – JSON schema of domain objects.
  - [Architecture](ai/architecture.uai) – System architecture details.

Agents should load these files for additional context when reasoning or generating code. The closest AGENTS.md wins (allowing nested overrides【1†L7-L15】【62†L201-L204】). 

When an agent sees @ai/glossary.uai, it should fetch and parse the JSON. The AGENTS.md file can live anywhere in the repo; if a subfolder has its own AGENTS.md, it can reference its own .uai files for that component.

Handoff Workflow (Human + Multi-Agent)

Below is a sequence workflow diagram showing how a human and two agents share structured info via .uai:

flowchart LR
    Human[Human] -->|Writes spec to| MD[AGENTS.md with .uai links]
    MD --> UAI[info.uai files on disk]
    Agent1[Agent A] -->|Reads| MD
    Agent1 -->|Reads| UAI
    Agent1 -->|Writes code & updates| Repo[Code Repository]
    Agent1 -->|Appends facts to| UAI  <!-- agent may add to .uai -->
    Agent2[Agent B] -->|Reads updated| MD
    Agent2 -->|Reads updated| UAI
    Agent2 -->|Runs tests/validation| Repo

• The human writes or updates AGENTS.md and creates .uai files (e.g. initial glossary, requirements).
• Agent A loads AGENTS.md and the .uai files (structured context), performs work (e.g. coding), then updates the repo and may augment a .uai (e.g. log of changes).
• Agent B (or the human) then loads the (possibly updated) .uai context and AGENTS.md to continue, verify, or extend the task.

This workflow ensures continuity: context and decisions in .uai are preserved and machine-readable, avoiding token loss between sessions. Because A2A-style exchanges use structured messages【61†L31-L34】, this file-based approach emulates a portable “public record” of context without requiring online service.

Entity Relationship Diagram

The following class-style diagram shows the relationships:

classDiagram
    class Project {
        +string name
        +AGENTSDoc agents.md
        +List~UAIFile~ info_files
    }
    class AGENTSDoc {
        +path
        +List~string~ linked_files
    }
    class UAIFile {
        +schemaVersion
        +name
        +intents[]
        +capabilities[]
        +context
        +version
        +provenance
    }
    class Agent {
        +string id
        +capabilities[]
    }
    Project "1" o-- "1" AGENTSDoc : contains
    Project "1" o-- "*" UAIFile : contains
    AGENTSDoc "1" -- "*" UAIFile : references
    Agent --> AGENTSDoc : reads
    Agent --> UAIFile : reads

• A Project contains one AGENTS.md and any number of .uai files.
• AGENTS.md lists references to the .uai files it uses.
• Each UAIFile carries fields as per the schema (shown).
• An Agent (AI agent instance) reads AGENTS.md and the referenced .uai to acquire knowledge.

This structure (inspired by A2A “agent card” diagrams【61†L109-L117】) keeps AI context explicit and discoverable.

Backward Compatibility & Migration#

Teams with existing AGENTS.md (or AGENT.md) can adopt this spec gradually:

• Rename AGENT.md: If a repository has an old AGENT.md, rename to AGENTS.md and symlink for compatibility【62†L201-L204】.
• Add .uai files gradually: Start by moving any large structured sections from AGENTS.md into .uai. Update AGENTS.md to link to the new files. Because Markdown links to .uai are standard, older agents that only read AGENTS.md will treat [Name](file.uai) as external references (which they may ignore if they don’t understand .uai). Newer agents supporting .uai will parse them.
• Prefix vs suffix rules: We do not change the meaning of existing AGENTS.md content. All .uai links are optional enhancements. There is no conflict: if no agent understands .uai, they simply won’t use the file. The spec is additive (non-breaking).
• Migration steps:

1. Create a new .uai file (e.g. glossary.uai) alongside AGENTS.md. Move content from AGENTS.md into it as structured JSON/YAML.
2. In AGENTS.md, add a reference (e.g. @glossary.uai or [Glossary](glossary.uai)).
3. Commit the changes, informing team members. The UAIX changelog entry should note this addition as additive and mention any migration guidance【59†L175-L184】.

• Monorepos and nesting: If using nested AGENTS.md for submodules【1†L7-L15】, each can have its own .uai files. Tools should load the nearest AGENTS.md and follow links therein.

Overall, adopting .uai adds no breaking changes. It is fully backwards-compatible: agents that do not support it simply ignore the links, while new or updated agents will pick up the structured data. Over time, teams can enrich .uai content (adding more fields) as needed.

Security, Privacy, and Trust#

As .uai files may contain sensitive project information, we include several trust measures:

• Checksums and Signatures: Include a checksum (e.g. SHA-256) or signature field in the file. Consumers can verify integrity. UAIX messages already use hashes in JCS format【18†L508-L514】; .uai files should similarly allow cryptographic verification. For example:

  "checksum": "sha256:3a7bd3e2360aaf...deadbeef",
  "signature": "eyJhbGciOiJFUzI1NiIsIn..."

Tools can provide uai-sign and uai-verify commands (or reuse existing DID/VC libraries) to sign and check .uai files. This prevents tampering during handoff.

• Access Control: The accessControl field (see schema) can specify which agents or roles are allowed to read or update the file. E.g., set "readRoles": ["admins","ci"] or "writeDIDs": ["did:web:example.com"]. Agent frameworks should enforce these policies (analogous to how UAIX protects message contents).
• Authentication standards: We recommend following UAIX/A2A best practices: run all handoffs over secure channels (HTTPS/OAuth)【61†L31-L34】【61†L109-L117】. The .uai files themselves might be stored in a Git repo (access controlled) or served via a secure registry, ensuring only authorized agents fetch them.
• Privacy: If .uai contains personally identifiable data or proprietary business logic, teams should review its contents carefully. Sensitive data should be redacted or kept in protected fields. Since UAIX governance treats data exposure as a trust issue【59†L165-L173】, any new .uai additions should go through review and be noted in the changelog if privacy-impacting.
• Provenance: The provenance fields (createdBy, createdDate) allow tracing who authored or updated the info. This aligns with UAIX’s emphasis on auditable exchange【48†L39-L43】【59†L175-L184】. An agent could refuse data from an untrusted origin.

Tooling and Validation#

We recommend the following tooling practices for .uai:

• Schema validation: Provide a JSON Schema (or YAML equivalent) for .uai files. Tools like ajv (Node) or @@UAIX_TOKEN_1@@ CLI can validate files. For example:

  npx ajv validate -s uai.schema.json -d ai/glossary.uai

or

  jsonschema -i ai/glossary.uai uai.schema.json

A UAIX-aware validator could be extended to check .uai conformance. In CI pipelines, add a step to validate all .uai files against the schema.

• Linters: Since .uai is JSON/YAML, existing linters/formatters apply. For JSON, use prettier or jq . to format. For YAML, use yamllint. We can also write a custom uai-lint script to check best practices (no missing fields, correct types).
• Converters: If teams prefer writing .uai in YAML or another format, provide conversion scripts. For example:

  pip install yq
  yq eval --tojson info.yaml > info.uai

Or build a small CLI (uai-tool) that can import/export .uai, sign it, merge definitions, etc.

• CLI references:
• Validation: uai-validator validate schema.json myinfo.uai (like UAIX’s validator for messages【59†L120-L123】).
• Sign/verify: uai-sign --key privkey.pem info.uai > info.uai.sig and uai-verify info.uai info.uai.sig.
• Merge: For multi-agent workflows, a command like uai-merge could combine multiple partial .uai into one.
• Editors: Use JSON/YAML language support in editors (VSCode, etc.) for code completion on the .uai schema.

By treating .uai files as first-class machine-validated assets, we align with UAIX’s focus on conformance and evidence【59†L165-L173】. Every change to .uai should ideally have an automated test (validate and maybe round-trip) to ensure compliance.

Contribution and Governance#

To add this specification to UAIX.org, follow UAIX’s public standards processes:

1. Write the spec as UAIX would: on UAIX, each public record has an ID (like REC-xx) and canonical URI. We would create a new record (e.g. “UAI-INFO-1”) covering this feature. The spec text (including schema) should be published under UAIX’s domains, linked in References/Contributors pages, etc.
2. Update navigation: Add links in UAIX site navigation (e.g. under “Examples” or “Specifications”) to the new Agents.md linking spec.
3. Example fixtures: Provide example .uai files and an AGENTS.md snippet as test fixtures in UAIX’s “Examples” section.
4. Change proposal steps: UAIX requires a defined process【59†L175-L184】. We would:

• Identify records to update (e.g. Add a new entry under Schemas or Examples).
• Describe compatibility impact (additive) in the changelog.
• Update all related pages together: specification prose, schema file, examples, validator outputs.
• Attach any validator evidence (e.g. output of JSON Schema validation).

1. Governance labels: Label this change as Additive in UAIX terms (perverse usage likely additive since it doesn’t break UAI messages).
2. PR template: When opening a PR on UAIX’s repository:

• Include a summary of the feature and rationale.
• List affected files/pages and describe the changes.
• Provide “Compatibility” notes (old agents ignore it; new ones consume it).
• Link to this issue/spec as reference.
• For any code or schema, attach conformance tests or validator logs.
• Ensure the PR follows UAIX guidelines: include fields like “Change Type,” “Record Code,” etc.

1. References and Contributors: As UAIX says, always cite sources【59†L120-L123】. In our case, we’d cite this proposal document itself and any authority (like Agent2Agent docs【61†L109-L117】 or Codex best practices【36†L713-L716】). We’d update the UAIX References page to credit this spec’s author and reviewers.
2. Validator and Conformance Pack: Extend UAIX’s validator with a .uai profile (similar to how UAI-1 has schemas and validator). In the Conformance Pack, include the .uai JSON Schema, example .uai files, and sample validator run.

By following UAIX’s documented workflow and using the changelog for migration guidance【59†L165-L173】【59†L175-L184】, this new feature can be added in a controlled, transparent way. Contributors should ensure all canonical UAIX requirements (styled pages, record codes, discoverability) are met.

Governance snapshot: UAIX is documentation-led and values traceability【59†L120-L123】. We’d thus add this spec to the public record (with a new REC code), update the changelog (with an Additive change note), and include validator/examples as proof. If published, it would be part of the UAIX stable reference suite alongside UAI-1, enabling any tool or team to cite it authoritatively.

PR Template (example fields)

*Title*: Add Agents.md linking spec with .uai files (REC-XX)

**Summary**: Defines .uai info files and AGENTS.md syntax to reference them.
**Goal**: Enable structured, multi-agent context sharing.
**Affected Records**: New Schema (UAI.info.v1), new Examples.
**Compatibility**: Additive (existing agents ignore .uai references).
**Migration**: Docs updated above; see changelog entry for upgrade instructions.
**References**: UAIX Governance, Agent2Agent protocol【61†L31-L34】【61†L109-L117】, Codex best practices【36†L713-L716】.
**Validator**: Included schema and sample .uai; validator output attached.

Alternatives Comparison#

We considered different approaches to share agent context and decided on .uai for these reasons:

• Plain AGENTS.md only: Simple but unstructured. As research shows, context files help agents but unstructured text can be token-inefficient【30†L121-L128】. Large AGENTS.md can get unwieldy.
• Sub-markdown files: Using multiple .md files is supported by codex/gemini【36†L713-L716】【63†L19-L27】, but Markdown lacks a schema (agents must guess meaning). It also ties context to prose.
• .uai vs JSON vs YAML vs other: We chose .uai as a semantic extension (could be JSON, YAML). JSON is easily machine-validated; YAML or JSONC allow comments but risk schema ambiguity. A JSON-based .uai aligns with UAIX’s JSON heritage【48†L39-L43】 and existing JSON schema tooling. We also compared .json, .yaml, and .toml, and found JSON best for schema enforcement (see Table 2 below).
• File vs network: Instead of a network service, file-based .uai keeps data versioned and auditable (fits “public record” philosophy【48†L39-L43】). Teams already use Git for source; adding .uai is trivial and decouples AI context from runtime uptime.

Table 2. File format options for .uai content.

We recommend JSON (with .uai extension) for interoperability. YAML is acceptable if teams prefer it, but a single agreed format avoids confusion. Note: regardless of format, the contents must obey the schema fields above; we treat the extension .uai as signaling "this is an AI info file."

References#

• UAIX Agents.md official site (“AGENTS.md” introduction and FAQ)【1†L7-L15】【62†L201-L204】.
• Anthropic Claude Code docs – context file referencing with @【27†L689-L697】.
• Google Gemini CLI docs – @file import syntax【63†L19-L27】.
• OpenAI Codex best practices on AGENTS.md usage【36†L713-L716】.
• Salesforce Agent2Agent protocol – open standard for agent collaboration and agent-card metadata【61†L31-L34】【61†L109-L117】.
• UAIX Governance – change workflow and references guidelines【59†L175-L184】【59†L120-L123】.
• ETH Zurich (2026) “Evaluating AGENTS.md” – context files are widely adopted (60k+ repos)【30†L121-L128】.

Each citation above points to the relevant source (primary docs or research) confirming aspects of our proposal. For example, [61†L109-L117] directly inspired the .uai metadata fields (capabilities, endpoint, auth), and [36†L713-L716] confirms that linking external context files is an accepted pattern. The UAIX Governance pages [59] guide how to incorporate this new spec into the standard.