# Generating Agents

> Agent definition file generation with mandatory schema validation against schemas/agent.schema.json

- Skill: `gitwalter/generating-agents` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add gitwalter/generating-agents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gitwalter/generating-agents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gitwalter (https://skillmd.com/u/gitwalter)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/gitwalter/generating-agents

---

# Agent Generation

Agent definition file generation with mandatory schema validation against schemas/agent.schema.json

Generates agent definition files that are **schema-compliant by construction**. Every generated agent MUST pass `schemas/agent.schema.json` validation before being written to disk.

## Canonical Schema Reference (schemas/agent.schema.json)

**CRITICAL**: Every agent MUST comply with this schema. Memorize these constraints:

### Required Frontmatter Fields

| Field | Type | Constraints |
|-||-|
| `name` | string | Pattern: `^[a-z0-9-]+$`, min 3 chars, must match filename without `.md` |
| `description` | string | Min 20 chars |
| `type` | const | Must be `"agent"` |
| `version` | string | Semantic version: `^\\d+\\.\\d+\\.\\d+$` (e.g. `1.0.0`) |
| `domain` | enum | **ONLY**: `ai-ml`, `development`, `testing`, `review`, `documentation`, `debugging`, `deployment`, `analysis`, `orchestration`, `trading`, `sap`, `dotnet`, `java`, `web`, `devops`, `onboarding`, `factory` |
| `skills` | array | Min 2 items, each matching `^[a-z0-9-]+(/[a-z0-9-]+)*$` |
| `knowledge` | array | Min 2 items, each matching `^[a-z0-9-]+\\.json$` (NO path prefixes like `schemas/`) |
| `tools` | array | Min 1 item (use `["none"]` if no tools) |
| `workflows` | array | Min 1 item (use `["none"]` if no workflows) |
| `blueprints` | array | Min 1 item (use `["none"]` if no blueprints) |

### Optional Fields

| Field | Type | Description |
|-||-|
| `mcp_servers` | array of strings | MCP servers this agent uses |
| `agent_team` | array of strings | Other agents this agent coordinates with |

### Domain Mapping Guide

Use this mapping when the natural domain doesn't match an allowed value:

| Natural Domain | Use Instead |
||-|
| data-science | `analysis` |
| security | `testing` |
| integration | `orchestration` |
| general | `development` (for coders), `documentation` (for writers), `deployment` (for infra) |
| meta | `factory` |

## Process

1. Review the task requirements.
2. Apply the skill's methodology.
3. Validate the output against the defined criteria.
### Step 1: Load Agent Pattern
For each requested agent:
1. Load pattern from `{directories.patterns}/agents/{agent-id}.json`
2. Parse metadata, frontmatter, and sections
3. Identify customization points

### Step 2: Validate Against Schema BEFORE Writing

**CRITICAL VALIDATION CHECKLIST** - verify each constraint:

```
[ ] name: lowercase kebab-case, >= 3 chars, matches filename
[ ] description: >= 20 characters
[ ] type: exactly "agent"
[ ] version: semantic version format (e.g. "1.0.0")
[ ] domain: is in the allowed enum list above
[ ] skills: array with >= 2 items, each lowercase kebab-case
[ ] knowledge: array with >= 2 items, each "name.json" format (no paths)
[ ] tools: array with >= 1 item (use ["none"] for no tools)
[ ] workflows: array with >= 1 item (use ["none"] for no workflows)
[ ] blueprints: array with >= 1 item (use ["none"] for no blueprints)
[ ] **New Requirement**: Run `verify_structures.py` to ensure H1, Purpose, and Important Rules sections are present.
```

### Step 3: Render Markdown

```markdown

name: {name}
description: {description}
type: agent
version: 1.0.0
domain: {domain from allowed enum}
skills: [{skill-1}, {skill-2}, ...]
knowledge: [{file-1}.json, {file-2}.json, ...]
tools: [{tool-1}, ...]
workflows: [{workflow-1} or "none"]
blueprints: [{blueprint-1} or "none"]


# {Title} Agent

## Purpose

{purpose}

## Philosophy

> "{philosophy quote}"

## When Activated

| Trigger Phrase | Context |
|||
| ... | ... |

## Skills Used

| Skill | Purpose |
|-||
| ... | ... |

## Workflow Diagram

```mermaid
graph TD
  ...
```

## Knowledge Used

| Knowledge File | Content |
|||
| ... | ... |

## Collaboration

| Agent | Interaction |
|-||
| ... | ... |

## Important Rules

1. ...
```

### Step 4: Write File
Write to target location:
- Path: `{TARGET}/{directories.agents}/{name}.md`
- Encoding: UTF-8

### Step 5: Post-Creation Sync (Factory Only)

**CRITICAL:** After creating agents in the Antigravity Agent Factory, run the repo-sync:

```powershell
{PYTHON_PATH} {directories.scripts}/validation/schema_validator.py --summary
{PYTHON_PATH} {directories.scripts}/validation/validate_readme_structure.py --update
{PYTHON_PATH} {directories.scripts}/build_knowledge_crossref.py
{PYTHON_PATH} {directories.scripts}/validation/verify_structures.py
```

## Common Schema Violations and Fixes

| Error | Cause | Fix |
|-|-|--|
| `domain: 'X' is not one of [...]` | Invalid domain value | Use mapping guide above |
| `blueprints: [] should be non-empty` | Empty array | Change to `["none"]` |
| `knowledge.N does not match pattern` | Path prefix in ref | Remove `schemas/` prefix |
| `skills: should have at least 2 items` | Too few skills | Add related skills |

## Important Rules

1. **ALWAYS validate against schema BEFORE writing** - Never create an agent without checking all required fields
2. **Use `{directories.XXX}` path variables** - NEVER hardcode directory paths
3. **Lowercase kebab-case filenames** - All files use `my-agent.md` format
4. **Knowledge refs are basename only** - Use `file.json` not `schemas/file.json`
5. **Empty arrays forbidden** - Use `["none"]` instead of `[]` for tools/workflows/blueprints
6. **Run schema_validator.py after creation** - Catch any remaining issues
7. **Update knowledge-cross-reference.json** - Run build_knowledge_crossref.py after adding agents
8. **Update README counts** - Run validate_readme_structure.py after adding agents

## References

- `schemas/agent.schema.json` - Canonical schema (source of truth)
- `{directories.knowledge}/knowledge-cross-reference.json` - Knowledge mapping
- `{directories.knowledge}/agent-taxonomy.json` - Agent classification
- `{directories.scripts}/validation/schema_validator.py` - Validation script
- `{directories.scripts}/build_knowledge_crossref.py` - Cross-reference builder

## When to Use
This skill should be used when strict adherence to the defined process is required.

## Prerequisites
- Basic understanding of the agent factory context.
- Access to the necessary tools and resources.

## Best Practices
- Always follow the established guidelines.
- Document any deviations or exceptions.
- Regularly review and update the skill documentation.