Agentform Skill

Create declarative AI agent configurations using Agentform's .af syntax.

File Structure

Number files for alphabetical processing order:

code

project/
├── 00-project.af      # Project metadata
├── 01-variables.af    # API keys, secrets
├── 02-providers.af    # LLM providers + models
├── 03-servers.af      # MCP servers (optional)
├── 04-capabilities.af # Server capabilities (optional)
├── 05-policies.af     # Cost/timeout limits
├── 06-agents.af       # Agent definitions
├── 07-workflows.af    # Workflow definitions
└── input.yaml         # Example inputs

Block Types Quick Reference

agentform (required)

hcl

agentform {
  version = "0.1"
  project = "my-project"
}

variable

hcl

variable "api_key" {
  type        = string
  description = "API key"
  sensitive   = true
}

Reference: var.api_key

provider

Format: provider "type.vendor" "name" { ... }

hcl

provider "llm.anthropic" "default" {
  api_key = var.anthropic_api_key
}

provider "llm.openai" "default" {
  api_key = var.openai_api_key
  default_params {
    temperature = 0.7
    max_tokens  = 2000
  }
}

Reference: provider.llm.anthropic.default

model

hcl

model "claude_sonnet" {
  provider = provider.llm.anthropic.default
  id       = "claude-sonnet-4-5-20250929"
}

model "gpt4o" {
  provider = provider.llm.openai.default
  id       = "gpt-4o"
  params {
    temperature = 0.5
  }
}

Reference: model.claude_sonnet

Model IDs

Do not hardcode model IDs. Always fetch current model names from the provider's API documentation:

•Anthropic: https://docs.anthropic.com/en/docs/about-claude/models
•OpenAI: https://platform.openai.com/docs/models

Model IDs change with new releases. Example workflow:

•Check provider docs for current model ID
•Use exact ID string in your config
•Test with agentform validate

server (MCP integration)

hcl

server "github" {
  type      = "mcp"
  transport = "stdio"
  command   = ["npx", "-y", "@modelcontextprotocol/server-github"]

  auth {
    token = var.github_token
  }
}

Reference: server.github

capability

hcl

capability "get_pr" {
  server      = server.github
  method      = "get_pull_request"
  side_effect = "read"
}

capability "create_review" {
  server            = server.github
  method            = "create_pull_request_review"
  side_effect       = "write"
  requires_approval = true
}

Reference: capability.get_pr

policy

Each budget needs its own budgets {} block:

hcl

policy "review_policy" {
  budgets { max_cost_usd_per_run = 0.50 }
  budgets { max_capability_calls = 15 }
  budgets { timeout_seconds = 300 }
}

Reference: policy.review_policy

agent

hcl

agent "reviewer" {
  model           = model.claude_sonnet
  fallback_models = [model.gpt4o]
  policy          = policy.review_policy
  allow           = [capability.get_pr, capability.create_review]

  instructions = <<EOF
You are a code reviewer.
Focus on security and performance.
EOF
}

Reference: agent.reviewer

Heredoc Syntax (CRITICAL)

Multi-line strings use heredoc. The closing marker MUST be at column 0 (no indentation):

hcl

instructions = <<EOF
Line 1
Line 2
EOF

WRONG (will fail validation):

hcl

  instructions = <<EOF
    Line 1
  EOF

The EOF has leading spaces - this breaks parsing.

Expression Syntax

References

Type	Syntax	Example
Variable	`var.name`	`var.api_key`
Provider	`provider.type.name`	`provider.llm.openai.default`
Model	`model.name`	`model.gpt4o`
Agent	`agent.name`	`agent.reviewer`
Capability	`capability.name`	`capability.get_pr`
Server	`server.name`	`server.github`
Policy	`policy.name`	`policy.default`
Step	`step.name`	`step.fetch_pr`

State References (in workflows)

Context	Syntax
Workflow input	`input.field`
Step output	`state.step_output`
Nested field	`state.review.response`
Result in step	`result.text`, `result.data`

Operators

hcl

// Comparison
condition = state.value == "expected"
condition = state.count > 10

// Logical
condition = state.a && state.b
condition = !state.flag

// Ternary
value = state.premium ? "gold" : "standard"

NO FUNCTION CALLS - contains(), length() etc. are NOT supported.

Workflow Reference

See references/workflows.md for complete workflow patterns.

CLI Commands

bash

# Validate
agentform validate --var api_key=$API_KEY

# Run workflow
agentform run workflow_name \
  --var api_key=$API_KEY \
  --input '{"field": "value"}'

# Verbose
agentform run workflow_name --verbose

Troubleshooting

Error	Cause	Fix
Unexpected token `<`	Heredoc `EOF` indented	Move `EOF` to column 0
Unexpected token `(`	Function call used	Use comparison operators
Variable has no value	Missing runtime var	Add `--var name=value`
MCP server not found	Wrong package name	Check npm package exists

Common MCP Servers

•@modelcontextprotocol/server-github
•@modelcontextprotocol/server-filesystem

Templates

Copy these pre-validated templates as starting points:

Simple Agent (no MCP)

bash

cp -r ~/.claude/skills/agentform/assets/templates/simple-agent ./my-agent

MCP Agent (GitHub PR reviewer)

bash

cp -r ~/.claude/skills/agentform/assets/templates/mcp-agent ./my-pr-reviewer