agentx
← Back to docs

Creating Agents

Learn how to build, test, and publish your own AI agents for the agentx ecosystem.

Scaffold a New Agent

Use the init command to create a new agent:

agentx init

This will prompt you for:

  • Agent name
  • Description
  • Category
  • MCP servers (optional)
  • License

It creates the following structure:

my-agent/
  agent.yaml          # Agent manifest
  system-prompt.md    # System prompt for Claude
  README.md           # Documentation
  LICENSE             # License file

The Agent Manifest

Every agent needs an agent.yaml file. Here's a minimal example:

name: my-agent
version: 1.0.0
description: A helpful AI assistant
author: "@yourusername"

See the [agent.yaml reference](/docs/agent-yaml-reference) for all available fields.

System Prompt

The system-prompt.md file defines the agent's personality and behavior. It's passed to Claude as the system prompt.

You can use template variables in the system prompt:

You are {{config.name}}, a helpful assistant.
The user prefers {{config.language}} language.

Config variables are defined in agent.yaml under the config section.

MCP Servers

Agents can declare MCP (Model Context Protocol) servers that provide tools and resources:

mcp_servers:
  gmail:
    command: npx
    args: ["-y", "@anthropic/mcp-server-gmail"]
    env:
      GMAIL_TOKEN: "${secrets.GMAIL_TOKEN}"

Secret references (${secrets.KEY}) are resolved from the encrypted secret store at runtime.

Secrets

Declare required secrets in agent.yaml:

secrets:
  - name: GMAIL_TOKEN
    description: Gmail API OAuth token
    required: true
  - name: BACKUP_EMAIL
    description: Backup email address
    required: false

Users configure secrets with agentx configure <agent>.

Permissions

Declare what permissions your agent needs:

permissions:
  filesystem: true
  network: true
  execute_commands: false

This helps users understand the agent's capabilities before installing.

Scheduling

Agents can declare cron-based schedules that run automatically via a background daemon. Add a schedule block to your agent.yaml:

schedule:
  - name: "Daily standup"
    cron: "0 9 * * 1-5"
    prompt: "Post the daily standup summary to #engineering"
  - name: "Weekly report"
    cron: "0 17 * * 5"
    prompt: "Generate and post the weekly activity summary"

Each entry requires:

  • cron — A standard 5-field cron expression (minute hour day-of-month month day-of-week)
  • prompt — The prompt sent to the agent when the schedule fires (max 2000 chars)
  • name (optional) — A human-readable label shown in schedule list

Limits: maximum 10 schedule entries per agent.

Users activate schedules with agentx schedule start <agent>. The daemon handles retries on failure (up to 2 retries with backoff) and rotates logs automatically.

Validate Your Agent

Run validation to check your manifest:

agentx validate

Run the test command for a more thorough check:

agentx test

Publish to the Registry

First, authenticate with GitHub:

agentx login

Then publish your agent:

agentx publish

Your agent will be available at @yourusername/agent-name.

Updating Your Agent

Bump the version in agent.yaml, then publish again:

agentx publish

Each version is immutable — you cannot overwrite an existing version.

Best Practices

  • Write a clear, focused system prompt
  • Declare all required secrets and permissions
  • Include usage examples in your README
  • Use semantic versioning
  • Test your agent locally before publishing
  • Keep your agent focused on a single task or domain
  • Add a schedule block for agents that benefit from automated runs