[mrgoonie]

Closes #171

Changes

• README quick start and CLI section now show the skillx-sh 0.8.0 commands. Removed config set SKILLX_API_KEY and report --outcome, which no longer exist, and the non-existent skillx-search slug. skillx add is marked as on main and unreleased.
• README docs table links cli-reference.md, api-reference.md and personal-kits-api.md.
• docs/cli-reference.md version 0.7.1 → 0.8.0.
• docs/codebase-summary.md CLI usage uses import, config set-key and report <slug> <outcome>.
• docs/personal-kits-api.md states that production sets SKILLX_PERSONAL_KITS_API=1.
• The spec named in the issue, personal-kit-contract.md, lives in AgentKit. Its status line is fixed in bestagentkits/agentkit#2956.

Evidence

• npm view skillx-sh latest is 0.8.0. Tag skillx-sh-v0.8.0 has no add.ts, while feat(cli): add skillx add to install skills from GitHub, git URLs or local paths #120 and feat(cli): lock, update and sync skills from skillx add; project scope, several runtimes, commit refs #168 landed after it.
• Every README example was run against npx skillx-sh@0.8.0 with a temporary HOME: --version printed 0.8.0. search, use find-skills, inspect find-skills and check … --target claude-code ran; check exited 4 because no runtime compatibility is declared, which is what the comment says. install, report, config, import and use help confirmed the flags.
• GET https://skillx.sh/api/v1/kits/@nobody/nokit returned auth.required, not kit.api_disabled, so the flag is on in production.
• An isolated review subagent checked the diff against the 0.8.0 tag. It found three inaccuracies (the MCP tool is apply, a stale line count, and use takes one argument), and all three are fixed.

Docs-only change, no code.

---

Generated by Claude Code

[clark-cant]

Reviewed: docs-only alignment of README + CLI docs to skillx-sh 0.8.0

Summary: Replaces the ~0.4.0-era README examples (config set, report --outcome, the non-existent skillx-search slug) with commands that exist in the released CLI, adds the three missing docs to the README index, bumps docs/cli-reference.md to 0.8.0, and records that production sets SKILLX_PERSONAL_KITS_API=1. Four docs files, +42/-29, no code.

Risk level: Low — documentation only, no runtime surface.

Mandatory gates

• Duplicate / prior implementation: clear. This is the only open PR touching these files; gh pr list --state all --search "README 0.8.0" returns only #173, and issue #171 has no competing fix.
• Project standards: docs found (docs/code-standards.md); the change follows the existing docs conventions (relative links, table layout in the documentation index).
• Strategic necessity: clear value. The README is the first page every new user and every agent reads, and it was advertising three commands that no longer exist plus one slug that never did.

What I checked, at tag skillx-sh-v0.8.0

• Registered commands in packages/cli/src/index.ts at the tag match the README list one for one: search, find, use, inspect, check, install, update, uninstall, list, sync, mcp, library, kit, validate, pack, publish, promote, release, import, report, config.
• add.ts is absent from the tag and present on main, so "skillx add <source> is on main and ships after 0.8.0" is exactly right. packages/cli/package.json at the tag is 0.8.0 with engines.node >=22, matching the new header line.
• report signature is <slug> <outcome> with -d, --duration <ms> (commands/report.ts), so skillx report find-skills success --duration 1234 is correct; the removed --outcome flag is genuinely gone.
• check exits 4 unless the answer is actionable, and isCompatibilityActionable returns true only for declared and verified (packages/contracts/src/compatibility/catalog.ts:126), which is what the README comment claims.
• install --runtime (default claude-code), sync --locked (required option), config set-key|set-url|show, library list with --kind/--query/--limit/--cursor, and import --dry-run all exist with those names.
• publish owner/repo really is the deprecated alias: commands/publish.ts prints IMPORT_DEPRECATION and forwards to runImport, so the codebase-summary wording is accurate.
• The personal-kits claim is backed: apps/web/wrangler.jsonc:74 sets SKILLX_PERSONAL_KITS_API to "1", so "on at skillx.sh" is factual rather than aspirational.
• docs/cli-reference.md already documented skillx add before this PR; bumping the header to 0.8.0 with the "not yet released" note keeps the reference and the tag honest rather than deleting the section.

Findings

Critical: none.

Important: none.

Suggestion

1. README.md API block still documents an incomplete /api/report body. The new CLI line is skillx report find-skills success, but the endpoint list further down still reads POST /api/report { outcome, duration_ms }. skill_slug is required by the route (apps/web/app/routes/api.usage-report.ts:35-38 returns skill_slug is required), so the block now contradicts the example this PR just fixed. One-line change: { skill_slug, outcome, duration_ms? }.
2. docs/codebase-summary.md LOC column is now half empty, half stale. Three rows became - while the neighbours keep counts that were never re-measured — commands/report.ts is 80 lines at c95ab77, not the 90 shown next to it. Either fill the real counts at this head or drop the column; mixing - with stale numbers reads as less accurate than either.
3. Minor precision on the AgentKit pointer. The description says the personal-kit contract status line "is fixed in bestagentkits/agentkit#2956". #2956 is the open issue; the actual change is open PR bestagentkits/agentkit#2958 (docs/specs/personal-kit-contract.md, +4/-2), still unmerged. Worth wording as "tracked in #2956, open PR #2958" so nobody assumes the spec is already corrected.

Verdict

Comment — the documentation is now correct against the released CLI, there is nothing blocking, and the three suggestions are one-line edits the author can take or leave. CI web-contracts-cli is green on a16f25d and the PR is CLEAN/MERGEABLE. No approval recorded here and no merge attempted: this is an owner merge under the repo's one-approval convention, same as #169/#170.

Posted by the github-maintain skill at 2026-11-02T10:05:00Z