open-source-publisher

name: open-source-publisher description: Prepare an open-source repository for polished public publishing. Use when a user asks to publish, open-source, launch, polish, package, brand, or make a GitHub project presentable with a minimal project icon, social preview image, GitHub Pages landing page, standardized README, essential shields, CI/CD quality gates, release automation checks, and optional donation setup. Prefer the external logo-generator skill for icon generation when available, and nolangz/pixel2motion for optional motion previews of generated static images. license: MIT allowed-tools: Bash, Read, Write, Edit, WebSearch, WebFetch compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires a writable git repository; browser or image rendering tools are useful for visual validation. metadata: targets: [_source-only] author: Oleg Koval tags: - open-source - github - readme - branding - github-pages - ci - release - social-image

Use this skill to audit whether an OSS repository is ready to publish, then help only with missing or weak pieces: recognizable icon, shareable social image, GitHub Pages site, standardized README, CI/CD hygiene, release readiness, and optional donation links.

Workflow

Inspect the repository before editing:
- package/tooling files: go.mod, package.json, pyproject.toml, Cargo.toml, Makefile, etc.
- current README, docs, website files, images, workflows, releases, license, funding files
- existing product purpose, author, install paths, examples, and public URLs
Produce a readiness audit before asking for changes:
- Ready: publish-critical pieces that already exist and look usable
- Weak: existing pieces that are present but incomplete, stale, broken, inconsistent, or below the house standard
- Missing: publish-critical pieces that do not exist
- Optional: nice-to-have pieces such as donations or extra badges
Classify the repository type before recommending changes:
- library, CLI, web app, framework, docs site, or other
- use the type to decide whether governance, packaging, or presentation work should come first
Identify maintainer identity and public home information when they affect publishing:
- Ask for the GitHub handle or org name if the repo will have a public owner/maintainer identity, funding links, release notes, or badges
- Ask for a canonical website/homepage URL if the project needs a homepage, docs site, or public project URL
- If homepage, author, or org metadata already exists and looks current, do not ask again
For existing usable pieces, do not propose replacement by default. Ask a change-oriented question only when useful, for example:
- "You already have a terminal-style GitHub Pages site. Do you want to keep it or restyle it?"
- "You already have an icon and social card. Do you want a refresh, or should I leave them as-is?"
- "You already have a static social card. Do you want me to animate it with pixel2motion, or leave it static?"
- "You already have release automation. Do you want me to audit only, or also tighten it?"
Ask only for choices needed to fix missing or weak pieces:
- If GitHub Pages is missing or weak, ask for style: oldschool linux, terminal, modern, brutalist, glassmorphism, y2k, hacker, or custom.
- If donation wiring is missing, ask whether to enable it: none, GitHub Sponsors, Ko-fi, Buy Me a Coffee, Open Collective, Thanks.dev, or custom URL.
- If the repo has a generated static social image or hero card, ask whether to animate it using nolangz/pixel2motion.
- If the repo has no clear product essence, ask for a one-sentence positioning statement.
Implement only approved, missing, or weak work in this order:
- OSS governance and support files
- minimal icon
- social preview image
- README standard
- GitHub Pages landing page
- GitHub Pages analytics setup, if requested
- CI/CD and release audit/fixes
- donation wiring, if requested
Validate locally and with browser/screenshots when possible.
Commit/push only when the user asks or the current task explicitly requires it.

Readiness Audit

Treat this skill as an OSS publishing readiness checker first and an implementer second. The first response after inspection should be a concise audit with concrete evidence from the repo.

Publish-critical checklist:

repository identity: clear project name, description, topic/keywords, author, license
install path: package manager, release assets, source build, or direct download instructions
maintainer identity: GitHub handle or org name when public identity is relevant
public home: canonical website/homepage URL when the project needs one
if either field does not exist, proceed without it and mark it as absent
OSS governance: LICENSE, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, support policy, issue/PR templates, changelog or release notes path
README standard: centered shields, icon, title, short description, horizontal rule, essential sections
icon: simple SVG mark plus rendered PNG, both committed in predictable paths
social image: 1200x630 image with matching metadata, with both SVG source and rendered PNG committed when practical
GitHub Pages or docs site: essential install/examples/links/SEO/Open Graph metadata
GitHub Pages analytics: optional setup to track visitor patterns and engagement
CI quality gates: formatter, linter/static analysis, tests, build/package check
release automation: tags/releases/artifacts/package update flow, docs-only changes excluded where needed
security posture: license, security notes or policy, OpenSSF Scorecard or equivalent when appropriate
contribution path: issues/PR guidance, support expectations, project status
donations: explicitly absent, declined, or configured

Audit output format:

## OSS Publish Readiness

Ready
- README uses the house top block with test, Go Report Card, and OpenSSF shields.
- Release workflow builds darwin arm64/amd64 binaries and updates the Homebrew tap.

Weak
- Direct download examples point at a fixed release tag; latest-release URLs would age better.

Missing
- No `.github/FUNDING.yml`; donations are not configured.

Questions
- You already have a terminal-style GitHub Pages site. Keep it, or restyle it?
- What is the GitHub handle or org name for public attribution?
- What is the canonical website or homepage URL, if any?
- Donations are not configured. Enable them or leave them off?

Rules:

Do not ask for style, donations, or redesign choices before the audit.
Do not overwrite existing icon, social image, README, site, workflows, or funding files unless the user approves a change or the audit classifies the item as weak.
If everything publish-critical is ready, say so and offer only optional improvements.
If the user asks to "run the skill" without more detail, audit first, then wait for approval before making non-trivial visual or workflow changes.
Keep the audit evidence-based. Reference filenames, workflow names, package metadata, or command outputs.

Minimal Icon

Create a simple, recognizable SVG logo from the repository's essence. Prefer logo.svg and also render logo.png so the icon can be reused in README assets, release artifacts, and platform-specific previews.

Use the external logo-generator skill first for icon generation when it is installed (see logo-generator Installation below). If it is not installed, follow the manual SVG guidance below and commit both the editable SVG and rendered PNG when practical.

`logo-generator` Installation

The logo-generator skill is external and is not bundled with this repository. Install it separately from https://github.com/op7418/logo-generator-skill before relying on it:

npx skills add https://github.com/op7418/logo-generator-skill.git

If automatic installation is unavailable, clone it into the Claude skills directory:

git clone https://github.com/op7418/logo-generator-skill.git ~/.claude/skills/logo-generator
cd ~/.claude/skills/logo-generator
pip install -r requirements.txt
cp .env.example .env

Then add GEMINI_API_KEY to .env and restart the agent runtime so the skill is discoverable.

Icon rules:

Use one clear metaphor from the project domain, not a collage.
Keep the mark readable at 32px.
Prefer 1-2 shapes and 1-2 accent colors.
Use a simple rounded tile only when it improves favicon readability.
Avoid terminal window chrome, decorative dots, random badges, and center glyph clutter unless the project itself is a terminal/window tool.
Avoid generic AI tells: glass effects, bokeh/orbs, over-layered gradients, busy shadows, and unrelated emojis.
If the repo has a website or homepage, ensure the icon fits that visual system.

Good icon pattern for sync/migration tools:

<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512" role="img" aria-labelledby="title desc">
  <title id="title">Project logo</title>
  <desc id="desc">Clean sync icon made from two circular arrows.</desc>
  <defs>
    <linearGradient id="topArrow" x1="142" y1="118" x2="392" y2="250" gradientUnits="userSpaceOnUse">
      <stop offset="0%" stop-color="#22c55e"/>
      <stop offset="100%" stop-color="#38bdf8"/>
    </linearGradient>
    <linearGradient id="bottomArrow" x1="370" y1="394" x2="120" y2="262" gradientUnits="userSpaceOnUse">
      <stop offset="0%" stop-color="#fb7185"/>
      <stop offset="100%" stop-color="#f59e0b"/>
    </linearGradient>
  </defs>
  <rect width="512" height="512" rx="112" fill="#0d1117"/>
  <rect x="42" y="42" width="428" height="428" rx="96" fill="#111827" stroke="#1f2937" stroke-width="8"/>
  <g fill="none" stroke-linecap="round" stroke-linejoin="round">
    <path d="M142 234c13-70 74-122 147-122 52 0 99 27 126 69" stroke="url(#topArrow)" stroke-width="42"/>
    <path d="M389 118l35 67-75 4" stroke="url(#topArrow)" stroke-width="42"/>
    <path d="M370 278c-13 70-74 122-147 122-52 0-99-27-126-69" stroke="url(#bottomArrow)" stroke-width="42"/>
    <path d="M123 394l-35-67 75-4" stroke="url(#bottomArrow)" stroke-width="42"/>
  </g>
</svg>

Adapt the geometry and metaphor. Do not reuse the sync arrows for unrelated projects.

Social Image

Create a 1200x630 social preview image for GitHub, Twitter/X, Slack, and link unfurls.

Recommended files:

social-card.svg as the editable source
social-card.png rendered from the SVG when render tooling is available
keep both files in the repo when practical so the preview can be updated without redrawing the whole asset

Social image rules:

Include project name, one clear value proposition, and 2-3 concrete capabilities.
Keep the composition simple and calm. Large readable type beats dense feature lists.
Use actual project language: commands, package name, supported platform, or primary workflow.
Match the icon color system.
Keep all text inside a safe margin of at least 64px.
Use og:image, twitter:image, width/height meta tags, and meaningful alt text.
If the repo has a homepage or canonical website, make the social card and metadata point to that URL consistently.

Render checks:

rsvg-convert -w 1200 -h 630 social-card.svg -o social-card.png
file social-card.png

Use magick or another renderer when rsvg-convert is unavailable.

Motion Preview

Some repos benefit from a short animated preview. Keep this opt-in.

If you already generated a static image, ask: Do you want me to animate the static image using pixel2motion?
If the user says yes, use nolangz/pixel2motion as the optional dependency for logo animation, animated HTML demos, and GIF/video previews.
Do not auto-animate by default.

README Standard

Shape the README like the house standard used for Go packages such as slow-query-detector and dcli.

Top block:

<p align="center">
  <a href="..."><img src="..." alt="tests"></a>
  <a href="..."><img src="..." alt="Go Report Card"></a>
  <a href="..."><img src="..." alt="OpenSSF Scorecard"></a>
</p>

<p align="center">
  <img src="./logo.svg" width="120" height="120" alt="project icon">
</p>

<h1 align="center">project-name</h1>

<p align="center">
  Short product description<br>
  <strong>One-line promise</strong>
</p>

---

Choose shields from the repo's tech:

always: test workflow badge if a test workflow exists
Go: Go Report Card, OpenSSF Scorecard
Node/npm: npm version, npm downloads, test workflow, OpenSSF Scorecard
Python: PyPI version, Python versions, test workflow, OpenSSF Scorecard
coverage: only include if coverage service is configured
release: only include if releases are automated and meaningful

OSS Governance

Treat governance files as first-class publishing work, not optional paperwork.

Check for, or add when appropriate:

LICENSE
CONTRIBUTING.md
SECURITY.md
CODE_OF_CONDUCT.md
SUPPORT.md
.github/ISSUE_TEMPLATE/*
.github/PULL_REQUEST_TEMPLATE.md
CHANGELOG.md or a release notes workflow
package metadata for homepage, repository, bugs, and funding links

Rules:

For libraries and CLIs, prioritize governance and release path before visual polish.
For web apps or product sites, keep the governance checks but allow branding and landing page work to happen earlier when the public-facing experience is the main product.
If a repo already has governance docs that are good enough, mark them Ready and move on.
If the project has no maintainer/support policy, ask whether support should be community-only, maintainer-only, or commercial.

GitHub Pages

Create a simple essential GitHub Pages site when the project lacks one or the existing one is weak.

Ask the user to choose one style first:

oldschool linux
terminal
modern
brutalist
glassmorphism
y2k
hacker
custom style

Required page content:

project name and icon
one-sentence value proposition
author link
install/download instructions
2-4 short examples
feature summary
links to GitHub, README, releases, issues
SEO meta description and keywords
Open Graph and Twitter meta tags
social image reference
footer with license and optional donation/badge links

Implementation defaults:

Use a static index.html unless the repo already has a site framework.
Add CNAME only when the user gives a domain.
Add .github/workflows/pages.yml when Pages uses GitHub Actions or no deploy path exists.
Avoid marketing fluff and oversized hero sections for developer tools. Make the first viewport useful.
Use system UI fonts for body text and monospace only for commands, labels, or terminal-specific elements.

GitHub Pages Analytics

Add basic analytics to track site visitor patterns and user behavior when the project has a GitHub Pages site.

Setup options:

Google Analytics (free, detailed): Add UA or GA4 tracking ID to site <head>
Plausible (simple, privacy-first, paid): Lightweight script alternative
Simple counter (basic): Visitor count badge using Shields.io or statically-generated endpoint

Minimal Google Analytics setup for static sites:

<script async src="https://www.googletagmanager.com/gtag/js?id=G-YOUR_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-YOUR_ID');
</script>

Track these essential events:

pageview (automatic): Site visitors and page sections
download_release: Clicks on install/download links (track each platform/format)
view_docs: Navigation to documentation pages
github_click: Click through to GitHub repo
copy_command: Code snippet copies in examples

Optional custom events for OSS projects:

search_docs: If docs site has search
view_example: Specific example/use-case sections viewed
support_click: Link clicks to issues, discussions, or support channels

Rules:

Add analytics after publishing the site; do not gate site launch on analytics.
If the user prefers privacy-first or no analytics, skip this step.
Store analytics credentials as GitHub Pages environment secret or site config, never in git.
Review monthly to catch unusual patterns or broken tracking links.

CI/CD And Release Audit

Check whether the repository has:

formatter check
linter/static analysis
tests
build/package check
dependency review / lockfile integrity checks
secret scanning or secret prevention
license scanning / OSS compliance scan
SBOM or provenance generation where appropriate
security scan or OpenSSF Scorecard where appropriate
release automation
docs/site-only path filters when release runs on main
docs link checker or markdown validation for repo/docs sites
package-specific smoke install / publish dry-run matrix

For Go projects, prefer:

- go test ./... -race
- go vet ./...
- gofmt check
- staticcheck ./...
- go build ./...

For Node projects, prefer existing package manager scripts:

npm ci
npm run lint
npm test
npm run build

Release automation rules:

Inspect existing release flow before changing it.
Do not create releases for docs/site-only changes.
Make Homebrew/package formulas update from real release artifacts and checksums.
Use least-privilege secrets and document required secret names.
If automation pushes tags, guard against rerun/version reuse.
Prefer signed or attestable releases where the ecosystem supports it.
Prefer release notes generation from tags or merged PRs instead of hand-written release bodies when the repo is release-heavy.

Donations

Ask whether the user wants donations enabled.

If yes:

Ask for provider and URL/handle if not inferable.
Add .github/FUNDING.yml for GitHub-supported providers.
Add a short README Support section or footer link.
Add site footer/link only if the project has a site.
Do not invent payment handles.

Provider hints:

github: username
ko_fi: handle
custom:
  - https://example.com/support

Validation

Run the checks that match the edits:

SVG syntax: xmllint --noout logo.svg social-card.svg
Render social image: rsvg-convert -w 1200 -h 630 social-card.svg -o social-card.png
README links and badge URLs where practical: curl -I
Site render: local static server plus browser/screenshot when available
Repo tests/build/lint
Workflow YAML parse, for example with Ruby: ruby -e 'require "yaml"; YAML.load_file(".github/workflows/ci.yml")'
git diff --check

Before final response, state:

files changed
validation commands run
release/donation caveats
any secrets the user must configure

open-source-publisher