Oss Bootstrap

oss-bootstrap

Bootstrap a GitHub-ready open-source project structure.

> Disclaimer: This skill is a scaffold, not a quality guarantee. > It helps a new repo acquire the standard OSS appearance (README badges, > CI green, Pages deployed, release tagged) — but structure-complete ≠ > project-successful. A repo can pass every checklist here and still have zero > users, zero value, or a fundamentally flawed premise. Use this skill to lower > the friction of starting; do not mistake the resulting polish for validation > of the idea itself. Validate the problem separately.

When to Use

• Starting a new open-source Python project
• Upgrading an existing repo to standard OSS structure
• Need CI, Docker, GitHub Actions, Pages, Releases setup
• Want bilingual (EN + zh) READMEs

The Pattern

This skill captures the reusable structure observed in anti-ai-style-factory — a GitHub-standard OSS project skeleton that can be applied to any Python project (LLM pipeline, CLI tool, library, or static-site generator).

Core Files (root level)

| File | Purpose | Required | |------|---------|----------| | README.md | English readme with badges, quick start, architecture | yes | | README_zh.md | Chinese readme (mirror of README.md) | optional | | LICENSE | MIT license (most permissive, most common) | yes | | CHANGELOG.md | Keep-a-changelog format, versioned | yes | | CONTRIBUTING.md | How to contribute: fork, branch, PR, tests | yes | | GETTING_STARTED.md | Detailed setup guide for newcomers | optional | | pyproject.toml | Package metadata + CLI entry points + ruff config | yes (Python) | | requirements.txt | Pinned deps (mirror for non-pip-tools users) | yes (Python) | | action.yml | GitHub Action composite action (if distributing as Action) | optional | | Dockerfile | Container image (openresty/nginx for static, python:slim for apps) | optional | | docker-compose.yml | Local + prod deployment | optional | | .env.example | Template for secrets (no real values) | yes | | .gitignore | Python + IDE + generated artifacts | yes | | .dockerignore | Slimmer image (exclude .venv, .git, tests) | optional |

Directory Structure

project/
├── .github/
│   └── workflows/
│       ├── ci.yml          # pytest matrix + ruff + self-test
│       └── deploy-pages.yml # GitHub Pages deployment
├── src/                    # Source code (package)
│   ├── __init__.py
│   ├── generator/
│   ├── scorer/
│   └── pipeline/
├── tests/                  # pytest tests
│   └── test_*.py
├── config/                 # YAML/TOML config
│   └── pipeline.yaml
├── catalog/                # Seed/data files
├── sample_styles/          # Curated examples (small, in-git)
├── examples/               # Usage examples
├── demos/                  # Standalone demo HTML
├── gallery/                # Static site (deployed to Pages)
├── scripts/                # Build/utility scripts
├── docs/                   # Documentation (optional)
└── state/                  # Runtime state (gitignored)

The Seven Pillars of a GitHub OSS Project

1. README with badges — Python version, License, CI status (auto-updating from workflow)
2. CI workflow — Multi-version matrix (3.9-3.12), pytest + ruff + self-test
3. GitHub Pages deployment — Auto-deploy on push to main, scoped to a subdirectory
4. GitHub Action (action.yml) — Distribute as a composite Action for others to use
5. Docker deployment — One-command docker compose up
6. Bilingual docs — EN + zh READMEs (Chinese dev community is large)
7. Releases + Tags — Semantic versioning (v0.1.0, v0.2.0, ...) with CHANGELOG entries

How to Apply

Option A: Use apply.sh (recommended)

The skill ships with apply.sh, a bash script that copies all templates to a target directory and replaces {{PLACEHOLDER}} values in one step.

# Inline via env vars
PROJECT_NAME=my-tool \
DESCRIPTION="Does X" \
AUTHOR=joe \
GITHUB_USER=joe \
PORT=8000 \
DEPS="openai>=1.0 pyyaml>=6.0" \
  bash ~/.claude/skills/oss-bootstrap/apply.sh ./my-tool

# Or via a placeholders file (copy placeholders.env.example, edit, pass it)
cp ~/.claude/skills/oss-bootstrap/placeholders.env.example ./my-placeholders.env
# edit my-placeholders.env...
bash ~/.claude/skills/oss-bootstrap/apply.sh ./my-tool ./my-placeholders.env

Required placeholders: PROJECT_NAME, DESCRIPTION, AUTHOR, GITHUB_USER. All others have sensible defaults derived from these. See placeholders.env.example for the full list.

Option B: Manual copy

1. Copy all template files from templates/ to the new project root.
2. Replace placeholders: {{PROJECT_NAME}}, {{DESCRIPTION}}, {{AUTHOR}}, {{GITHUB_USER}}.
3. Pick the right Python version target (3.9+ recommended for broad compat).
4. Choose a license (MIT default; Apache 2.0 for enterprise; GPL for copyleft).
5. Enable GitHub Pages in repo Settings -> Pages -> Source: GitHub Actions.
6. Create first release: gh release create v0.1.0 --generate-notes.

Templates Available

All templates live in templates/ and use {{PLACEHOLDER}} syntax:

Root-level docs

• README.md — English readme template
• README_zh.md — Chinese readme template
• LICENSE — MIT license
• CHANGELOG.md — Keep-a-changelog format
• CONTRIBUTING.md — Contribution guidelines
• GETTING_STARTED.md — Detailed setup guide
• CODE_OF_CONDUCT.md — Contributor Covenant v2.1
• SECURITY.md — Vulnerability reporting policy
• Makefile — Common commands (test/lint/build/run/release)

Python packaging

• pyproject.toml — Package config + CLI entry points + ruff
• requirements.txt — Deps (mirrors pyproject for non-pip-tools users)

GitHub Action + Docker

• action.yml — Composite Action for others to use in CI
• Dockerfile — openresty/nginx static-site deployment (gallery, docs, SPA)
• Dockerfile.python-app — Multi-stage Python app (FastAPI/Flask/CLI server)
• docker-compose.yml — Compose config with healthcheck

Config / hygiene

• .env.example — Env var template (no real values)
• .gitignore — Python + IDE + generated artifacts
• .dockerignore — Slimmer image
• .pre-commit-config.yaml — ruff + pre-commit-hooks + bandit

.github/ (community + CI)

• .github/ISSUE_TEMPLATE/bug_report.yml — Structured bug report form
• .github/ISSUE_TEMPLATE/feature_request.yml — Feature request form
• .github/PULL_REQUEST_TEMPLATE.md — PR description template
• .github/dependabot.yml — Auto-update pip + github-actions + docker
• .github/FUNDING.yml — Sponsor button (commented out by default)
• .github/workflows/ci.yml — Test matrix (3.9-3.12) + lint + self-test
• .github/workflows/release.yml — Build + GitHub Release + PyPI on tag
• .github/workflows/codeql.yml — Weekly security scan
• .github/workflows/deploy-pages.yml — GitHub Pages deployment

Choosing a Dockerfile

| File | Use when | Base image | Typical app | |------|----------|------------|-------------| | Dockerfile | Serving a static site (gallery, docs, SPA) | openresty/openresty:alpine | nginx + Lua proxy | | Dockerfile.python-app | Running a Python server (FastAPI/Flask/CLI) | python:3.11-slim (multi-stage) | uvicorn / gunicorn / CLI |

If your project is a library (no server), you may not need a Dockerfile at all — CI handles testing and PyPI publishing.

Anti-Patterns to Avoid

• Do not commit .env (real secrets)
• Do not commit generated output (styles/, logs/, state/, output/)
• Do not commit __pycache__/, .venv/, *.egg-info/
• Do not skip CI matrix — test on 3.9-3.12 minimum
• Do not skip ruff — formatting is part of CI
• Do not skip self-test — score your own output as a sanity check
• Do not create a release without CHANGELOG entry

Verification Checklist

Before publishing:

• [ ] README badges all green (CI passing)
• [ ] LICENSE present (MIT recommended)
• [ ] CHANGELOG has entry for current version
• [ ] CONTRIBUTING.md explains PR process
• [ ] .env.example present, .env in .gitignore
• [ ] CI workflow runs on push + PR to main
• [ ] GitHub Pages enabled (if applicable)
• [ ] First release tagged (v0.1.0)
• [ ] Dockerfile builds without errors
• [ ] docker compose up works locally
• [ ] Tests pass: pytest tests/ -v
• [ ] Lint passes: ruff check .
• [ ] No secrets in git history

Origin

Pattern extracted from anti-ai-style-factory (github.com/QianJinGuo/anti-ai-style-factory). Structure validated on 2026-06-28 with: MIT license, v0.3.0 release, GitHub Pages enabled, CI passing on Python 3.9-3.12 matrix, Docker deployment on port 8004.

> Note: The origin project itself had a flawed product premise (see its ISSUE.md). > The structure is sound; the product was not. This skill helps you avoid the > structural friction the origin project solved — it does not help you avoid > the product-validation gap the origin project exhibited.

Evaluation

This skill ships with an eval suite at eval/. Run it after any change to apply.sh, templates/, or SKILL.md:

python3 ~/.claude/skills/oss-bootstrap/eval/run_eval.py

The suite runs 8 cases (minimal, multi-deps, special chars, Chinese, empty deps, version constraints, numeric names, long descriptions) with 36 expectations total. Results are written to eval/results/.json.

Current baseline: 8/8 cases passed, 36/36 expectations (100%) as of 2026-06-28.

Borrowed from skill-creator's eval pattern (assertion-based, JSON results), but adapted: oss-bootstrap is render-based (deterministic output), so no LLM grader or trigger-precision testing is needed — pure file/content assertions.

Related Skills

These adjacent skills handle different lifecycle stages — use alongside, not instead of, oss-bootstrap:

• opensource-pipeline — Strip secrets and sanitize an existing private repo for open-sourcing. Use oss-bootstrap for new projects, opensource-pipeline for converting private → public.
• oh-my-claudecode:release — Guide the release action (version bump, tag, CHANGELOG). Use after oss-bootstrap when cutting a release.
• everything-claude-code:git-workflow — Git branch strategy and commit conventions. Complements oss-bootstrap's PR template.
• skill-creator:skill-creator — Meta-tool for building other skills. Use this if you want to author a new skill (oss-bootstrap itself was hand-written, not generated).

Source & license

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

• Author: QianJinGuo
• Source: QianJinGuo/oss-bootstrap
• License: MIT
• Homepage: https://github.com/QianJinGuo/oss-bootstrap#readme

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