**Note** from Bead: Agentify Bead · [canonical source](https://redfish.acequia.io/guerin/.agents/d9dfa5e4-3c92-4216-bd53-13b520c59a5e/2026-06-11/notes/agent-md-and-the-agent-face.md) · session 2026-06-11 · discussion: Talk: Agentify Bead
**Date:** 2026-06-11 **Status:** Open design thread. Stephen (2026-06-11): *"we are starting to standardize with skills and mcp but we haven't addressed agent.md wrt to bead that can ducktype as an agent."* Staged in this bead's URI-space; not a binding decision. Frame: [bead-duck-typing-file-folder-agent.md](https://redfish.acequia.io/guerin/.agents/d9dfa5e4-3c92-4216-bd53-13b520c59a5e/2026-06-11/notes/bead-duck-typing-file-folder-agent.md).
## The gap We have standard formats for two of a bead's three faces, and a *capability* format, but **nothing for the agent-face itself**: | Bead face | What it needs | Standard we have | |---|---|---| | **file** | a representation | HTTP content negotiation (`Accept`, Client Hints, query) — *standard, deployed* | | **folder** | an index / enumeration | `PROPFIND`, directory listing, **`about.md`** — *have it* | | **agent** | a self-description of what it can do when invoked as an agent | **— missing —** | And for **capabilities the agent holds** (not the agent itself): | Capability format | What it packages | Status | |---|---|---| | **`SKILL.md`** | a procedure/skill the model invokes (frontmatter `name`/`description` + instructions) | standardizing (`.ai/skills/<name>/SKILL.md`) | | **MCP** | tools / resources / prompts a server exposes to an LLM host | standardizing | The key distinction Stephen is pointing at: **Skills and MCP describe what a bead can *do*. They do not describe the bead *as an agent* — its polarity, its role, the capability set it exposes at its URI, how a peer agent should negotiate with it, its lifecycle/apoptosis policy.** That self- description is the agent-face's manifest, and it has no home yet. `about.md` is the *human/folder* index; `SKILL.md` is *one capability*; MCP is *a transport*. None of them is the agent-card.
## What `agent.md` (or `agent.json`) should be The agent-face manifest is the **negotiable surface made into a first-class artifact** — exactly what [beads.md](https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/2026-04-23/notes/beads.md) gestured at with "OPTIONS / HATEOAS / `/about`" but never standardized. It answers, for a caller who approaches the bead **as an agent**: 1. **Identity & polarity** — what demand does this bead align with? (role is emergent, but the manifest can declare the bead's *current* primary polarity so callers can predict usefulness.) 2. **Capabilities exposed** — which `SKILL.md`s it offers, which MCP tools/servers it fronts or is backed by. (References, not copies — bind, don't duplicate.) 3. **Invocation contract** — verbs it answers (`GET`/`POST`/`PUT`/`OPTIONS`), the negotiated media types per the polymorphic-GET table, auth/capability tokens required. 4. **Lifecycle** — apoptosis conditions, freshness/TTL, who maintains it, what sustains its charge. 5. **Composition** — beads it chains to (HATEOAS links); how it behaves as a composite. Crucially, under duck-typing the manifest is **itself content-negotiated**: `agent.md` is the human/Markdown face; `agent.json` (e.g. `application/ld+json; profile="acequia/bead"`, the exact media type already named in the polymorphic-GET note) is the machine face. Same resource, two faces. It is not a separate file *type* so much as the **agent-face representation of the bead's `about`**.
## Mapping to existing standards (so we don't reinvent) - **A2A-style Agent Cards** (`.well-known/agent.json`) are the closest external prior art: a JSON descriptor of an agent's skills, endpoints, and auth, served at a well-known path for agent-to-agent discovery. Our `agent.json` is the **per-bead, per-URI** version of this — every bead URI can serve its own card, not just one card per origin. - **MCP** is the *transport/runtime* a bead's agent-face can advertise ("invoke me via this MCP server"); the manifest references it, doesn't replace it. - **`SKILL.md`** is a *capability the agent holds*; the manifest lists which skills the bead exposes. - **`AGENTS.md`** (the coding-agent instruction convention) is **not** this — that configures a tool-agent operating *inside* a repo. Our `agent.md` describes a *resource-agent* serving a URI. Same filename family, opposite direction (instructions-to-an-agent vs. description-of-an-agent). Worth picking a name that doesn't collide — likely **`agent.json` + `agent.md` under the bead root**, sibling to `about.md`, rather than overloading `AGENTS.md`.
## Where it lives in the bead ``` <bead>/ ├── about.md # folder-face index (human + structure) ← have ├── agent.md # agent-face manifest (human-readable) ← PROPOSED ├── agent.json # agent-face manifest (machine, JSON-LD) ← PROPOSED ├── <date>/ │ ├── skills/ # SKILL.md capabilities the agent holds ← standardizing │ ├── notes/ chats/ artifacts/ ``` `about.md` answers "what is in this folder?" — `agent.md` answers "what can I do if you talk to me as an agent, and how?" They are the **folder-face** and **agent-face** of the same bead, and they should cross-reference. (The duck-typing claim says they're ultimately one resource projected two ways; in practice we may store two files until the serving layer can negotiate them from one.)
## Open questions for Stephen (binding decisions) 1. **Name & collision.** `agent.md`/`agent.json` sibling to `about.md`? Or fold the agent-face into `about.md` via content negotiation and never store a second file? (Duck-typing purist answer: one `about`, negotiated. Pragmatic answer: two files until the SW/origin can negotiate.) 2. **Schema.** Adopt/adapt the A2A Agent Card schema, or define an acequia-native `profile="acequia/bead"` JSON-LD shape? (Leaning: acequia profile that *embeds* A2A-compatible fields so external agents can read it.) 3. **Skills/MCP references.** Manifest links to `SKILL.md` URIs and MCP server descriptors by reference (bind, not copy) — confirm that's the discipline. 4. **Who writes it.** CE scribe authors `agent.md` from the chat the way it authors `about.md`? Or is it generated from `OPTIONS`/PROPFIND introspection of the live bead? 5. **Degenerate case.** A dead-file bead has no agent-face — does it simply omit `agent.md`, or serve a minimal "I am static, here are my representations" card? (Consistent with "static file = degenerate agent": a minimal card is the honest answer.)
## Why this matters now Standardizing Skills and MCP without an agent-face manifest leaves beads **invokable but not discoverable as agents**. A peer agent can call a known MCP tool, but it can't walk up to an arbitrary bead URI and ask "what are you, what can you do, how do I negotiate with you?" — which is the whole point of the negotiable surface and the agentic web (negotiation IS the protocol). `agent.md`/`agent.json` is the artifact that makes the agent-face **self-describing**, completing the trio: file (negotiated bytes) · folder (`about.md` + PROPFIND) · agent (`agent.json` + OPTIONS).
## Ratified — 2026-06-11 Stephen: *"yes let's make agent.md and agent.json as a standard. we might also include keywords.json … also a names.json on local names that bead uses to refer to other beads, agents, urls, skills, any uri."* **Prior art found** (this standard ratifies, it doesn't invent): bead [5595c7f1's `agent.md`](https://redfish.acequia.io/guerin/.agents/5595c7f1-4621-437c-a4ae-7902b640f0e8/agent.md) already defined the exact framing — `agent.md` = *operative self* vs. `about.md` = *descriptive self*; `.well-known/agent.json` = *machine twin*; `mcp.md` = *tool interface*. The earlier open questions in this note are largely answered by that prototype: - **Name/collision:** `agent.md` + `agent.json` siblings to `about.md` at the bead root. Confirmed — `AGENTS.md` (instructions-to-a-tool-agent) is the opposite direction and not reused. - **Schema:** acequia-native `profile="acequia/bead"` JSON that *embeds* A2A-compatible fields. - **Two faces of one resource:** `agent.json` is the content-negotiated twin of `agent.md`. **Two new root files added** (Stephen's directive): - **`keywords.json`** — flat index surface for fast find/index across the commons (folder-face discovery metadata). - **`names.json`** — the per-bead **local namespace**: short names → absolute URIs for other beads / agents / skills / URLs. This is [uri-bind-mount](https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/2026-04-23/notes/uri-bind-mount.md) made concrete per bead — a Plan-9 per-process namespace / import map. Resolves `localname`. **Codified** in [.agents/beads.md §Standard Bead Root Files](https://redfish.acequia.io/guerin/.agents/beads.md). **Reference implementation** dogfooded on this bead: [agent.md](https://redfish.acequia.io/guerin/.agents/d9dfa5e4-3c92-4216-bd53-13b520c59a5e/agent.md), [agent.json](https://redfish.acequia.io/guerin/.agents/d9dfa5e4-3c92-4216-bd53-13b520c59a5e/agent.json), [keywords.json](https://redfish.acequia.io/guerin/.agents/d9dfa5e4-3c92-4216-bd53-13b520c59a5e/keywords.json), [names.json](https://redfish.acequia.io/guerin/.agents/d9dfa5e4-3c92-4216-bd53-13b520c59a5e/names.json). **Connection to today's hey-you-its-me bead** ([ec4d09d8](https://redfish.acequia.io/guerin/.agents/ec4d09d8-7f06-41d3-80fe-80aeaedba680/2026-06-11/notes/00-concepts.md)): its `acequia.json` per-folder ingress router is the **runtime** counterpart of these static manifests — `acequia.json` negotiates the verb set per caller (file when offline, live agent stream when online), which is exactly the duck-typing collapse rule. `agent.json` declares *what the agent is*; `acequia.json` decides *how to route to it right now*. The two compose: a peer reads `agent.json` to discover the bead, then `acequia.json` at the path routes the actual "hey you, it's me" connection. **Open (still Stephen's):** `mcp.md` shape; whether to physically store `agent.json` once and negotiate `agent.md` from it (duck-typing purist) or keep both files until the serving layer can negotiate; and whether `.ai/beads.md` (the divergent sibling copy) should receive the same section.
## Related - The three faces: [bead-duck-typing-file-folder-agent.md](https://redfish.acequia.io/guerin/.agents/d9dfa5e4-3c92-4216-bd53-13b520c59a5e/2026-06-11/notes/bead-duck-typing-file-folder-agent.md) - Negotiable surface origin: [beads.md (874fce5b)](https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/2026-04-23/notes/beads.md) - Manifest is itself negotiated: [polymorphic-get-content-negotiation.md (96597c32)](https://redfish.acequia.io/guerin/.agents/96597c32-7f1c-4e95-acd5-635673461781/2026-05-16/notes/polymorphic-get-content-negotiation.md) - Capability-first identity: [uri-as-primitive.md (31bd5380)](https://redfish.acequia.io/guerin/.agents/31bd5380-d743-420f-81a1-9258e7fbbf9a/2026-06-03/notes/uri-as-primitive.md) - Bead protocol / standard layout: [.agents/beads.md](https://redfish.acequia.io/guerin/.agents/beads.md)
## References (bead cross-links) - Bead: 874fce5b · [canonical](https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/) - Bead: CV · [canonical](https://redfish.acequia.io/guerin/.agents/5595c7f1-4621-437c-a4ae-7902b640f0e8/) - Bead: Hey You Its Me · [canonical](https://redfish.acequia.io/guerin/.agents/ec4d09d8-7f06-41d3-80fe-80aeaedba680/) - Bead: 96597c32 · [canonical](https://redfish.acequia.io/guerin/.agents/96597c32-7f1c-4e95-acd5-635673461781/) - Bead: 31bd5380 · [canonical](https://redfish.acequia.io/guerin/.agents/31bd5380-d743-420f-81a1-9258e7fbbf9a/)