Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/hirokisakabe/issuekit

Agent Skills for issue-driven development.
https://github.com/hirokisakabe/issuekit

agent-skills claude-code claude-code-skills issue-driven-development skills-sh

Last synced: 9 days ago
JSON representation

Agent Skills for issue-driven development.

Awesome Lists containing this project

README 

          



# 🧷 issuekit



### _Issue-driven development for AI coding agents._



A Claude Code skill bundle that treats each GitHub issue as the canonical "rich plan" for a unit of work β€” so volatile specs stay out of your repository and only durable code gets versioned.



[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

[![Install via skills.sh](https://img.shields.io/badge/install-skills.sh-black)](https://skills.sh)

[![Claude Code](https://img.shields.io/badge/Claude_Code-skill_bundle-D97757)](https://docs.claude.com/en/docs/claude-code)






---



> [!NOTE]

> **Japanese-oriented plugin.** Skill bodies, descriptions, and this README are written in English, but the skills read Japanese section headers (e.g. `## 受けε…₯γ‚Œζ‘δ»Ά`) hardcoded into issue bodies. Issue contents themselves are expected to remain in Japanese. To use issuekit with English-only issues, you will currently need to fork and adjust the hardcoded keywords.



> [!IMPORTANT]

> **Casual OSS.** No SLA, no response guarantees. Distributed as-is for users who share the underlying philosophy. PRs and issues are welcome but may be closed without action if they conflict with the maintainer's solo-dev workflow.



## Table of Contents



- [πŸ“¦ Install](#-install)

- [πŸ› οΈ Dependencies](#-dependencies)

- [🧩 Skills](#-skills)

- [πŸ” Workflow](#-workflow)

- [πŸ’‘ Philosophy](#-philosophy)

- [πŸ†š Comparison with related frameworks](#-comparison-with-related-frameworks)

- [πŸ“„ License](#-license)



---



## πŸ“¦ Install



### via `gh skill` (recommended β€” supports version pinning)



```bash

# Install a skill interactively (choose from the list)

gh skill install hirokisakabe/issuekit



# Install a specific skill (e.g. issue-implement)

gh skill install hirokisakabe/issuekit issue-implement



# Pin to a specific version

gh skill install hirokisakabe/issuekit issue-implement@v1.0.0



# Or use the --pin flag

gh skill install hirokisakabe/issuekit issue-implement --pin v1.0.0



# Install for Claude Code at user scope explicitly

gh skill install hirokisakabe/issuekit issue-implement --agent claude-code --scope user

```



The install location depends on `--agent` and `--scope`; for Claude Code at user scope, skills land in `~/.claude/skills/`. Version tags follow [GitHub Releases](https://github.com/hirokisakabe/issuekit/releases).



### via `npx skills` (Claude Code, Codex CLI, Cursor, Gemini, …)



```bash

# Install all seven skills (always installs HEAD β€” version pinning not yet supported)

npx skills add hirokisakabe/issuekit



# Or install a specific skill only

npx skills add hirokisakabe/issuekit --skill issue-implement

```



This installs the skills under your agent's skill directory (e.g. `~/.claude/skills/` for Claude Code). See [skills.sh](https://skills.sh) for the list of supported agents (Claude Code, Codex CLI, Cursor, Gemini, ...).



---



## πŸ› οΈ Dependencies



issuekit assumes the following tools are available on the host:



- **An [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)-compatible agent runtime** (e.g. [Claude Code](https://docs.claude.com/en/docs/claude-code), Codex CLI, Cursor) that loads the skills.

- **[`gh` CLI](https://cli.github.com/)** β€” used for all GitHub interactions (issue read/write, PR creation, CI status).

- **At least one cross-review backend CLI** β€” required by `cross-review`. Pick whichever pairs with the agent driving the implementation:

  - **[Codex CLI](https://github.com/openai/codex)** (`brew install --cask codex`) for the `codex` backend.

  - **[Claude CLI](https://docs.claude.com/en/docs/claude-code)** (`npm install -g @anthropic-ai/claude-code`) for the `claude-self` backend (uses `claude --bare -p` headless mode).

- **Claude Code v2.1.49 or newer** β€” required by `worktree-start` only (it uses the `EnterWorktree` tool added in 2.1.49). The other six skills run on any Agent Skills-compatible runtime.



`gh` must be authenticated against the repository you want to operate on. The `cross-review` backend is selected via the `CROSS_REVIEW_BACKEND` environment variable (`codex` / `claude-self`); if it is unset, the skill auto-detects whichever CLI is on `PATH`. If neither backend CLI is available, `cross-review` fails explicitly rather than silently skipping the review.



---



## 🧩 Skills



issuekit ships seven Claude Code skills under `skills/`:



| Skill                | Role        | Description                                                                                                                                            |

| -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |

| `issue-create`       | Entry point | Open a new GitHub issue using issuekit's standard format (`Status: Ready` / `Status: Draft` header, intent, plan, acceptance criteria, out-of-scope).  |

| `issue-refine`       | Entry point | Re-shape an existing issue (title-only or partially formatted) into the standard format.                                                               |

| `issue-pick`         | Entry point | Read-only triage: from a set of open issues, suggest the next one to take on, with rationale.                                                          |

| `worktree-start`     | Entry point | **Claude Code only.** Switch the running session into a freshly named git worktree via the `EnterWorktree` tool. Accepts a task description **or** an issue URL/number β€” when the input is a `Status: Ready` issue, it chains into `issue-implement` after the worktree switch (otherwise it stops at the switch). |

| `issue-implement`    | Orchestrator| Drive the full cycle from an issue number: status check β†’ worktree start β†’ implementation / commits β†’ acceptance check β†’ cross-review β†’ PR β†’ CI.     |

| `acceptance-check`   | Verifier    | Read-only verifier that extracts `## 受けε…₯γ‚Œζ‘δ»Ά` from an issue body and reports each item as `βœ“ / βœ— / ?`. Called by `issue-implement` after implementation/commits, before `cross-review`. |

| `cross-review`       | Verifier    | Delegate a second-opinion code review to a different AI backend (Codex CLI or Claude CLI headless, selectable via `CROSS_REVIEW_BACKEND`) before PR creation. Called by `issue-implement` after `acceptance-check` passes; review fixes land as additional commits. |



`issue-implement` is the orchestrator; the other skills are either entry points or verifiers it calls. `worktree-start` is the only entry point that is Claude Code-specific (`EnterWorktree` is a Claude Code primitive β€” Codex CLI has no equivalent), so it has no fallback under other agent runtimes. It is also the only entry point that conditionally chains into the orchestrator: when invoked with an issue URL/number whose body has `Status: Ready`, it hands off to `issue-implement` after the worktree switch.



---



## πŸ” Workflow



The skills compose into a single issue-driven cycle. Entry points feed an issue into the orchestrator, which calls the verifiers before producing a commit and a PR.



```mermaid

flowchart LR

    A[issue-create] --> I[(GitHub issue
Status: Ready)]

    R[issue-refine] --> I

    P[issue-pick] -. suggests .-> I

    I --> W[worktree-start]

    W --> IMPL[issue-implement
implementation + commits]

    IMPL --> AC[acceptance-check]

    AC --> CR[cross-review]

    CR --> C[PR + CI]



    classDef entry fill:#e8f4ff,stroke:#3b82f6,color:#1e3a8a

    classDef orch  fill:#fef3c7,stroke:#d97706,color:#78350f

    classDef ver   fill:#ecfdf5,stroke:#10b981,color:#065f46

    classDef out   fill:#f3f4f6,stroke:#6b7280,color:#1f2937



    class A,R,P,W entry

    class IMPL orch

    class CR,AC ver

    class I,C out

```



---



## πŸ’‘ Philosophy



Most "spec-driven" or "plan-driven" frameworks for AI coding agents store the spec **in the repository** as markdown files (`spec.md`, `plan.md`, etc.) checked in alongside the code. issuekit takes a different position:



- **Specs and plans are volatile.** They describe a single unit of intent. Once the work is merged, the plan is dead β€” what survives is the code, the test, and (if anything) a one-line commit message.

- **Versioning volatile artifacts in git is friction.** A merged plan rots in the repo, gets stale, and pollutes diffs and search.

- **GitHub issues are already a versioned, queryable, time-bounded plan store.** They have state (`open` / `closed`), threading, references, and a natural lifecycle that matches the work itself.



So issuekit treats the **GitHub issue as the rich plan** for the work, and the repository contains only the durable artifacts (code, tests, configs). When the issue is closed, the plan disappears from the active surface area β€” exactly as intended.



This is opinionated. issuekit will not be a good fit if you want plans to live next to the code, or if your team's workflow expects spec markdown checked in.



---



## πŸ†š Comparison with related frameworks



issuekit shares one core idea with Spec Kit, cc-spex, and superpowers: **make the "what" an explicit contract that an AI agent can read, follow, and be checked against.** Where they differ is _where_ that contract lives, and how compliance is verified.



| Framework                                          | Contract location                                           | Verification model                                                                                    | Fit                                                 |

| -------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------- |

| [Spec Kit](https://github.com/github/spec-kit)     | Spec markdown checked into the repo                         | Agent re-reads the spec                                                                               | Teams that want specs versioned alongside code      |

| [cc-spex](https://github.com/rhuss/cc-spex)        | Spec markdown checked into the repo                         | Agent re-reads the spec                                                                               | Solo / small team, lighter than Spec Kit            |

| [superpowers](https://github.com/obra/superpowers) | Skill bundle of general-purpose engineering workflows       | Skill conventions + agent judgment                                                                    | Broad augmentation of Claude Code; not spec-centric |

| **issuekit**                                       | GitHub issue body (`## 受けε…₯γ‚Œζ‘δ»Ά`, `## γ‚Ήγ‚³γƒΌγƒ—ε€–`, ...) | `acceptance-check` skill mechanically verifies each acceptance criterion as `βœ“ / βœ— / ?` before PR creation | Solo dev who already runs an issue-first workflow   |



The differentiator that matters most to issuekit's design is the **verification model**. Detailed specs help agents stay on-rails, but spec compliance is itself a problem: the longer the spec, the more places the agent can drift. issuekit's response is structural rather than prescriptive β€” instead of writing more spec, write fewer but **mechanically verifiable** acceptance criteria, and have a dedicated skill (`acceptance-check`) check them before PR creation. The spec stays small; the verification stays honest.



---



## πŸ“„ License



[MIT](./LICENSE)