Agent-Skills.md

Agent Skills: Skills Repo Maintenance

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).

UncategorizedID: akiojin/skills/skills-repo-maintenance

Repository

akiojin/skills
akiojinLicense: MIT
52

Install this agent skill to your local

pnpm dlx add-skill https://github.com/akiojin/skills/tree/HEAD/skills-repo-maintenance

Skill Files

Browse the full folder contents for skills-repo-maintenance.

Download Skill

Loading file tree…

skills-repo-maintenance/SKILL.md

Skill Metadata

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.