mxyhi/ok-skills: 30 SKILL.md Directories You Clone Into ~/.agents/skills

The problem is prompt reuse across agents, not prompt quality

Most teams using coding agents do not lack good prompts. They lack a place to put them. A prompt that works well in Claude Code lives in a chat window or a personal notes file, and the next engineer on Cursor rewrites it from scratch. The README frames the target user as someone who wants "reusable skills instead of ad-hoc prompts" and who maintains CLAUDE.md, AGENTS.md or SKILL.md files across more than one project. That is a narrower audience than "AI coding agent users" and it matters, because everything about the distribution model assumes you already know where your agent looks for instructions. The repository bundles 30 skills, all as top-level directories, covering docs lookup, browser automation, planning, prompt engineering, frontend design, and PDF, Word, PPTX and XLSX authoring. If your problem is that your agent writes plausible code against an API version that changed two years ago, find-docs is aimed at that. If your problem is that a long refactor loses its thread after forty tool calls, planning-with-files is aimed at that. Neither is a model improvement. Both are instruction files.

The mechanism is a directory convention, not a runtime

There is no CLI, no daemon and no plugin loader here. The mechanism is that each skill is a directory containing a SKILL.md file, and that the directory names inside the repository already match the layout the agents expect. The README shows the resulting tree: a CLAUDE_AGENTS.md at the root, then planning-with-files/SKILL.md, find-docs/SKILL.md, agent-browser/SKILL.md and so on. Once cloned to ~/.agents/skills/ok-skills, nothing needs to be built or registered. The second half of the mechanism is the trigger rule. The README gives an explicit block to add to AGENTS.md or merge into CLAUDE.md, with lines such as planning-with-files being used "for complex tasks, research, or anything that will take 5+ tool calls" and find-docs being used "when you need current library docs, API references, or Context7-backed examples". Those lines are what make the skills fire. Without them the agent has directories on disk it has no reason to open. The README also describes CLAUDE_AGENTS.md as a Claude Code-oriented playbook packaging a Chinese-first, KISS-oriented workflow with current-doc and source checks, multi-agent preference, planning-with-files and karpathy-guidelines defaults, strict TypeScript expectations, and context-mode routing rules. Note the word Chinese-first: the README instructs you to edit the 语言要求 section before reuse, and calls the 其他注意项 section intentionally project-local. That is unusually honest about a default that will not suit every reader.

Cloning it: two paths, one of which is Autohand-specific

The general path is three commands. Create the skills directory, move into it, clone. The README gives mkdir -p ~/.agents/skills, then cd ~/.agents/skills, then git clone https://github.com/mxyhi/ok-skills.git ok-skills. Autohand Code gets a separate set of instructions because it reads a different location. For user-level skills the README shows mkdir -p ~/.autohand/skills followed by git clone https://github.com/mxyhi/ok-skills.git ~/.autohand/skills/ok-skills. For project-level skills it shows mkdir -p .autohand/skills followed by the same clone into .autohand/skills/ok-skills. The project-level variant is the more interesting one, because it implies you can scope a skill set to a single repository rather than every project on the machine. After cloning, the README's suggested invocation is natural language rather than a command, for example "Use planning-with-files before refactoring this module" or "Use agent-browser to reproduce this UI bug". That is the whole install story. There is no package.json, no install script, and no release artifact retrieved for this repository, so the clone is the version you get.

planning-with-files writes three markdown files, and that is the constraint

The README names planning-with-files, find-docs and agent-browser as the three to start with, and describes planning-with-files as "persistent markdown planning with task_plan.md, findings.md, and progress.md". Three named files is a concrete design choice with a concrete cost. The skill survives context loss because state lives on disk rather than in the conversation, which is the point for research and long-running work. The cost is that a planning run leaves files behind in your working tree, and those files are not obviously excluded from a commit. The README does not describe a cleanup step, a gitignore entry, or a location outside the repository root. If you adopt this skill, decide where task_plan.md, findings.md and progress.md are allowed to appear before the first run, not after. find-docs carries a different constraint: the README describes it as a "focused Context7 CLI workflow", so the skill is only as useful as the Context7 coverage for the library in question. For a small internal SDK, or a library that changed last week, the lookup has nothing to return and the agent falls back to whatever it already believed. agent-browser is described as covering navigation, forms, screenshots, scraping and web QA, which is a broad surface for a single instruction file, and the README does not say which browser or driver it assumes.

Thirty skills in one clone is a distribution trade-off, not a feature

A single git clone is the simplest possible install and the least precise one. You cannot take find-docs without also taking migrate-to-shoehorn, teach, grilling, ontoly-software-graph and the rest of the 30. Updates arrive by git pull, which means the whole set moves together, and there is no retrieved release history to pin against, so a pull has no version boundary to inspect. Compare that with how a tool like Context7 is consumed: as a service the agent queries at run time, where the documentation is fetched fresh and nothing is stored in your repository. ok-skills takes the opposite approach. The instructions are files on disk, which makes them auditable, diffable and offline, and makes them your maintenance problem. Neither model is better in the abstract. The file model wins when you need to read exactly what the agent was told and change it. The service model wins when currency matters more than control. A team that wants both would run find-docs for the lookup and keep the planning skill as a file, which is roughly what the README's own starting set does.

CLAUDE_AGENTS.md is the part most likely to need editing before it helps

The README is direct that CLAUDE_AGENTS.md is not drop-in. It says to edit the 语言要求 section for your project before reusing it, and describes 其他注意项 as intentionally project-local. Read that as a warning rather than a footnote. A playbook that is Chinese-first by default, that prefers multi-agent operation, that expects strict TypeScript, and that routes by context mode is encoding one team's opinions. Copying it unedited into a Python codebase with a single-agent workflow produces instructions that contradict your actual setup, and the agent has no way to tell which of the two it should follow. The safer sequence is to start with the AGENTS.md trigger block, which is short and mechanical, and treat the full playbook as a document to read and excerpt. The README's own framing supports this: it says to "start from" CLAUDE_AGENTS.md and "copy or merge" it, not to symlink it.

Licence, maintenance and what a git pull actually costs you

The repository is Apache-2.0. That is a permissive licence, and it is the licence on the repository as a whole. The README describes the 30 skills as "all maintained as top-level skill directories in this repo", which is the only maintenance statement available, and there is no retrieved release history, so there is no changelog to read before a pull. Practically, that means an upgrade is git pull inside ~/.agents/skills/ok-skills, followed by re-reading any SKILL.md your AGENTS.md trigger rules point at, because a skill's behaviour is its text and the text can change without a version number moving. The Apache-2.0 grant covers copyright and patent use of the material as distributed; it does not tell you whether an individual skill directory wraps a third-party service, and several of them clearly do, since find-docs is built on Context7, exa-search on Exa, and ontoly-software-graph on Ontoly's Software Graph and MCP capabilities. If your organisation reviews dependencies, the review unit here is the skill directory and what it calls, not the repository licence. This is not legal advice; it is a description of where the boundaries sit in the material.

Editorial conclusion

Adopt it if you already run Codex, Claude Code, Cursor, OpenClaw or Autohand Code and want a starting set of SKILL.md directories plus trigger rules you can paste into AGENTS.md. Skip it if you need versioned dependency resolution, per-skill installation, or a licence review of every bundled skill before they reach a company machine. Verify three things before you commit: that your agent actually reads ~/.agents/skills, that CLAUDE_AGENTS.md's 语言要求 section matches your project's language, and that the Apache-2.0 licence covers the individual skill directories you intend to keep.

Official sources

1. Issues
2. License: Apache-2.0
3. mxyhi/ok-skills on GitHub
4. README