rk-skills

Workflow skills for Claude Code — automate GitHub issues, PR review loops, docs syncing, and releases.

A "skill" is a reusable instruction file that teaches Claude Code how to do one job well (like filing a GitHub issue or cutting a release). You trigger one by name, and Claude follows its steps.

Skills

Most workflow skills come in two forms: a base skill that does one step and stops, and a -loop variant that keeps going on its own — through code review and re-review — until the pull request (PR) is approved.

flowchart LR
    A([validate-issue]) --> B([work-on-issue])
    B --> C([PR + review])
    C -- findings --> D([fix-pr-review])
    D --> C
    C -- LGTM --> E([issue complete])

Several skills mention a complexity score (C0–C100): a model + effort routing signal in the issue title. Capability (which LLM / whether a Fable plan runs first) lives in the score band; Volume (how hard to push) lives in the depth inside the band — see validate-issue step 6. "Fable" skills hand part of the work to a subagent running on the Fable 5 model — a second Claude instance that plans, validates, or drafts while your main session does the building.

Every issue's first line also carries an explicit fableplan: yes|no signal, so later steps read the planning decision instead of re-deriving it from the score. It's yes at score ≥ 61 — a Fable 5 plan is posted before the build; the builder is Opus 5 at both plan bands: high at 61–80, xhigh at 81+. Effort runs high/xhigh for Opus and Sonnet builds. A Fable build exists only when the user explicitly directs it — no band defaults to one; stamped, it may also run at medium or, at the planner's discretion, low for issues lighter than the formula's own floor. Fable 5 never runs at xhigh — high is its ceiling on every stage (build, plan, validate, review, fix).

Issue skills

PR review skills

Docs & release skills

Fable-driven skills

App pipeline skills

The full path from a raw app idea to a running multi-agent build, with a user checkpoint between every stage:

flowchart LR
    A([app-prd]) --> B([prd-questions]) --> C([prd-to-issues]) --> D([execution-plan-review]) --> E([milestoneplan]) --> F([milestone-workflow])

Every new issue records direct predecessors as **Depends on:** #<n>[, #<n>…] | none for required code/product results and **Runs after:** #<n>[, #<n>…] | none for serialization without code inheritance. The workflows/milestone-pipeline.js dynamic workflow validates the full dependency graph before starting. Typed tracks use after for hard prerequisites and runsAfter for ordering-only predecessors. Unrelated tracks run concurrently; both successor types wait for stable predecessor review results. Hard successors build from verified predecessor heads, including a checked integration base for multiple heads, while ordering-only successors inherit no code. Legacy array tracks remain compatible and treat serial edges as hard dependencies. Re-running a partially completed milestone is safe: closed issues are skipped and issues that already have an open PR resume through fix-pr-review-loop instead of opening a duplicate; when a token target is set, a best-effort budget floor (budgetFloor, default 80k tokens) defers the remaining issues and returns partial results instead of dying at the hard ceiling, and each run posts its runId to the milestone's first issue so state survives losing the conversation. Reviews run through the repo's @claude Action by default (reviewMode: 'github'), or as in-session subagent reviewer/fixer cycles with reviewMode: 'subagent' (no GitHub Actions dependency); reviewBot: 'codex' routes github-mode reviews to the @codex Action instead, where every band collapses onto Codex's single flagship and only the cheap re-review keeps a shorthand (@codex luna review). A @claude fable review first review is first-review-only — every blocking re-review after it uses the standard @claude review. With merging on (merge, default reviewLoop), no subagent merges: the run pauses each LGTM PR as awaiting_merge, the orchestrating session squash-merges it in-session at green CI on the pinned reviewed head (branch deleted, issue closed), then resumes with the merge recorded in merged as an {issue, pr, merge_sha, issue_state} record the run checks against the issue/PR pair it is gating — successors build from the updated base branch instead of stacking on unmerged heads; when every issue merges, the release stage (release, default merge) defers to the orchestrator, which runs sync-docs-release in-session to sync docs and publish a GitHub release. Bun regression tests execute the workflow through its async harness.

Utility skills

Review bot prerequisite

The PR-review skills (fix-pr-review, all -loop variants) depend on an automated reviewer that responds to @claude review comments and answers in a specific format (an LGTM / Needs Updates verdict plus structured findings). This repo ships two Claude options plus a Codex twin of each:

• Full bundle (recommended): templates/claude-workflow/ — the complete least-privilege setup: @claude review (read-only), any other @claude ... comment on a trusted-author PR (re-validate and fix all review feedback in place, folding in any extra text as additional scope), plain @claude asks on an issue (implement via the issue-workflow prompt), optional docs/release flows, prompt files, comment-patching scripts, and regression tests. The agent never executes the project's code in any mode (no test suites, builds, or scripts — CI owns checks). See its README for install and triggers.
• Minimal: templates/claude-review.yml — a single review-only workflow; copy it into .github/workflows/, add an ANTHROPIC_API_KEY secret, and the bot and skills speak the same format out of the box.
• Codex full bundle: templates/codex-workflow/ — the same three routes, router, review contract, and install shape driven by openai/codex-action instead. It needs an OPENAI_API_KEY secret, your own GitHub App for the write routes (CODEX_APP_ID / CODEX_APP_PRIVATE_KEY, because that action mints no App token), and the CODEX_BOT_LOGIN repository variable. Its review route holds no write credential at all and runs the read-only Codex sandbox, which denies the agent network too, so the run body stages the pull request on disk first and a trusted step posts the result. See its README.
• Codex minimal: templates/codex-review.yml — the review-only Codex companion; copy it into .github/workflows/ and add an OPENAI_API_KEY secret.

Claude and Codex are independent: separate workflow files, separate concurrency groups, separate secrets, and installing one changes nothing about the other.

The skills default to Claude. fix-pr-review, the -loop skills, and milestone-workflow's github review mode post @claude even when codex.yml is installed. They post @codex only when Codex is explicitly selected — you say so, you pass codex to /fix-pr-review, a caller argument names it (reviewBot: 'codex'), or the run itself was started by an @codex GitHub comment. Once a cycle picks a bot, every re-review in that cycle stays on it.

Without a review bot, the loop skills detect its absence and stop instead of waiting for a review that never arrives.

Grab the workflow directly into a repo:

mkdir -p .github/workflows && \
  curl -fsSL https://raw.githubusercontent.com/richkuo/rk-skills/main/templates/claude-review.yml \
  -o .github/workflows/claude.yml

Also included:

• CLAUDE.md — an example set of global instructions these skills are tuned for (attribution footers, complexity scores, the worktree+PR workflow). Use it as a reference for your own ~/.claude/CLAUDE.md.
• commands/commit.md — a /commit slash command for creating well-formed git commits.
• docs/contract-inventory.md — inventory of shared pipeline rules loop/validate skills must carry (review-cycle stop, score gate, duplicate/convergence and validation stops); Response Style limits point at CLAUDE.md/AGENTS.md instead of restating. bun test fails when a covered skill drops a required rule, so the family can't drift apart silently.

Install (from a clone)

If you work from a checkout of this repo, install.sh symlinks every skill into ~/.claude/skills and, when ~/.codex already exists on the machine, into ~/.codex/skills as well. It also links CLAUDE.md, AGENTS.md (as ~/.codex/AGENTS.md), workflows, and the /commit command into ~/.claude only. Re-run after pulling to pick up new or renamed skills.

./install.sh

Install (with npx)

Copy every skill into your personal ~/.claude/skills/ with one command — no marketplace, no clone:

npx rk-skills

Add --project to install into the current repo's .claude/skills/ instead. This path is copy-based — re-run it to update — whereas the plugin below auto-updates. It installs the skills and any dynamic workflow scripts (the milestone-workflow skill invokes a dynamic workflow script from workflows/, which lands in ~/.claude/workflows/) into Claude destinations only; it does not link into ~/.codex, install CLAUDE.md (the example global config), or the /commit command.

Install (as a plugin)

This repo is a Claude Code plugin marketplace. In any Claude Code session:

/plugin marketplace add richkuo/rk-skills
/plugin install rk-skills@rk-skills

Claude Code auto-discovers everything under skills/ (and the /commit command). CLAUDE.md is not installed by the plugin — treat it as a reference. Restart Claude Code (or start a new session), then trigger any skill by name, e.g. /fableplan <task>.

Prefer to install a single skill? Each is just a directory with a SKILL.md, so you can copy one in directly:

mkdir -p ~/.claude/skills/work-on-issue && \
  curl -fsSL https://raw.githubusercontent.com/richkuo/rk-skills/main/skills/work-on-issue/SKILL.md \
  -o ~/.claude/skills/work-on-issue/SKILL.md

License

MIT — see LICENSE.