CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

78%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A dense, highly actionable authoring workflow: concrete verb-call syntax for every operation, exact frontmatter contracts, a scope decision table, and a genuinely validated RED→GREEN→pressure-test loop with feedback and rollback. Its main weakness is redundancy — the graph/wiki-link rules, install semantics, and Stage-1 gate are each stated more than once, inflating token cost without adding information.

Suggestions

State the project-vs-global reference-linking rule once (in Stage 5, where bundle files are added) and cut the near-duplicate paragraph in Stage 3 down to a one-line pointer — the ~10 duplicated lines are the largest single token saving available.

Consolidate Stage 1's import guidance: the `import({ source, skill, add })` syntax and the "do not run `npx skills add` as the default" rule each appear multiple times; give one decision path (OK MCP query → skills.sh URL → CLI fallback) with the call syntax shown once.

Drop Reminders that restate earlier stages verbatim (the Stage-1-gate and install-fan-out restatements) and keep only the genuinely new cautions — the scripts trust-domain warning and the grounding-claims rule — plus add an explicit "confirm with the user / capture `history` before `delete({ skill })`, since global skills are unversioned" step to close the destructive-path validation gap.

DimensionReasoningScore

Conciseness

Mostly efficient — dense, imperative, and free of basic-concept padding — but it duplicates itself: the project-vs-global reference-linking rule appears nearly verbatim in Stage 3 ("a backticked `references/<topic>.md` path is fine; use a `[[references/<topic>]]` wiki-link only when…") and again in Stage 5 ("a backticked `references/<name>.md` path joins the graph just like a `[[references/<name>]]` wiki-link… Global skills are different…"), "Keep references one level deep" is stated in both stages, and the Reminders section restates the Stage 1 gate and Stage 8 install-fan-out points. Fits anchor 3 (mostly efficient, some unnecessary explanation, could be tightened). Not 2: nearly all tokens carry non-obvious OpenKnowledge-specific semantics Claude cannot already know. Not 4: the duplication is whole passages, more than minor instances.

3 / 5

Actionability

Every operation has copy-paste-ready verb syntax with realistic parameters — `write({ skill: { name: "<lowercase-hyphen-name>", description: "<triggers>", body: "<markdown>", scope: "project" } })`, `edit({ skill: { name, file: "references/tiers.md", find: "…", replace: "…" } })`, `install({ name: "<name>", add: ["codex", "opencode"] })`, `skills({ query: "<2-4 trigger words>" })`, `import({ source: "https://www.skills.sh/<owner>/<repo>/<skill>", add: [...] })` — plus exact limits ("name — lowercase letters, digits, hyphens; ≤64; equals the directory"; "description — ≤1024 chars, no XML tags, no `version` field"), a scope decision table, and named pressures (time, authority, sunk cost). Matches anchor 5: examples cover all common cases; placeholders are inherent user content, not pseudocode, so the executable-example rule is satisfied. Not 4: no meaningful execution gaps beyond the abbreviated location-id list.

5 / 5

Workflow Clarity

Eight clearly sequenced stages with explicit checkpoints: the Stage 1 gate ("Surface the overlap and the installed-skill plus marketplace search outcome before drafting or writing anything. Never discover overlap after the skill is written"), the Stage 4 RED baseline, Stage 6 GREEN with a validate→fix→retry loop ("confirm the agent still follows the rule — then patch any loophole and re-test"), the Stage 7 near-miss sanity check, and Stage 8 rollback via `history({ skill })` → `restore_version`. Fits anchor 4 (clear sequence, most checkpoints). Not 5: the destructive `delete({ skill })` path — which "removes the source and every location" — carries no pre-delete validation step, and "global skills are unversioned in this build" makes that deletion unrecoverable. Not 3: the core authoring workflow has explicit validation and feedback loops, so the destructive-operation cap doesn't apply to the primary flow.

4 / 5

Progressive Disclosure

Verified against the actual bundle: both body references exist as real one-level-deep files — `references/pressure-testing.md` (signaled from Stage 6) and `references/description-optimization.md` (signaled from Stage 7) — with no dangling paths and no `scripts/`/`assets/` claims. The body stays within its own ~500-line budget and appropriately keeps deep procedural detail (the pressure-test loop, description-optimization method) in the references while the stages carry the decisions. Matches anchor 5: clear overview, well-signaled one-level-deep references, appropriate split. Not 4: both references are signaled exactly at the point of need and the split is clean.

5 / 5

Total

17

/

20

Passed

Description

96%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A near-exemplary description: explicit 'Use when…' triggers with verbatim user phrasings, verb synonyms, a clear what/when split, and concrete artifact names (SKILL.md, frontmatter). Its only weakness is breadth — covering creation, improvement, evaluation, and plugin-repo authoring creates minor overlap risk with closely related skills.

DimensionReasoningScore

Specificity

Lists multiple concrete actions spanning the full lifecycle — "create, author, write, or design a new Agent Skill (a SKILL.md)", "choosing scope (project vs global)", "authoring inside a plugin or skills-distribution repo", "the SKILL.md frontmatter contract, progressive-disclosure structure, evaluating the skill, and installing it into the user's editors" — comprehensive coverage matching the anchor-5 example's action enumeration. Not 4: the action list has no minor gaps; it covers create → scope → author → structure → evaluate → install. Voice is third person ("Use when the user wants to…", no "I can" / "You can"), so no person-penalty applies.

5 / 5

Completeness

Explicitly answers both: what — "Covers choosing scope (project vs global)… the SKILL.md frontmatter contract, progressive-disclosure structure, evaluating the skill, and installing it into the user's editors"; when — leads with "Use when the user wants to create…" and adds a second explicit trigger class ("Also use when capturing reusable agent guidance that should live as an installable skill rather than a one-off prompt"). Matches anchor 5 exactly; the 'Use when' clause is present so the ≤3 cap does not apply. Not 4: the 'when' is explicit and multi-variant, not merely present.

5 / 5

Trigger Term Quality

Comprehensive natural-term coverage with synonyms and artifact names: quoted user phrasings "'help me write a skill'", "'make a skill that…'", "'turn this workflow into a skill'", plus "create, author, write, or design", "SKILL.md", "Agent Skill", "installable skill rather than a one-off prompt". Not 4: rather than a few natural terms missing, the phrasing space is covered with multiple verbatim variants users would actually type.

5 / 5

Distinctiveness Conflict Risk

Clear niche with artifact-level triggers ("a new Agent Skill (a SKILL.md)", "for OpenKnowledge or for their editors") that would rarely fire for the wrong skill, but it spans creation, "improving an existing skill's triggering and discipline", evaluation, and "authoring inside a plugin or skills-distribution repo" — minor overlap risk with closely related skill-evaluation and plugin-authoring skills. Fits anchor 4 (mostly distinct, minor overlap). Not 5: that breadth of adjacent territory leaves real, if minor, collision surface. Not 3: the SKILL.md/OK-specific anchors keep it firmly distinguishable from generic authoring requests.

4 / 5

Total

19

/

20

Passed

Validation

81%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 13 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

relative_links

Relative link issues: 1 missing

Warning

referenced_paths_exist

Referenced path issues: 4 missing

Warning

Total

13

/

16

Passed

Repository

inkeep/open-knowledge

Path

packages/server/assets/skills/write-skill/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.