open-knowledge-write-skill
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.
inkeep · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add inkeep/open-knowledge --skill open-knowledge-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