# Open Source Project Polish

> Turn a project folder into a polished open source project. Use when: open source ready, polish README, default MIT license, add LICENSE/CONTRIBUTING/CODE_OF_CONDUCT/CHANGELOG, automatically create public GitHub remote for projects without git remote, prepare repository for public release. Only add or modify project metadata/docs, never change source code.

- Skill: `openghz/open-source-project-polish` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add openghz/open-source-project-polish`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openghz/open-source-project-polish/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: openghz (https://skillmd.com/u/openghz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openghz/open-source-project-polish

---


# Open Source Project Polish

## Goal

Transform an existing project folder into a high-quality open source repository by improving public-facing documentation, community files, repository metadata, and Git/GitHub setup while preserving the original source code.

## Hard Boundaries

- Do not modify original product/source code, generated logic, tests, notebooks, assets, or runtime behavior unless the user explicitly asks.
- Allowed changes are limited to project-facing metadata and documentation such as README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, CHANGELOG, SUPPORT, CITATION, issue/PR templates, release notes, badges, `.gitignore`, `.gitattributes`, `.editorconfig`, and GitHub workflow/docs scaffolding.
- Never include user-specific local machine paths in README or public docs, such as `/home/<user>/...`, `/Users/<user>/...`, drive-letter paths, personal workspace names, download folders, or machine-specific absolute project paths. Use relative paths, `$HOME`, `<repo>`, or placeholders instead.
- Default to MIT licensing when no license exists and no user preference overrides it.
- Default to automated public GitHub publication for folders without a Git remote. Determine the target owner/name if not obvious, then create a public remote and push documentation-only changes after secrets checks pass.
- When `gh` is authenticated, configuring low-risk GitHub repository settings is in scope and enabled by default, whether the remote was just created or already existed: set the repository description, homepage, and topics, and **enable Discussions** (the generated `SUPPORT.md` links to it, so it should exist). Do not disable existing features, change visibility, or alter branch-protection/security settings without an explicit request.
- If a network/GitHub command fails, retry once with the configured local proxy before declaring the remote step blocked.
- Preserve existing docs and community files where possible; improve them incrementally rather than replacing useful content.

## Inputs to Clarify When Missing

Ask only for information that materially affects irreversible or public-facing actions:

1. Target scope: workspace project path, or current folder if already clear.
2. Public identity: GitHub owner/repo name before creating any remote if it cannot be inferred from the folder and authenticated GitHub account.
3. License override: use an existing license if present; otherwise apply MIT by default unless the user requests another license.
4. Project positioning: one-sentence value proposition, target users, and maturity if not inferable from code/docs.
5. Source-code edits: assume forbidden; ask before touching anything beyond metadata/docs.

## Procedure

### 1. Audit Project State

- Inspect the folder structure, existing README/docs, package manifests, build files, examples, license files, and Git state.
- Check whether `.git` exists and whether any remote is configured.
- Identify secrets-risk files before any remote creation or push: `.env`, credentials, tokens, large binaries, datasets, private notes, local logs, and machine-specific paths.
- Summarize existing strengths, missing open-source essentials, and any uncertainty that needs user input.

### 2. Plan Non-Code Additions

Create a concise plan covering only allowed documentation and metadata work:

- README improvements using the `create-readme` skill as the basis for structure, tone, and GitHub-flavored Markdown.
- Bilingual README by default: after the primary (English) README is finalized, produce a Chinese version saved as `README.zh-CN.md` and cross-link the two. Author the mirror directly; reserve the `baoyu-translate` skill for long or terminology-dense docs where global term consistency matters.
- Community health files: MIT license by default, contributing guide, code of conduct, security policy, support guide, changelog, citation, governance, issue templates, PR template.
- Repository hygiene: `.gitignore`, `.gitattributes`, `.editorconfig`, docs index, examples index, badges, project description, topics, funding/sponsor metadata if relevant.
- Git/GitHub setup: initialize Git if absent, create public remote if absent, set default branch, and push documentation-only changes after safety checks. When `gh` is available, set the repository description/homepage/topics and enable Discussions by default.

### 3. Improve README

Use the `create-readme` skill for README creation or refresh. Ensure the README is concise, attractive, and useful:

- Clear project name, tagline, and short value proposition.
- Badges only when truthful and maintainable.
- Quick start with verified commands when possible.
- Commands must be copy-pastable from the repository root and must not contain the current user's absolute local paths; prefer `./script.sh`, `$HOME/...`, `/path/to/...`, or `<repo>/...` examples.
- Installation, usage, configuration, examples, project structure, troubleshooting, and links to dedicated files.
- Do not duplicate full LICENSE, CONTRIBUTING, CHANGELOG, or SECURITY content inside README; link to those files.
- Preserve existing project-specific knowledge and examples.

After the English `README.md` is finalized, produce a Chinese translation by default:

- The English `README.md` must include a language-switch line near the top by default, e.g. `English | [简体中文](README.zh-CN.md)`. Add it even when the Chinese file is still being generated in the same run — the link points to the path that will exist when the workflow completes.
- Produce the Chinese `README.zh-CN.md` from `README.md`. Authoring the mirror directly is preferred for a typical README (mostly short prose plus code/commands that must stay verbatim); invoke the `baoyu-translate` skill only when the README is long or terminology-dense and benefits from its analyze/translate/review flow and a shared glossary.
- The Chinese `README.zh-CN.md` carries the mirror switch line at the top, e.g. `[English](README.md) | 简体中文`.
- Keep all code blocks, commands, paths, links, badges, and placeholders unchanged; translate only prose.
- Skip the Chinese version only if the user explicitly opts out. If the project is already authored primarily in Chinese, treat `README.md` as the Chinese version, translate into `README.en.md`, and put the corresponding switch line at the top of each file.

### 4. Add Community Files

Add or update files only when they help the project appear complete and trustworthy:

- `LICENSE`: use existing license if present; otherwise add MIT by default with the detected current year and owner/project name where appropriate.
- `CONTRIBUTING.md`: development setup, branch/commit conventions if inferable, test expectations, issue/PR process.
- `CODE_OF_CONDUCT.md`: use a standard concise contributor covenant style unless user has another policy.
- `SECURITY.md`: supported versions, responsible disclosure channel placeholder, vulnerability reporting expectations.
- `CHANGELOG.md`: initialize with `Unreleased` and current public baseline; do not invent release history.
- `SUPPORT.md`: where to ask questions, report bugs, and request features.
- `.github/ISSUE_TEMPLATE/*` and `.github/PULL_REQUEST_TEMPLATE.md`: practical forms/checklists tailored to the project.
- `CITATION.cff` only for research/academic/scientific projects or when authorship metadata is available.

### 5. Repository Hygiene

- Create or refine `.gitignore` based on detected languages/tools without excluding files that are likely source artifacts.
- Add `.gitattributes` for text normalization and common binary patterns when useful.
- Add `.editorconfig` with conservative whitespace defaults matching the repo style.
- Do not add CI workflows unless build/test commands are known or verified; if added, keep them minimal and non-invasive.

### 6. Git and Remote Handling

For folders without Git:

1. Initialize a repository for the target folder after verifying the folder path.
2. Stage only metadata/docs files created or changed by this workflow.
3. Commit with a documentation-focused message when publication is proceeding.

For Git repositories without a remote:

1. Infer the GitHub owner from `gh` authentication and the repo name from the folder when possible; ask only if ambiguous.
2. Check for `gh` authentication before creating a remote.
3. Create a public GitHub repository by default.
4. Add `origin`, set the default branch, and push after reviewing staged changes and confirming no secrets are included.

Recommended GitHub CLI flow, adapted to the project:

```bash
git status --short
git remote -v
gh auth status
gh repo create OWNER/REPO --public --source=. --remote=origin --push
```

If network commands fail, retry once with:

```bash
export {HTTP_PROXY,HTTPS_PROXY,ALL_PROXY,http_proxy,https_proxy,all_proxy}=http://127.0.0.1:7890
```

### 6a. Configure Repository Features (when `gh` is available)

Whether the remote was just created or already existed, when `gh` is authenticated, configure standard repository metadata and features by default. These changes are low-risk and reversible:

- Set the description, homepage, and relevant topics for discoverability:
  ```bash
  gh repo edit OWNER/REPO \
    --description "One-line value proposition." \
    --homepage "https://example.org/or/pypi/url" \
    --add-topic TOPIC1 --add-topic TOPIC2
  ```
- Enable Discussions by default, because the generated `SUPPORT.md` points contributors there and the link should resolve. There is no dedicated `gh` subcommand, so use the API endpoint:
  ```bash
  gh api --method PATCH repos/OWNER/REPO -F has_discussions=true --jq '.has_discussions'
  ```

Skip a feature only when it is already enabled/set or the user opts out; verify with `gh repo view OWNER/REPO --json description,repositoryTopics,hasDiscussionsEnabled`. If `gh` is unavailable or unauthenticated, list these as manual steps in the completion summary instead of performing them.

### 7. Quality Checks

Before finalizing:

- Re-open changed Markdown snippets to verify headings, links, code fences, and copy-pastable command indentation.
- Search README and public docs for local machine paths before finalizing, including `/home/`, `/Users/`, drive-letter paths, personal workspace names, and absolute paths copied from the current environment.
- Confirm no source code files were modified unless explicitly approved.
- Confirm all links to local files target files that exist.
- If a Chinese README was produced, confirm `README.zh-CN.md` exists, the language-switch links resolve in both files, and code/commands/paths remain identical to the English version.
- Run lightweight formatting or markdown linting if available; do not install heavy dependencies just for this workflow unless user agrees.
- Show `git diff --stat` and summarize changed files.
- If a remote was created, report the URL, visibility, default branch, and whether anything was pushed.

## Decision Points

- Existing README is strong: preserve structure and patch missing sections rather than rewrite.
- No verified install/test commands: include clearly marked placeholders or "not yet documented" notes instead of inventing commands.
- License unknown: add MIT by default unless the user requests a different license.
- Possible secrets or private data: stop remote creation/push and report the risky paths.
- `gh` available and authenticated: set description/homepage/topics and enable Discussions by default as part of setup, since generated docs (e.g. `SUPPORT.md`) reference Discussions; verify each is not already set before changing it.
- No `gh` CLI or not authenticated: provide exact commands for the user to run (including the repository-feature commands from step 6a), but still complete local docs polish and prepare a documentation-only commit if safe.
- Monorepo: create or update root community files and per-package README files only when package boundaries are clear.

## Completion Summary

End with:

- Files added/updated.
- What was intentionally not touched, especially source code.
- Validation performed.
- Remote repository status, if applicable.
- Repository features configured via `gh` (description, homepage, topics, Discussions), or the exact commands to run when `gh` is unavailable.
- Suggested next steps such as enabling CI, adding examples, or cutting a first release.