> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# RFC-3: Agent Card Spec

## Abstract

An agent card is a UTF-8 encoded Markdown file with YAML frontmatter that serves as the public-facing documentation for an agent. It is purely descriptive and communicates what an agent is and what it can do, but does not drive any functional behavior (deployment, visibility, etc.), which remains the responsibility of `astropods.yml`.

The file is named `AGENT.md` and lives at the root of the agent's project directory, alongside `astropods.yml`. It is submitted to the registry during `ast push`.

## Changelog

| Version | Date       | Changes        |
| ------- | ---------- | -------------- |
| v1.0    | 2026-03-09 | Initial draft. |

## Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

***

## 1. File Format

An agent card is a UTF-8 encoded Markdown file consisting of two parts:

1. **Frontmatter**: A YAML block delimited by `---` lines at the top of the file. Contains structured metadata for discovery and attribution.
2. **Body**: Free-form GitHub-Flavored Markdown (GFM) following the frontmatter. Contains human-readable documentation.

Both parts are OPTIONAL. A valid agent card MAY be an empty file, a file with only frontmatter, or a file with only a Markdown body (no `---` delimiters).

***

## 2. Frontmatter Schema

All frontmatter fields are OPTIONAL unless noted otherwise.

### 2.1 `description`

| Property   | Value          |
| ---------- | -------------- |
| Type       | string         |
| Required   | OPTIONAL       |
| Max length | 200 characters |

A short summary of the agent. Used for agent cards, sidebar display, and search results. SHOULD be a single sentence or short phrase.

```yaml
---
description: "GitHub Issue Analyzer — ingests GitHub issues into a Neo4j knowledge graph"
---
```

When absent, the agent name is used as a fallback.

This field replaces the deprecated `meta.description` in `astropods.yml`. Existing agents SHOULD migrate their description to the agent card frontmatter.

### 2.2 `tags`

| Property    | Value     |
| ----------- | --------- |
| Type        | string\[] |
| Required    | OPTIONAL  |
| Max entries | 10        |

A list of category labels for discovery and filtering.

Each entry MUST be a lowercase string using only letters, numbers, and hyphens. Tags that do not conform are normalized: whitespace is trimmed, characters are lowercased, spaces are converted to hyphens, and non-alphanumeric/non-hyphen characters are stripped.

```yaml
---
tags:
  - analytics
  - data-processing
  - knowledge-graph
---
```

Implementations MUST reject the frontmatter if more than 10 tags are provided.

This field replaces the deprecated `meta.tags` in `astropods.yml`. Existing agents SHOULD migrate their tags to the agent card frontmatter.

### 2.3 `authors`

| Property | Value              |
| -------- | ------------------ |
| Type     | AgentCardAuthor\[] |
| Required | OPTIONAL           |

A list of people or organizations who built the agent.

#### AgentCardAuthor

| Field     | Type   | Required     | Description                                                                                                                                 |
| --------- | ------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`    | string | **REQUIRED** | Display name of the author.                                                                                                                 |
| `account` | string | OPTIONAL     | Platform account handle. When present, clients SHOULD render it as a link to `/{account}`. Normalized to lowercase with whitespace trimmed. |

```yaml
---
authors:
  - name: Jane Doe
    account: janedoe
  - name: Acme Corp
    account: acme
  - name: External Contributor
---
```

### 2.4 `capabilities`

| Property   | Value                    |
| ---------- | ------------------------ |
| Type       | string\[]                |
| Required   | OPTIONAL                 |
| Max length | 100 characters per entry |

A list of high-level capabilities the agent provides. Each entry SHOULD be a concise verb phrase describing an action the agent performs.

Unlike tags (broad categories), capabilities describe specific behaviors and are displayed on the agent's detail page.

```yaml
---
capabilities:
  - Analyzes GitHub issues and extracts patterns
  - Builds and maintains a Neo4j knowledge graph
  - Answers natural-language queries about issue history
---
```

Implementations MUST truncate entries exceeding 100 characters silently.

### 2.5 `repository`

A pointer to the source-code repository for the agent.

The value is either a **string shorthand** or an **object**.

#### String shorthand

```yaml
---
repository: "github:acme/my-agent"
---
```

Accepted shorthand prefixes:

| Prefix       | Resolves to                                   |
| ------------ | --------------------------------------------- |
| *(none)*     | `https://github.com/{value}` (GitHub assumed) |
| `github:`    | `https://github.com/{user}/{repo}`            |
| `gitlab:`    | `https://gitlab.com/{user}/{repo}`            |
| `bitbucket:` | `https://bitbucket.org/{user}/{repo}`         |
| `gist:`      | `https://gist.github.com/{id}`                |

A bare `user/repo` (no prefix) is treated as `github:user/repo`. A full URL (`https://...`) is also accepted as-is.

#### Object form

```yaml
---
repository:
  type: git
  url: "https://github.com/acme/my-agent.git"
  directory: packages/my-agent
---
```

| Field       | Type   | Required     | Description                                     |
| ----------- | ------ | ------------ | ----------------------------------------------- |
| `type`      | string | **REQUIRED** | Version-control system (`git`, `svn`, etc.).    |
| `url`       | string | **REQUIRED** | Repository URL (should be publicly accessible). |
| `directory` | string | OPTIONAL     | Subdirectory within the repo (for monorepos).   |

### 2.6 `integrations`

| Property | Value     |
| -------- | --------- |
| Type     | string\[] |
| Required | OPTIONAL  |

A list of third-party services or platforms the agent connects to. Used to display brand icons and connection information on the agent's detail page.

```yaml
---
integrations:
  - Jira
  - My Custom API
---
```

#### 2.6.1 Derivation

Integrations are derived from two sources: the `integrations` section of `astropods.yml` (via `provider` fields) and the `integrations` frontmatter in `AGENT.md`. The platform MUST combine and deduplicate both sources for display. Use the agent card to declare integrations that cannot be inferred from the spec.

#### 2.6.2 Matching

Matching is case-insensitive. Each integration string is resolved against the known integrations registry by `id`, `name`, or `aliases`. Strings that do not match any known integration are displayed with a generic icon and the original text as a label.

#### 2.6.3 Known Integrations Registry

The platform maintains a registry of known integrations, each with an `id`, `name`, and optional `aliases`. See [Known Integrations](/known-integrations) for the full list.

***

## 3. Body

The body is free-form GitHub-Flavored Markdown (GFM). There is no required structure, but authors SHOULD cover:

* **Overview**: What the agent does and why it exists.
* **Usage**: How to interact with the agent (APIs, protocols, chat, etc.).
* **Limitations**: Known constraints, failure modes, or scope boundaries.
* **Examples**: Sample interactions or outputs.

***

## 4. Normalization

The following normalizations are applied during parsing:

| Field               | Rule                                                                                      |
| ------------------- | ----------------------------------------------------------------------------------------- |
| `description`       | Truncated to 200 characters (rune-aware).                                                 |
| `tags`              | Lowercased, spaces converted to hyphens, non-alphanumeric/non-hyphen characters stripped. |
| `authors[].account` | Trimmed and lowercased.                                                                   |
| `capabilities[]`    | Truncated to 100 characters per entry (rune-aware).                                       |
| `integrations[]`    | Resolved against known integrations registry (see Section 2.6.2).                         |

***

## 5. Registration Flow

During `ast push`, the CLI:

1. Reads `AGENT.md` from the project root (if present).
2. Submits the raw file content as the `readme` field in the registration payload. The CLI does not parse the frontmatter.

The server:

1. Receives the raw agent card content.
2. Parses the YAML frontmatter to extract structured metadata.
3. Resolves integrations by merging spec-derived and card-declared integrations (Section 2.6.1).
4. Stores both the raw content and the parsed metadata (as JSON) for efficient reads.

### 5.1 Legacy Compatibility

Existing agents without an `AGENT.md` continue to work. For agents using the deprecated `meta.description` and `meta.tags` fields in `astropods.yml`, the server synthesizes an agent card from those fields as a fallback.

***

## 6. Client Display

The client renders the agent card on the agent detail page:

* **Frontmatter metadata** is displayed in structured UI elements (author links, capability badges, integration icons).
* **Integrations** are rendered as brand icons (known) or generic icons with labels (unknown).
* **Body** is rendered as styled Markdown.
* **Description** is displayed in sidebars, cards, and search results. Falls back to the agent name if absent.

***

## Appendix A: Example

```yaml AGENT.md
---
description: "GitHub Issue Analyzer — ingests GitHub issues into a Neo4j knowledge graph"
tags:
  - analytics
  - knowledge-graph
authors:
  - name: Jane Doe
    account: janedoe
  - name: Bob Smith
repository: "github:acme/github-issue-analyzer"
capabilities:
  - Analyzes GitHub issues and extracts patterns
  - Builds and maintains a Neo4j knowledge graph
  - Answers natural-language queries about issue history
integrations:
  - Jira
  - My Custom Webhook
---

# GitHub Issue Analyzer

This agent ingests GitHub issues into a Neo4j knowledge graph and provides
natural-language querying over the resulting data.

## How It Works

1. Connect your GitHub repository via the `GITHUB_TOKEN` input.
2. The agent polls for new issues on a configurable schedule.
3. Each issue is analyzed using an LLM to extract entities and relationships.
4. Results are stored in Neo4j and queryable via the agent's chat interface.

## Limitations

- Only processes issue bodies and comments; PR reviews are not yet supported.
- Large repositories (>10k issues) may require extended initial ingestion time.
```