Specification For Linking UAI Files In Agents Markdown (Uaix Proposal)

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:

Metadata

Field	Value
Source site	uaix.org
Source URL	https://uaix.org/
Canonical AIWikis URL	https://aiwikis.org/uaix/files/raw-system-archives-uaix-internal-memory-reorg-2026-05-01-docs-specifica-2d775cbd/
Source reference	raw/system-archives/uaix/internal-memory-reorg/2026-05-01/docs/Specification for Linking uai Files in AGENTS by ChatGPT.md
File type	md
Content category	memory-file
Last fetched	2026-06-22T01:56:21.9510185Z
Last changed	2026-04-25T22:57:49.7455975Z
Content hash	sha256:2d775cbda172d15917008d4c54b7c5f8e91eed78c716fe9dd14510d514a0ef79
Import status	unchanged
Raw source layer	data/sources/uaix/raw-system-archives-uaix-internal-memory-reorg-2026-05-01-docs-specification-for-linking-uai-fil-2d775cbda172.md
Normalized source layer	data/normalized/uaix/raw-system-archives-uaix-internal-memory-reorg-2026-05-01-docs-specification-for-linking-uai-fil-2d775cbda172.txt

Current File Content

Structure Preview

• Specification for Linking .uai Files in AGENTS.md (UAIX Proposal)
• Goals and Scope
• Linking .uai Files from AGENTS.md
• AI Information Files
• .uai File Schema
• Directory/Layout and Naming Conventions
• Examples and Workflows
• AGENTS.md snippet example
• AGENTS.md: AI Context for Project X
• Handoff Workflow (Human + Multi-Agent)
• Entity Relationship Diagram
• Backward Compatibility & Migration
• Security, Privacy, and Trust
• Tooling and Validation
• Contribution and Governance
• PR Template (example fields)
• Alternatives Comparison
• References

Raw Version

This public page shows a bounded preview of a large source file. The complete source remains in the raw and normalized source layers named in metadata, with the SHA-256 hash above for verification.

• Source characters: 28183
• Preview characters: 11935

Local absolute paths are redacted in this public view. The source hash and source-side raw layer are based on the unredacted source file.

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

> Status note: This is the source proposal behind the public report at `/en-us/specification/agents-md/`. For current UAIX launch truth, start with `/en-us/specification/project-handoff/`, then use this file for deeper link syntax, record-shape, and background rationale. Mentions of `.uai` generators, validators, SDKs, CLIs, certification, endorsement, or template libraries are proposal or roadmap ideas unless the public Roadmap, Changelog, and published tooling evidence say otherwise.

**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 (source-relative: glossary.uai) – Key terms for this project
- Data Schema (source-relative: 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 (source-relative: 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:

| Method                   | Syntax in AGENTS.md      | Advantages                                    | Drawbacks                                   |
|--------------------------|--------------------------|-----------------------------------------------|---------------------------------------------|
| **Inline text**          | N/A (no external file)   | No setup; simple for tiny context.            | Hard to maintain as context grows; no structure. |
| **Markdown link**        | `Info (source-relative: file.md)`        | Standard Markdown; human-readable content.    | Agents must manually fetch and parse file content. |
| **@-include (Gemini)**   | `@./path/to/file.md`     | Built-in in some agents; auto-includes content【27†L689-L697】【63†L19-L27】. | Requires agent support for `@`. Handles only Markdown. |
| **New `.uai` file (this spec)** | `@info.uai` or `Info (source-relative: info.uai)` | Structured, schema-validated data; tool-friendly; language-agnostic. | New file type; requires defining tooling and agent support. |

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):**
```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
  ```

Why This File Exists

This is a memory-system evidence file from uaix.org. It is shown here because AIWikis.org is demonstrating the real source files that make the UAIX / LLM Wiki memory system work, not only summarizing those systems after the fact.

Role

This file is memory-system evidence. It records source history, archive transfer, intake disposition, or another piece of provenance that should be retrievable without becoming an unsupported public claim.

Structure

The file is structured around these visible headings: Specification for Linking .uai Files in AGENTS.md (UAIX Proposal); Goals and Scope; Linking .uai Files from AGENTS.md; AI Information Files; .uai File Schema; Directory/Layout and Naming Conventions; Examples and Workflows; AGENTS.md snippet example. Those headings are retrieval anchors: a crawler or LLM can decide whether the file is relevant before reading every line.

Prompt-Size And Retrieval Benefit

Keeping this material in a separate file reduces prompt pressure because an agent can load this exact unit only when its role, source site, category, or hash is relevant. The surrounding index pages point to it, while this page preserves the full content for audit and exact recall.

How To Use It

• Humans should read the metadata first, then inspect the raw content when they need exact wording or provenance.
• LLMs and agents should use the source site, category, hash, headings, and related files to decide whether this file belongs in the active prompt.
• Crawlers should treat the AIWikis page as transparent evidence and follow the source URL/source reference for authority boundaries.
• Future maintainers should regenerate this page whenever the source hash changes, then review the explanation if the role or structure changed.

Update Requirements

When this source file changes, update the raw source layer, normalized source layer, hash history, this rendered page, generated explanation, source-file inventory, changed-files report, and any source-section index that links to it.

Related Pages

• Source overview
• Site file index
• Site report index
• UAI system index
• Source provenance
• Site directory
• Organization reports

Provenance And History

• Current observation: 2026-06-22T01:56:21.9510185Z
• Source origin: current-source-workspace
• Retrieval method: local-source-workspace
• Duplicate group: sfg-228 (primary)
• Historical hash records are stored in data/hashes/source-file-history.jsonl.

Machine-Readable Metadata

{
    "title":  "Specification For Linking UAI Files In Agents Markdown (Uaix Proposal)",
    "source_site":  "uaix.org",
    "source_url":  "https://uaix.org/",
    "canonical_url":  "https://aiwikis.org/uaix/files/raw-system-archives-uaix-internal-memory-reorg-2026-05-01-docs-specifica-2d775cbd/",
    "source_reference":  "raw/system-archives/uaix/internal-memory-reorg/2026-05-01/docs/Specification for Linking uai Files in AGENTS by ChatGPT.md",
    "file_type":  "md",
    "content_category":  "memory-file",
    "content_hash":  "sha256:2d775cbda172d15917008d4c54b7c5f8e91eed78c716fe9dd14510d514a0ef79",
    "last_fetched":  "2026-06-22T01:56:21.9510185Z",
    "last_changed":  "2026-04-25T22:57:49.7455975Z",
    "import_status":  "unchanged",
    "duplicate_group_id":  "sfg-228",
    "duplicate_role":  "primary",
    "related_files":  [

                      ],
    "generated_explanation":  true,
    "explanation_last_generated":  "2026-06-22T01:56:21.9510185Z"
}