GitHub-skill-publisher

GitHub-skill-publisher

Use this skill to turn a local agent skill into a polished single-skill GitHub repository and to maintain it over time.

This skill is for skill publishing workflows, not general Git tutorials.

Core rule

The user's preferred structure is:

one skill = one GitHub repository

The repository root is the skill root. Do not create a skills/<name>/ wrapper unless the user explicitly asks for a collection repository.

Publish authorization rule

This rule applies to GitHub-skill-publisher itself and to every other skill repository it publishes or updates.

Local edits and GitHub publication are separate actions. Use two authorization modes:

1. Local-only by default.
   • If the user says "修改", "更新", "调整", "写进去", "完善", or similar edit-only wording, make local changes only.
   • After local changes, report what changed and ask before any commit, push, repository creation, sync, publish, or GitHub metadata update.
2. Explicit edit-plus-publish authorization.
   • If the user says "修改并发布", "改完发布", "更新并同步到 GitHub", "修改后推送", "改完直接发布", or another unambiguous edit-plus-publish instruction, treat that as permission to publish after checks.
   • In this mode, do not ask for a second confirmation after successful checks.
   • Still stop and ask before publishing if checks fail, sensitive data is found, cleanup requires deletion/redaction/moving user files, compatibility is partial or unsupported, the remote/branch/visibility is ambiguous, or the publish action would be destructive such as force push.

Always run the relevant pre-publish checks and provide a publish summary before or during the final response.

Release surface normalization rule

Any skill published through GitHub-skill-publisher is a publisher-managed release by default. Before publishing, normalize the public release surface:

README.md      English, GitHub default
README.zh.md   Chinese
GitHub description: English by default

Old projects may still have the legacy layout:

README.md      Chinese
README.en.md   English

Do not silently keep this layout during a publisher-managed release. Migrate it by default before publishing.

Only keep the legacy layout when the user explicitly says to preserve the old README, not migrate README, or publish the current files as-is. In that pass-through case, report the legacy layout as a warning and run:

node scripts/publish-check.mjs --allow-legacy-readme

When to use

Use this skill when the user asks to:

• publish a skill to GitHub,
• update a skill repository,
• improve a skill README,
• create bilingual README files,
• prepare a skill for public release,
• check whether a skill is safe and portable before publishing,
• create a new GitHub repo for a skill,
• push local skill updates to GitHub.

Standard workflow

Inspect -> Normalize -> Capture screenshot -> Write README -> Pre-publish cleanup -> Smoke test -> Publish check -> Show screenshot/summary -> User confirmation -> Commit -> Publish or Push -> Verify

1. Inspect the local skill files and current git state.
2. Normalize to single-skill repository structure.
3. Capture a real product screenshot before finalizing README when the skill has a visual surface.
   • If it is a web page, run/open the page and capture a browser screenshot.
   • If it is an app/program, launch the program and capture the real UI.
   • Store the image in the repository, usually under assets/, and reference it from both README.md and README.zh.md.
   • Do not use mock screenshots when a real page/program can be opened. If sample data is safer than private data, keep the real UI but use safe sample data and say so.
   • Before publishing, show the screenshot to the user and wait for their confirmation.
4. Write or update README.md, README.zh.md, LICENSE, and .gitignore when useful.
   • Treat the README template as a release quality gate, not only as writing guidance.
   • For publisher-managed releases, evaluate any existing README against the current default README structure before publishing.
   • For every update release, review the current diff before publishing and decide whether the change affects README content.
   • If changes touch user-visible capability, usage, install flow, dependencies, compatibility, outputs, repository structure, templates, scripts, security/copyright boundaries, or GitHub metadata, update both README.md and README.zh.md before publishing.
   • If the changes are small and do not affect README content, do not force a README edit; document the no-impact reason in the final pre-publish summary and run the publish check with --readme-no-impact.
   • Do not blindly overwrite old READMEs, but if the user did not explicitly ask to preserve the current README as-is, upgrade missing key modules before publishing.
   • Required README modules include audience fit, program or page screenshot when the skill has a visual surface, what it does, core capabilities, platform compatibility, install, quick start, usage examples, how it works, repository/file structure, requirements or configuration, and license.
   • Productize README copy before release: use a two-column user-facing core-capabilities table and make the main install section a copy-ready natural-language request that asks the current Agent to install the public repository URL.
   • For agent-facing skill repositories, remove default git clone, directory-copy, manual-install, platform-path, dependency, and restart instructions from the main README. The installing Agent owns environment detection, installation, dependency checks, and load verification.
   • When an existing README still uses a clone-and-copy installation flow, rewrite that section during normalization before running the final publish check. Do not merely report the old structure and leave it for the user to fix.
5. Generate or update GitHub repository metadata, especially the repository description.
   • Use an English repository description by default unless the user explicitly requests Chinese or a China-facing repository.
   • The description should match the first-screen value proposition in README.md.
6. Create a pre-publish cleanup plan for drafts, caches, logs, generated output, and local-only files.
   • Do not automatically delete or move files when the action is destructive or ambiguous.
   • Ask the user before deletion, redaction, file moves, or any high-risk cleanup.
   • Use .gitignore as prevention, but also check tracked files with Git because .gitignore does not protect files already committed.
7. Run automated quality checks when possible.
   • Prefer node scripts/smoke-test.mjs from the skill repository when available.
   • Use the smoke test to verify the skill's own required files, references, templates, language switch style, and publish-check script.
8. Run automated publish checks when possible.
   • Prefer node scripts/publish-check.mjs from the skill repository when available.
   • By default, node scripts/publish-check.mjs requires the normalized release surface: English README.md, Chinese README.zh.md, and no legacy README.en.md.
   • The publish check must validate README structure, not only README language layout. A README that is English by default but misses required product/documentation modules is not release-ready.
   • The publish check must also validate README freshness against the current diff. If relevant non-README files changed but README files did not, treat that as a release blocker unless the diff was reviewed and explicitly marked no-impact with --readme-no-impact.
   • Use node scripts/publish-check.mjs --allow-legacy-readme only when the user explicitly requests a pass-through release that preserves old README files.
   • The script must report PASS, WARNING, or FAIL; it must not commit, push, create repositories, or publish.
   • Treat FAIL as a hard stop until fixed.
9. Run completeness, dependency, sensitive-data, portability, and security checks.
   • Check for API keys, user accounts, private tokens, local paths, private files, and machine-specific assumptions.
   • Redact or replace sensitive/local-only content before publishing.
   • Check for third-party names, brand names, platform names, copyright notices, trademark notices, upstream-source statements, and external license-limit notes.
   • Allow neutral references to design style, design language, and company names such as Apple, Anthropic, and Meta when they are used only as design or compatibility context and do not imply ownership, endorsement, copied assets, or relicensing.
   • Treat README and LICENSE findings involving other third parties as high-priority review items when they include attribution, copyright, trademark, source, license, generated-by, or ownership language.
   • Check for public identity and attribution signals, including author names, maintainer names, private emails, personal usernames, social handles, generator watermarks, tool watermarks, and visible Git commit author/signature metadata.
   • If third-party or copyright-related content is found, do not remove it automatically. List the findings and ask the user whether to keep, rewrite, add attribution, or remove them before publishing.
   • If identity or attribution metadata is found, do not remove it automatically. List the findings and ask the user whether to keep, anonymize, replace with organization identity, or remove it before publishing.
   • Check whether the skill is complete and whether it has hard dependencies on other skills or private local resources.
   • If a dependency is required, document it clearly or bundle/adapter-isolate it before publishing.
10. Test runtime and operating-system compatibility where possible.

• Target agent runtimes are Codex, Claude Code, and OpenClaw.
• Required target operating systems are macOS and Windows when the skill includes scripts, installers, path handling, shell commands, browser automation, filesystem operations, or external CLIs.
• Linux compatibility is optional. Test or review it when it is easy or relevant, but do not treat missing Linux validation as a release blocker by default.
• If macOS or Windows cannot be tested or reviewed before publishing, stop before GitHub publication and tell the user what has not been checked.
• If macOS or Windows is incompatible or only partially compatible, tell the user before publishing and pause for confirmation.

11. Present a final pre-publish summary after all content, including README files, has been generated and checked.

• Include target repository, remote URL, branch, visibility, files to publish, README status, screenshot path, screenshot approval status, security result, third-party/copyright review result, completeness result, dependency result, compatibility result, GitHub metadata, warnings, and remaining risks.
• Show the captured screenshot to the user before publishing.
• Ask explicitly whether to publish to GitHub only when the user's current request did not already include explicit edit-plus-publish authorization.

12. Commit, create repositories, push, sync, or update GitHub metadata only after explicit publish authorization exists.
13. Create the GitHub repository or push to the existing remote.
14. Verify URL, branch, remote, repository description, and clean working tree.

Required references

Read only what is needed:

• references/repo-structure.md for repository layout rules.
• references/pre-publish-flow.md for the full publish flow and confirmation gates.
• references/readme-style.md for the bilingual README style.
• references/install-section.md for skill installation instructions that README files should include.
• references/skill-completeness.md before public release.
• references/platform-compatibility.md before public release.
• references/publish-checklist.md before publishing.
• references/security-checklist.md before public release.
• references/github-workflow.md for first-time GitHub publishing.
• references/update-workflow.md for later updates.

Scripts

Optional helper scripts:

node scripts/smoke-test.mjs
node scripts/publish-check.mjs
node scripts/se-quality.mjs

The smoke test script is a local quality gate. It verifies that this skill's own files, references, templates, and publish-check script are coherent.

The publish check script is a reporting gate only. It must never publish, push, commit, delete files, or mutate GitHub state. It reports a release gate (PASS/WARNING/FAIL) plus an engineering-hygiene score covering metadata, documentation, structure, security, and tooling.

The se-quality script reports a separate software-engineering quality score (completeness, openness/extensibility, reusability, cohesion, coupling, robustness), plus advisory document-craftsmanship signals (no thin/placeholder sections, instructional phrasing, concrete specifics, low hedging language, encoded failure modes, anti-example lists, and runtime-neutral cross-agent phrasing) that judge how the docs read rather than merely whether sections exist. Like publish-check, it only reports and never mutates state. Each sub-metric is tagged deterministic or proxy so the score stays honest.

Run order: publish-check is the release gate — run it first. se-quality assumes that gate has passed; it does not re-detect blockers (secrets, broken references, missing license, unparseable scripts are caught by publish-check, not duplicated here). A high se-quality score is only meaningful once publish-check reports PASS.

Templates

Use these as starting points, not rigid boilerplate:

• templates/README.md
• templates/README.zh.md
• templates/README.practical-tool.md
• templates/README.practical-tool.zh.md
• templates/README.hero.md
• templates/README.hero.zh.md
• templates/LICENSE-MIT
• templates/gitignore

Use templates/README.md and templates/README.zh.md as the default Standard high-conversion README templates. README.md is English by default for GitHub's repository homepage, and README.zh.md is the Chinese switch page. They prioritize user value, product pain, product highlights, workflow, optional preview, Agent-directed installation, direct-use prompt, default configuration, final result, compatibility, and license.

Use templates/README.practical-tool.md and templates/README.practical-tool.zh.md when a skill is a practical utility with rich usage examples, rule categories, manual workflows, before/after examples, warning lists, references, and source attribution.

The README templates intentionally omit a limitations section by default. Use MIT for LICENSE unless the user requests another license.

Collaboration rule

If the user asks for writing or README improvement, draft locally and discuss before pushing unless they explicitly say to sync or publish.

If the user explicitly asks to both modify and publish, complete the edits, run the checks, and publish without asking a second time unless a blocking risk appears.

Before consequential GitHub actions, explain:

• target repository,
• visibility,
• branch,
• files being committed,
• expected result.

For final publishing, provide the final pre-publish summary. Ask whether to publish only when publish authorization was not already explicit in the user's current request.

Safety boundaries

• Do not ask the user to paste GitHub tokens.
• Prefer gh auth login browser/device authorization.
• Check for secrets, personal paths, local-only assumptions, and unsafe scripts before public release.
• Do not publish private or user-specific memory files.
• Do not force push unless the user explicitly requests it and understands the impact.