Make your agent discoverable

When you publish an agent to the registry, other users see it on browse pages, search results, and detail pages. An agent card (AGENT.md) controls what they see — a description, tags for filtering, author attribution, capability badges, and integration icons.

Create an AGENT.md file at the root of your project (next to astropods.yml). It’s published automatically when you run ast push.

Quick example

1
---
2
description: "GitHub Issue Analyzer — ingests GitHub issues into a Neo4j knowledge graph"
3
tags:
4
  - analytics
5
  - knowledge-graph
6
authors:
7
  - name: Jane Doe
8
    account: janedoe
9
  - name: Bob Smith
10
capabilities:
11
  - Analyzes GitHub issues and extracts patterns
12
  - Builds and maintains a Neo4j knowledge graph
13
  - Answers natural-language queries about issue history
14
integrations:
15
  - Jira
16
  - My Custom Webhook
17
---
18
19
# GitHub Issue Analyzer
20
21
This agent ingests GitHub issues into a Neo4j knowledge graph and provides
22
natural-language querying over the resulting data.
23
24
## How It Works
25
26
1. Connect your GitHub repository via the `GITHUB_TOKEN` input.
27
2. The agent polls for new issues on a configurable schedule.
28
3. Each issue is analyzed using an LLM to extract entities and relationships.
29
4. Results are stored in Neo4j and queryable via the agent's chat interface.
30
31
## Limitations
32
33
- Only processes issue bodies and comments; PR reviews are not yet supported.
34
- Large repositories (>10k issues) may require extended initial ingestion time.

What’s in an agent card

An agent card has two parts:

1. Frontmatter — A YAML block between --- delimiters at the top of the file. Powers structured UI elements like tags, author links, and integration icons.
2. Body — Free-form Markdown after the frontmatter. Rendered as the main content on your agent’s detail page.

Both parts are optional — even a file with just a description in the frontmatter improves discoverability. For the full format specification, see the Agent Card Spec.

Frontmatter fields

All fields are optional.

description

The most important field for discoverability. This short summary appears on cards, search results, and the detail page sidebar. Keep it under 200 characters.

1
---
2
description: "Slack bot that summarizes daily standups into action items"
3
---

If no description is provided, the agent name is used as a fallback.

tags

Category labels that help users find your agent when browsing or filtering. Each tag must be lowercase, using only letters, numbers, and hyphens. Maximum 10 tags. See normalization rules for how tags are processed.

1
---
2
tags:
3
  - devops
4
  - monitoring
5
  - slack
6
---

authors

A list of people or organizations who built the agent. Each entry requires a name and optionally an account that links to a platform profile.

1
---
2
authors:
3
  - name: Alice Chen
4
    account: alicechen
5
  - name: Acme Corp
6
    account: acme
7
  - name: External Contributor
8
---

capabilities

Short verb phrases describing what the agent can do. These appear as badges on the detail page and help users understand the agent’s functionality at a glance. Keep each under 100 characters.

1
---
2
capabilities:
3
  - Monitors pull requests for security vulnerabilities
4
  - Generates weekly summary reports
5
  - Responds to Slack commands in real time
6
---

integrations

Third-party services your agent connects to. Known integrations are displayed with brand icons; unknown ones show a generic icon with the name as a label.

1
---
2
integrations:
3
  - Slack
4
  - Jira
5
  - My Custom API
6
---

Matching is case-insensitive — slack, Slack, and SLACK all resolve the same way.

Integrations declared in your astropods.yml (via the integrations section with a provider field) are automatically derived and displayed on your agent’s detail page. Use the agent card to declare additional integrations that aren’t in the spec — for example, services your agent calls directly using user-supplied credentials.

Each integration string is matched against a list of known integrations (Slack, GitHub, Jira, Notion, Linear, Google Drive, Discord, Microsoft Teams, and many more). Known integrations are displayed with brand icons. Any string that doesn’t match a known integration is displayed with a generic icon and the original text as a label.

For the full list, see Known Integrations.

Body

The Markdown body below the frontmatter is rendered as the main content on your agent’s detail page. There’s no required structure, but consider covering:

• Overview — What the agent does and why it exists.
• Usage — How to interact with the agent (APIs, chat, scheduled tasks, etc.).
• Limitations — Known constraints or scope boundaries.
• Examples — Sample interactions or outputs.

A well-written body helps users evaluate whether your agent fits their needs before they deploy it.

Publishing your agent card

Your agent card is published automatically with ast push — no extra flags needed. The CLI reads AGENT.md from your project root and includes it in the registration payload.

$
ast push

If you update your AGENT.md, push again and the changes appear immediately on your agent’s detail page.

Migration from meta fields

If your astropods.yml uses the deprecated meta.description or meta.tags fields, move them to your agent card:

Before (astropods.yml):

1
spec: package/v1
2
name: my-agent
3
meta:
4
  description: "My agent description"
5
  tags:
6
    - analytics
7
    - slack
8
  visibility: public

After (AGENT.md + updated astropods.yml):

1
---
2
description: "My agent description"
3
tags:
4
  - analytics
5
  - slack
6
---

1
spec: package/v1
2
name: my-agent
3
meta:
4
  visibility: public

Existing agents without an AGENT.md continue to work — the meta.description and meta.tags fields are still read as a fallback. This may change in the future. See the Agent Card Spec for full details on field behavior and normalization.