oss-bootstrap

name	oss-bootstrap
description	Bootstrap a GitHub-ready open-source Python project structure — README, README_zh, LICENSE, CONTRIBUTING, CHANGELOG, action.yml, Dockerfile, docker-compose, CI workflows, GitHub Pages deployment, releases. Use when starting a new open-source project or upgrading an existing repo to a standard OSS structure. Reusable pattern extracted from anti-ai-style-factory.

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/<timestamp>.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).