custom-skills-updater

Manage manually installed skills (non-ClawHub). Supports checking updates, updating, and listing custom skills from GitHub or local sources.

Manages manually installed skills not installed from ClawHub.

Supported types: github-dir, github-file, github-readme, local

This skill checks and updates existing skills only. It does NOT create new skills.

---

Prerequisites

All GitHub operations require an authenticated gh CLI session. Before any GitHub request, run gh auth status. If it fails, prompt: "Run gh auth login first." and stop.

---

Operations

Check for updates

Scan REGISTRY.yaml, detect remote versions, compare with stored versions, report:

skill-name ........ up-to-date
skill-name ........ update available

Update skills

Target all outdated skills or a specific skill by name.

1. Run update check
2. For each outdated skill, notify the user before updating:
   • Skill name and type
   • Summary of what changed (e.g. diff highlights, new commit description, or content delta)
   • How the update will be applied (overwrite, merge, delegate to skill-creator, etc.)
   • Wait for explicit user approval before proceeding
3. Update approved skill(s)
4. Update REGISTRY.yaml

If the user cannot respond immediately (e.g. scheduled/automated run, no active session), do not execute updates. Instead, write a summary of pending updates (skill name, change description, proposed action) and leave it for the user to review and approve later.

List installed skills

Read and list all entries in REGISTRY.yaml.

---

Registry

Location: REGISTRY.yaml in the same directory as this SKILL.md.

If it does not exist:

1. If REGISTRY.example.yaml exists, copy it to REGISTRY.yaml
2. Otherwise create with:

skills: {}

Do not rename the skills root key.

Format

Map structure keyed by skill name:

skills:
  example-dir-skill:
    type: github-dir
    source: example-owner/example-repo@main:skills/example-dir-skill
    version: abc123
    updated: 2026-01-01
  example-readme-skill:
    type: github-readme
    source: example-owner/example-project@main
    version: def456
    updated: 2026-01-02

Field	Meaning
key	skill name
type	github-dir / github-file / github-readme / local
source	source location
version	commit SHA (github-dir) or SHA256 (file-based types)
updated	last update date

---

Automatic Skill Discovery

Scan skills/*/SKILL.md. Only direct subdirectories of skills/, no recursion.

If a skill exists but is not in REGISTRY.yaml:

1. Notify the user and ask for source type and location
2. Add to registry

If unable to prompt, register as local and notify the user to configure later.

---

Version Detection

Compare remote version against version in REGISTRY.yaml.

github-dir

gh api "repos/{owner}/{repo}/commits?path={path}&per_page=1" --jq '.[0].sha // empty'

github-file

gh api "repos/{owner}/{repo}/contents/{path}?ref={branch}" -H "Accept: application/vnd.github.raw+json" | shasum -a 256

github-readme

Find README filename:

gh api "repos/{owner}/{repo}/contents/?ref={branch}" --jq '.[].name' | grep -i '^readme' | head -n 1

Take first match, download and hash:

gh api "repos/{owner}/{repo}/contents/{readme_filename}?ref={branch}" -H "Accept: application/vnd.github.raw+json" | shasum -a 256

local

Skip entirely.

---

Update Procedure

Only update when remote version differs from stored version.

github-dir

gh api "repos/{owner}/{repo}/tarball/{branch}" > archive.tar.gz

Verify the file is valid gzip before extracting. Copy target path to skills/{name}/.

github-file

gh api "repos/{owner}/{repo}/contents/{path}?ref={branch}" -H "Accept: application/vnd.github.raw+json" > skills/{name}/SKILL.md

github-readme

1. Download the new README using the same method as version detection
2. Compare the new README against the existing local README to identify changes
3. Assess change scope:
   • Major changes (structural changes, new/removed sections, significant content rewrites): check if the skill-creator skill is installed. If yes, delegate the SKILL.md update to skill-creator with the new README as input. If skill-creator is not installed, fall through to step 4.
   • Minor changes (wording tweaks, small additions): proceed to step 4 directly.
4. Evaluate whether the changes contradict any statements in the current SKILL.md, or introduce important new information that should be reflected in SKILL.md
5. Update the skill only for the relevant parts based on the evaluation above.

---

Error Handling and Safety

Handle gh api failures by HTTP status:

Status	Action
401	"Authentication expired. Run gh auth login." Stop all operations.
403	"Permission denied or rate limit for {skill-name}." Skip.
404	"Source not found for {skill-name}." Skip.
Other	"Check failed for {skill-name}." Skip.

On any failure: do NOT overwrite local files, do NOT modify registry.

Registry updates: modify only the target entry, do not reorder or remove others, update version and updated only after success.

This skill manages manually installed skills only. ClawHub-installed skills are out of scope.