Publish Code

Publish Code

Guide a repository from private to public. Adapts to user intent - from "just make it public" to "want contributors."

Requirements

Workflow

1. QUICK SCAN     (2-3s) → Gather context
2. SMART QUESTION        → What's your goal?
3. TARGETED WORK         → Based on intent
4. PUBLISH               → Make public, optional announcements

Phase 1: Quick Scan

Run these checks synchronously (~2-3 seconds total):

# Git state - dirty?
git status --porcelain | head -5

# Remote exists?
git remote -v

# Already public? What is it?
gh repo view --json visibility,description,url 2>/dev/null || echo "No GitHub remote"

# What files exist?
ls -la LICENSE* README* CONTRIBUTING* 2>/dev/null
ls pyproject.toml package.json Cargo.toml go.mod 2>/dev/null

Parse results into context:

• is_dirty: Has uncommitted changes?
• has_remote: Connected to GitHub?
• is_public: Already visible to world?
• has_license: LICENSE file exists?
• has_readme: README exists?
• language: Python/Node/Rust/Go/other
• description: One-line summary from GitHub or README first line

Phase 2: Smart Question

Use AskUserQuestion with context baked into the question:

Example (adapt based on scan results):

"This is a Python CLI tool, currently private, has README but no license. What's your goal?"

Options:

1. Just make it public - Minimal: add license, quick sanity check, flip visibility
2. Make it usable by others - Standard: license, README polish, install docs, portability check
3. Want community/contributors - Full: above + CONTRIBUTING.md, issue templates, CI

Adapt the question:

• If already public: "Already public. Want to improve discoverability?"
• If dirty state: "You have uncommitted changes. Commit first, or proceed anyway?"
• If no remote: "No GitHub remote. Want to create one?"

Phase 3: Targeted Work

Path A: Minimal ("just make it public")

1. Add LICENSE if missing

Ask which license:

• MIT - Simple, permissive. Best for utilities/libraries.
• Apache-2.0 - Adds patent protection. Better for applications.

Fetch from GitHub API, substitute placeholders using git config:

# Get author name from git config
AUTHOR=$(git config user.name)

# MIT license
gh api /licenses/mit --jq '.body' | sed "s/\[year\]/$(date +%Y)/g" | sed "s/\[fullname\]/$AUTHOR/g" > LICENSE

# Apache-2.0 (no placeholders in template)
gh api /licenses/apache-2.0 --jq '.body' > LICENSE

Verify the LICENSE file:

• Check it exists and has content: wc -l LICENSE (should be 20+ lines)
• For MIT: grep '\[year\]\|\[fullname\]' LICENSE || true (no output = placeholders substituted)
• Quick sanity check: head -3 LICENSE (should show license name and copyright)

2. Quick sanity check

Read README and any config files. Look for:

• Hardcoded user paths (/Users/xxx/, /home/xxx/)
• Organization-specific references that should be generalized
• API keys or secrets (STOP if found)
• Hardcoded service IDs (Notion, Discord, Slack, etc.)

This is Claude reading files, not mechanical grep. Use judgment.

3. Make public

gh repo edit --visibility public --accept-visibility-change-consequences

Verify it worked:

gh repo view --json visibility,url --jq '"Visibility: \(.visibility), URL: \(.url)"'

Confirm output shows PUBLIC before proceeding. Done for minimal path.

Path B: Standard ("usable by others")

Everything in Minimal, plus:

1. README quality check

Read full README. Verify it has:

• One-line description at top
• Installation instructions (with actual commands)
• Usage example (working code or CLI invocation)
• License mention

Also check for implicit dependencies - list ALL tools needed, including "obvious" ones:

• curl, jq, grep - not installed everywhere
• Language runtimes (python3, node)
• Package managers (brew, apt)

If missing sections, offer to add them. Keep it concise.

2. Portability audit

Run the audit script (in the same directory as this SKILL.md):

./audit.py [repo-path]

The script uses external tools (exit codes: 0=clean, 1+=issues found - this is expected):

• Secrets: gitleaks - scans git history for leaked credentials
• Typos: typos - spell checking for code and documentation
• Broken links: lychee - fast async link checker
• Markdown: markdownlint --fix - autofixes formatting, reports unfixable
• Hardcoded paths: /Users/xxx/, /home/xxx/, C:\Users\xxx\
• Personal refs: Scans for git user.name/user.email in tracked files

Limits: Scans first 300 tracked files, skips files >200KB. Large repos may have unscanned files.

JSON output schema:

{
  "repo_path": "/path/to/repo",
  "repo_name": "repo",
  "files_checked": 42,
  "basics": {
    "has_license": true,
    "has_readme": true,
    "has_contributing": false,
    "has_gitignore": true
  },
  "has_blockers": true,       // secrets found - STOP
  "needs_review": true,       // non-blocking issues found
  "secrets": [...],           // HIGH severity
  "typos": [...],
  "broken_links": [...],
  "markdown_unfixable": [...],
  "hardcoded_paths": [...],
  "personal_refs": [...]      // username/email found in files
}

Review output for:

• has_blockers: true: STOP - secrets found, address immediately
• hardcoded_paths: Fix or document
• broken_links: Update or remove
• typos: Review suggestions and fix
• markdown_unfixable: Manual fixes needed
• personal_refs: Review if expected (LICENSE ok, README probably not)

3. Check tracked files that should be gitignored

Run git ls-files and flag files that typically shouldn't be tracked:

• *.local.* (personal settings)
• .env* (even empty templates can be risky)
• *_cache/, __pycache__/, node_modules/
• *.log, *.bak, *.tmp
• .DS_Store, Thumbs.db

If found, untrack with git rm --cached and add to .gitignore.

4. README quality review

Check README.md manually for:

• Length: If >300 lines, suggest splitting into docs/
• Structure: Should have Install, Usage, License sections at minimum
• Examples: Should be generic, not personal projects/data
• Links: Verify they're useful for external users

5. Claude review of key files

Read these files and flag anything that assumes personal/org context:

• README.md (intro and examples)
• Config files (config.toml, settings.py, etc.)
• Example files

Look for:

• Personal examples that should be generic (names, interests, projects)
• Organization-specific terminology or internal jargon
• Hardcoded service IDs (Notion, Discord, Slack, etc.)
• Location-specific content (flag - might be intentional)

6. GitHub topics

If no topics set, suggest relevant ones:

gh repo edit --add-topic python --add-topic cli-tool

7. Make public + optional announcement

Make public, then offer to draft a tweet:

🚀 Just open-sourced [name]!

[One-line description]

GitHub: [url]

Keep it simple. User can embellish.

Path C: Full ("want contributors")

Everything in Standard, plus:

1. CONTRIBUTING.md

Create if missing:

# Contributing

## Setup

[Clone and install instructions]

## Development

[How to run tests, lint, etc.]

## Pull Requests

1. Fork the repo
2. Create a branch
3. Make changes
4. Submit PR

Keep it short. Long CONTRIBUTING.md files go unread.

2. Issue templates

Create .github/ISSUE_TEMPLATE/bug_report.md:

---
name: Bug Report
about: Report a bug
labels: bug
---

**What happened?**

**Steps to reproduce**

**Expected behavior**

**Environment**
- OS:
- Version:

Create .github/ISSUE_TEMPLATE/feature_request.md:

---
name: Feature Request
about: Suggest an idea
labels: enhancement
---

**Problem**

**Proposed solution**

3. Announcements

Offer to draft for multiple platforms:

Hacker News (Show HN):

Show HN: [Name] – [description]

[2-3 sentences: what it does, why it exists]

GitHub: [url]

Looking for feedback on [specific aspect].

Reddit:

[Name] - [description] [open source]

Just open-sourced this tool that [solves X].

Quick start: [install command]

GitHub: [url]

Present drafts for user approval. Never post without explicit confirmation.

Important Rules

• NEVER make public without explicit user confirmation
• NEVER post announcements without user approval
• STOP immediately if real secrets found (API keys, tokens)
• Ask, don't assume - if unsure whether something is personal/sensitive, ask
• 80/20 - Don't over-polish. Ship it.

Quick Reference

License cheat sheet:

Announcement priority (for dev tools):

1. Twitter/X (quick, low friction)
2. Hacker News (high impact if it lands)
3. Reddit (targeted subreddits)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.