/write-skill

name: open-knowledge-write-skill
description: "Use when the user wants to create, author, write, or design a new Agent Skill (a SKILL.md) — for OpenKnowledge or for their editors — including requests like 'help me write a skill', 'make a skill that…', 'turn this workflow into a skill', or improving an existing skill's triggering and discipline. Also use when capturing reusable agent guidance that should live as an installable skill rather than a one-off prompt. Covers choosing scope (project vs global), authoring inside a plugin or skills-distribution repo (write in the repo's own layout, never install), the SKILL.md frontmatter contract, progressive-disclosure structure, evaluating the skill, and installing it into the user's editors."
compatibility: "OpenKnowledge project recommended (uses the `write` / `edit` / `install` MCP verbs). Authoring + validation are pure file ops; live preview + eval want a running server (`ok start`)."
metadata:
  author: "Inkeep"
  repository: "https://github.com/inkeep/open-knowledge-skills"

Writing an OpenKnowledge skill

You are helping the user author an **Agent Skill** — a `SKILL.md` file (plus optional `references/` and `scripts/`) that teaches an AI agent how to do a recurring task. In OpenKnowledge a skill is a first-class, versioned, installable artifact: you author it with the `write` / `edit` skill verbs, then `install` it into the user's editors.

Skills earn their keep by being **recognized at the right moment** and **followed faithfully**. Most of the craft is in two places: a `description` that triggers reliably, and a body short and concrete enough that the agent actually does what it says. Work the stages below in order, but jump to where the user already is.

Stage 1 — Capture intent and classify the skill

**Gate — does this already exist? Check BEFORE you build.** First list managed skills with `skills({})`, then read any likely match with `skills({ name })`; these are the Project/Global skills OpenKnowledge already manages. Also search the public marketplace with `skills({ query: "<2-4 trigger words>" })` before drafting when the task sounds reusable beyond this project. Each marketplace row returns `name`, `source`, and `description`; inspect the strongest descriptions, then import a chosen candidate with `import({ source, skill: name, add: [...] })` and adapt it only if reuse is the right call. Use the Vercel `find-skills` skill, `npx skills find <query>`, or manual skills.sh search only when the OK MCP `skills({ query })` path is unavailable. If the user already has a skills.sh page open, pass the full skill-page URL as `source`, e.g. `import({ source: "https://www.skills.sh/<owner>/<repo>/<skill>", add: [...] })` — the middle segment is the REPO, not a literal `skills`. Do not run `npx skills add` as the default install path in this flow: import through OpenKnowledge (`import({ source, skill, add })`) so the skill lands as a real folder with provenance, versioning, and managed fan-out; `add` says where it goes, and `install` afterwards changes where it lives. Use 2-4 concrete trigger phrases from the user's request plus the domain or tool name, then open/read the strongest candidates' descriptions before judging. If an existing or public skill covers most of it, STOP and **recommend reuse** — a near-duplicate with overlapping triggers mis-fires and dilutes both. If a public skill is close but not exact, decide WITH the user whether to import/adapt it into OpenKnowledge, install it outside OK with the Skills CLI, or write a narrower companion whose `description` explicitly hands off to it. Build a new skill only when it is genuinely distinct. Surface the overlap and the installed-skill plus marketplace search outcome before drafting or writing anything. This is a disclosure gate: tell the user what you checked, what matched, and why reuse/import/adapt/new-skill is the right next step. Never discover overlap after the skill is written. If `skills({ query })` / skills.sh is unreachable, say so plainly and continue with the installed-skill check.

Ask only what you can't infer:

• **What recurring task** should this skill handle? Get one concrete example.
• **Skill type**, because it sets how much rigor to apply:
• **Reference / technique** (most skills) — "how to do X." Prose body, examples.
• **Discipline** — enforces a behavior the agent tends to skip under pressure

(e.g. "always write a failing test first"). These need the RED baseline + pressure-testing in Stage 4–6; reference skills don't.

• **Degrees of freedom** (calibrate body precision to task fragility):

*high* (free prose — judgment tasks), *medium* (parameterized steps), *low* (a fixed `scripts/` command — when any deviation breaks the result). Don't over-specify a judgment task or under-specify a fragile one.

Stage 2 — Resolve scope FIRST (never infer silently)

Scope determines where the skill lives and where `install` fans it. This is the user's decision and has different blast radius — make it explicit.

| Scope | Lives in | `install` fans it to | | --- | --- | --- | | **Global** | a real folder under your home's skill roots (e.g. `~/.claude/skills/<name>/`) | your editors, in **every** project | | **Project** | a real folder in this repo's skill roots (e.g. `.claude/skills/<name>/` or the `.agents/skills/` hub — shared via git) | this project's editors; teammates get it on `git pull` |

Default heuristic: inside an OK project and the task is specific to it → **project**; "for all my work / globally" → **global**; otherwise ask one question. State the choice and its consequence before writing.

**Developing a skills repo or plugin? Then NEITHER scope applies.** If the repo you are working in is itself a skill *distribution* — a plugin (e.g. a `.claude-plugin/` manifest or marketplace listing) or a catalog repo that shelves skills as `skills/<name>/` for others to import — the skill you are authoring is a **product of that repo**, not