> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-beta.getzep.com/v3/agent-skills/retrieve-skills/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-beta.getzep.com/_mcp/server.

# Retrieve Skills and record use

> Search the admitted Skills of an Agent, put Skill text in a prompt, record each Skill use and its outcome, and connect agents through the Context MCP Server.

An agent retrieves Skills before a task and puts the applicable Skill text in its prompt. Your application then records which Skill the agent used and the result. This feedback controls the trust value and the search rank of each Skill.

Use the Zep SDKs to search, read, and report outcomes from your application code. To connect an MCP-compatible agent without changes to the agent code, see [Use Skills through MCP](#use-skills-through-mcp).

## Search for Skills

Search returns only the admitted Skills of one Agent. Candidates, retired Skills, and the Skills of other Agents are not in the results.

| Parameter      | Description                                                        |
| -------------- | ------------------------------------------------------------------ |
| `query`        | Required. A description of the task.                               |
| `task_family`  | Return only Skills of this task family.                            |
| `kind`         | Return only Skills of this kind.                                   |
| `tools`        | Return only Skills for these tools.                                |
| `environments` | Return only Skills for these environments.                         |
| `limit`        | The maximum count of results on one page. The maximum value is 20. |
| `cursor`       | The cursor of the next page.                                       |

**`Python`**

```python Python
results = client.agent.skill.search(
    agent_uuid=agent_uuid,
    query="customer reports a duplicate charge",
    task_family="billing.support",
    limit=3,
)
search_id = results.response.search_id
skills = results.items
```

**`TypeScript`**

```typescript TypeScript
const results = await client.agent.skill.search(agentUuid, {
  query: "customer reports a duplicate charge",
  taskFamily: "billing.support",
  limit: 3,
  cursor: null,
});
const searchId = results.response.searchId!;
const skills = results.data;
```

Each result has these fields, in addition to the Skill identity, version, and text:

| Field                     | Description                                                                                                                |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `maturity`                | The [maturity](/agent-skills#maturity-and-trust) of the Skill: `authored`, `provisional`, `corroborated`, or `established` |
| `trust`                   | A score from 0 to 1 that increases with strongly verified successful uses                                                  |
| `verified_applications`   | The count of strongly verified uses                                                                                        |
| `source_attempt_families` | The count of attempt families that support the version                                                                     |

Search ranks results by match to the query, by maturity, and by feedback.

### Put a Skill in the prompt

Put the `markdown` of each applicable Skill in the system prompt or in a tool result. Tell the agent to follow the procedure only when the `use_when` conditions are true and the `do_not_use_when` conditions are false. The agent decides if a Skill applies. Zep does not decide.

## Record Skill use

A search alone does not record a Skill use. When the agent makes a decision about a search result, record the decision with the `search_id` of that search and the Trajectory of the current task.

| `usage`          | Meaning                                           |
| ---------------- | ------------------------------------------------- |
| `selected`       | The agent chose the Skill, but did not use it yet |
| `used`           | The agent followed the Skill                      |
| `partially_used` | The agent followed some of the Skill              |
| `ignored`        | The agent did not use the Skill                   |
| `inapplicable`   | The Skill did not apply to the task               |

The `search_id` must come from a search that returned the same Skill version. Otherwise, the API returns `409 Conflict`.

**`Python`**

```python Python
use = client.agent.skill.use.create(
    agent_uuid=agent_uuid,
    skill_uuid=skill.uuid_,
    search_id=search_id,
    trajectory_uuid=trajectory_uuid,
    usage="used",
)
```

**`TypeScript`**

```typescript TypeScript
const use = await client.agent.skill.use.create(
  agentUuid,
  skill.uuid!,
  { searchId, trajectoryUuid, usage: "used" },
);
```

## Record the outcome

After the task ends, close its Trajectory with an outcome and a verification strength. Then add the outcome to the Skill use. The outcome value is `succeeded`, `failed`, `partial`, `abandoned`, or `unknown`. You can also send the outcome in the Skill use request when the result is known at that time.

**`Python`**

```python Python
client.agent.skill.use.add_outcome(
    agent_uuid=agent_uuid,
    skill_uuid=skill.uuid_,
    use_uuid=use.uuid_,
    outcome="succeeded",
)
```

**`TypeScript`**

```typescript TypeScript
await client.agent.skill.use.addOutcome(
  agentUuid,
  skill.uuid!,
  use.uuid!,
  { outcome: "succeeded" },
);
```

Zep takes the verification strength of the feedback from the Trajectory of the Skill use. Only outcomes with strong verification change `trust` and `verified_applications`. Record failures too. Verified failures decrease the `trust` value.

## Get Agent context

The Agent context endpoint assembles the applicable admitted Skills into one text block for a prompt. Send an `objective`, or send the `trajectory_uuid` of the current task. Do not send both. You can also filter by `task_family`, `kind`, `models`, `tools`, and `environments`, and limit the size with `max_characters` (from 1 to 50,000).

**`Python`**

```python Python
context = client.agent.get_context(
    agent_uuid=agent_uuid,
    objective="Resolve a duplicate charge question for invoice 2077",
    task_family="billing.support",
)
prompt_context = context.context
```

**`TypeScript`**

```typescript TypeScript
const context = await client.agent.getContext(agentUuid, {
  objective: "Resolve a duplicate charge question for invoice 2077",
  taskFamily: "billing.support",
});
const promptContext = context.context;
```

The response contains the `context` text and a `snapshot` of the Skill versions in the text. The `truncated` field is `true` when `max_characters` removed content. The context response has no `search_id`. To record a Skill use, use search.

## Use Skills through MCP

The [Context MCP Server](/context-mcp-server) can give an MCP client the Skills of one Agent. An administrator enables this on the MCP connection of the project:

1. In the Zep Dashboard, open the project's **Settings ▸ MCP** page.
2. In **Agent Skills**, select the Agent.
3. Turn on **Allow Agent Skills**.
4. To let clients send feedback, turn on **Allow Skill outcome feedback**.

The connection binds to one Agent. To change the Agent, delete the connection and create it again. Graph scopes do not give access to Skills.

The MCP server has these tools:

| Tool                     | Description                                                                                                 |
| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `search_agent_skills`    | Search the approved Skills of the bound Agent. The default page size is 20 and the maximum is 50.           |
| `read_agent_skill`       | Read one exact Skill version by its artifact URI.                                                           |
| `report_agent_skill_use` | Record the use of one exact Skill version and an optional outcome. This tool needs outcome feedback access. |

Zep checks the access of the user at each call. Results are not cached.

> Give an agent the applicable Skills before a task, and tell Zep how each Skill performed