Agent Skills

Agent Skills are versioned procedures that help an Agent complete a task. Capture Trajectories first. Zep compiles eligible Trajectories into Skills, which gives each Skill a traceable source.

Capture first

Create a Trajectory with objective and task_family:

{
  "objective": "Resolve the customer billing question",
  "task_family": "billing.support"
}

Append events with the smallest request:

{
  "event_type": "tool_call",
  "content": "The Agent checked the billing system."
}

Close with an outcome and a verifier. The first close registers the full verifier object:

{
  "outcome": "succeeded",
  "verification": "tool",
  "verifier": {
    "verifier_id": "billing-check-v1",
    "class": "billing_system",
    "outcome": "succeeded",
    "assertion_id": "assertion-123",
    "evidence_reference": "ticket-456"
  }
}

Later close operations can use "verifier_id": "billing-check-v1" without repeating the verifier object. The public verification values are none, agent, tool, customer, and external.

Search Skills

Search uses the task query and can restrict results to a task family:

{
  "query": "reservation cancellation",
  "task_family": "tool.airline"
}

The response includes search_id and items[].markdown by default. Set include_markdown to false when you need metadata only:

{
  "query": "reservation cancellation",
  "include_markdown": false
}

Report use and outcome

Send the signed search_id with the Skill use. The server resolves the Skill version and rank from the signed search result. You can include the outcome in the same request:

{
  "search_id": "signed-search-reference",
  "trajectory_uuid": "00000000-0000-0000-0000-000000000000",
  "usage": "used",
  "outcome": {
    "outcome": "succeeded",
    "verification": "tool"
  }
}

The signed reference binds the Agent, principal, query, request identity, and ordered Skill hits. It expires after one hour. A missing, expired, tampered, or mismatched reference returns HTTP 409.

Use POST /api/v4/agents/{agent_uuid}/skills/{skill_uuid}/uses/{use_uuid}/outcome to add an outcome after the use. The outcome request uses outcome, verification, and optional assertion_uuid.

Compilation and approval

Zep compiles eligible Trajectories into a candidate Skill. The default memory_settings.approval value is manual, so a developer approves the candidate. Use approval: auto when the configured admission policy allows automatic approval. Use GET /api/v4/agents/{agent_uuid}/learning?task_family=tool.airline to inspect the learning state. The response lists the evaluations that the admission policy requires for each candidate in this task family.

Seed or correct a Skill

Use direct authoring when you need to seed a Skill or correct compiled content. The request uses the public SkillDefinition:

{
  "definition": {
    "name": "Cancel a reservation",
    "description": "Cancel a reservation after policy checks.",
    "task_family": "tool.airline",
    "use_when": ["The customer requests cancellation."],
    "procedure": [
      {"instruction": "Verify the reservation and cancellation policy."}
    ]
  }
}

The required fields are name, description, task_family, use_when, and procedure. Optional fields include do_not_use_when, preconditions, outputs, done_when, stop_when, failures, tools, environments, aliases, package_name, kind, related_skills, agent_versions, and sections.

Skill reads return definition, markdown, self_contained, searchable, unavailable_reason, and agent_versions. Add include=contract to request the internal SkillContractV1 projection.