> ## Documentation Index > Fetch the complete documentation index at: https://docs.komodor.com/llms.txt > Use this file to discover all available pages before exploring further. # Skills > Package your runbooks and procedures as reusable, versioned skills, attach them to any agent, and see which ones a run actually used. A skill is a reusable unit of know-how — a runbook, a procedure, a pattern — that any agent can load. Skills are how you give the Komodor Agentic Operation Platform (KAOP) your team's operational knowledge without rewriting an agent's instructions every time the procedure changes. This page covers the two kinds of skill, how to author and version one, how to attach it, and how an agent finds it at run time. ## Why skills instead of instructions An agent's instructions describe what it is. A skill describes how a particular job is done. Keeping them apart buys you three things: * **Reuse.** One escalation procedure, attached to every agent that might need it. * **Change without redeploy.** Publishing a new version of a skill updates the agents attached to it. Nothing restarts. * **Attribution.** A run records which skills were available to it and which it actually used, so you can tell a procedure that helps from one that is never opened. ## The two kinds **Skills** lists both, and the kind filter separates them. | Kind | Where it comes from | Who versions it | | ----------------- | ----------------------------------------------------------- | ----------------------------------------- | | **Authored** | Written in KAOP — by you, in the console or through the API | KAOP, with an integer version per publish | | **Self-reported** | Published by a worker from files next to its own code | Your repository, by whatever you deploy | Authored skills are the ones you manage as a library. Self-reported skills are visible so that you can see what your workers are carrying — and if you want to take one under management, **Claim as authored** copies it into the registry and versions it from then on. ## Author a skill Go to **Skills** and press **Create skill**. **Name** and **Description** are what an agent sees when deciding whether a skill is relevant, so write the description as a one-line statement of when to use it — not a title restated. **SKILL.md content** is Markdown. Say what the agent should do and when, concretely: the checks to run, the order to run them in, the thresholds that matter, what to do with the result. **Labels** are key/value metadata. They group the library and can be used to control who sees a skill. Creating with content publishes version 1. Write for an agent that has your tools but not your context. The most useful skills are specific — "if error rate exceeded 2% for five minutes, check the last three deploys before looking at infrastructure" beats "investigate carefully". ### Authoring in a worker's repository instead If you would rather keep a skill next to the code that uses it, put it in the worker's `skills/` directory and it registers when the worker connects. Two layouts work: ```text theme={null} skills/ triage-checklist.md # the skill id is the filename rca/ SKILL.md # the skill id is the directory name postgres-queries.md # any sibling Markdown becomes a reference ``` Frontmatter carries three fields, all optional: ```markdown theme={null} --- name: Root cause analysis description: Use when an incident needs a documented root cause. tags: [incident, rca] --- # Root cause analysis ... ``` This is the same `SKILL.md` convention Claude Code uses, and a worker also reads a `.claude/skills` directory if it finds one. Skills you already keep for a coding agent transfer as a copy — no format change. ## Versions Authored skills are versioned with plain increasing integers, and the distinction that matters is what does and does not create a version: | Change | Creates a version? | | ---------------------------------------------- | ------------------------------------------------------------ | | Editing the name, description, tags, or labels | No | | Publishing new content | Yes — **Publish as v2**, and so on | | Rolling back | Yes — the old content is republished as a new latest version | Rollback is append-only on purpose. Version history stays a true record of what was in force when, which is what makes it useful for auditing a run that happened three weeks ago. ## Attach a skill to an agent Attaching is a binding between an agent and a skill, and it carries one decision: track latest, or pin a version. | Binding | Behavior | | ---------- | ----------------------------------------------------------------- | | **Latest** | The agent picks up every new version as it is published | | **Pinned** | The agent stays on the version you pinned until someone repins it | Three places attach a skill, and they write the same binding: * **From the skill** — the *Currently attached* list on the skill's editor. * **From the agent** — its **Skills & tools** tab, using **Attach a skill**. * **While creating the agent** — the wizard's skills section. Publishing a new version moves every agent bound at *latest* immediately. If a skill is load-bearing for an agent you cannot afford to surprise, pin that agent and repin it deliberately. ### Declared versus discovered, on the agent An agent's **Skills & tools** tab splits its skills the same way: * **Declared** — explicitly attached and versioned. These are the ones you manage. * **Discovered** — self-reported by the running agent. **Promote to declared** brings one under management. ## How an agent finds the right skill at run time Skills are not all pasted into the prompt. An agent gets a short index of everything attached to it — each skill's name, description, and tags — and the content of the most relevant few. The rest are available for the agent to open during the run when it decides it needs them. Two consequences for how you write them: 1. **The description is the routing decision.** It is what the agent reads when choosing, so a vague description means a skill that never gets opened. 2. **Long skills are fine.** Length costs nothing until the skill is actually loaded, so put the detail in rather than compressing it into something ambiguous. A published version reaches a running agent on its next run. Skills reload live — unlike an agent's instructions or its tool configuration, a skill change does not need a restart. ## See which skills a run used Open a run and look at its **Skills** card. It lists every skill that was available to the run and marks the ones the agent actually invoked. Over time this is the honest signal about your library: skills that are consistently available but never used are either badly described or not needed. Skills are also graded alongside your agents — **Skills** sorts by rating, and a skill that has not been graded says so. See [Evaluations](/manage-your-agents/optimize/evaluations). ## Delete a skill Deleting is refused while a skill is still attached to an agent — detach it first. Once deleted, the skill and its version history are removed from the library while the runs that used it keep their record of having done so. ## Next steps Skills tell an agent how to work; the knowledge base tells it what you know. Ship skills alongside an agent you author. Attach and repin skills on a live agent. How a skill's contribution gets graded. ## Related topics - [Concepts & glossary](/get-started/concepts.md) - [Use cases](/manage-your-agents/build/use-cases.md) - [Python SDK](/developer-tools/python-sdk.md) - [Observability & OTel export](/manage-your-agents/optimize/observability-otel-export.md) - [Go SDK](/developer-tools/go-sdk.md)