Rich Kuo

via GitHub · Posted Jul 23, 2026 · 1 min read

rk-skills: Claude Code Workflow Skills

richkuo/rk-skills

Claude Skill

Claude Code workflow skills — GitHub issue/PR/release automation and Fable-driven planning. Install via npx or as a Claude Code plugin.

38Stars

6Forks

0Open issues

JavaScript MIT v1.12.1 Updated 8 hours ago

#ai-agents #claude #claude-code #github-automation

View on GitHub

A collection of reusable instruction files that teach Claude Code to automate GitHub workflows including issue creation, PR review loops, and release management. Skills can run standalone or in automated loops, with optional Fable subagent support for complex planning and validation tasks.

0 comments

README

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.

Issue skills

Skill	What it does
`new-issue`	Turns a bug, idea, or conversation into a complete GitHub issue. Checks the claims against the actual code first, adds a complexity score, and never files a half-empty stub.
`new-issue-loop`	Runs `new-issue`, then automatically validates the new issue, implements it, and drives the PR through review — one command from idea to reviewed PR. Stops early if it finds a duplicate issue.
`validate-issue`	Fact-checks an existing issue: verifies every claim against the real code (with file and line references), and checks that the proposed approach is feasible and self-consistent.
`github-issue-format`	Reference skill: the required format for creating or editing any GitHub issue (`[C<score>]` title, complexity rationale line, complete-body rule). Loaded automatically before an issue is filed or edited.
`validate-issue-loop`	Runs `validate-issue`, applies any fixes the verdict calls for to the issue itself, then hands off to `work-on-issue-loop`. Stops instead if the issue is too large, infeasible, or already fixed elsewhere.
`work-on-issue`	Implements an issue end-to-end: builds the fix in an isolated git worktree (a separate working copy, so your main checkout stays untouched), verifies it, and opens a PR that closes the issue.
`work-on-issue-loop`	Runs `work-on-issue`, requests a code review, then keeps fixing whatever the review finds until the PR gets an approval ("LGTM" — looks good to me).

PR review skills

Skill	What it does
`fix-pr-review`	Reads all unaddressed feedback on a PR — review comments, inline threads, and any failing CI checks — re-checks each point against the actual code (never blindly applies a suggestion), fixes what holds up, resolves any merge conflicts with the base branch, pushes, replies point-by-point, and requests a fresh review.
`fix-pr-review-loop`	Repeats `fix-pr-review` after every new review until the PR is approved, and won't stop on an approval while the PR is still unmergeable. After 5 review rounds it accepts the first approval even if minor, non-blocking notes remain.
`pr-review-format`	Reference skill: the required format for any PR review comment (verdict line, section structure, materiality filter, safety carve-out). Every finding must include a plain-simple-English summary; `Requires Human Review` items must also include a recommended proposed solution. Loaded automatically before a review is written.

Docs & release skills

Skill	What it does
`sync-docs`	Updates `CLAUDE.md`, `AGENTS.md`, `SKILL.md`, and `README.md` to match what recent commits actually changed.
`create-release`	Cuts a version tag and publishes a GitHub release with generated notes, bumping the package version first so publish workflows fire correctly.
`sync-docs-release`	The two above in sequence: sync docs, commit, then cut the release.

Fable-driven skills

Skill	What it does
`fableplan`	Has a Fable 5 subagent write an implementation plan; posts the plan to the related issue if there is one, then asks whether to build now or stop there.
`fable-new-issue`	Like `new-issue`, but a read-only Fable 5 subagent researches and drafts the issue; your main session spot-checks and files it.
`fable-new-issue-loop`	Runs `fable-new-issue`, then drives the new issue all the way to a reviewed PR automatically.
`fable-validate`	Like `validate-issue`, but the fact-checking runs on a Fable 5 subagent; your main session presents the verdict and acts on it.
`fable-validate-loop`	Runs `fable-validate`, applies issue fixes, gets a Fable plan (only when Capability ≥ 2 / score ≥ 50, or touching safety-critical code), then drives to a reviewed PR.
`fable-validate-fableplan-loop`	Same as above, but the Fable plan is unconditional — every issue gets a posted plan before implementation, no matter how simple.
`validate-fableplan-loop`	The hybrid: validates on your session's own model, but still brings in Fable for planning when Capability ≥ 2 / score ≥ 50 or safety-flagged, then drives to a reviewed PR.
`fableplan-work-on-issue`	The trimmed chain: Fable 5 plans the issue and posts the plan, then `work-on-issue` builds it and opens a PR. No validation, no review loop — stops at the open PR.
`fableplan-loop`	Same as above, plus the review loop: after the Fable plan is posted, `work-on-issue-loop` builds it, opens the PR, and keeps fixing review findings until approval. No validation.
`fable-advisor`	Runs on your session's own model (Sonnet, typically). A persistent Fable 5 advisor writes the plan and stays available for mid-build consults (hard-to-reverse decisions, stuck signals, plan deviations); a separate fresh Fable 5 reviewer issues a binding pre-commit verdict. When a GitHub issue is referenced, it gates the issue and runs `work-on-issue`'s build-and-ship pipeline under the advisor instead of a duplicate flow.
`fable-orchestrate`	Runs on Fable 5. Decomposes the task into self-contained worker specs, dispatches Sonnet 5 workers to implement them, reviews each result inline, integrates everything into one branch, and gets a binding verdict from a fresh Fable 5 reviewer before opening the PR.

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([milestone-workflow])

Skill	What it does
`new-app-pipeline`	The orchestrator: idea → PRD → resolved questions → issues → execution-plan review → milestone workflow, stopping at every stage boundary for your review. Re-enterable mid-pipeline when artifacts already exist.
`app-prd`	Turns an idea dump into a complete, section-numbered `PRD.md` landed via worktree + PR (bootstrapping an empty repo when needed), then iterates on the same PR as you refine.
`prd-questions`	"Ask me all questions": sweeps the PRD for every open question and ambiguity, asks them in batched multiple-choice form with a recommended option, folds each answer into the owning spec section, and empties the Open Questions list.
`prd-to-issues`	Breaks the refined PRD into dependency-ordered milestones and 15–25 complete, complexity-scored issues, each stamped with an `## Execution` block: hard `Depends on` prerequisites, ordering-only `Runs after` constraints, build model, effort, whether a Fable plan comes first, and the `@claude` review trigger.
`execution-plan-review`	Renders the ordering/model/effort/fableplan table from the issues themselves, takes revisions ("11 should be medium", "12 runs after 11"), rejects cycles across both edge kinds, and writes changes back to the issues.
`milestone-workflow`	Reads typed ordering fields before legacy prose, labels inferred edges, builds dependency tracks for a milestone, presents the run plan for approval (mandatory), then runs `milestone-pipeline` and reports PRs, blocked descendants, and review outcomes.

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 as in-session subagent reviewer/fixer cycles by default (reviewMode: 'subagent' — no GitHub Actions dependency), or through the repo's @claude Action with reviewMode: 'github'. Bun regression tests execute the workflow through its async harness.

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 options:

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.

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 — the inventory of shared rules the loop/validate skills restate (review-cycle stop, Capability gate, duplicate/convergence and validation stops); bun test fails when a covered skill drops a required rule, so the family can't drift apart silently.

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, their subagent files, and any dynamic workflow scripts (a few skills delegate their work to helper agents in agents/, which land in ~/.claude/agents/; the milestone-workflow skill invokes a dynamic workflow script from workflows/, which lands in ~/.claude/workflows/); it does not 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.

30 skills in this repo

Plugin marketplace

app-prd

Use when the user wants an app idea turned into a Product Requirements Document (PRD) committed to a repo — "create a PRD", "/app-prd", "turn this idea into a PRD", or a raw idea dump ending with "save it to this repo". Produces a complete,...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install app-prd

create-release

Use when the user asks to "create a release", "cut a release", "tag a version", "publish release notes", or ship a new versioned GitHub release for the current repo.

Install

/plugin marketplace add richkuo/rk-skills
/plugin install create-release

execution-plan-review

Use when the user wants to review or revise the ordering/model/effort/fableplan assignments on a milestone's GitHub issues — "review the execution plan", "/execution-plan-review", "show me the model assignments", or piecemeal revisions like...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install execution-plan-review

fable-advisor

Use when the user wants a task executed by the current session model (typically Sonnet 5) with a persistent Fable 5 advisor overseeing it. Spawns a long-lived read-only Fable 5 subagent that authors the plan, gets consulted at fixed checkpo...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install fable-advisor

fable-new-issue

Use when the user wants a GitHub issue created by a Fable 5 subagent. Spins up a read-only subagent running on Fable 5 that executes the new-issue procedure (duplicate check, code grounding, approach design, complexity score) and returns a...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install fable-new-issue

fable-new-issue-loop

Use when the user asks to have a Fable 5 subagent draft and file a GitHub issue, then autonomously drive it all the way to a reviewed PR in one shot — "fable-new-issue-loop", "fable create the issue and run it to completion". Runs fable-new...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install fable-new-issue-loop

fable-orchestrate

Use when the user wants a task decomposed and driven by a Fable 5 orchestrator delegating implementation to Sonnet 5 workers. The Fable session decomposes into self-contained worker specs, dispatches Sonnet subagents (plain Agents for 1–2 p...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install fable-orchestrate

fableplan

Use when the user wants a task planned by a Fable 5 planning subagent before building it. Spins up a Plan subagent running on Fable 5 to produce an implementation plan, relays the plan back to the main agent, and — if a GitHub issue is refe...

Install

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

fableplan-loop

Use when the user wants a GitHub issue planned by Fable 5 and then autonomously driven to a reviewed PR in one shot, without validation — "fableplan-loop", "fableplan #N and loop until approved", "plan #N with fable then drive it to a revie...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install fableplan-loop

fableplan-work-on-issue

Use when the user wants a GitHub issue planned by Fable 5 and then implemented in one shot, without validation or a review loop — "fableplan-work-on-issue", "fableplan and work on #N", "plan #N with fable then implement it". Runs the fablep...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install fableplan-work-on-issue

fable-validate

Use when the user wants a GitHub issue validated by a Fable 5 subagent. Spins up a read-only subagent running on Fable 5 that executes the validate-issue procedure (claim tracing, architecture/consistency checks, complexity score), then rel...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install fable-validate

fable-validate-fableplan-loop

Use when the user asks to validate a GitHub issue with Fable 5, always plan it with Fable 5, and autonomously drive it to a reviewed PR in one shot — "fable-validate-fableplan-loop", "fable validate, fable plan, and work on #N", "fully auto...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install fable-validate-fableplan-loop

fable-validate-loop

Use when the user asks to validate a GitHub issue with Fable 5 and then autonomously drive it to a reviewed PR in one shot — "fable-validate-loop", "fable validate and work on #N", "fully automate issue #N with fable". Runs fable-validate,...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install fable-validate-loop

fix-pr-review

Use when the user asks to fix, address, or respond to a PR review — "fix the PR review", "address the review comments", "/fix-pr-review". Takes an optional PR number/URL (defaults to the current branch's PR). Fetches all unaddressed review...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install fix-pr-review

fix-pr-review-loop

Use when the user asks to fix a PR review and drive it to approval autonomously — "fix the PR review and loop until approved", "fix-pr-review-loop", "keep addressing review comments until this PR is approved", or as the standalone counterpa...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install fix-pr-review-loop

github-issue-format

Required format for creating or editing any GitHub issue — [C<score>] title convention, complexity rationale line, complete-body rule, attribution footer. Load BEFORE creating or editing a GitHub issue.

Install

/plugin marketplace add richkuo/rk-skills
/plugin install github-issue-format

milestone-workflow

Use when the user wants a milestone of Execution-block-stamped GitHub issues implemented via a multi-agent dynamic workflow — "create the workflow for v0", "run v0 continuously", "/milestone-workflow v0". Builds dependency tracks, presents...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install milestone-workflow

new-app-pipeline

Use when the user wants to take a new app from raw idea to running multi-agent implementation — "/new-app-pipeline", "let's build a new app", "run the app pipeline on this idea". Orchestrates the full sequence - idea → PRD → question refine...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install new-app-pipeline

new-issue

Use when the user says "new issue", "create an issue", "file an issue", "/new-issue", or asks to turn a bug, idea, or discussion into a GitHub issue. Takes an optional description of what the issue should cover; with no input, derives the i...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install new-issue

new-issue-loop

Use when the user asks to file a GitHub issue and then autonomously drive it all the way to a reviewed PR in one shot — "new-issue-loop", "create the issue and run it to completion", "file this and fully automate it". Runs new-issue to crea...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install new-issue-loop

prd-questions

Use when the user wants every open question in a PRD resolved interactively — "ask me all questions", "/prd-questions", "let's resolve the open questions". Sweeps the PRD for open questions and ambiguities, asks them in batched multiple-cho...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install prd-questions

prd-to-issues

Use when the user wants a finished PRD broken into GitHub milestones and issues — "file the issues from the PRD", "/prd-to-issues", "break this into GitHub issues". Derives dependency-ordered milestones, files complete complexity-scored iss...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install prd-to-issues

pr-review-format

Required format and rules for writing any pull request (PR) review comment — verdict line, section structure, materiality filter, safety carve-out. Load BEFORE composing or posting a PR review.

Install

/plugin marketplace add richkuo/rk-skills
/plugin install pr-review-format

sync-docs

Use when the user asks to sync, update, or refresh CLAUDE.md, AGENTS.md, SKILL.md, and README.md to reflect recent commits or PRs. Triggers on phrases like "sync docs", "update CLAUDE.md", "update AGENTS.md", "update SKILL.md", "update READ...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install sync-docs

sync-docs-release

Use when the user wants to sync docs and then cut a release in one shot. Combines sync-docs → commit → create-release in sequence. Triggers on phrases like "sync docs and release", "sync and cut a release", "update docs and publish a releas...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install sync-docs-release

validate-fableplan-loop

Use when the user asks to validate a GitHub issue (without Fable), conditionally plan it with fableplan, then autonomously drive it to a reviewed PR in one shot — "validate-fableplan-loop", "validate, plan, and work on #N", "validate and fa...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install validate-fableplan-loop

validate-issue

Use when the user asks to validate, review, or check whether a GitHub issue is valid. Takes a GitHub issue URL or number (defaults to the latest open issue in the current repo). Verifies every factual claim against the actual code with file...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install validate-issue

validate-issue-loop

Use when the user asks to validate a GitHub issue and then autonomously drive it to a reviewed PR in one shot — "validate and work on this issue", "validate-issue-loop", "fully automate issue #N". Runs validate-issue, auto-applies its updat...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install validate-issue-loop

work-on-issue

Use when the user says "work on issue", "work on this issue", "implement issue", "/work-on-issue", or otherwise asks to implement a GitHub issue end-to-end (not merely validate it). Takes a GitHub issue URL or number (defaults to the just-v...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install work-on-issue

work-on-issue-loop

Use when the user asks to implement a GitHub issue and drive it through review to completion autonomously — "work on issue and loop until approved", "work-on-issue-loop", or as the automatic follow-on from validate-issue-loop. Runs work-on-...

Install

/plugin marketplace add richkuo/rk-skills
/plugin install work-on-issue-loop

Comments (0)

No comments yet

Be the first to share your take.