Codex Skillhub Package Conversion

Codex SkillHub package conversion

When to use

Use this when:

1. The source bundle is a local skill export that is not directly installable by Codex.
2. The user asks for "codex 可以安装的格式", a packaged .skill output, or a direct install into ~/.codex/skills/.
3. The bundle contains multiple specialist skills and benefits from a top-level router skill.

Do not use this when:

1. The source is already a valid Codex skill directory with a clean SKILL.md.
2. The task is only to explain what an existing installed skill does.
3. The user wants a repo-local skill for one project rather than a converted external bundle.

Inputs / context to gather

1. Confirm the source path from $ARGUMENTS or the user request.
2. Inspect the bundle shape first:
   • manifest.json
   • skillsets/*.md
   • zipped child skills
   • existing SKILL.md
3. Decide the output mode:
   • install: validate, package if useful, and copy to ~/.codex/skills/
   • package-only: leave a converted bundle folder and optional .skill archives
4. Check whether the bundle should keep all child skills or only a focused subset.

Procedure

1. Inventory the source bundle.
   • Find manifest.json, skillsets/, archives, and any existing SKILL.md.
   • Identify the natural router name and the child skill list.
2. Expand to Codex directory shape.
   • Create one directory per installed skill.
   • Ensure each child skill has SKILL.md.
   • Add agents/openai.yaml only when it improves discoverability or the bundle already uses that presentation layer.
3. Normalize frontmatter before any packaging.
   • Keep required top-level fields like name and description.
   • Move SkillHub-only presentation fields such as label, homepage, category, version, model, or keywords under metadata or remove them from top level.
   • Quote descriptions that contain YAML-breaking colons.
   • Align each name with the directory name, using lowercase kebab-case where needed.
4. Add a router skill when the bundle is multi-skill.
   • The router should describe when to use the bundle and how to route to each child skill.
   • Keep the router small and task-oriented.
5. Validate early.
   • Run quick_validate.py on the converted skills.
   • If the bundle contains Python resources, run a lightweight syntax pass such as python3 -m compileall and then remove __pycache__.
6. Package correctly.
   • Run python3 -m scripts.package_skill from the skill-creator project root, not as a loose script from an arbitrary directory.
   • Verify the archive layout is skill-name/SKILL.md.
7. Install only if requested.
   • Copy validated skill directories into ~/.codex/skills/.
   • Keep the converted bundle folder separate so the user can delete it later if they want.
8. Explain the result.
   • Summarize what the router skill does.
   • List the child skills and their main triggers in plain language.

Efficiency plan

1. Start by fixing frontmatter and names; that catches most install failures early.
2. Reuse one conversion pattern across sibling bundles instead of redesigning each one.
3. Create the router once the child set is stable; do not rewrite it after every file tweak.
4. Stop after validation plus the requested install/package output is proven.

Pitfalls and fixes

• Codex rejects the skill even though the body looks fine
  • Likely cause: invalid frontmatter or non-Codex top-level keys.
  • Fix: keep top-level frontmatter minimal and move extra metadata under metadata.
• package_skill.py cannot import its helpers
  • Likely cause: it was run from the wrong working directory.
  • Fix: run python3 -m scripts.package_skill from the skill-creator root.
• The converted bundle is bloated with unrelated generic skills
  • Likely cause: the source export mixed core domain skills with broad extras.
  • Fix: keep only the domain core plus the router when that matches the user’s goal.
• Python resource bundles look dirty after validation
  • Likely cause: compileall left __pycache__.
  • Fix: delete __pycache__ before final packaging.
• The user still asks what the installed bundle can do
  • Likely cause: the run stopped at file conversion.
  • Fix: always end with a router-plus-children capability summary.

Verification checklist

1. Every installed skill directory has a valid SKILL.md.
2. Top-level frontmatter is Codex-compatible and names match folders.
3. Multi-skill bundles have a clear router skill.
4. Validation passed before packaging or install.
5. If packaging was requested, the archives contain skill-name/SKILL.md.
6. If install was requested, the validated skills exist under ~/.codex/skills/.
7. The final handoff explains what the router and child skills do.