gh-epieczko-betty/agents/meta.agent/README.md

meta.agent - Agent Creator

The meta-agent that creates other agents through skill composition.

Overview

meta.agent transforms natural language descriptions into complete, functional agents with proper skill composition, artifact metadata, and documentation.

What it produces:

• Complete agent.yaml with recommended skills
• Auto-generated README.md documentation
• Proper artifact metadata (produces/consumes)
• Inferred permissions from skills

Quick Start

1. Create an Agent Description

Create a Markdown file describing your agent:

# Name: api.architect

# Purpose:
An agent that designs comprehensive REST APIs and validates them
against best practices.

# Inputs:
- API requirements

# Outputs:
- openapi-spec
- validation-report
- api-models

# Examples:
- Design a RESTful API for an e-commerce platform
- Create an API for a task management system

2. Run meta.agent

python3 agents/meta.agent/meta_agent.py examples/api_architect_description.md

3. Output

✨ Agent 'api.architect' created successfully!

📄 Agent definition: agents/api.architect/agent.yaml
📖 Documentation: agents/api.architect/README.md

🔧 Skills: api.define, api.validate, workflow.validate

Usage

Basic Creation

# Create agent from Markdown description
python3 agents/meta.agent/meta_agent.py path/to/agent_description.md

# Create agent from JSON description
python3 agents/meta.agent/meta_agent.py path/to/agent_description.json

# Specify output directory
python3 agents/meta.agent/meta_agent.py description.md -o agents/my-agent

# Skip validation
python3 agents/meta.agent/meta_agent.py description.md --no-validate

Description Format

Markdown Format:

# Name: agent-name

# Purpose:
Detailed description of what the agent does...

# Inputs:
- artifact-type-1
- artifact-type-2

# Outputs:
- artifact-type-3
- artifact-type-4

# Constraints:
(Optional) Any constraints or requirements...

# Examples:
- Example use case 1
- Example use case 2

JSON Format:

{
  "name": "agent-name",
  "purpose": "Detailed description...",
  "inputs": ["artifact-type-1", "artifact-type-2"],
  "outputs": ["artifact-type-3", "artifact-type-4"],
  "examples": ["Example 1", "Example 2"]
}

What meta.agent Creates

1. agent.yaml

Complete agent definition with:

• Recommended skills - Uses agent.compose to find compatible skills
• Artifact metadata - Proper produces/consumes declarations
• Permissions - Inferred from selected skills
• Description - Professional formatting

Example output:

name: api.architect
description: Designs and validates REST APIs against best practices
skills_available:
  - api.define
  - api.validate
permissions:
  - filesystem:read
  - filesystem:write
artifact_metadata:
  consumes:
    - type: api-requirements
  produces:
    - type: openapi-spec
      schema: schemas/openapi-spec.json
    - type: validation-report
      schema: schemas/validation-report.json

2. README.md

Auto-generated documentation with:

• Agent purpose and capabilities
• Skills used with rationale
• Artifact flow (inputs/outputs)
• Example use cases
• Usage instructions
• "Created by meta.agent" attribution

How It Works

1. Parse Description - Reads Markdown or JSON
2. Find Skills - Uses agent.compose to recommend compatible skills
3. Generate Metadata - Uses artifact.define for artifact contracts
4. Infer Permissions - Analyzes required skills
5. Create Files - Generates agent.yaml and README.md
6. Validate - Ensures proper structure and compatibility

Integration with Other Meta-Agents

With meta.compatibility

After creating an agent, use meta.compatibility to analyze it:

# Create agent
python3 agents/meta.agent/meta_agent.py description.md

# Analyze compatibility
python3 agents/meta.compatibility/meta_compatibility.py analyze api.architect

With meta.suggest

Get suggestions after creating an agent:

python3 agents/meta.suggest/meta_suggest.py \
  --context meta.agent \
  --artifacts agents/api.architect/agent.yaml

Common Workflows

Workflow 1: Create and Analyze

# Step 1: Create agent
python3 agents/meta.agent/meta_agent.py examples/my_agent.md

# Step 2: Analyze compatibility
python3 agents/meta.compatibility/meta_compatibility.py find-compatible my-agent

# Step 3: Test the agent
# (Manual testing or agent.run)

Workflow 2: Create Multiple Agents

# Create several agents
for desc in examples/*_agent_description.md; do
    python3 agents/meta.agent/meta_agent.py "$desc"
done

# Analyze the ecosystem
python3 agents/meta.compatibility/meta_compatibility.py list-all

Artifact Types

Consumes

• agent-description - Natural language agent requirements
  • Format: Markdown or JSON
  • Pattern: **/agent_description.md

Produces

• agent-definition - Complete agent.yaml

  • Format: YAML
  • Pattern: agents/*/agent.yaml
  • Schema: schemas/agent-definition.json

• agent-documentation - Auto-generated README

  • Format: Markdown
  • Pattern: agents/*/README.md

Tips & Best Practices

Writing Good Descriptions

✅ Good:

• Clear, specific purpose
• Well-defined inputs and outputs
• Concrete examples
• Specific artifact types

❌ Avoid:

• Vague purpose ("does stuff")
• Generic inputs ("data")
• No examples
• Unclear artifact types

Choosing Artifact Types

Use existing artifact types when possible:

• openapi-spec for API specifications
• validation-report for validation results
• workflow-definition for workflows

If you need a new type, create it with meta.artifact first.

Skill Selection

meta.agent uses keyword matching to find skills:

• "api" → finds api.define, api.validate
• "validate" → finds validation skills
• "agent" → finds agent.compose, meta.agent

Be descriptive in your purpose statement to get better skill recommendations.

Troubleshooting

Agent name conflicts

Error: Agent 'api.architect' already exists

Solution: Choose a different name or remove the existing agent directory.

No skills recommended

Warning: No skills found for agent purpose

Solutions:

• Make purpose more specific
• Mention artifact types explicitly
• Check if relevant skills exist in registry

Missing artifact types

Warning: Artifact type 'my-artifact' not in known registry

Solution: Create the artifact type with meta.artifact first:

python3 agents/meta.artifact/meta_artifact.py create artifact_description.md

Examples

See examples/ directory for sample agent descriptions:

• api_architect_description.md - API design and validation agent
• (Add more as you create them)

Architecture

meta.agent is part of the meta-agent ecosystem:

meta.agent
    ├─ Uses: agent.compose (find skills)
    ├─ Uses: artifact.define (generate metadata)
    ├─ Produces: agent.yaml + README.md
    └─ Works with: meta.compatibility, meta.suggest

Related Documentation

• META_AGENTS.md - Complete meta-agent architecture
• ARTIFACT_STANDARDS.md - Artifact system
• agent-description schema - JSON schema

Created By

Part of the Betty Framework meta-agent ecosystem.