rk-skills

Workflow skills for Claude Code: GitHub issues, pull request (PR) review loops, docs syncing, and releases.

A skill is a reusable instruction file that teaches Claude Code one job (file an issue, cut a release). 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 continues through review and re-review until the 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])

Issues carry a complexity score (C0 to C100) in the title and a fableplan: yes|no signal on the first line. The score routes the validate model, the build model and effort, and the first reviewer; validate-issue step 6 owns the band table. fableplan is yes at score 71 or higher, and a Fable 5.1 plan is then posted before the build. "Fable" skills hand part of the work to a subagent on the Fable 5.1 model; it runs at high by default and at xhigh only when you ask for it.

Issue skills

| Skill | What it does | |-------|--------------| | new-issue | Turns a bug, idea, or conversation into a complete GitHub issue. Checks claims against the code first, adds the score, the fableplan signal, and a plain-language summary. | | new-issue-loop | Runs new-issue, then validates, implements, and drives the PR through review. Stops on a duplicate. | | validate-issue | Fact-checks an issue against the code with file and line references, checks the approach, and rescores it. | | validate-issue-loop | Runs validate-issue, applies the verdict's fixes to the issue, then hands off to work-on-issue-loop. | | github-issue-format | Reference skill: the required issue format. Loaded before any issue is filed or edited. | | work-on-issue | Implements an issue in an isolated git worktree, builds to any posted plan (newest wins, deviations named in the PR), verifies, and opens a PR that closes the issue. An optional targetBranch replaces the default branch as worktree and PR base. | | work-on-issue-loop | Runs work-on-issue, triggers the first review, then delegates to fix-pr-review-loop until the PR gets an LGTM. | | issueplan | Plans and builds on the session's own model with no subagent. For an issue it posts the plan and asks whether to build. |

PR review skills

| Skill | What it does | |-------|--------------| | fix-pr-review | Reads every unaddressed review comment, inline thread, and failing check, re-checks each against the code, fixes what holds up, resolves merge conflicts, replies point by point, and requests a fresh review from @claude (or @codex with a codex argument). | | fix-pr-review-loop | Repeats fix-pr-review after every review until approval. After 5 rounds it accepts the first LGTM even with non-blocking notes. Escalates when 4 or more cycles keep raising blocking findings in code the loop itself added. | | pr-review | Reference skill: the required review comment format (verdict line, findings, materiality filter, completeness passes that gate LGTM). Loaded before a review is written. |

Docs and release skills

| Skill | What it does | |-------|--------------| | sync-docs | Updates CLAUDE.md, AGENTS.md, SKILL.md, and README.md to match what recent commits changed. | | create-release | Bumps the package version, tags it, and publishes a GitHub release with generated notes. | | sync-docs-release | Runs sync-docs, lands the doc changes on a PR, asks whether to merge, then runs create-release. |

Fable-driven skills

| Skill | What it does | |-------|--------------| | fableplan | A Fable 5.1 subagent writes an implementation plan, posts it to the issue, and asks whether to build now. | | fable-new-issue | new-issue drafted by a read-only Fable 5.1 subagent; your session spot-checks and files it. | | fable-new-issue-loop | Runs fable-new-issue, then drives the issue to a reviewed PR. | | fable-validate | validate-issue run on a Fable 5.1 subagent; your session presents the verdict and acts on it. | | fable-validate-loop | Runs fable-validate, applies fixes, gets a Fable plan when score is 71 or higher or the code is safety-critical, then drives to a reviewed PR. | | fable-validate-fableplan-loop | Same, with an unconditional Fable plan. | | fable-validate-fableplan | Fable validates, fixes are applied, a Fable plan is posted, and it stops there. | | validate-fableplan-loop | Validates on the session's own model, brings in Fable for planning at score 71 or higher or when safety-flagged, then drives to a reviewed PR. | | fableplan-work-on-issue | Fable plans, work-on-issue builds and opens the PR. No validation, no review loop. | | fableplan-loop | Fable plans, then work-on-issue-loop builds and drives review to approval. No validation. | | fable-advisor | Your session builds; a persistent Fable 5.1 advisor writes the plan and answers mid-build consults, and a fresh Fable 5.1 reviewer issues a binding pre-commit verdict. | | fable-orchestrate | Runs on Fable 5.1: splits the task into worker specs, dispatches Sonnet 5 workers, reviews each result, integrates one branch, and gets a binding verdict from a fresh Fable 5.1 reviewer before opening the PR. | | cli-dispatch | Reference skill: how a build stamped on the Codex CLI or Cursor CLI reaches that CLI. Loaded by the Opus driver that milestone-pipeline dispatches for such an issue. | | fable-dispatch | Reference skill: how every Fable skill reaches Fable 5.1 on the current harness, with the fallback ladder and its reporting. Loaded before any Fable subagent is dispatched. |

App pipeline skills

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

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

| Skill | What it does | |-------|--------------| | new-app-pipeline | The orchestrator: stops at every stage boundary for review and re-enters mid-pipeline when artifacts exist. | | app-prd | Turns an idea dump into a section-numbered PRD.md landed via worktree and PR. | | prd-questions | Sweeps the PRD for open questions, asks them in batched multiple-choice form, and folds each answer into the owning section. | | prd-to-issues | Maps PRD requirements to dependency-ordered milestones and complete scored issues, with verified dependencies and an ## Execution block (Depends on, Runs after, build model, effort, fableplan, review trigger). | | execution-plan-review | Renders the execution table from the issues, takes revisions ("11 should be medium", "build 275 with luna on codex at max"), rejects cycles, and writes changes back. | | milestoneplan | Read-only: renders a milestone's plan as one table, one row per issue. Missing fields show as missing. | | milestone-workflow | Builds dependency tracks, presents the run plan for approval, then runs milestone-pipeline: validate, plan, build, review loops, in-session merges, and the release. An optional targetBranch points every stage at that branch. |

The workflows/milestone-pipeline.js dynamic workflow validates the dependency graph, runs unrelated tracks concurrently, and builds hard successors from verified predecessor heads. Re-running a partial milestone skips closed issues and resumes open PRs through fix-pr-review-loop. Reviews run through the repo's @claude Action by default (reviewMode: 'github'), as in-session subagents with reviewMode: 'subagent', or on the @codex Action with reviewBot: 'codex'. No subagent merges: each LGTM PR pauses as awaiting_merge and the orchestrating session squash-merges it at green CI on the reviewed head; a remaining PR that conflicts after a merge is resolved in-session, where the hand-resolved diff decides by behavior: a prose-only resolution keeps the standing LGTM, and a behavior change or any doubt, including agent-executed Markdown such as a SKILL.md, needs a @claude sonnet review before merging, then resumes; when every issue merges, the orchestrator runs sync-docs-release.

Utility skills

| Skill | What it does | |-------|--------------| | tldr | Recaps the previous answer in ASD-STE100 (Simplified Technical English) under 55 words. | | wans | Answers "what are next steps?" in ASD-STE100 as a numbered list, each step marked You: or Me:. |

Review bot prerequisite

The PR-review skills (fix-pr-review and every -loop variant) need an automated reviewer that answers @claude review comments with an LGTM / Needs Updates verdict and structured findings. Without one, the loop skills detect its absence and stop. This repo ships:

• Claude bundle: templates/claude-workflow/: the least-privilege setup with @claude review (read-only), @claude ... fix routes on trusted-author PRs, @claude issue implementation, prompt files, and tests. See its README for install and triggers.
• Codex full bundle: templates/codex-workflow/: the same routes driven by openai/codex-action. Needs OPENAI_API_KEY, your own GitHub App for the write routes, and the CODEX_BOT_LOGIN variable. See its README.
• Codex minimal: templates/codex-review.yml: review only; copy it into .github/workflows/ and add OPENAI_API_KEY.

Claude and Codex are independent: separate workflows, concurrency groups, and secrets.

The skills default to Claude. They post @codex only when you select it: you say so, you pass codex to /fix-pr-review, a caller sets reviewBot: 'codex', or the run started from an @codex comment. A cycle stays on the bot it picked.

The reviewer follows the complexity band. @claude sonnet review at C0 to C20, @claude review at C21 to C70, @claude opus review effort:high at C71 to C80, and @claude fable review effort:high at C81 or higher or with no score. A stamped PR review: trigger in an Execution block overrides the band. Every reviewer above @claude review reviews one blocking cycle only; each blocking re-review steps down one rung and stops at @claude review. A pass that addressed only non-blocking items re-triggers @claude sonnet review. With Codex, C21 and higher collapse onto @codex review and the cheap tier is @codex luna review. skills/fix-pr-review/rereview-routing.md owns the ladder.

External build harnesses. An Execution block can stamp Build model: <Name> (Codex CLI) or <Name> (Cursor CLI), with an optional model id, and milestone-pipeline then runs the build and every fix pass through the cli-dispatch shim under an Opus 5 driver. Codex runs in its workspace-write sandbox. Cursor has no sandbox, so a Cursor build holds the driver's full shell rights and a git status diff is its only guard. The driver never substitutes a Claude build and reports the serving model only when the CLI names one.

Grab the Claude workflow directly:

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

Then add the CLAUDE_CODE_OAUTH_TOKEN secret and install the Claude GitHub App. The workflow uses self-hosted runners; change runs-on and runs_on when you have none. See the bundle Install and Customization inputs sections.

Also included:

• CLAUDE.md: the global instructions these skills are tuned for. AGENTS.md is a symlink to it.
• commands/commit.md: a /commit slash command.
• docs/contract-inventory.md: the shared pipeline rules the loop and validate skills must carry; bun test fails when a covered skill drops one.

Install (from a clone)

install.sh symlinks every skill into ~/.claude/skills (and ~/.codex/skills when ~/.codex exists), plus CLAUDE.md, AGENTS.md, the workflows, and the /commit command. Re-run after pulling.

./install.sh

Install (with npx)

npx rk-skills

Copies the skills and workflow scripts into ~/.claude/; add --project for the current repo's .claude/. Re-run to update. It does not install CLAUDE.md, the /commit command, or anything into ~/.codex.

Install (as a plugin)

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

The plugin auto-discovers skills/ and the /commit command and auto-updates; CLAUDE.md is a reference only. Restart Claude Code, then trigger any skill by name, e.g. /fableplan <task>. To install one skill, copy its directory's SKILL.md into ~/.claude/skills/<name>/.

License

MIT, see LICENSE.