Skills

Skills

Skills let you install reusable agent instructions into a task workspace before the runtime starts. AgentContainer uses the skills CLI inside the task container, so the value you configure is the same argument you would pass to skills add.

Use skills when an agent should consistently know a workflow, review style, tool convention, framework pattern, or internal process without copying those instructions into every task request.

Skill Shape

Skill entries are objects with a required skill string and an optional sshKeyId for private Git sources.

{
  "skill": "mattpocock/skills/design-an-interface"
}

The skill field is stored as provided and passed to skills add. AgentContainer does not split it into owner/repo/path fields.

Local filesystem paths such as ./skills, ../skills, /skills, and ~/skills are not supported in the hosted API because task workspaces run in remote containers.

Agent Skills

Add skills to an agent when every task created from that agent should receive the same installed instructions. Agent skills are part of the agent version. Updating them creates a new version, while existing tasks continue using the version they were created with.

curl -X POST https://agentcontainer.co/api/v1/agents \
  -H "Authorization: Bearer ac_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Interface Designer",
    "runtime": {
      "containerImage": "ghcr.io/jonaslsaa/base-ac-claude:latest",
      "agentRuntime": "pi"
    },
    "basePrompt": "Follow /workspace/task/HARNESS.md and complete the task.",
    "defaults": {
      "provider": "anthropic",
      "model": "haiku",
      "internetAccess": true,
      "maxRuntimeSeconds": 1800,
      "outputPolicy": { "mode": "any" },
      "runtimeRegion": "any"
    },
    "skills": [
      {
        "skill": "mattpocock/skills/design-an-interface"
      }
    ]
  }'

On PATCH /api/v1/agents/{agentId}, omitting skills keeps the current version's skill list. Sending skills replaces the list for the new agent version.

Task Skills

Tasks can also include additional skills. These are installed after the agent version's skills, so they are useful for one-off task-specific behavior.

curl -X POST https://agentcontainer.co/api/v1/agents/agt_abc123/tasks \
  -H "Authorization: Bearer ac_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Design a settings page for a team billing workflow.",
    "skills": [
      {
        "skill": "mattpocock/skills/design-an-interface"
      }
    ]
  }'

Task skills are API-first. The dashboard shows and edits agent-level skills on the agent page; task-level skills can be sent through the REST API.

Private Skills

For private Git sources, create an SSH key in AgentContainer, grant it read access to the private skills repository, and pass the key ID on the skill entry.

{
  "skills": [
    {
      "skill": "git@github.com:my-org/private-skills.git#abc123",
      "sshKeyId": "ssh_9fd5d..."
    }
  ]
}

When sshKeyId is set, AgentContainer makes that key available only while installing that skill. The key must belong to the same account that owns the custom agent or task. Standard platform agents can use platform-managed keys for platform-managed skills.

Runtime Behavior

At task startup, the daemon prepares files and repositories, installs configured skills, then starts Pi. If a skill fails to install, the task fails before the runtime begins. Install stdout and stderr are written to daemon logs to make failures debuggable.

The effective install order is:

1. Agent version skills, in configured order.
2. Task skills, in configured order.

The task object returned by the API includes the task-level skills array. Agent responses include skills under currentVersion.skills.

Next Steps

• Tasks & Output covers task dispatch, input files, output policies, and results.
• API Reference shows the exact request and response schemas for agents and tasks.
• Core Concepts explains how agents, versions, and tasks fit together.