skills-repo-maintenance

name	skills-repo-maintenance
description	Add or update skills in a skills repository for Codex and/or Claude Code. Use when creating new skills, packaging .skill files for Codex, or converting a skill into a Claude Code plugin (marketplace.json + plugin.json).

Skills Repo Maintenance

Overview

Maintain a skills repository and keep Codex and Claude Code artifacts in sync.

Workflow

0) Defaults to apply

• Target runtime: Codex + Claude Code (both).
• Package output: must be specified by the user every time (no default).

1) Identify the repo root

• Use the current repo (git root) as the base.
• Example: git rev-parse --show-toplevel

2) Decide the target runtime(s)

• Default is both. If the user explicitly asks for only one runtime, confirm before skipping the other.
• Codex: add a skill folder with SKILL.md at repo root.
• Claude Code: add a plugin folder with .claude-plugin/plugin.json and update .claude-plugin/marketplace.json.
  • For both, do both and package .skill files for Codex distribution.

3) Create or update the skill content

• Skill folder must contain SKILL.md with YAML frontmatter (name, description).
• Use lowercase + hyphens for skill names.
• Put extra materials under references/, scripts/, assets/ as needed.

4) Claude Code plugin requirements (if applicable)

• Plugin lives at repo root (e.g. drawio/, gh-fix-ci/, cli-design/).
• Add .claude-plugin/plugin.json inside the plugin folder.
• Add an entry to <repo-root>/.claude-plugin/marketplace.json:
  • name, source, description, version, category, keywords
• If the plugin contains multiple skills, place them under <plugin>/skills/<skill-name>/SKILL.md.

5) Codex packaging (if applicable)

• Package to the user-specified output directory using the skill packager.
• On Windows, set UTF-8 to avoid decode errors.

$env:PYTHONUTF8=1
$codexHome = $env:CODEX_HOME
if (-not $codexHome) { $codexHome = "$env:USERPROFILE\.codex" }
$outDir = "<output-dir>"
python "$codexHome\skills\.system\skill-creator\scripts\package_skill.py" `
  "<repo-root>\\<skill-folder>" `
  $outDir

export PYTHONUTF8=1
codex_home="${CODEX_HOME:-$HOME/.codex}"
out_dir="<output-dir>"
python "$codex_home/skills/.system/skill-creator/scripts/package_skill.py" \
  "<repo-root>/<skill-folder>" \
  "$out_dir"

Repeat for each Codex-supported skill.

6) Update documentation

• README.md
  • Add to Available Plugins and Usage (Claude Code) when pluginized.
  • Add to Available Codex skills and Usage (Codex) when packaged.

7) Commit + push

• Ensure codex-skills/dist/*.skill are tracked for Codex delivery.
• Push changes and open PR if required by your workflow.

Notes

• Codex reads skills from .codex/skills folders; .skill is a packaged zip for distribution.
• Claude Code requires the plugin entry in .claude-plugin/marketplace.json.