Manage Skills Hub v0.5.0

Operating Model

Treat CATALOG.yaml as the canonical registry. Keep README.md as the human-facing mirror and the Astro site as a catalog consumer.

Keep only the latest accepted version of each skill in the repository tree. Preserve history in Git, not in draft or version-suffixed folders.

Use these roots:

skills/team/<skill-name>/
skills/personal/<skill-name>/
third_party/<publisher>/<skill-folder>/

Require SKILL.md; keep references/, scripts/, assets/, agents/, and evals/ only when used.

Browse Skills

Read CATALOG.yaml first. Report the skill id, path, version, maturity, owner, recommendation status, license, and pinned upstream when relevant. Read README.md only for the human-facing overview or installation guidance.

Install or Sync a Skill

Claude Code

Copy the complete skill folder to ~/.claude/skills/<skill-name>/ or <project>/.claude/skills/<skill-name>/, then reload the session.

Codex

Prefer $skill-installer for a first install. From any shell, the hub installer is also available:

curl -fsSL https://raw.githubusercontent.com/Coco422/ray-skills-hub/main/scripts/install-skill-from-github.py \
  | python3 - --path skills/team/<skill-name>

For an existing installation:

1. Resolve the catalog path and local target, normally ~/.codex/skills/<skill-name>.
2. Compare the remote folder with the installed folder.
3. Back up the installed folder with a timestamp.
4. Reinstall the complete folder with the installer and --force; do not copy only SKILL.md when resources also changed.
5. Verify SKILL.md and every changed references/, scripts/, assets/, agents/, or evals/ file.
6. Record the synced commit when reproducibility matters, then restart Codex.

Audit Local Skills

Inventory ~/.codex/skills, ~/.cc-switch/skills, and ~/.claude/skills when present. Compare folder names, frontmatter names, file hashes, and catalog entries.

• Treat identical copies across tool roots as intentional unless the user approves removal.
• Treat drifted hub skills as update candidates and back them up before replacement.
• Do not edit .system skills or plugin caches through this workflow.
• Do not delete or archive any local skill until the user confirms the exact candidates.
• Validate every changed skill with quick_validate.py.

Add or Update a Hub Skill

1. Classify it as team, personal, or third_party before moving files.
2. Keep team and personal folder names equal to the SKILL.md frontmatter name.
3. Keep frontmatter concise and limited to name and description for hub-owned skills.
4. Move lengthy, conditional guidance to a directly linked file under references/.
5. Update only the target entry in CATALOG.yaml and the matching README table row.
6. Use an absolute review date in YYYY-MM-DD form and keep the catalog version aligned with any version embedded in the skill heading.
7. Do not change hub-level version or updated in a normal skill PR; reserve those fields for a release or repository-maintenance PR.
8. Validate the catalog, the changed skill, and the site before delivery.

Audit and Clean the Repository

1. Enumerate every SKILL.md under skills/team, skills/personal, and third_party.
2. Compare discovered directories with catalog paths in both directions.
3. Check folder/frontmatter names, source/path placement, versions, README rows, maturity, license, tags, and review dates.
4. Verify that third-party entries include a non-moving upstream ref and license; keep imported files isolated.
5. Remove empty optional directories and stale draft artifacts only after the user confirms deletion.
6. Keep project rules in AGENTS.md, user guidance in README.md, and one-off history in Git rather than adding changelog prose to either file.

Review a Pull Request

Inspect PR metadata, changed files, patch, checks, author, base/head refs, fork status, and maintainerCanModify. Review the target skill, catalog entry, README row, assets, and provenance before changing the branch.

Reject or request changes for unpinned third-party sources, unexplained binaries, missing licenses, invalid frontmatter, stale generated artifacts, or unrelated repository-wide edits.

Resolve PR Conflicts

Use this sequence when multiple PRs are open:

1. List the conflicting PRs and their shared files.
2. Choose a landing order from dependencies and shared metadata. Land a repository-maintenance PR before a skill PR that depends on its rules; otherwise prefer the least dependent or oldest-base PR.
3. Update and validate one PR at a time. Refresh the next PR only after the earlier one lands, so it does not become dirty again.
4. Merge the latest base branch into the PR head. Do not rebase or force-push contributor history unless the user explicitly requests it.
5. Resolve semantically:
   • Keep the latest base version of unrelated skills, site code, workflows, and catalog entries.
   • Keep the PR version of its intended skill files and target catalog/README fields.
   • Keep release metadata from the designated release or maintenance PR; discard stale hub-level dates and versions from ordinary skill PRs.
   • Search the full tree for conflict markers after resolution.
6. Run all required validations before committing.
7. Push only after remote Git authorization is clear. For a fork, require maintainerCanModify; otherwise ask the author to update or create a maintainer-owned replacement PR.
8. Wait for required checks. Merge only when the PR content is approved and the user has authorized merging.

Typical local commands:

gh pr list --state open --json number,title,headRefName,baseRefName,mergeable,mergeStateStatus
gh pr checkout <number>
git fetch origin main
git merge origin/main

For a modifiable fork, push the resolved commit to the exact fork head branch rather than creating an unrelated branch.

Branch Rules and Releases

Protect main with pull requests and the validate-catalog check. Let administrators bypass only for bootstrap or emergency recovery.

For a release, update the hub version/date, affected skill versions, README rows, and install examples. Validate first; tag, push, or merge only with user authorization.

Validation

Run the catalog and site checks:

python3 scripts/validate_catalog.py
npm run build

Validate each changed skill with the installed skill-creator validator:

python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" \
  skills/team/<skill-name>

Do not claim completion when a required command could not run. Report the missing dependency or failing check explicitly.