# Publish Repo > Publishes the current Agent Skills repository to skills.sh - pre-flight checks, public visibility flip, protections (PVR, rulesets), a gh skill release, consumer-style install verification, telemetry seeding, and repo-page groupings. Use when the user asks to publish, deploy, release, go public, or get listed on skills.sh. Not for authoring skills or scaffolding repositories. - Skill: `paldom/publish-repo` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add paldom/publish-repo` - Raw SKILL.md: https://api.skillmd.com/api/skills/paldom/publish-repo/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - License: MIT - Author: Paldom (https://skillmd.com/u/paldom) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/paldom/publish-repo --- # publish-repo Deploys the current repository to the skills.sh ecosystem. There is no publish API — deployment = a public, installable repo plus a first real install that seeds the catalogue telemetry. This skill makes that sequence deliberate. Slash-invoked only: it flips repository visibility, which is socially hard to undo (everything ever pushed becomes visible). ## When NOT to use - Writing or fixing a skill → `add-skill`. - Scaffolding a new repo → `create-skill-repo`. - The repo has zero skills under `skills/` → build first; never publish an empty catalogue. - Routine pushes to an already-public repo → plain git (done by the owner). ## Workflow 1. **Pre-flight (hard gates — stop on any failure):** the working tree must be clean and pushed **by the owner** — this skill never runs `git commit` or `git push`; if there are uncommitted changes, stop and hand the list to the owner instead. ```bash git status --porcelain # must be empty make check 2>/dev/null || python3 scripts/validate_skills.py # repo validator, if present npx skills@latest add . --list # every skill under skills/ discovered (@latest: a stale npx cache lies) gh skill publish --dry-run # spec validation (needs gh >= 2.90; older gh: skip, use the step-6 fallback) env | grep -E 'DISABLE_TELEMETRY|DO_NOT_TRACK|^CI=' || true # any hit -> the step-7 seed MUST use env -u ``` `skills.sh.json`, when present, must match the schema shape — top-level `groupings` (required) with `title`/`description`/`skills` per group; the schema rejects unknown keys like `groups`/`name` and skills.sh silently ignores a non-conforming file. Triage every `gh skill` warning: add missing `license:` frontmatter; a `.claude/skills/` warning is expected when the repo deliberately bundles its own first-party dev skills. Bundled dev skills must carry `metadata.internal: true` in their frontmatter so consumer installs skip them (they must not appear in `add . --list`; maintainers opt back in with `INSTALL_INTERNAL_SKILLS=1` or `--include-internal`). Verify README catalogue + CHANGELOG current and every skill description benefit-led (it is the listing copy); CI green. 2. **Manual blockers — require explicit user confirmation, never assume:** - full-history secret scan (gitleaks/trufflehog) done; - personal/private-file review done (everything ever committed goes public). With `--dry-run` in `$ARGUMENTS`, stop here and report readiness instead. 3. **Groupings:** ensure `skills.sh.json` lists every skill in exactly one group with an engaging one-sentence description per group — it is the repo's landing copy on skills.sh. 4. **Flip visibility** (confirm with the user immediately before): ```bash gh repo edit / --visibility public --accept-visibility-change-consequences ``` 5. **Protections** (public repo unlocks them): ```bash gh api repos///private-vulnerability-reporting --method PUT ``` Add a default-branch ruleset — solo-maintainer default: block force pushes and deletions only (require-PR would block the owner's direct-push workflow); upgrade to require-PR + code-owner review + required checks when outside contributors arrive. Add a **tag ruleset** on `v*` (block update + deletion) so releases are immutable. 6. **Release** — cut a versioned GitHub release matching `.claude-plugin/plugin.json` (or the repo's version source): ```bash gh skill publish --tag v ``` It re-validates, adds the `agent-skills` topic if missing, and creates the release with auto-generated notes. Add `skills-sh` too: `gh repo edit / --add-topic skills-sh`. `gh` < 2.90 has no `gh skill` — equivalent fallback: ```bash gh release create v --generate-notes gh repo edit / --add-topic agent-skills --add-topic skills-sh ``` 7. **Verify like a consumer, and seed the catalogue.** The first real install is what lists the repo — and the CLI reports it ONLY when `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, and CI variables are all **fully unset** (any value disables, even `0` or `false` — env strings are truthy). Run locally, never in CI, with the opt-outs explicitly unset for these commands only: ```bash npx skills@latest add / --list mkdir -p /tmp/skills-verify && cd /tmp/skills-verify env -u DISABLE_TELEMETRY -u DO_NOT_TRACK npx skills@latest add / -a claude-code -y # NO --skill '*': the wildcard opts into internal dev skills npx skills list -a claude-code ``` Then confirm the listing: `curl -sIL https://skills.sh//` turns 200 within minutes of a valid seed (canonical URL is lowercase on www.skills.sh; the search API lags the page). Still 404 after ~15 minutes means the telemetry never fired — re-check the env, don't wait on "cache". Publishing SEVERAL repos? Seed them ONE at a time, ~5 minutes apart, and confirm each page before the next: burst install events for multiple unlisted repos from one machine are throttled server-side — the security audit still runs but the listings never materialize, and re-seeding inside the burst does nothing. A single spaced event lists within ~5 minutes. 8. **Polish:** README badge `[![skills.sh](https://skills.sh/b//)](https://skills.sh//)`; homepage via `gh repo edit --homepage` (e.g. the skills.sh page); social preview image (manual UI step — remind the owner). 9. **Report:** repo URL, skills.sh page URL, install command, release tag, protections applied, anything skipped with its unlock condition, and the note that the skills.sh page appears only after telemetry processes the seed install (pages are cached). ## Output spec Public repo installable via `npx skills add /` (verified by an actual install), PVR enabled, rulesets active, groupings valid, release cut, seed install performed, owner told exactly what to expect next. ## Gotchas - The visibility flip is the point of no return for history — step 2 demands explicit confirmation and never self-certifies. - `npx skills add . --list` reporting "No skills found" means frontmatter or layout problems — fix via the repo validator's output, never by restructuring blindly. - **Telemetry opt-outs silently kill the listing**: `DISABLE_TELEMETRY` or `DO_NOT_TRACK` set to ANY value (even `0`/`false`) stops the install report — the page then 404s forever while every install "succeeds". Always seed via `env -u DISABLE_TELEMETRY -u DO_NOT_TRACK`. - Pin `npx skills@latest` — npx happily reuses a stale cached CLI version. - The badge endpoint (`skills.sh/b/...`) returns 200 even for unlisted repos — it proves nothing; only the repo page URL does. - The page appears within minutes of a **valid** seed install; the search API and leaderboard lag longer. A 404 beyond ~15 minutes = suppressed telemetry — or a burst: seeding several unlisted repos back-to-back from one machine gets throttled; space seeds ~5 minutes apart, one repo at a time. - Agent harnesses may permission-block the visibility flip and release commands (public-surface actions): hand the exact command to the owner to run themselves instead of retrying. - No Node on the machine? The consumer verification and seed install must run somewhere with Node ≥18 — report it as pending, never as done.