Skip to main content
Packs are defined using the paperclip.ai/v1 AgentPack schema — a YAML file that describes a collection of agents, pipelines, and settings.

​
Minimal example

apiVersion: paperclip.ai/v1
kind: AgentPack
metadata:
  name: my-pack
  version: "1.0.0"
  description: "What this pack does."

spec:
  agents:
    - ref: clawhq://my-agent
      role: primary
      config:
        model: claude-sonnet-4-6
        tools: [web_search, doc_writer]
        instructions: |
          You are a helpful agent.

  pipelines:
    - name: my-pipeline
      trigger: command "run"
      steps:
        - agent: my-agent
          action: "Do the thing"

​
metadata fields

FieldRequiredDescription
name✓Unique identifier (kebab-case)
namespaceGrouping namespace
version✓Semver string
description✓One-line description
tagsArray of category tags

​
spec.agents fields

FieldRequiredDescription
ref✓Agent reference — clawhq://name or relative path
role✓Role in the pack. Use primary / support for general packs. For multi-agent coordination packs, use worker, observer, or operator — see Agent Teams.
permissionsFilesystem permission overrides. Only meaningful for observer and operator roles.
permissions.readGlob list of paths the agent may read. ["*"] = all worktrees.
permissions.writeGlob list of paths the agent may write. [] = read-only (correct for observers).
permissions.execAllowlist of shell commands the agent may invoke (e.g. ["git log", "git diff"]).
priorityExecution order (lower = higher priority)
config.modelModel override for this agent
config.toolsTool list
config.temperature0.0–1.0
config.instructionsSystem prompt

​
spec.pipelines fields

FieldDescription
namePipeline identifier
triggercron "expr", command "name", or event "name"
steps[].agentAgent name to invoke
steps[].actionInstruction passed to the agent
steps[].hitltrue to require human approval before proceeding
steps[].deliver_toChannel or user to send output to

​
spec.settings.hitl

settings:
  hitl:
    enabled: true
    human_handles:
      - "Final approval"
    ai_handles:
      - "Research and drafting"