--- name: skill-open-sourcer description: Package and publish one local agent Skill, or audit and release a Registry-driven public Skill portfolio, as polished installable GitHub packages. Use when the user gives a SKILL.md, Skill directory, or multi-Skill repository and asks to open-source, publish, release, share, validate, detect drift, synchronize mirrors, manage versions, make installable with npx skills, prepare release documentation, or generate launch copy. The workflow includes safety, self-containment, declared capabilities, project-native README design, isolated installation, release planning, and publishing. --- # Skill Open Sourcer Turn one local Skill into a clean public release package, or govern a complete public Skill portfolio from one canonical repository. Default posture: move fast, but stop on release risk. If the safety scan finds secrets, private paths, client data, unpublished proprietary material, or ambiguous ownership, report the blockers and do not publish until the user resolves them. ## Select the mode - A `SKILL.md` path or directory containing `SKILL.md` uses **Single-Skill mode** and follows the existing workflow below. - A repository root containing `registry/skills.json` uses **Portfolio mode**. Read [Portfolio mode](references/portfolio-mode.md) and [Registry contract](references/registry-contract.md) before auditing or releasing. - A directory matching neither contract is an input error. Do not guess which nested directory is authoritative. Run the repository-owned validator in either mode: ```bash python3 /scripts/portfolio.py validate-skill /path/to/skill python3 /scripts/portfolio.py audit --repo /path/to/portfolio --strict ``` ## Quick Start 1. Resolve the input to a real skill directory. Accept a `SKILL.md` file, a folder containing `SKILL.md`, or a symlink under `.codex/skills`, `.agents/skills`, `.claude/skills`, or another local skill root. 2. Run the environment check before packaging or publishing: ```bash SKILL_OPEN_SOURCER_DIR="${CODEX_HOME:-$HOME/.codex}/skills/skill-open-sourcer" python3 "$SKILL_OPEN_SOURCER_DIR/scripts/check_release_env.py" ``` Required local commands are `python3`, `git`, `node`, and `npx`. `gh` is the default local GitHub publishing surface, but GitHub MCP/app or an existing authenticated remote can replace it. If no GitHub publishing surface is available, build and validate the repo locally, then stop with the missing setup. 3. Read the skill entrypoint and inspect directly referenced `scripts/`, `references/`, `assets/`, and `agents/` files. Do not copy unrelated local folders. 4. Run the safety scanner: ```bash SKILL_OPEN_SOURCER_DIR="${CODEX_HOME:-$HOME/.codex}/skills/skill-open-sourcer" python3 "$SKILL_OPEN_SOURCER_DIR/scripts/scan_skill_release.py" /path/to/skill-or-SKILL.md ``` 5. If the environment and safety scans are clear, create a fresh release repository outside the source skill directory. 6. Choose the package layout from the install payload. A truly self-contained, single-file Skill may keep `SKILL.md` at the repo root. If the Skill needs `agents/`, `references/`, `scripts/`, or agent-facing `assets/`, place the complete payload under `skills//`. Current `npx skills` root-level remote installs intentionally copy only `SKILL.md`; a flat package with support files installs incompletely. Preserve applicable source license and third-party notice files. Multi-skill collections also use `skills//`; add `skills.sh.json` only when curated grouping metadata is useful. 7. Extract the release story, choose the README presentation tier, and build the public release files described in `references/release-package.md`. Read `references/readme-design.md` before writing either README or any `assets/readme/` visual. 8. Audit the README package before publishing: ```bash SKILL_OPEN_SOURCER_DIR="${CODEX_HOME:-$HOME/.codex}/skills/skill-open-sourcer" python3 "$SKILL_OPEN_SOURCER_DIR/scripts/audit_release_readme.py" /path/to/release-repo --strict ``` 9. Validate the packaged skill, `npx skills` listing, and one isolated real installation before publishing. Inspect the installed file tree; listing success alone does not prove support files were copied. 10. Publish to GitHub when low-risk checks pass, then produce launch copy. Read `references/release-package.md` before writing the release repo. ## Output Contract For a successful release, return: - GitHub repo URL. - Install command using `npx skills`. - Verification results for skill validation and `npx skills add / --list`. - README audit result, presentation tier used, and any visual assets deliberately included or omitted. - Short risk summary: what was scanned, what was removed or sanitized, and any residual assumptions. - GitHub Description and Topics recommendations when creating a new public repo. - Launch copy: at least one X/Twitter post, plus optional Chinese version when the user works in Chinese. If blocked, return: - Blocker list with file paths and reasons. - Suggested sanitization steps. - The safest next action, usually "clean these files, then rerun the release". ## Safety Rules Hard stop when any of these appear in the source package: - API keys, tokens, private keys, cookies, credentials, `.env` files, or auth config. - Absolute personal paths such as `/Users/...`, `/home/...`, local vault paths, or machine-only cache paths that would confuse public users. - Customer names, private company data, internal docs, private URLs, unpublished prompts, or paid/proprietary assets without a clear license. - Symlinks that escape the package, large binaries, databases, logs, browser profiles, `.DS_Store`, or generated artifacts outside ignored cache directories. Exclude `__pycache__` and dependency caches from every release package; their local presence alone is not a release blocker. - Unclear license or ownership for bundled code/assets. Low-risk auto publish is allowed only when the scanner and manual review find no blockers. If the target GitHub repo already exists with unrelated content, stop and ask before overwriting or force pushing. ## Packaging Rules - Keep the original skill behavior intact. Refactor only enough to remove private assumptions and make public installation reliable. - Use a flat root layout only for a self-contained `SKILL.md` with no supporting payload. Use `skills//` whenever installation must include `agents/`, `references/`, `scripts/`, or agent-facing `assets/`, including single-skill repositories. - Prefer a lean `SKILL.md`; move detailed public guidance into `references/` only when an agent will genuinely need it. - Do not add a README inside the skill folder. Put human-facing documentation at the release repo root. - Preserve `agents/openai.yaml` when present. If absent, create it with `display_name`, `short_description`, and a `default_prompt` that explicitly mentions `$`. - Include `scripts/` only for deterministic helper logic the skill actually uses. - Include `assets/` only when licensing and size are safe for public release. - Put release-specific visuals under `assets/readme/`. Use real outputs or project-native diagrams; skip visuals when they add no explanatory value. - Keep install commands, requirements, links, and long explanations in Markdown. Visuals support the story and must not become the only carrier of essential information. - Use MIT as the default license only when the source skill has no conflicting license and ownership is clear. ## Publication Flow 1. Run `scripts/check_release_env.py`. Add `--repo-dir ` when updating an existing local repo. Add `--check-npx-skills` when package/network access is uncertain. 2. If required commands are missing, stop and report the exact blockers. If only `gh` is missing, continue only when GitHub MCP/app is available or the release repo already has an authenticated `origin` remote. 3. Build the release repo locally, including the README package and any licensed proof assets. 4. Run `scripts/audit_release_readme.py --strict`. Fix hard failures and review every warning; visual taste still requires local rendering and inspection. 5. Validate with the repository-owned validator: ```bash python3 "$SKILL_OPEN_SOURCER_DIR/scripts/portfolio.py" validate-skill /path/to/packaged/skill ``` 6. Create or update the GitHub repository using the available GitHub surface (`gh`, GitHub MCP/app, or existing remote). Avoid force push. 7. Push the branch or `main`. 8. Verify listing. In a Portfolio repository use its lockfile and `--no-install`; for a standalone release environment without a pinned dependency, record the resolved CLI version in the release evidence: ```bash npx --no-install skills add / --list ``` 9. Run an isolated real install with copy mode, then verify the expected support files exist under the temporary agent skill directory. Use the exact target agent intended by the release. Never treat `--list` as sufficient package validation. 10. If listing and the isolated install work, provide the install command: ```bash npx skills add / -g -a codex --skill --copy -y ``` Adjust the agent flag and install wording when the target platform is not Codex. ## Launch Copy After a successful release, draft concise social copy that explains: - The problem the skill solves. - What a user gives it. - What it publishes or automates. - The install command or repo link. - One concrete example request. For Chinese users, include a natural Chinese launch post. Keep it human-facing; do not over-explain scripts.