Create Agent Skill Version | Zep Documentation

{
  "contract": {
    "aliases": [
      "duplicate-refund"
    ],
    "applicability": {
      "agent_versions": [
        "2026.09.01"
      ],
      "citations": [
        "event-001"
      ],
      "models": [
        {
          "name": "support-agent-prod",
          "version_constraint": "^1.0.0"
        }
      ]
    },
    "citations": [
      "event-001"
    ],
    "confidence": 0.5,
    "contraindications": [
      {
        "citations": [
          "event-001"
        ],
        "text": "The duplicate charge was refunded."
      }
    ],
    "customer_sections": [
      {
        "heading": "Verify the duplicate charge",
        "markdown": "Confirm the duplicate charge before issuing a refund.",
        "schema_version": "v1",
        "section_id": "refund_workflow"
      }
    ],
    "dependencies": [
      {
        "package_name": "payments",
        "version_constraint": "^1.0.0"
      }
    ],
    "description": "Refund a duplicate charge after you confirm the duplicate payment.",
    "environments": [
      {
        "aliases": [
          "duplicate-refund"
        ],
        "citations": [
          "event-001"
        ],
        "name": "refund_payment",
        "version_constraint": "^1.0.0"
      }
    ],
    "evidence": [
      {
        "attempt_family_id": "c58dd7b4-bd8a-41ed-a8be-e32dc6a7c0e3",
        "id": "evidence-1",
        "polarity": "supporting",
        "source_id": "fe2f7bc1-0a8f-4834-98a2-715c8d2b56bc",
        "source_kind": "trace",
        "trace_id": "6a906e70-50ca-4e43-a874-5fcae02a71fa"
      }
    ],
    "failures": [
      {
        "condition": {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        },
        "recovery": [
          {
            "citations": [
              "event-001"
            ],
            "text": "The duplicate charge was refunded."
          }
        ]
      }
    ],
    "invocation": {
      "conditions": [
        {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        }
      ],
      "summary": {
        "citations": [
          "event-001"
        ],
        "text": "The duplicate charge was refunded."
      }
    },
    "kind": "principle",
    "name": "refund_payment",
    "origin": "evidence_derived",
    "outputs": [
      {
        "citations": [
          "event-001"
        ],
        "text": "The duplicate charge was refunded."
      }
    ],
    "package_name": "payments",
    "preconditions": [
      {
        "citations": [
          "event-001"
        ],
        "text": "The duplicate charge was refunded."
      }
    ],
    "procedure": [
      {
        "decision": {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        },
        "expected_observations": [
          {
            "citations": [
              "event-001"
            ],
            "text": "The duplicate charge was refunded."
          }
        ],
        "instruction": {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        }
      }
    ],
    "relations": [
      {
        "citations": [
          "event-001"
        ],
        "kind": "composes",
        "target_package_name": "refund-guidance",
        "version_constraint": "^1.0.0"
      }
    ],
    "schema_version": "v1",
    "success_criteria": [
      {
        "citations": [
          "event-001"
        ],
        "text": "The duplicate charge was refunded."
      }
    ],
    "task_family": "support/refund",
    "termination_conditions": [
      {
        "citations": [
          "event-001"
        ],
        "text": "The duplicate charge was refunded."
      }
    ],
    "tools": [
      {
        "aliases": [
          "duplicate-refund"
        ],
        "citations": [
          "event-001"
        ],
        "name": "refund_payment",
        "version_constraint": "^1.0.0"
      }
    ]
  },
  "created_at": "2026-01-01T00:00:00Z",
  "definition": {
    "agent_versions": [
      "2026.09.01"
    ],
    "aliases": [
      "duplicate-refund"
    ],
    "description": "Refund a duplicate charge after you confirm the duplicate payment.",
    "do_not_use_when": [
      "The payment has not settled."
    ],
    "done_when": [
      "support/refund"
    ],
    "environments": [
      {
        "aliases": [
          "duplicate-refund"
        ],
        "name": "Refund a duplicate charge",
        "version": "2026.09.01"
      }
    ],
    "failures": [
      {
        "recover": [
          "Retry the refund after the payment service recovers."
        ],
        "when": "A duplicate charge is confirmed."
      }
    ],
    "kind": "principle",
    "name": "Refund a duplicate charge",
    "outputs": [
      "support/refund"
    ],
    "package_name": "payments",
    "preconditions": [
      "support/refund"
    ],
    "procedure": [
      {
        "decision": "If the payment is settled.",
        "expect": [
          "A refund is confirmed."
        ],
        "instruction": "Confirm that the payment was processed twice."
      }
    ],
    "related_skills": [
      {
        "relation": "depends_on",
        "skill": "refund-duplicate-charge",
        "version": "2026.09.01"
      }
    ],
    "sections": [
      {
        "heading": "Verify the duplicate charge",
        "id": "refund-workflow",
        "markdown": "Confirm the duplicate charge before issuing a refund."
      }
    ],
    "stop_when": [
      "Stop if the duplicate charge cannot be confirmed."
    ],
    "task_family": "support/refund",
    "tools": [
      {
        "aliases": [
          "duplicate-refund"
        ],
        "name": "Refund a duplicate charge",
        "version": "2026.09.01"
      }
    ],
    "use_when": [
      "A customer reports a duplicate charge."
    ]
  },
  "markdown": "Confirm the duplicate charge before issuing a refund.",
  "self_contained": false,
  "version": 1
}

Create Agent Skill Version. Agent Skills is in closed release. Zep enables Agent Skills only for select accounts. A request from an account without access returns 403 permission_denied. To get access, contact support@getzep.com.

Authentication

AuthorizationApi-Key

Type “Api-Key” followed by a space and the project API key.

Path parameters

agent_uuidstringRequired

Agent UUID

skill_uuidstringRequired

Skill UUID, or the 8-character short_id

Request

Customer-authored Skill definition

definitionobjectRequired

The developer supplies the structured content for the new Skill version.

expected_versionintegerRequired

The developer supplies the current Skill version to protect against concurrent edits.

Response

contractobjectOptional

The service returns skill contract.

created_atstringOptional

The service returns when Zep created this resource.

definitionobjectOptional

The service returns the customer-authored Skill definition.

markdownstringOptional

Markdown is the agent view of the Skill unless the request selects markdown_format=full.

self_containedbooleanOptional

The service reports whether the Skill can run without external context.

versionintegerOptional

The service returns the Skill version number.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

503

Service Unavailable Error