Skip to navigation
Agent Skills

Write a Skill manually

Add a procedure that your team already has, or correct a compiled Skill

The main Agent Skills workflow is to capture task runs and let Zep compile the Skills, as the Agent Skills quickstart shows. Manual Skills are a secondary feature.

You can write a Skill manually. Use this to start a task family with a procedure that your team already has, before your agent has verified runs. You can also use it to correct a compiled Skill. A manual Skill has the maturity authored, and it does not cite captured runs.

Write a Skill definition

A definition needs name, description, task_family, use_when, and procedure. Each procedure step has an instruction, and can have a decision and a list of expect results.

FieldDescription
nameA short name for the Skill
descriptionOne sentence that tells what the Skill does
task_familyThe task family of the Skill
use_whenThe conditions that make the Skill applicable
do_not_use_whenThe conditions that make the Skill not applicable
preconditionsThe state that must be true before the agent starts
procedureThe ordered steps
outputsThe expected outputs
done_whenThe success criteria
stop_whenThe conditions that stop the procedure
failuresKnown failures and the recovery for each one
tools, environments, agent_versionsThe applicability of the Skill. Search filters use these fields.

Create the Skill

A Skill create request needs an Idempotency-Key header with a UUIDv4 value. A project API key or a member can create a Skill.

import uuid
from zep_cloud import SkillDefinition, SkillProcedureStep, SkillResource
skill = client.agent.skill.create(
    agent_uuid=agent_uuid,
    definition=SkillDefinition(
        name="Resolve a duplicate charge question",
        description="Confirm the payment status before a refund.",
        task_family="billing.support",
        use_when=["The customer reports a duplicate charge."],
        do_not_use_when=["The customer asks to cancel a subscription."],
        procedure=[
            SkillProcedureStep(
                instruction="Get the payments for the invoice.",
                expect=["The list shows each payment and authorization."],
            ),
            SkillProcedureStep(
                instruction="Compare the payments.",
                decision="If one entry is a voided authorization, do not refund.",
            ),
            SkillProcedureStep(instruction="Tell the customer the result."),
        ],
        tools=[SkillResource(name="billing.get_payments")],
    ),
    idempotency_key=str(uuid.uuid4()),
)

Approve the Skill

A new Skill is a candidate. Search does not return a candidate. The approval mode for the task family of the Skill controls who can approve a written Skill:

Approval mode for the task familyWho can approve
auto, the defaultA member or a project API key
manualA member only

With auto approval and a list of auto_approval_task_families, Zep uses manual approval for each task family that is not in the list. When a project API key cannot approve the Skill, the API returns 409 Conflict.

To approve a written Skill:

  1. Read the Skill, and get its current_version.
  2. If the approval mode for the task family is manual, use a member bearer token for the next request.
  3. Call client.agent.skill.approve with the current_version as expected_version and a UUIDv4 idempotency key.

Change a Skill

Skill versions are immutable. To change a Skill, create a new version with the complete new definition and the current version number as expected_version. If another write added a version first, the API returns a conflict. The new version is a candidate and must pass admission again. The earlier versions stay in the version history.

You can also restore an earlier version.

Retire a Skill

Retire a Skill to remove it from search. The request needs the current version as expected_version. The version history stays available. A later version must pass admission before search returns the Skill again.

Next steps