write-skill

Name: write-skill
Author: inkeep

3.1kstars191forks

How to install write-skill?

inkeep/open-knowledge/write-skill

$npx -y skills add inkeep/open-knowledge --skill write-skill

Installs into the current project.

Summary

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 trigger

Files · 1

View on GitHub

SKILL.md

1	# Writing an OpenKnowledge skill
2
3	You are helping the user author an Agent Skill — a `SKILL.md` file (plus
4	optional `references/` and `scripts/`) that teaches an AI agent how to do a
5	recurring task. In OpenKnowledge a skill is a first-class, versioned,
6	installable artifact: you author it with the `write` / `edit` skill verbs, then
7	`install` it into the user's editors.
8
9	Skills earn their keep by being recognized at the right moment and **followed
10	faithfully**. Most of the craft is in two places: a `description` that triggers
11	reliably, and a body short and concrete enough that the agent actually does what
12	it says. Work the stages below in order, but jump to where the user already is.
13
14	## Stage 1 — Capture intent and classify the skill
15
16	Gate — does this already exist? Check BEFORE you build. Scan the installed
17	skills (the host surfaces the full catalog when this skill loads) for one whose
18	role or triggers already cover the task. If an existing skill covers most of it,
19	STOP and recommend reuse — a near-duplicate with overlapping triggers
20	mis-fires and dilutes both. Build a new skill only when it is genuinely distinct,
21	or a deliberately tighter companion whose `description` explicitly hands off to
22	the existing one. Surface the overlap and decide WITH the user before drafting or
23	writing anything — never discover it after the skill is written.
24
25	Ask only what you can't infer:
26
27	- What recurring task should this skill handle? Get one concrete example.
28	- Skill type, because it sets how much rigor to apply:
29	- Reference / technique (most skills) — "how to do X." Prose body, examples.
30	- Discipline — enforces a behavior the agent tends to skip under pressure
31	(e.g. "always write a failing test first"). These need the RED baseline +
32	pressure-testing in Stage 4–6; reference skills don't.
33	- Degrees of freedom (calibrate body precision to task fragility):
34	high (free prose — judgment tasks), medium (parameterized steps), low
35	(a fixed `scripts/` command — when any deviation breaks the result). Don't
36	over-specify a judgment task or under-specify a fragile one.
37
38	## Stage 2 — Resolve scope FIRST (never infer silently)
39
40	Scope determines where the skill lives and where `install` projects it. This is
41	the user's decision and has different blast radius — make it explicit.
42
43	\| Scope \| Lives in \| `install` projects to \|
44	\| --- \| --- \| --- \|
45	\| Global \| `~/.ok/skills/<name>/` (your user store) \| your editors, in every project \|
46	\| Project \| `<kb>/.ok/skills/<name>/` (this KB, shared via git) \| this project's editors; teammates get it on `git pull` \|
47
48	Default heuristic: inside an OK project and the task is specific to it → project;
49	"for all my work / globally" → global; otherwise ask one question. State the
50	choice and its consequence before writing.
51
52	## Stage 3 — Plan the contents
53
54	- Body = the durable, reusable instructions — under ~500 lines. If it's
55	growing past that, move depth into `references/<topic>.md` (loaded only when
56	needed) and point at it from the body. For a project skill the reference
57	auto-connects in the graph either way, so a backticked `` `references/<topic>.md` ``
58	path is fine; use a `[[references/<topic>]]` wiki-link only when you want the
59	mention to be a clickable inline link. For a global skill use a plain
60	backtick path — global references aren't graph docs, so a wiki-link there
61	dangles. Keep references one level deep.
62	- Do NOT include: a README/CHANGELOG/QUICK_REFERENCE, install instructions
63	for the skill itself, version histories, or anything host-specific. The skill
64	is the instructions, not documentation about the instructions.
65	- For a discipline skill, plan the failure mode you're correcting and how
66	you'll prove the skill fixes it (Stage 4).
67
68	## Stage 4 — RED baseline (discipline skills only)
69
70	Before writing the skill, run the scenario WITHOUT it and capture what the agent
71	does wrong — verbatim, including its rationalizations ("the test is trivial so I
72	skip

People who liked this also viewed

6 picks

Type

write-skill

3.1kstars191forks

View on GitHub

How to install write-skill?

inkeep/open-knowledge/write-skill

$npx -y skills add inkeep/open-knowledge --skill write-skill

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Writing an OpenKnowledge skill
2
3	You are helping the user author an Agent Skill — a `SKILL.md` file (plus
4	optional `references/` and `scripts/`) that teaches an AI agent how to do a
5	recurring task. In OpenKnowledge a skill is a first-class, versioned,
6	installable artifact: you author it with the `write` / `edit` skill verbs, then
7	`install` it into the user's editors.
8
9	Skills earn their keep by being recognized at the right moment and **followed
10	faithfully**. Most of the craft is in two places: a `description` that triggers
11	reliably, and a body short and concrete enough that the agent actually does what
12	it says. Work the stages below in order, but jump to where the user already is.
13
14	## Stage 1 — Capture intent and classify the skill
15
16	Gate — does this already exist? Check BEFORE you build. Scan the installed
17	skills (the host surfaces the full catalog when this skill loads) for one whose
18	role or triggers already cover the task. If an existing skill covers most of it,
19	STOP and recommend reuse — a near-duplicate with overlapping triggers
20	mis-fires and dilutes both. Build a new skill only when it is genuinely distinct,
21	or a deliberately tighter companion whose `description` explicitly hands off to
22	the existing one. Surface the overlap and decide WITH the user before drafting or
23	writing anything — never discover it after the skill is written.
24
25	Ask only what you can't infer:
26
27	- What recurring task should this skill handle? Get one concrete example.
28	- Skill type, because it sets how much rigor to apply:
29	- Reference / technique (most skills) — "how to do X." Prose body, examples.
30	- Discipline — enforces a behavior the agent tends to skip under pressure
31	(e.g. "always write a failing test first"). These need the RED baseline +
32	pressure-testing in Stage 4–6; reference skills don't.
33	- Degrees of freedom (calibrate body precision to task fragility):
34	high (free prose — judgment tasks), medium (parameterized steps), low
35	(a fixed `scripts/` command — when any deviation breaks the result). Don't
36	over-specify a judgment task or under-specify a fragile one.
37
38	## Stage 2 — Resolve scope FIRST (never infer silently)
39
40	Scope determines where the skill lives and where `install` projects it. This is
41	the user's decision and has different blast radius — make it explicit.
42
43	\| Scope \| Lives in \| `install` projects to \|
44	\| --- \| --- \| --- \|
45	\| Global \| `~/.ok/skills/<name>/` (your user store) \| your editors, in every project \|
46	\| Project \| `<kb>/.ok/skills/<name>/` (this KB, shared via git) \| this project's editors; teammates get it on `git pull` \|
47
48	Default heuristic: inside an OK project and the task is specific to it → project;
49	"for all my work / globally" → global; otherwise ask one question. State the
50	choice and its consequence before writing.
51
52	## Stage 3 — Plan the contents
53
54	- Body = the durable, reusable instructions — under ~500 lines. If it's
55	growing past that, move depth into `references/<topic>.md` (loaded only when
56	needed) and point at it from the body. For a project skill the reference
57	auto-connects in the graph either way, so a backticked `` `references/<topic>.md` ``
58	path is fine; use a `[[references/<topic>]]` wiki-link only when you want the
59	mention to be a clickable inline link. For a global skill use a plain
60	backtick path — global references aren't graph docs, so a wiki-link there
61	dangles. Keep references one level deep.
62	- Do NOT include: a README/CHANGELOG/QUICK_REFERENCE, install instructions
63	for the skill itself, version histories, or anything host-specific. The skill
64	is the instructions, not documentation about the instructions.
65	- For a discipline skill, plan the failure mode you're correcting and how
66	you'll prove the skill fixes it (Stage 4).
67
68	## Stage 4 — RED baseline (discipline skills only)
69
70	Before writing the skill, run the scenario WITHOUT it and capture what the agent
71	does wrong — verbatim, including its rationalizations ("the test is trivial so I
72	skip

People who liked this also viewed

6 picks

Type