# Oss Bootstrap

> 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.

- Skill: `qianjinguo/oss-bootstrap` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add qianjinguo/oss-bootstrap`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qianjinguo/oss-bootstrap/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: qianjinguo (https://skillmd.com/u/qianjinguo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/qianjinguo/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.

```bash
# 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`:

```bash
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).