> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentsystems.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List on Index

> Add your agent to the public index for discovery

<Note>
  Publishing metadata to the agent index makes your agent **discoverable** in the AgentSystems platform. The index contains metadata only - your actual agent image can be public or private. Metadata submissions are automatically validated and merged.
</Note>

## Prerequisites

* GitHub account with commit signing enabled ([Setup Guide](https://docs.github.com/en/authentication/managing-commit-signature-verification))
* Agent deployed (see [Quickstart](/fortress/deploy-agents/quickstart))
* 5 minutes

<Note>
  **Commit Signing Required**: All commits in your PR must be signed with a verified GPG or SSH key. Unverified commits will be rejected by the auto-merge workflow. This requirement helps verify that commits are cryptographically signed and match the author identity.
</Note>

## Overview

The [agent-index repository](https://github.com/agentsystems/agent-index) is an open-source, Git-based registry for agent metadata enabling federated discovery. Instead of a centralized API:

* Developers manage their own YAML files in `developers/your-github-username/`
* Pull requests are automatically validated and merged—no manual approval needed
* Metadata is published to `https://agentsystems.github.io/agent-index/`
* The AgentSystems UI consumes this index (and can connect to multiple indexes)
* Anyone can fork the repository and run their own independent index

**Disclaimer**: Inclusion in the index does not constitute endorsement. The index provides metadata submitted by developers and does not verify agent quality, functionality, or security.

## Step 1: Fork the Repository

Go to [github.com/agentsystems/agent-index](https://github.com/agentsystems/agent-index) and click **"Fork"**.

Clone your fork:

```bash theme={null}
git clone https://github.com/your-github-username/agent-index.git
cd agent-index
```

## Step 2: Create Your Developer Profile

Create your developer folder (must match your GitHub username):

```bash theme={null}
mkdir -p developers/your-github-username
```

Copy the example profile:

```bash theme={null}
cp examples/profile.yaml developers/your-github-username/profile.yaml
```

Edit `developers/your-github-username/profile.yaml`:

```yaml theme={null}
name: Your Name or Company
developer: your-github-username  # Must match folder name
type: individual          # individual, organization, company, or enterprise
bio: Developer of AI agents for...
website: https://example.com
support_email: hello@example.com

# Optional fields
tagline: Building the future of AI agents
location: San Francisco, CA
twitter_handle: yourhandle
linkedin_url: https://linkedin.com/in/yourprofile
expertise:
  - Natural Language Processing
  - Data Analysis
  - Multi-Agent Systems
open_to_collaboration: true
```

<Accordion title="Complete Developer Profile Schema">
  **Required**:

  * `name` (string): Display name
  * `developer` (string): Developer namespace - must match folder name

  **Optional**:

  * `type` (string): "individual", "organization", "company", or "enterprise"
  * `avatar_url` (string): Profile image URL
  * `bio` (string): Short biography
  * `tagline` (string): Short tagline or slogan
  * `company` (string): Company name
  * `location` (string): Geographic location
  * `years_experience` (integer): Years in AI/ML
  * `website` (string): Your website URL
  * `support_email` (string): Support email
  * `documentation_url` (string): Docs URL
  * `twitter_handle` (string): Twitter/X handle (without @)
  * `linkedin_url` (string): LinkedIn profile
  * `discord_username` (string): Discord username
  * `expertise` (array): Areas of expertise
  * `featured_work` (array): URLs to featured projects
  * `open_to_collaboration` (boolean): Open to collaboration
  * `sponsor_url` (string): GitHub Sponsors or similar
</Accordion>

## Step 3: Add Your Agent Metadata

Create the agents folder:

```bash theme={null}
mkdir -p developers/your-github-username/agents
```

Copy the example agent:

```bash theme={null}
# Create your agent directory
mkdir -p developers/your-github-username/agents/your-agent

# Copy example files
cp examples/agents/demo-agent/agent.yaml developers/your-github-username/agents/your-agent/
cp examples/agents/demo-agent/versions.yaml developers/your-github-username/agents/your-agent/
cp examples/agents/demo-agent/0.1.0.yaml developers/your-github-username/agents/your-agent/
```

The directory structure will be:

```
developers/your-github-username/agents/your-agent/
  agent.yaml      # Agent identity (who/what it is)
  versions.yaml   # Version management (which versions)
  0.1.0.yaml     # Version specification (how it behaves)
```

Edit the three YAML files:

**`agent.yaml`** - Set your agent identity:

* `developer` - Must match your GitHub username
* `name` - Must match directory name
* `description`, `container_image`, `tags`, `capabilities` - See examples folder for all fields

**`versions.yaml`** - Set version management:

* `latest_version: "0.1.0"`
* `listed_versions:` with `- "0.1.0"` (use dash notation)

**`0.1.0.yaml`** - Set version-specific attributes:

* `version` - Must match filename ("0.1.0")
* `model_dependencies:` with `- gemma3:1b` (use dash notation)
* `readiness_level`, `input_schema`, `facets` - See examples folder for all fields

<Note>
  See `examples/agents/demo-agent/` in the repository for complete examples of all three files with all available fields and documentation.
</Note>

<Accordion title="Complete Agent Metadata Schema">
  **Required in agent.yaml (Agent Identity)**:

  * `name` (string): Agent name (lowercase, alphanumeric, hyphens)
  * `developer` (string): Your GitHub username (must match folder name)
  * `description` (string): Short description
  * `container_image` (string): Container image reference without tag (e.g., docker.io/user/agent)

  **Optional in agent.yaml (Agent Identity)**:

  * `source_repository_url` (string): Source code URL
  * `primary_function` (string): Primary function category
  * `tags` (array): Searchable tags
  * `capabilities` (array): High-level capability descriptions

  **Required in versions.yaml (Version Management)**:

  * `latest_version` (string): Latest version (must match an existing {version}.yaml file)
  * `listed_versions` (array): Versions visible in discovery (each must match an existing {version}.yaml file)

  **Required in {version}.yaml files (Version Specification)**:

  * `version` (string): Semantic version (e.g., "0.1.0" or "1.0.0-beta.1"), used as container image tag
  * `model_dependencies` (array): Required AI models (at least one)

  **Optional in {version}.yaml files**:

  * `readiness_level` (string): "experimental", "beta", "production", or "deprecated"
  * `container_image_access` (string): "public" or "private"
  * `source_repository_access` (string): "public" or "private"
  * `required_egress` (array): Required network egress URLs
  * `required_integrations` (array): Required external integrations
  * `input_types` (array): Supported input data types
  * `output_types` (array): Supported output data types
  * `input_schema` (object): Input parameter schema
  * `facets` (object): Behavioral characteristics and categorization
    * `context` (string): Operating context (personal, professional, general)
    * `autonomy` (string): Autonomy level (Assist, Co-pilot, Auto-pilot)
    * `latency` (string): Latency profile (real-time, interactive, batch)
    * `cost_profile` (string): Cost model (free, $/task, $/month)
    * `modalities` (array): Supported modalities (text, image, audio, video)
    * `domains` (array): Application domains
    * `model_tooling` (array): Model frameworks (LLM, RAG, fine-tuned, embeddings)
    * `industries` (array): Target industries
    * `integrations` (array): Supported integrations
  * `release_notes` (string): Markdown-formatted release notes

  See the schemas for complete details:

  * [agent-identity.schema.json](https://github.com/agentsystems/agent-index/blob/main/schema/agent-identity.schema.json) - agent.yaml
  * [versions.schema.json](https://github.com/agentsystems/agent-index/blob/main/schema/versions.schema.json) - versions.yaml
  * [agent-version.schema.json](https://github.com/agentsystems/agent-index/blob/main/schema/agent-version.schema.json) - {version}.yaml
</Accordion>

## Step 4: Validate Locally (Optional)

<Note>
  Validation runs automatically on your PR, but testing locally helps catch issues early.
</Note>

```bash theme={null}
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install pyyaml jsonschema
python scripts/validate.py all
```

Should output:

```
✅ All validations passed!
```

## Step 5: Submit Pull Request

Commit and push:

```bash theme={null}
git add developers/your-github-username/
git commit -m "Add your-github-username profile and your-agent"
git push origin main
```

Go to your fork on GitHub and click **"Contribute"** → **"Open pull request"**.

## What Happens Next

Your PR triggers automated workflows:

1. **Policy Gate**: Validates folder ownership (checks your GitHub username matches folder name)
2. **YAML Validation**: Checks syntax and schema compliance
3. **Auto-Merge**: If all checks pass, PR is automatically approved and merged
4. **Build & Deploy**: Index is rebuilt and published to GitHub Pages

Your agent should appear at `https://agentsystems.github.io/agent-index/` shortly after the build completes.

## Publishing New Versions

To publish a new version of your agent:

1. Create a new version file in your agent directory:

```bash theme={null}
# Copy your current version as a template
cp developers/your-github-username/agents/your-agent/0.1.0.yaml \
   developers/your-github-username/agents/your-agent/0.2.0.yaml
```

2. Edit the new version file:
   * Update `version: "0.2.0"` (must match filename)
   * Modify any behavioral changes (model, facets, schema, etc.)
   * Add release notes

3. Update versions.yaml:
   * Change `latest_version: "0.1.0"` to `latest_version: "0.2.0"`
   * Add `"0.2.0"` to `listed_versions` array
   * Optionally remove old versions from `listed_versions` to hide them

```yaml theme={null}
latest_version: "0.2.0"

listed_versions:
  - "0.1.0"    # Keep if users might want old version
  - "0.2.0"    # New version
```

4. Commit and push:

```bash theme={null}
git add developers/your-github-username/agents/your-agent/
git commit -m "Release 0.2.0 of your-agent"
git push origin main
```

**Git diff clarity**: Adding 0.2.0 shows as a clean new file in your PR, making reviews simple and clear.

## Updating Agent Identity

To update your agent's identity (description, tags, capabilities):

1. Edit `developers/your-github-username/agents/your-agent/agent.yaml`
2. Commit and push to your fork
3. Open a new pull request
4. Auto-merge handles the rest

Note: Identity fields affect all versions. Version-specific changes go in the {version}.yaml files.

## Security Model

The index uses **fork-based ownership**:

* ✅ Only you can modify `developers/your-github-username/` (checked via fork ownership)
* ✅ PRs touching only your folder auto-merge
* ✅ PRs touching core files require maintainer approval
* ✅ Multiple validation layers protect the index

## Troubleshooting

### PR not auto-merging

**Check**:

1. All files are in `developers/your-github-username/` (folder name must match your GitHub username exactly)
2. YAML validation passes (check the workflow logs)
3. You're submitting from a fork (not a branch in the main repo)
4. All commits are signed and verified (see below)

### YAML validation fails

Common issues:

* **Syntax error**: Check YAML indentation (use spaces, not tabs)
* **Missing required field**: Ensure `name`, `developer` (in profile.yaml), `version`, `description`, and `model_dependencies` are present
* **Invalid value**: Check enum fields like `readiness_level`

Run `python scripts/validate.py all` locally to see detailed error messages.

### Folder ownership check fails

**Error**: "Developer folder (your-name) does not match PR head repository owner (different-name)"

**Solution**: Your folder name must exactly match your GitHub username. If your fork is under a different account, the folder name must match that account.

### Unverified commits

**Error**: "PR contains unverified commits. All commits must be signed with a verified GPG or SSH key."

**Solution**:

1. Verify your git config matches your signing key:
   ```bash theme={null}
   git config user.name    # Should match your GitHub username
   git config user.email   # Should match your signing key email
   ```
2. Set up commit signing: [GitHub Docs](https://docs.github.com/en/authentication/managing-commit-signature-verification)
3. Configure auto-signing:
   ```bash theme={null}
   git config commit.gpgsign true   # For GPG
   # or
   git config gpg.format ssh        # For SSH keys
   git config user.signingkey ~/.ssh/id_ed25519.pub
   ```
4. If commits are already pushed, you'll need to amend and force-push (or create a new PR with signed commits)

## Next Steps

* **Discover agents**: Browse the index at [agentsystems.github.io/agent-index](https://agentsystems.github.io/agent-index/)
* **Deploy private agents**: See [Deploying Private Agents](/fortress/deploy-agents/private-agents)
* **Review schemas**: Full schemas at [github.com/agentsystems/agent-index/tree/main/schema](https://github.com/agentsystems/agent-index/tree/main/schema)