Skip to navigation
Agent Skills

Agent Skills overview

Build agents that learn from experience

Agent Skills let an agent learn from its own task runs. Zep records each run, learns how the task is best completed, and gives the agent a Skill to follow on the next run. Each new run refines the Skill.

Why agents need Skills

Without Skills, each run starts from zero. An agent that completed a task yesterday discovers the procedure again today. It tries the same wrong steps, calls the same tools again, and spends tokens and time on a route that it found before. What the agent learned during the run is lost when the run ends.

With Skills, the agent starts from the procedure that worked. The agent can complete more tasks on the first attempt, with fewer steps, fewer tokens, and less time. A smaller or lower-cost model can follow a procedure that a larger model had to discover.

You do not write the Skills. Zep compiles them from the runs that your agent already makes.

How Agent Skills work

Each outcome feeds the next compilation 1. Capture 2. Compile 3. Curate 4. Review 5. Serve
  1. Capture. Your agent runtime records each task run as a Trajectory: the objective, the ordered events, and the verified outcome.
  2. Compile. Zep reads the verified runs of a task family. It proposes a new Skill, or it proposes a change to an existing Skill.
  3. Curate. Zep checks each proposal automatically. It merges the proposal into the Skill as a new version, or it rejects the proposal.
  4. Review. Zep scans and evaluates each new version. By default, Zep then admits the version automatically. You can enable member review for all versions or for some versions.
  5. Serve. At task time, the agent finds the applicable Skills and reads the current version over MCP or the Zep SDKs. Your application records the Skill use and the outcome.

Each verified outcome changes the trust value and the search rank of the Skill. The next runs give new evidence to the next compilation.

What a Skill is

A Skill is a versioned procedure for one task family, learned from the agent’s own runs. Zep renders each Skill version as a SKILL.md document. Your agent reads the text and decides how to act. Zep does not run your code.

Each Skill version has these parts:

PartPurpose
use_when and do_not_use_whenThe conditions that tell an agent when the Skill applies
preconditionsThe state that must be true before the agent starts
procedureOrdered steps. Each step has an instruction, an optional decision, and optional expect results
outputs and done_whenThe expected result and the success criteria
stop_when and failuresThe stop conditions and the recovery behavior
tools, environments, and agent_versionsThe applicability of the Skill

Each compiled step cites the captured runs that it came from. A change creates a new version, and earlier versions stay readable. You can compare versions, restore an earlier version, and read the evidence of a Skill.

Skills and fine-tuning

Fine-tuning changes how a model behaves. Skills record how a task gets done. You can use both.

Fine-tuningAgent Skills
Operating effortYou curate datasets, run training jobs, maintain evaluations, and host each model version.Zep compiles Skills from the runs that your agent already makes. You do not need datasets, training jobs, or model hosting.
UpdatesUpdates arrive on a retraining cycle. A new base model needs a new fine-tune.Skills change as new runs arrive. A Skill is text, so it continues to work when you change the model.
Inspection and rollbackThe learned behavior is in the model weights. To revert, you deploy an earlier model.Each Skill is a readable procedure with cited steps. To revert, you restore an earlier version.

Knowledge and Skills

An agent needs knowledge and Skills to complete a task. A Context Graph gives the agent current facts about users, accounts, and your domain. Agent Skills give the agent the procedures that worked. Use both when an agent must know what is true and how to complete the task.

Boundaries

Each Agent sees only its own Skills. Agents do not share Skills automatically. To copy a Skill to a different Agent in the same security domain, see Share Agent Skills.

Terms

TermMeaning
AgentOne deployed agent in a project. An Agent owns its Trajectories and Skills.
TrajectoryThe record of one task run: an objective, a task family, ordered events, and an outcome.
Task familyA slug that groups runs of the same kind of task, for example billing.support. Zep compiles and filters Skills by task family.
Attempt familyOne initial Trajectory and its retries. Zep counts attempt families when it decides if a task family has sufficient evidence.
VerificationThe strength of the evidence for an outcome: none, agent, tool, customer, or external. The tool, customer, and external values are strong verification.
CandidateA new Skill version that waits for admission. Search does not return a candidate.
AdmissionThe decision that makes a candidate available to its Agent.
Skill useA record of how the agent used one Skill version in one Trajectory, with an optional outcome.

Maturity and trust

Each search result has a maturity value:

MaturityCondition
provisionalOne supporting attempt family supports the current version.
corroboratedTwo or more supporting attempt families support the current version.
establishedThe trust value is 0.6 or more.
authoredA person wrote the Skill manually. The Skill has no compiled source.

The trust value is a score from 0 to 1. Strongly verified successful uses increase the score, and strongly verified failures decrease the score.

Availability

Agent Skills are available only to accounts with access to the feature. The API returns 403 permission_denied when the account does not have access. Agent Skills are not available while BYOK is active.

Next steps