github-ops

Files (19)

• SKILL.md
• SECURITY.md.template · assets/
• auditor-scripts.md · references/
• delegation-and-authorship.md · references/
• files.md · references/
• issue-ops.md · references/
• metadata-checklist.md · references/
• operations-preview.md · references/
• pr-ops.md · references/
• readme-description.md · references/
• readme-landing-page.md · references/
• readme-recent-updates.md · references/
• readme-steps.md · references/
• release-strategy.md · references/
• repo-visibility.md · references/
• check-issues.sh · scripts/
• check-security-posture.sh · scripts/
• repo-scorecard.sh · scripts/
• run.sh · tests/

SKILL.md (first lines)

# 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-preflight      github-ops  (this skill)
```

Ownership by concern, row by row: [references/delegation-and-authorship.md](references/delegation-and-authorship.md).

## 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-preflight` before any push to a remote.** No exceptions. If push-preflight 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\<name>\…`, `/home/<name>/…`, `/Users/<name>/…`, `/tmp/<one-off-test-dir>`, 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/`, `<temp-dir>`, "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
   - Tagline only or under 80 words: draft 2–3 paragraphs (what / why / for whom) from
     metadata, CHANGELOG and the entry point, never fabricated; get approval first.
     Detail: references/readme-steps.md
   - Commit via git-ops with: docs: Expand README intro

2b. Build the landing-page layer — see references/readme-landing-page.md
   The intro answers "what is this"; this step answers the other three questions a
   cold visitor asks in their first ten seconds (is it alive / what do I get /
   what does it look like). Benefits before mechanics.

   FIRST pick the register, and surface it as a flippable line like visibility:
     "Laying the README out as **Reference** — say 'showcase' to flip"
   - Showcase — reader is deciding WHETHER to adopt. Apps, dashboards, TUIs,
     generators, anything with visible output. Visual high, Features above Install,
     airier prose.
   - Reference — reader has already decided and needs to USE it. Libraries, SDKs,
     plain-output CLIs, internal tooling. Install + a real usage example in the
     first screenful; Features denser and lower.
   Tie-breakers: output is visible → Showcase. It's a dependency of other code →
   Reference. Register controls emphasis and density, NEVER honesty — Showcase is
   not permission for marketing verbs; the readme-description.md anti-patterns
   apply identically to both. Never mix the two.

   Then, in either register: badge row, Features above Install written as benefits,
   and a screenshot only if there is a visual surface. Rules: references/readme-steps.md
   - Surface the layout to the user with the intro draft; commit together.

3. Add "Recent Updates" section to README if missing
   - Use claude-mods style by default (see references/readme-recent-updates.md)
   - Place after Quickstart, before deep "why this exists" sections — i.e. below the
     Features + visual added in step 2b (see references/readme-landing-page.md for the
     full section order and why liveness sits there, not above Features)
   - For first release, single bullet block describing the initial extraction
   - Commit via git-ops with: docs: Add Recent Updates section

4. Surface the publish plan to user, with visibility as a flippable line:
   "Creating as **private** at github.com/<org>/<repo> — say 'public' to flip"
   Wait for explicit confirmation.

5. Create the repo:
   gh repo create <org>/<repo> --private --source=. --remote=origin \
     --description "<one-line — distilled from the README intro draft in step 2, ≤ 350 chars>" \
     --homepage "<homepage URL or omit>"
   (NEVER pass --push; we want push-preflight 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-preflight:
   bash $HOME/.claude/skills/push-preflight/scripts/preflight.sh --cwd <repo> origin main
   On any non-zero exit: stop, report, do not push.

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

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

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

10. Verify:
    gh repo view <org>/<repo>
    gh release view <tag>
    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 <repo> log $(git describe --tags --abbrev=0)..HEAD --oneline
   Categorise commits by Conventional Commits prefix.

2. Determine version bump (see references/release-strategy.md):

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods