Skills — Reasonix Playbooks

A skill is a named playbook the Reasonix agent can invoke with run_skill. Each skill packages instructions, tooling patterns, and context into a reusable recipe so the agent doesn't need to re-derive the approach every time.

How they work

Skills appear in the agent's system prompt as a pinned index (one-liner + tag). The agent calls run_skill({ name: "<skill-name>", arguments: "<task>" }) and the skill body tells it what to do. Two modes:

Mode	Behavior
Inline	The skill body becomes a tool result the agent reads and follows directly — steps are visible in the conversation
Subagent ([🧬 subagent])	Spawns an isolated child loop — only the final answer comes back. Tool calls and reasoning during the run never enter the main context

Built-in skills

Skill	Mode	Purpose
explore	subagent	Wide-net codebase investigation — read-only, returns one distilled answer
research	subagent	Web search + code reading combined for external questions
review	subagent	Review pending changes (branch diff) — flags correctness, security, style
security-review	subagent	Security-focused diff review — injection, authz, secret leakage
test	inline	Run test suite, diagnose failures, propose fixes, re-run until green

User-added skills

Skill	Mode	Purpose
gog	inline	Google Workspace CLI — Gmail, Calendar, Drive, Contacts, Sheets, Docs via gog. Requires OAuth setup. See MCP Directory for the skill definition.

Cross-tool skill installation (Skillfish)

Skillfish installs skills across multiple AI coding tools simultaneously. Each tool stores its skills here:

Tool	Skills directory
Claude Code	~/.claude/skills/
Cursor	~/.cursor/skills/
Codex	~/.codex/skills/
GitHub Copilot	~/.github/skills/
Gemini CLI	~/.gemini/skills/
OpenClaw	~/.agents/skills/ (shared with pi)

On-disk layout (Mac Studio)

The canonical skills folder is ~/.agents/skills, a real directory shared by pi and OpenClaw.

~/.agents/skills                              # canonical, real dir (pi + OpenClaw)
~/.openclaw/skills                            # real, currently EMPTY - reserved for OpenClaw-specific skills
~/Work/llm/dom-agent-skills/skills            # source repo behind the 12 symlinked skills
~/.nvm/versions/node/*/lib/node_modules/openclaw/skills   # bundled (read-only, ships with OpenClaw)
~/.openclaw/plugin-skills/                    # plugin-managed (symlinks, don't touch)

Most entries in ~/.agents/skills are real folders. Twelve are symlinks into ~/Work/llm/dom-agent-skills/skills:

asana, diagrams, git-commit, git-squash, granola, mongo-atlas, notion, plan-to-feature-doc, posthog, pr-review, validate-implementation, vercel

What it replaced (2026-09-25)

Both roots used to be symlinks to a third directory, and the two symlinks were the same file:

~/.openclaw/skills  ->  ~/Work/llm/skills
~/.agents/skills    ->  ~/Work/llm/skills

OpenClaw refused the 12 nested symlinks with symlink prefix resolves outside the root ancestry (12 skips, each printed twice because both roots resolved to the same directory). Neither skills.load.allowSymlinkTargets nor skills.load.extraDirs fixed it. The actual cause was that the root itself was a symlink pointing outside ~/.openclaw, so the ancestry check ran against the wrong base.

Making ~/.agents/skills a real directory fixed it outright, with no config workaround:

1. rm ~/.agents/skills (remove the symlink)
2. mv ~/Work/llm/skills ~/.agents/skills (move the real directory into place)
3. rm ~/.openclaw/skills + mkdir ~/.openclaw/skills (real, empty)

Verify

openclaw status --all | grep -i eligible        # expect: 53 eligible, 0 missing
openclaw skills list --json | grep -c '"name"'   # 81
# and: no "Skipping invalid skill" lines anywhere

OpenClaw skills.load config

~/.openclaw/openclaw.json now carries an empty skills.load:

"skills": { "load": {} }

It previously held two keys, extraDirs and allowSymlinkTargets, both pointing at ~/Work/llm/dom-agent-skills/skills. Both dated from before the layout fix. Removed 2026-09-25 and re-verified the same day: still 53 eligible, 0 missing, 81 skills, zero skips, so the symlinks genuinely load on their own.

Creating a new skill

The agent uses create_skill to scaffold a SKILL.md file under .reasonix/skills/<name>.md. The skill is then available in future sessions via /skill <name> or run_skill.

Claude Code — review vs gh-pr-review

Two PR review skills available in Claude Code. They solve the same problem differently.

review (plugin: pr-review-toolkit)

• Source: Installed from the Claude Code plugin marketplace into ~/.claude/plugins/.../pr-review-toolkit/
• Mechanism: Launches specialized review agents (code-reviewer, silent-failure-hunter, comment-analyzer, pr-test-analyzer, type-design-analyzer, code-simplifier) each focused on one aspect
• Scope: Local only — analyzes git diffs and codebase files
• GitHub integration: None — doesn't post comments, doesn't interact with PRs
• Best for: Pre-PR self-review before pushing code

gh-pr-review (custom skill)

• Source: Hand-written skill in ~/.claude/skills/gh-pr-review/SKILL.md
• Mechanism: Single workflow using the GitHub CLI (gh) — fetch diff → review → present findings → user picks which to post → post inline comments via GitHub API
• Scope: Full GitHub integration — can fetch PR diffs, post inline comments, submit reviews, approve/request changes
• GitHub integration: Deep — uses gh pr diff, gh api for inline comments, gh pr review for summaries
• Best for: Reviewing someone else's PR on GitHub with actual inline feedback

When to use which

Scenario	Use
Self-review before pushing	review
Reviewing a teammate's open PR	gh-pr-review
Need inline comments on GitHub	gh-pr-review
Deep dive on a specific aspect (tests, types, etc.)	review with targeted agent
End-to-end PR feedback workflow	gh-pr-review