Content
75%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is highly actionable — every workflow gives exact, copy-paste commands with environment-aware fallbacks and clean decision trees, and risky-looking actions (temp sessions, browser pops) are explicitly guarded. The main drag is redundancy: the project-local-skill separation and several URL caveats are each stated multiple times, which costs conciseness without adding information.
Suggestions
State the project-local runtime skill's role once (in the 'Working inside a project' section) and have the intro and the `ok init` bullet point to it with a one-line cross-reference instead of re-explaining it three times.
In 'Opening a file outside a project', merge the two URL-hygiene caveats ('Get the URL from `preview_url` only — never hunt for it via `ok ps`...' and 'Never construct or guess the URL') into a single rule, and deduplicate 'boots the session itself'.
Fold the two-line 'What else OK does' section into 'Learn more' so capability questions and the docs/source links live in one clearly-signaled place.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient — nearly every sentence carries a command or a decision rule — but there is real repetition that could be tightened: the project-local-runtime-skill point is made three times in the body (intro "that ships separately as the project-local skill installed by `ok init`", the install bullet "installs the **project-local runtime skill**", and the entire "Working inside a project" section), and within the open-file section "boots the session itself", "Get the URL from `preview_url` only — never hunt for it" and "Never construct or guess the URL" each appear twice. This fits the 3 anchor ('mostly efficient but some unnecessary explanation or could be tightened') better than the 4 anchor, whose over-explanation is only minor. | 3 / 5 |
Actionability | Fully executable, copy-paste-ready commands throughout: `npx @inkeep/open-knowledge init`, `npm install -g @inkeep/open-knowledge`, `ok init`, `ok cowork`, `ok start`, `ok open /abs/path/to/file.md`, the `preview_url` MCP tool "with `file` set to the absolute path", and flag variants "`--project <dir>` or `--project=<dir>`, before or after the path". The open-file section even resolves the common cases by environment (in-app browser vs pure-stdio CLI) with an npx fallback "If `ok` isn't on PATH", matching the 5 anchor's 'copy-paste ready ... specific examples cover the common cases'. | 5 / 5 |
Workflow Clarity | Sequences are clear and well-ordered — the share workflow is an explicit numbered list (commit `.ok/` and skills dirs → clone and re-run `ok init` → `ok start`), and the open-file workflow is a clean decision tree by viewing surface with a fallback when "the OK MCP server isn't wired into this host". Validation signals are present but partly implicit: "If it cannot be honored the command exits non-zero and says why" and "Read that line rather than assuming which project you got" are checkpoints, but no explicit validate-before-proceed loop exists — the 4 anchor ('clear sequence with most checkpoints; minor validation gaps') rather than 5. | 4 / 5 |
Progressive Disclosure | A single well-sectioned SKILL.md (~150 lines) with clear headers and no bundle files; the only deferred content is appropriately external and clearly signaled ("**Docs** — <https://openknowledge.ai/docs>", "**Source** — <https://github.com/inkeep/open-knowledge>") for capability questions the skill deliberately does not enumerate. It sits at the 4 anchor ('good structure; most content appropriately placed; minor organization gaps') rather than 5 because nothing is split into one-level-deep reference files and a couple of sections ("What else OK does", "Learn more") are thin stubs that could be consolidated. | 4 / 5 |
Total | 16 / 20 Passed |