playbooks

home / skills / kkkkhazix / khazix-skills / skill-manager

skill-manager skill

/skill-manager

This skill audits, checks, and guides upgrades for GitHub-wrapped skills, helping you keep your skill library current with automated reports and updates.

npx playbooks add skill kkkkhazix/khazix-skills --skill skill-manager

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
2.5 KB
---
name: skill-manager
description: Lifecycle manager for GitHub-based skills. Use this to batch scan your skills directory, check for updates on GitHub, and perform guided upgrades of your skill wrappers.
license: MIT
---

# Skill Lifecycle Manager

This skill helps you maintain your library of GitHub-wrapped skills by automating the detection of updates and assisting in the refactoring process.

## Core Capabilities

1.  **Audit**: Scans your local skills folder for skills with `github_url` metadata.
2.  **Check**: Queries GitHub (via `git ls-remote`) to compare local commit hashes against the latest remote HEAD.
3.  **Report**: Generates a status report identifying which skills are "Stale" or "Current".
4.  **Update Workflow**: Provides a structured process for the Agent to upgrade a skill.
5.  **Inventory Management**: Lists all local skills and provides deletion capabilities.

## Usage

**Trigger**: `/skill-manager check` or "Scan my skills for updates"
**Trigger**: `/skill-manager list` or "List my skills"
**Trigger**: `/skill-manager delete <skill_name>` or "Delete skill <skill_name>"

### Workflow 1: Check for Updates

1.  **Run Scanner**: The agent runs `scripts/scan_and_check.py` to analyze all skills.
2.  **Review Report**: The script outputs a JSON summary. The Agent presents this to the user.
    *   Example: "Found 3 outdated skills: `yt-dlp` (behind 50 commits), `ffmpeg-tool` (behind 2 commits)..."

### Workflow 2: Update a Skill

**Trigger**: "Update [Skill Name]" (after a check)

1.  **Fetch New Context**: The agent fetches the *new* README from the remote repo.
2.  **Diff Analysis**:
    *   The agent compares the new README with the old `SKILL.md`.
    *   Identifies new features, deprecated flags, or usage changes.
3.  **Refactor**:
    *   The agent rewrites `SKILL.md` to reflect the new capabilities.
    *   The agent updates the `github_hash` in the frontmatter.
    *   The agent (optionally) attempts to update the `wrapper.py` if CLI args have changed.
4.  **Verify**: Runs a quick validation (if available).

## Scripts

- `scripts/scan_and_check.py`: The workhorse. Scans directories, parses Frontmatter, fetches remote tags, returns status.
- `scripts/update_helper.py`: (Optional) Helper to backup files before update.
- `scripts/list_skills.py`: Lists all installed skills with type and version.
- `scripts/delete_skill.py`: Permanently removes a skill folder.

## Metadata Requirements

This manager relies on the `github-to-skills` metadata standard:
- `github_url`: Source of truth.
- `github_hash`: State of truth.

Overview

This skill is a lifecycle manager for GitHub-based skills that automates scanning, status reporting, and guided upgrades. It helps keep a local skills directory synchronized with remote sources and streamlines safe refactoring of skill wrappers. Designed for batch operations, it supports auditing, updating, listing, and deletion workflows.

How this skill works

The manager scans the local skills folder for entries that include GitHub metadata and uses remote queries to compare local commit hashes with the latest remote head. It produces a concise status report marking skills as current or stale and provides a guided update flow that fetches remote documentation, performs a diff against local documentation, and applies controlled changes to metadata and wrapper code. Optional helper scripts back up files and validate changes after update.

When to use it

  • Periodically scan your skills collection to detect outdated wrappers
  • Before running or deploying agents that depend on third-party skill code
  • When you want a guided, repeatable process to update skill metadata and wrappers
  • To audit and produce an inventory of installed skills and versions
  • Before removing a skill to ensure safe cleanup and backups

Best practices

  • Keep each skill annotated with github_url and github_hash metadata so the manager can track state
  • Run the scanner in CI or scheduled jobs to catch drift early
  • Review generated status reports before automated updates to avoid unintended API or CLI changes
  • Use the update helper to create backups before refactoring wrapper code
  • Validate updated wrappers with quick integration checks when available

Example use cases

  • Run a periodic scan to list skills that are behind upstream by N commits and schedule updates
  • Perform a guided update for a specific skill: fetch remote docs, detect changes, update metadata, and adjust the wrapper
  • Generate an inventory report for compliance or debugging teams showing installed skills and their remote state
  • Delete deprecated or unused skills safely with backup and cleanup scripts

FAQ

What metadata is required for a skill to be managed?

Each skill must include github_url and github_hash metadata so the manager can find the remote source and compare commit state.

How does the manager detect updates remotely?

It uses lightweight remote queries to fetch the current head hash and compares that to the stored github_hash to determine staleness.

Will updates modify wrapper code automatically?

The manager offers a structured refactor workflow that can update metadata and attempt wrapper tweaks, but you should review changes and run validation before committing.