ok-skills

What It Does

ok-skills is a curated pack of 31 top-level agent skills (37 SKILL.md files counting the seven nested opencli sub-skills) maintained by a single author, mxyhi, under the Apache-2.0 license. Thirty of the 31 skills are vendored from declared upstreams: planning-with-files from OthmanAdi, tdd and seven more from mattpocock/skills, caveman from JuliusBrussee, agent-browser from vercel-labs, kimi-webbridge from Kimi's official distribution, huashu-design and product-decision-agent from smaller Chinese-community repos. One skill (exa-search) is original. The repo also ships CLAUDE_AGENTS.md, a Chinese-first agent playbook meant to be merged into a CLAUDE.md or AGENTS.md, and READMEs in ten languages. The target user is someone running Codex, Claude Code, Cursor, OpenClaw, Autohand Code, or Trae who wants a pre-vetted starter set instead of hand-picking skills from a dozen repos. The repo sits at 480 stars with 44 forks, was created 2026-02-02, was pushed the day of review, and has accumulated 142 commits, 138 of them from mxyhi, plus one commit each from three outside contributors, two of whom are the upstream authors of vendored skills.

The Good

The vendoring is honest and verifiable, which is rare. The README's full skill index carries a Source URL column pointing at the canonical upstream for 30 of 31 skills, 13 per-skill LICENSE files are retained alongside the root Apache-2.0, and the sync discipline holds up under byte comparison: caveman, tdd, and karpathy-guidelines are byte-identical to their upstreams at review time, and planning-with-files differs from OthmanAdi's master in exactly four line pairs, all of them the install-location-independent script paths the README says are the only intended local difference. The commit log reads as a steady stream of "sync upstream" chores (planning-with-files 3.16.0, kimi-webbridge 2.0.5, exa-search 3.4.1 metadata), and the vendored copies were fresh as of the review date.

The executable parts run from a bare clone with zero dependencies, and they assert on real output. product-decision-agent ships a 230-line quality_gate.py plus its own 112-line unittest file; both run on the Python standard library alone and all 8 tests pass in under 0.01 seconds. diagram-design ships a 389-line self_check.py that validates generated diagram HTML against the skill's accessible-SVG and single-file safety contract, and it rejected a planted violating file with 10 named violations (remote script, onclick handler, missing ARIA structure, missing motion root) while passing its own checked-in template. planning-with-files ships 13 hook scripts including a plan-doctor.sh that self-diagnoses canonicalization, plan resolution, injection silence, and even reports an 8ms injection timing.

The one original skill is version-pinned to a degree most vendor packs do not match. exa-search documents the hosted MCP endpoint, pins the exact npm package (exa-mcp-server@3.4.1) and its tarball SHA-256, names the upstream commit, provides a working curl-based MCP-over-HTTP pattern with session handling, and includes a routing table that tells the agent which Exa tools are deprecated and what to call instead. It reads like documentation written by someone who verified every claim against the live schema.

The install paths that work, work byte-clean. The README quick start (clone into ~/.agents/skills) works verbatim in an isolated HOME. Installing a single skill through the universal installer (npx skills add mxyhi/ok-skills --agent hermes-agent --skill exa-search --copy --yes) lands a SKILL.md that is byte-identical to the repo copy whether the source is a local path or the GitHub remote, and it writes a skills-lock.json with a computed hash. Requesting a skill name that no longer exists fails loudly with exit 1, "No matching skills found", and zero files written.

There is supply-chain thinking in the CI. The repo's single workflow guards the author's personal global-essentials branch: it closes unauthorized pull requests against that branch using pull_request_target without ever checking out or executing PR code, and tells contributors to target main instead. The playbook and README also tell you, before you reuse CLAUDE_AGENTS.md, to edit its language-requirement section for your project.

The Bad

One of the 31 advertised skills is invisible to the universal installer. opencli keeps its seven SKILL.md files at opencli//SKILL.md, two levels deep, and npx skills add mxyhi/ok-skills finds only 30 skills (verified by enumerating the CLI's available-skills list). Only users who follow the git-clone quick start receive opencli at all; users of the skills CLI, including Hermes and OpenClaw installs, silently get 30 of 31.

The skills.sh registry is littered with this repo's retired names. The registry's search page carries 99 mxyhi/ok-skills entries, and 68 of them name skills that no longer exist in the repo (minimax-docx 103 installs, pptx-generator 97, dogfood 97, eight gsap-* entries, and more), totalling 1,750 lifetime installs on ghost entries against 2,126 on the 31 live skills. The repo cycled through large vendored sets (superpowers-style workflow skills, impeccable, gsap, minimax office skills) before settling on the current 31, and the registry remembers everything. A scripted install of a retired name does fail loudly, but anyone following an old tutorial or README fork installs nothing and must guess the current name.

Reference docs inherited broken links from the upstream layouts. SKILL.md entry points are clean (78 local links, zero broken), but the deeper reference files are not: ai-elements carries 8 doc links stripped of their domain (they begin with /components/ or /docs/ and resolve nowhere), opencli's references carry 10 paths like ../../../clis/1point3acres/utils.js that point into the upstream repo rather than the vendored copy, caveman's README links ../../README.md one level too high, and huashu-design references a demos/hero-animation-v9.mp4 that is not in the repo. Progressive disclosure works until an agent follows a reference link and hits a dead path.

The playbook is personal, not product. CLAUDE_AGENTS.md is the author's own Chinese-first workflow: all replies must be in Chinese, and one instruction tells the agent to source ~/proxy.sh on network trouble, which only exists on the author's machine. The README discloses the language requirement and invites editing, but nothing marks the proxy line, and a user who copies the file wholesale gets both behaviors. Related: product-decision-agent and huashu-design are Chinese-first by design, which is stated but limits reach for non-Chinese users.

No releases, no changelog, and CI runs no tests. In seven months and 142 commits the repo has cut zero tags; version information lives in per-skill metadata where present (planning-with-files 3.16.0, kimi-webbridge 2.0.5) and nowhere else. The single CI workflow is the PR guard; nothing validates frontmatter, links, or the vendored-copy parity on push, so all the sync discipline that held at review time is enforced manually.

Smoke Test Results

Hands-on run on the macOS review host (aarch64, Node 24.13.1, git 2.x); the sbx microVM was unavailable, so scripts ran host-side against unique clone directories with isolated HOMEs, following the established host-based pattern. Three runs: structural on a bare clone, install surface with the skills CLI available, and functional assertions on bundled scripts.

Run A. Fresh clone, no deps preinstalled

$ git clone --depth 1 https://github.com/mxyhi/ok-skills.git # main, 72MB
✅ clone present (72M, branch main)

$ find . -name "SKILL.md" | wc -l # README claims 31 skills
✅ 37 files = 30 skills + opencli (7 nested); the "31" claim is accurate

$ python3.11 structure-check # frontmatter audit, all 37 files
✅ name + description present, names match directories, max description 925 chars

$ python3.11 link-check # SKILL.md navigation links
✅ 78 local links, 0 broken (reference-doc artifacts counted separately, see Bad)

$ grep -c "Apache License" LICENSE && find . -iname "LICENSE*" | wc -l
✅ root Apache-2.0 (11,355 bytes) + 13 per-skill license files retained

$ python3.11 product-decision-agent/scripts/test_quality_gate.py
✅ Ran 8 tests in 0.004s OK # stdlib only, runs with nothing installed

$ python3.11 diagram-design/scripts/self_check.py diagram-design/assets/template-motion.html
✅ OK diagram-design/assets/template-motion.html # stdlib only

$ grep -c "^| \[" README.md # source-attribution rows
✅ 31 index rows; 30 declare an upstream Source URL (exa-search is the one Custom)

Pass rate: 8 of 8. A bare clone is structurally sound and its self-contained test assets run with zero setup.

Full sandbox log →

Run B. Sandbox with deps preinstalled (install surface, node + git + npx skills)

$ git clone https://github.com/mxyhi/ok-skills.git ~/.agents/skills/ok-skills # isolated HOME
✅ README quick start verbatim; planning-with-files/SKILL.md reachable

$ npx skills add /tmp/okskills-review --agent hermes-agent --skill exa-search --copy --yes
✅ byte-identical SKILL.md + skills-lock.json (computedHash b107a712...)

$ npx skills add mxyhi/ok-skills --agent hermes-agent --skill exa-search --copy --yes
✅ registry-sourced install byte-identical to repo HEAD (in sync at review time)

$ npx skills add mxyhi/ok-skills --skill zzz-nonexistent ... # enumerate visible skills
❌ 30 of 31 visible; opencli invisible (SKILL.md nested two levels below scan depth)

$ npx skills add mxyhi/ok-skills --agent hermes-agent --skill pptx-generator --copy --yes
✅ loud failure: exit 1, "No matching skills found", 0 files installed

$ curl -s "https://skills.sh/api/search?q=mxyhi" # registry reconciliation
❌ 68 of 99 entries name skills absent from the repo (1,750 installs on ghost entries)

$ diff upstream vs vendored (caveman, tdd, karpathy-guidelines, planning-with-files)
✅ 3 byte-identical; planning-with-files differs in 4 documented path-normalization lines

Pass rate: 5 of 7. Both failures are install-surface gaps, not content problems: the nested opencli layout and the registry's memory of retired names.

Full sandbox log →

Run C. Functional verification (does it do what it claims?)

$ python3.11 quality_gate.py canonical-answer.md # Chinese PM answer, canonical headers
✅ PASS, exit 0

$ python3.11 quality_gate.py thin-english-answer.md # negative control
✅ FAIL, exit 1: 6 named violations (not Chinese-dominant; no judgment, action,
 metric, or risk sections; output too thin)

$ python3.11 quality_gate.py same-content-renamed-headers.md
❌ equivalent content under ## 判断 / ## 风险 headers fails 2 checks: the gate keys
 on the canonical section words 问题判断 / 风险提醒, not on semantics

$ python3.11 diagram-design/scripts/self_check.py planted-bad.html
✅ FAIL, exit 1: 10 named violations (remote script, onclick, ARIA contract, motion root)

$ sh planning-with-files/scripts/check-complete.sh # with no plan present
✅ exit 0 with a "No task_plan.md found; no active planning session" notice

$ sh planning-with-files/scripts/plan-doctor.sh
✅ full self-diagnostic: canonicalizer, resolver, injection-silence check, 8ms timing

$ grep -c "exa-mcp-server@3.4.1\|SHA-256\|mcp.exa.ai" exa-search/SKILL.md
✅ version-pinned package + tarball SHA-256 + hosted endpoint + deprecated-tool routing

Functional pass rate: 6 of 7. The single marked failure is disclosed design strictness in the quality gate (format contract over semantic equivalence), recorded as a caveat rather than a defect claim.

Full functional log →

What the runs tell you

The pack's structure and its self-contained executables are in good shape from a cold clone, and the two install-surface defects (opencli nesting, registry ghosts) are the only things standing between the README's promises and a clean 20 of 22 across all runs. What no standalone run can cover is the agent-side behavior of the 30 doc-only skills, which is why functional verification is partial.

Setup Walkthrough

1. Whole-pack install, README verbatim: mkdir -p ~/.agents/skills && git clone https://github.com/mxyhi/ok-skills.git ~/.agents/skills/ok-skills. About 72MB. All 31 skills are present in this layout, including opencli.
2. Single-skill install for a skills-CLI host: npx skills add mxyhi/ok-skills --agent hermes-agent --skill planning-with-files --copy --yes (swap the agent id for claude-code, cursor, openclaw, and so on). The copy lands byte-identical with a skills-lock.json. Note opencli is not reachable this way.
3. If you use the bundled playbook, copy CLAUDE_AGENTS.md content into your CLAUDE.md or AGENTS.md, then edit the 语言要求 section to your language and delete the source ~/proxy.sh line unless that is your setup.
4. Per-skill prerequisites are listed in the README's Common Prerequisites section: gh for some skills, a Chrome/CDP environment for browser skills, Playwright plus Chromium for diagram-design PNG export (pip install playwright && playwright install chromium), and npm dependencies inside huashu-design (pdf-lib, playwright, pptxgenjs, sharp) if you use its exporters.

Alternatives

1. vercel-labs/skills - the universal installer and registry this pack depends on; prefer it when you want to pick individual skills from upstreams and manage lockfiles yourself.
2. mattpocock/skills - the upstream for 8 of the 31 vendored skills (tdd, grilling, teach, domain-modeling, codebase-design, and friends); go here for the source of truth and its router skill.
3. anthropics/claude-plugins-official - if your target is Claude Code specifically, the official marketplace pins 236 external entries to exact commit SHAs, solving the drift problem this pack handles manually.