{
  "markdown": "# gh-issue-skills\n\nSix skills for the GitHub **issue and discussion lifecycle** — everything that\nhappens to a card before a branch exists, plus the one skill that turns a card\ninto file edits. Read an issue verbatim, file the current chat as a classified\nissue, implement it, execute the protocol a directive issue embeds, and author\nor promote an RFC-shaped Discussion. Packaged as a single plugin named\n`gh-issue`, installable on six coding-agent harnesses.\n\nIts siblings own the rest of the pipeline:\n[`gh-pr-skills`](https://github.com/dEitY719/gh-pr-skills) (commit -> PR ->\nreview -> merge) and [`gh-flow-skills`](https://github.com/dEitY719/gh-flow-skills)\n(one-shot compositions). Like\n[`gh-setup-skills`](https://github.com/dEitY719/gh-setup-skills), this repo owns\nno shared assets — it links out for the\n[per-harness tool mappings and the CI workflow](#shared-assets).\n\n## Skills\n\n| Skill | Invoke | What it does |\n|-------|--------|--------------|\n| `read` | `/gh-issue:read <N> [remote]` | Fetches one issue and prints a structured, **verbatim** summary — body and comments unaltered. Read-only; it mutates nothing. |\n| `create` | `/gh-issue:create [options]` | Saves the current conversation as an Issue, classified by conventional-commit prefix, with auto-labels, a dependency scan, and an ai-metrics footer. Stops and asks rather than inventing requirements the chat never decided. |\n| `implement` | `/gh-issue:implement <N> [mode] [remote]` | Claims the issue, moves its board card to `In progress`, captures a pre-edit test baseline, then edits and tests. **Never commits and never opens a PR.** |\n| `proceed` | `/gh-issue:proceed <N> [remote]` | Executes the 8-section protocol a *directive* issue embeds, unattended — strict schema validation, a safety gate per write step. Not a code implementer. |\n| `discussion-create` | `/gh-issue:discussion-create [category]` | Saves a pre-decision chat as an RFC-shaped Discussion (default `Ideas`). Refuses a decided to-do and routes it to `create`. |\n| `discussion-convert` | `/gh-issue:discussion-convert <N>` | Promotes a decided `Ideas` Discussion into a backlinked Issue, then locks and closes it. Idempotent. |\n\n`create` and `discussion-create` are a pair split by *decidedness*: a converged\nto-do becomes an Issue, an open question becomes a Discussion.\n`discussion-convert` is the bridge back once the question is settled.\n\n`read` is the only skill here that mutates nothing, which is why it is also the\none safe to point at someone else's repo.\n\n### Visual guides and worked examples (GitHub Pages)\n\n- `read` — [visual guide](https://deity719.github.io/gh-issue-skills/skill-guides/read.html) · [usage example](https://deity719.github.io/gh-issue-skills/skill-output/read-usage.html) (issue number to verbatim terminal summary)\n- `create` — [visual guide](https://deity719.github.io/gh-issue-skills/skill-guides/create.html) · [usage example](https://deity719.github.io/gh-issue-skills/skill-output/create-usage.html) (conversation to GitHub Issue)\n- `implement` — [visual guide](https://deity719.github.io/gh-issue-skills/skill-guides/implement.html) · [usage example](https://deity719.github.io/gh-issue-skills/skill-output/implement-usage.html) (issue to file edits and test run)\n- `proceed` — [visual guide](https://deity719.github.io/gh-issue-skills/skill-guides/proceed.html) · [usage example](https://deity719.github.io/gh-issue-skills/skill-output/proceed-usage.html) (directive issue to executed protocol)\n- `discussion-create` — [visual guide](https://deity719.github.io/gh-issue-skills/skill-guides/discussion-create.html) · [usage example](https://deity719.github.io/gh-issue-skills/skill-output/discussion-create-usage.html) (conversation to RFC Discussion)\n- `discussion-convert` — [visual guide](https://deity719.github.io/gh-issue-skills/skill-guides/discussion-convert.html) · [usage example](https://deity719.github.io/gh-issue-skills/skill-output/discussion-convert-usage.html) (Ideas Discussion to backlinked Issue)\n\nEach page is generated from a Markdown source under\n[`docs/skill-guides/`](docs/skill-guides) and [`docs/skill-output/`](docs/skill-output).\n\n## Requirements\n\n| Skill | Needs |\n|-------|-------|\n| `read` | An authenticated `gh` CLI with read access. Host and repo both resolve from one remote URL and are passed explicitly on every call. |\n| `create` | `gh` with write access to issues. Discussion routing additionally needs the discussion scopes. |\n| `implement` | `gh` with write access, plus a **clean working tree on a feature branch** — it refuses to run on the default branch and never creates a worktree for you. A test runner is detected if present; without one the test steps are skipped, not faked. |\n| `proceed` | `gh` with write access, same branch preconditions as `implement`, plus whatever the individual protocol's steps require. |\n| `discussion-create`, `discussion-convert` | `gh` with the GraphQL discussion scopes. `discussion-convert` also needs permission to lock and close. |\n\nEvery skill carries `GH_HOST` **and** `--repo` on every `gh` call, both resolved\nfrom the same remote URL. `--repo` alone names no server: on a dual-host login\n(github.com plus a GHES instance) a bare call silently queries the wrong one and\nreports an OPEN issue as \"not found\" (dEitY719/dotfiles#1403).\n\n## Install\n\n### Claude Code\n\n```\n/plugin marketplace add dEitY719/gh-issue-skills\n/plugin install gh-issue@gh-issue-skills\n```\n\n### Codex\n\n```\ncodex plugin install dEitY719/gh-issue-skills\n```\n\n### Kimi CLI\n\n```\nkimi plugin install dEitY719/gh-issue-skills\n```\n\n### Hermes Agent\n\n```\nhermes plugins install dEitY719/gh-issue-skills\n```\n\n### OpenCode\n\nSee [`.opencode/INSTALL.md`](.opencode/INSTALL.md).\n\n### Gemini CLI / Antigravity\n\n```\ngemini extensions install https://github.com/dEitY719/gh-issue-skills\n```\n\nAntigravity (`agy`) shares `~/.gemini`, so it inherits the install.\n\n## Harness support\n\nThese are `gh` CLI calls and file writes, so they port cleanly with one\nexception — `implement`'s TDD path calls `superpowers:test-driven-development`\nthrough Claude Code's `Skill()` tool. Every gap and its workaround is documented\nper harness in\n[`harness-skills/references/`](https://github.com/dEitY719/harness-skills/tree/main/references);\nread the one file for the harness you are on.\n\n| Skill | Claude Code | Codex | Kimi | Gemini / Antigravity | Hermes | OpenCode |\n|-------|:-----------:|:-----:|:----:|:--------------------:|:------:|:--------:|\n| `read` | full | full | full | full | full | full |\n| `create` | full | full, confirm in chat | full | full on Gemini, confirm in chat on Antigravity | full, confirm in chat | full, confirm in chat |\n| `implement` | full | fallback path | fallback path | fallback path | fallback path | fallback path |\n| `proceed` | full | full | full | full | full | full |\n| `discussion-create` | full | full, confirm in chat | full | full on Gemini, confirm in chat on Antigravity | full, confirm in chat | full, confirm in chat |\n| `discussion-convert` | full | full | full | full | full | full |\n\n*fallback path* — `implement` picks between two complete routes. The TDD path\nneeds `superpowers:test-driven-development` to resolve **and** a test runner to be\ndetected; otherwise it runs the built-in path (pre-edit baseline, edits, test run,\nbounded 3-attempt failure loop, full report), as harnesses without a `Skill()`\nequivalent always do. Same finish line — the skill never requires the plugin.\n\n*confirm in chat* — two steps need a real answer: `create`'s clarification guard\n(conversation has not converged) and `discussion-create`'s category selection.\nKimi (`AskUserQuestion`) and Gemini CLI (`ask_user`) have a structured question\ntool; Codex, Hermes, Antigravity, and OpenCode do not, so ask and wait for a real\nreply. An auto-approve session setting is not the user's answer.\n\n## Shared assets\n\nThis repo owns none — deliberately.\n\n- **Per-harness tool mappings** live in\n  [`harness-skills/references/`](https://github.com/dEitY719/harness-skills/tree/main/references)\n  (`{codex,kimi,gemini,antigravity,hermes,opencode}-tools.md`). That repo is\n  their sole owner; the other fourteen `*-skills` repos link there rather than\n  carrying copies, so one tool rename is one edit, not fifteen\n  (dEitY719/dotfiles#1410 F-5 / NF-2). The only condensed mirror here is\n  `.kimi-plugin/plugin.json`'s `skillInstructions`, because Kimi CLI cannot read\n  a reference file at load time — it points back to the canonical file.\n- **The reusable CI workflow** is\n  [`harness-skills/.github/workflows/skill-check.yml`](https://github.com/dEitY719/harness-skills/blob/main/.github/workflows/skill-check.yml)\n  (dEitY719/dotfiles#1410 D-10). See [CI](#ci).\n\n## Layout\n\nManifests live at the repo root and all point at one flat `skills/` directory:\n\n```\n.\n├── skills/{read,create,implement,proceed,discussion-create,discussion-convert}/\n│   ├── SKILL.md\n│   └── references/\n├── .claude-plugin/{marketplace,plugin}.json     Claude Code\n├── .codex-plugin/plugin.json                    Codex\n├── .kimi-plugin/plugin.json                     Kimi CLI\n├── .hermes-plugin/{plugin.yaml,__init__.py}     Hermes Agent\n├── .opencode/plugins/gh-issue.js + INSTALL.md   OpenCode\n├── .agents/plugins/marketplace.json             Antigravity\n├── gemini-extension.json + GEMINI.md            Gemini CLI\n├── package.json\n├── CLAUDE.md · AGENTS.md -> CLAUDE.md\n└── LICENSE\n```\n\nOnly Claude Code understands a nested `plugins/<name>/skills/` layout; the other\nfive resolve manifests at the repo root and a skills tree at `./skills/`, so this\nrepo keeps everything flat. Skill directory names dropped their old `gh-issue-` /\n`gh-` prefixes in the migration — `/gh-issue:gh-issue-implement` stutters and the\nnamespace already carries that meaning (dEitY719/dotfiles#1410 F-4). `.kimi-plugin/` is\npre-provisioned for a CLI not yet installed. Rationale: [`CLAUDE.md`](CLAUDE.md).\n\n## Cross-repo names\n\nUnlike the Phase 2 repos, this one was migrated **after** the Phase 3 names were\nfixed, so references to sibling repos are written in their final form even where\nthe sibling does not exist yet (dEitY719/dotfiles#1676 §2):\n\n| Old | New | Lives in |\n|-----|-----|----------|\n| `gh:issue-read` / `-create` / `-implement` / `-proceed` | `gh-issue:read` / `:create` / `:implement` / `:proceed` | this repo |\n| `gh:discussion-create` / `-convert` | `gh-issue:discussion-create` / `:discussion-convert` | this repo |\n| `gh:commit` | `gh-pr:commit` | `gh-pr-skills` |\n| `gh:pr` | `gh-pr:create` | `gh-pr-skills` |\n| `gh:pr-merge` | `gh-pr:merge` | `gh-pr-skills` |\n| `gh:issue-flow` | `gh-flow:issue` | `gh-flow-skills` |\n| `devx:autopilot` | `gh-flow:autopilot` | `gh-flow-skills` |\n| `devx:trd-to-issues` | `spec-flow:trd-to-issues` | `spec-flow-skills` |\n\nOne thing deliberately did **not** move: the `[step:gh-issue-implement/<id>] OK`\nand `[step:gh-issue-proceed/<id>] OK` marker lines — a wire format matched\nverbatim by `dEitY719/dotfiles/claude/hooks/skill_completion_guard.py` against its\n`skill_step_catalog.yml` keys. Renaming them would break the guard (dEitY719/dotfiles#1676 NF-4).\n\n## CI\n\n[`.github/workflows/validate.yml`](.github/workflows/validate.yml) calls the\nreusable workflow owned by `harness-skills`:\n\n```yaml\njobs:\n  validate:\n    uses: dEitY719/harness-skills/.github/workflows/skill-check.yml@main\n    with:\n      plugin-name: gh-issue\n      allow-emoji-paths: |\n        lib/ai-metrics-footer.sh\n        ...\n```\n\nIt validates manifests, skill frontmatter (the `name:` must be bare and match\nthe directory), progressive-disclosure line limits, the Codex description budget,\nversion agreement across all seven manifests, shell scripts, and the no-emoji\nrule. There is no local copy to keep in sync; a check added upstream applies here\non the next run.\n\nThe `allow-emoji-paths` entries cover text the skills **quote** rather than\ndecorate with: the ai-metrics footer, whose glyphs are the wire format itself\n(dEitY719/dotfiles#317 F-2, PR dEitY719/dotfiles#320), and the `Postpone` block label that `implement` and\n`proceed` refuse to start on. Nothing else in the repo may carry an emoji.\n\n## Provenance\n\nExtracted from [`dEitY719/dotfiles`](https://github.com/dEitY719/dotfiles)\n(`claude/skills/{gh-issue-read,gh-issue-create,gh-issue-implement,gh-issue-proceed,gh-discussion-create,gh-discussion-convert}`)\nas a content snapshot — no history rewriting, behaviour unchanged. Only the\nnamespace moved, from `gh:` to `gh-issue:`, and the directory names lost their\nnow-redundant prefixes. That source tree is gone — Phase 4 removed the dotfiles\ncopies (dEitY719/dotfiles#1410 NF-1 / NF-3).\nThis is Phase 3, shared with `gh-pr-skills` and `gh-flow-skills`;\n`packaging-skills` was Phase 0 and `harness-skills` (Phase 1) owns the shared assets.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 12834,
  "sha": "4c5145d2efdf64dab3cbedb53c43e5435b40107a36ae4e7af7a77c132c802b4a",
  "repo_slug": "deity719/gh-issue-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_deity719_gh_issue_skills_1f348161/readme"
}