# Github Ops

> GitHub remote operations — repo creation, metadata (description/homepage/topics), releases, README 'Recent Updates' enforcement, issue / PR management with preview-before-send discipline, and read-only repo security-posture auditing. Companion to git-ops (local) and push-gate (pre-push safety). Three modes: new (first publish), update (subsequent release), audit (read-only checklist), plus atomic…

- **Type:** Skill
- **Install:** `agentstack add skill-0xdarkmatter-claude-mods-github-ops`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [0xDarkMatter](https://agentstack.voostack.com/s/0xdarkmatter)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [0xDarkMatter](https://github.com/0xDarkMatter)
- **Source:** https://github.com/0xDarkMatter/claude-mods/tree/main/skills/github-ops
- **Website:** https://github.com/0xDarkMatter/claude-mods#readme

## Install

```sh
agentstack add skill-0xdarkmatter-claude-mods-github-ops
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# GitHub Ops

GitHub-side operations skill. Owns everything that talks to `api.github.com` via `gh` CLI: repo creation, metadata configuration, releases, and the conventions that govern how 0xDarkMatter repos present on GitHub.

Sits alongside two related skills:

```
LOCAL                          BRIDGE              REMOTE (GitHub)
─────                          ──────              ───────────────
git-ops                        push-gate           github-ops  (this skill)
```

| Concern | Owner |
|---|---|
| Commits, branches, local tags, rebases, worktrees, stash | `git-ops` |
| Pre-push secret scan + dirty-tree refusal + confirm | `push-gate` |
| `gh repo create`, push to remote, tag push | **`github-ops`** |
| Repo description / homepage / topics / visibility | **`github-ops`** |
| `gh release create` + release notes | **`github-ops`** |
| README "Recent Updates" section maintenance | **`github-ops`** |
| Package metadata audit (pyproject/package.json ↔ GH topics ↔ tag ↔ version) | **`github-ops`** |
| `gh issue` operations (view/list/create/comment/edit/triage/close) | **`github-ops`** |
| `gh pr` operations (view/list/diff/checks/create/comment/review/edit/merge/close) | **`github-ops`** |
| Security posture audit (Dependabot / secret+code scanning / PVR / SECURITY.md / branch protection) — read-only | **`github-ops`** (`scripts/check-security-posture.sh`) |
| Actions / secrets / social preview / branch-protection *writes* | **`github-ops`** (future) |

## Hard rules

1. **Visibility defaults to private.** Pass `--private` to `gh repo create` unless the user has explicitly said "public" / "make it public" for this specific repo. See `references/repo-visibility.md`.
2. **Major version bumps require explicit approval.** Default to minor; patch for fix-only ranges. Never auto-suggest a 1.0.0 from `BREAKING CHANGE:` markers — surface and ask. See `references/release-strategy.md`.
3. **Always run `push-gate` before any push to a remote.** No exceptions. If push-gate refuses, do not proceed — fix the cause and re-run.
4. **Delegate local git operations to `git-ops`.** Don't reimplement commit/tag/push logic. github-ops orchestrates the GitHub-side calls (`gh`) and the README/CHANGELOG edits; git-ops handles git itself.
5. **README "Recent Updates" updates on every release.** This is the one README touch that always happens, regardless of how minor the release. See `references/readme-recent-updates.md` for the canonical claude-mods style.
6. **Never push without confirming visibility decision.** When creating a new repo, surface visibility as a flippable line in the plan ("creating as **private** — say 'public' to flip"), not buried in flag soup.
7. **No local-machine paths in committed content.** Never bake `C:\Users\\…`, `/home//…`, `/Users//…`, `/tmp/`, or any other machine-specific path into README entries, Recent Updates bullets, CHANGELOG entries, release notes, tag annotations, or commit messages. Public release artefacts have to read the same on someone else's machine. Use generic placeholders (`~/Temp/`, ``, "a temp directory") or describe the file's purpose abstractly instead. If a path genuinely is part of the project's public API (install location, config path), state it canonically (`$HOME/.claude/skills/...`), not as a literal absolute that includes a user name.
8. **Preview every public post before sending.** Anything with author voice that lands on a third-party surface — `gh issue create/comment/edit --body`, `gh pr create/comment/review/edit --body`, `gh release create --notes`, merge commit `--subject`/`--body` — must be quoted verbatim in chat with the exact send command named, then await explicit approval before invoking. Mechanical actions with no body (label, assign, milestone, mark-ready, close-without-message) skip preview. See `~/.claude/rules/public-posts.md` for the full rule.

## Three modes

### Mode `new` — first publish of a repo

Triggered by: "publish to github", "create repo on github", "push to github" (when no `origin` remote exists), "ship this repo".

```
1. Audit (run mode `audit` checklist; abort on critical fail)
   - LICENSE present?
   - README has tagline + install + quickstart?
   - pyproject.toml / package.json has description, keywords, license, repository URL?
   - At least one tag exists (typically v0.1.0)?
   - CHANGELOG.md has an entry for the latest tag?

2. Draft / refine README intro (2–3 paragraphs) — see references/readme-description.md
   - If the README intro is just a tagline or / — say 'public' to flip"
   Wait for explicit confirmation.

5. Create the repo:
   gh repo create / --private --source=. --remote=origin \
     --description "" \
     --homepage ""
   (NEVER pass --push; we want push-gate to run between)
   Note: the GitHub `--description` is a single line and distinct from the README intro.
   Derive it FROM the intro you just wrote, not from package metadata blindly.

6. Run push-gate preflight:
   bash $HOME/.claude/skills/push-gate/scripts/preflight.sh --cwd  origin main
   On any non-zero exit: stop, report, do not push.

7. Push main + tags:
   git -C  push -u origin main
   git -C  push origin --tags

8. Set topics (derived from package keywords + language + frameworks):
   gh repo edit / --add-topic  --add-topic  ...
   Aim for 6–12 topics. See references/metadata-checklist.md for derivation.

9. Create the release for the latest tag:
   gh release create  --title " — " \
     --notes "$(extract from CHANGELOG.md)"

10. Verify:
    gh repo view /
    gh release view 
    Report URL to user.
```

### Mode `update` — subsequent release

Triggered by: "ship a release", "cut a release", "release v0.X.Y", "publish update".

```
1. Audit current state vs last release:
   git -C  log $(git describe --tags --abbrev=0)..HEAD --oneline
   Categorise commits by Conventional Commits prefix.

2. Determine version bump (see references/release-strategy.md):
   - Any feat: → minor (default)
   - Only fix:/chore:/docs:/perf:/style:/test: → patch
   - Any BREAKING CHANGE: or !: → STOP, ask user, never auto-major

3. Update CHANGELOG.md:
   New section for the new version with categorised changes (Added/Changed/Fixed/Removed).
   Delegate the file edit + commit to git-ops with: docs: CHANGELOG for v

4. Update README "Recent Updates":
   Prepend a new version block (claude-mods style) at the top of the section.
   Trim oldest if section exceeds 7 versions.
   Bullets per change, emoji + bold tagline + 1-3 sentence prose.
   See references/readme-recent-updates.md for the emoji vocabulary.

   For minor: update Recent Updates AND scan diff for new commands/config/install steps;
              touch README body sections only if found.
   For patch: update Recent Updates ONLY (single bullet); no body changes unless asked.

   Also: if the README intro is still 

6. Create local tag via git-ops:
   git tag -a v -m "v"

7. Run push-gate preflight:
   bash $HOME/.claude/skills/push-gate/scripts/preflight.sh --cwd  origin 
   On any non-zero exit: stop, report, do not push.

8. Push commits + tag:
   git push origin 
   git push origin v

9. Create GitHub release:
   gh release create v --title "v — " \
     --notes "$(extract CHANGELOG section for v)"

10. Verify:
    gh release view v
    Report URL to user.
```

### Mode `audit` — read-only checklist

Triggered by: "audit github repo", "is this repo ready to publish", "check repo metadata", "score this repo", "how healthy is this repo", "score the fleet".

**Headline: `scripts/repo-scorecard.sh` — one command for a scored repo/fleet health report.** It orchestrates the two read-only auditors (`check-security-posture.sh` + `check-issues.sh`) and adds metadata / release / actions signals, rolling everything into a single **0–100 score + letter grade** per repo, and a **matrix + roll-up** across an org. Reach for it first; drop to the manual checklist below only when you need a specific row the scorecard doesn't surface.

```bash
bash scripts/repo-scorecard.sh --repo 0xDarkMatter/flarecrawl     # single repo: score + dimensions + top 3 fixes
bash scripts/repo-scorecard.sh --org 0xDarkMatter                 # fleet matrix + roll-up (avg/median/worst, fleet open-alert total)
bash scripts/repo-scorecard.sh --org 0xDarkMatter --min-score 75  # CI gate: exit 10 if ANY repo scores / --json | jq '.data[0].top_fixes'
```

Five weighted dimensions — **security (35)** highest, then **metadata (25)**, **release (15)**, **issues (15)**, **actions (10)**. Each scores its weight in full (ok) / half (warn) / zero (gap **or** unreadable n/a — an unreadable dimension never counts as healthy). Grade: A≥90 B≥75 C≥60 D≥40 F/` and fold its checklist in; the enable commands it emits are surfaced for the user to approve, never auto-run.

## Operations

Atomic GH-side actions that don't fit the three multi-step modes. Each operation that writes author voice to a third-party surface (issue/PR body, comment, review body, release notes, merge commit subject/body) is governed by **hard rule 8** and [public-posts](~/.claude/rules/public-posts.md): quote the exact body in chat, name the send command, wait for explicit approval, then send. Mechanical actions (labels, assign, close-without-message, mark-ready) skip preview.

### Issues

Reads (no preview): `gh issue view `, `gh issue view  --comments`, `gh issue list`, `gh api repos///issues/` (for fields not in the default view).

Writes:

| Op | Command | Preview? |
|---|---|---|
| Create | `gh issue create --title --body` | **Yes** (title + body) |
| Comment | `gh issue comment  --body` | **Yes** (body) |
| Edit title/body | `gh issue edit  --title --body` | **Yes** |
| Triage (label/assign/milestone) | `gh issue edit  --add-label … --assignee … --milestone …` | No (mechanical) |
| Close / reopen | `gh issue close ` / `gh issue reopen ` | No, **unless** closing with a comment — preview the comment |
| Transfer | `gh issue transfer  ` | No (mechanical), but confirm target with user |

See `references/issue-ops.md` for full playbooks, triage flow, and closing-comment templates.

### Pull Requests

Reads (no preview): `gh pr view `, `gh pr view  --comments`, `gh pr list`, `gh pr diff `, `gh pr checks `, `gh pr checks  --watch`, `gh api repos///pulls//comments` (inline review comments).

Writes:

| Op | Command | Preview? |
|---|---|---|
| Create | `gh pr create --title --body` | **Yes** (title + body) |
| Comment | `gh pr comment  --body` | **Yes** |
| Review (approve / request changes / comment) | `gh pr review  --approve --body …` | **Yes** (body, if any) |
| Edit title/body | `gh pr edit  --title --body` | **Yes** |
| Edit labels / reviewers | `gh pr edit  --add-label … --add-reviewer …` | No (mechanical) |
| Mark ready (un-draft) | `gh pr ready ` | No (mechanical) |
| Merge | `gh pr merge  --squash` (or `--merge` / `--rebase`) | No body to preview by default, but **explicit user approval required** + run pre-merge gate first. If passing `--subject` / `--body`, preview those (they become the commit message on `main`) |
| Close | `gh pr close ` | No, **unless** closing with a comment — preview the comment |

**PR creation lives here, not in git-ops.** git-ops handles local commits/branches/push; the `gh pr create` call itself talks to `api.github.com` and belongs in this skill. (Existing git-ops T2 PR-create still works; new flows should route through github-ops.)

**Pre-merge gate** — never invoke `gh pr merge` without first confirming:

1. `gh pr view  --json mergeable,mergeStateStatus` → `mergeable: MERGEABLE`, `mergeStateStatus: CLEAN`
2. `gh pr checks ` → every check passed (or explicitly ignored with user approval)
3. `gh pr diff ` reviewed — confirm no surprise scope, no committed secrets/local paths, no stale PR-body claims
4. Merge strategy picked — **default squash** for fix/feature branches with multiple WIP commits; `--merge` only when individual commits matter; `--rebase` for linear-history repos. Ask if uncertain.
5. Branch deletion is a **separate explicit step**, not bundled. Default to keeping the branch; delete remote + local after merge only on explicit user OK (it's destructive enough to warrant its own confirmation, and a checked-out branch can't be deleted).

See `references/pr-ops.md` for full playbooks, review-flow templates, and the merge-strategy decision tree.

## Conventions enforced (load reference files for detail)

| Convention | File | Default |
|---|---|---|
| Release strategy | `references/release-strategy.md` | minor on `feat:`, patch on `fix:`-only, major requires approval |
| README intro (2–3 paragraphs) | `references/readme-description.md` | what it is / why it exists / who it's for; concrete, dry, no marketing fluff |
| README Recent Updates style | `references/readme-recent-updates.md` | claude-mods per-version blocks (alternate: flarecrawl table) |
| Repo visibility default | `references/repo-visibility.md` | `--private` unless user says "public" |
| Metadata audit checklist | `references/metadata-checklist.md` | full source-of-truth for mode `audit` |
| Issue operations | `references/issue-ops.md` | view → triage → comment (with preview) → close; closing comments preview-gated |
| PR operations | `references/pr-ops.md` | create (preview body) → review → pre-merge gate → squash by default; branch deletion separate explicit step |

## Git authorship

For 0xDarkMatter repos, set repo-local config before any commit work:

```bash
git -C  config user.name "0xDarkMatter"
git -C  config user.email "0xDarkMatter@users.noreply.github.com"
```

Verify with `git -C  config user.name`. If a commit was made under a different identity *before* publish (no push has happened), rewrite via:

```bash
git -C  rebase --root --exec 'git commit --amend --reset-author --no-edit'
```

After history rewrite, re-create any tags so they point at the new SHAs:

```bash
git -C  tag -d v0.1.0
git -C  tag -a v0.1.0 -m "..."
```

This is safe pre-publish only. After push, treat history as immutable and set authorship correctly going forward.

## Delegation pattern

```
github-ops           git-ops              push-gate
─────────            ───────              ─────────
mode `new`:
  audit
  edit README   ───► commit (T2)
                                          preflight (before push)
  gh repo create
                ───► push -u origin main
                ───► push --tags
  gh repo edit (topics)
  gh release create
  verify

mode `update`:
                ───► CHANGELOG edit + commit (T2)
  edit Recent Updates
                ───► commit (T2)
                ───► tag (T2)
                                          preflight (before push)
                ───► push (T2)
                ───► push tag (T2)
  gh release create
  verify
```

When invoking git-ops T2 operations, dispatch to git-agent with a one-shot prompt — no need to load the full git-ops orchestrator state for these mechanical steps.

## Future expansion (not yet implemented)

- **Actions** — workflow file scaffolding, `gh workflow` operations
- **Secrets** — `gh secret set/list/delete` (with secure handling)
- **Branch protection** — `gh api` calls for protection rules
- **Social preview** — image upload via `gh api`
- **Org-level** — teams, repo templates

When adding any of the above, keep the boundary discipline: anything talking to `api.github.com` belongs here, anything purely local belongs to `git-ops`.

## Files

| File | Role |
|---|---|
| `SKILL.md` | This file — modes, rules, delegation |
| `references/release-strategy.md` | Version bump policy |
| `references/readme-description.md` | 2–3 paragraph README intro — voice, structure, anti-patterns |
| `references/readme-recent-updates.md` | "Recent Updates" section format + emoji vocabulary |
| `references/repo-visibility.md` | Private-by-default policy |
| `references/metadata-checklist.md` | Audit checklist source of truth |
| `references/issue-ops.md` | Issue operation playbooks (view/triage/comment/create/close) + preview template

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [0xDarkMatter](https://github.com/0xDarkMatter)
- **Source:** [0xDarkMatter/claude-mods](https://github.com/0xDarkMatter/claude-mods)
- **License:** MIT
- **Homepage:** https://github.com/0xDarkMatter/claude-mods#readme

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-0xdarkmatter-claude-mods-github-ops
- Seller: https://agentstack.voostack.com/s/0xdarkmatter
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.