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

# Write a Skill manually

> Write a Skill definition, create new Skill versions, approve a written Skill, and retire a Skill.

> **Note**
>
> The main Agent Skills workflow is to capture task runs and let Zep compile the Skills, as the [Agent Skills quickstart](/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.

| Field                                     | Description                                                      |
| ----------------------------------------- | ---------------------------------------------------------------- |
| `name`                                    | A short name for the Skill                                       |
| `description`                             | One sentence that tells what the Skill does                      |
| `task_family`                             | The task family of the Skill                                     |
| `use_when`                                | The conditions that make the Skill applicable                    |
| `do_not_use_when`                         | The conditions that make the Skill not applicable                |
| `preconditions`                           | The state that must be true before the agent starts              |
| `procedure`                               | The ordered steps                                                |
| `outputs`                                 | The expected outputs                                             |
| `done_when`                               | The success criteria                                             |
| `stop_when`                               | The conditions that stop the procedure                           |
| `failures`                                | Known failures and the recovery for each one                     |
| `tools`, `environments`, `agent_versions` | The applicability of the Skill. Search filters use these fields. |

## Create the Skill

A project API key or a member can create a Skill. The SDK sends the required `Idempotency-Key` header with a UUIDv4 value.

**`Python`**

```python Python
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")],
    ),
)
```

**`TypeScript`**

```typescript TypeScript
const skill = await client.agent.skill.create(
  agentUuid,
  {
    definition: {
      name: "Resolve a duplicate charge question",
      description: "Confirm the payment status before a refund.",
      taskFamily: "billing.support",
      useWhen: ["The customer reports a duplicate charge."],
      doNotUseWhen: ["The customer asks to cancel a subscription."],
      procedure: [
        {
          instruction: "Get the payments for the invoice.",
          expect: ["The list shows each payment and authorization."],
        },
        {
          instruction: "Compare the payments.",
          decision: "If one entry is a voided authorization, do not refund.",
        },
        { instruction: "Tell the customer the result." },
      ],
      tools: [{ name: "billing.get_payments" }],
    },
  },
);
```

## 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 family | Who can approve               |
| --------------------------------- | ----------------------------- |
| `auto`, the default               | A member or a project API key |
| `manual`                          | A 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`.

## 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](/agent-skills/manage-skills#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

* [Retrieve Skills and record use](/agent-skills/retrieve-skills)
* [Share Agent Skills](/agent-skill-publication)