donggua-zen/guada/skill-installer

Skill Installer — Skill Installation & Management Guide

Overview

This skill guides you through installing, updating, and uninstalling skills. The core workflow is:

Download/Prepare → Validate (must pass) → Install to {SKILL_DIR}/<name>/

Target directory: {SKILL_DIR}/（该占位符运行时已替换为真实绝对路径，直接使用，不要自行拼 ~）

1. Installation Workflow

All installation methods follow the same three-step workflow.

1.1 Download — to Working Directory

Place the skill source in the current working directory, not the target directory:

# Git clone
git clone https://github.com/.../repo.git  ./<skill-name>
 
# ZIP extraction
unzip skill.zip -d ./<skill-name>
 
# Manual creation
mkdir ./<skill-name>  (then edit SKILL.md)

1.2 Validate — Must Pass

Run the bundled validation script before installing. The script lives in this skill's own directory (scripts/validate-skill.mjs), relative to the resourceBase directory returned by skill_learn. Run it from that directory:

node scripts/validate-skill.mjs ./<skill-name>

All 14 checks must pass before proceeding. If validation fails, fix the reported issues and re-run until it passes.

1.3 Install — Move to Skills Directory

Once validated, move the directory to the target location:

mv ./<skill-name> {SKILL_DIR}/<skill-name>

The file watcher automatically detects and registers the skill within seconds.

2. Installation Methods

2.1 From Git Repository

Best for: Published skills, team-shared skills, version history.

Required from user:

• Git URL (required): e.g. https://github.com/owner/repo or git@github.com:owner/repo.git
• Branch (optional): specific branch (defaults to repo default)
• Subdirectory (optional): path in monorepos where the skill lives

Steps:

1. Validate Git URL format (must start with http://, https://, or git@)
2. Clone to current working directory: git clone --depth 1 <url> ./temp-<name>
3. Locate SKILL.md (search root, then 1-2 levels deep)
4. Extract name from frontmatter
5. Run validation script (must pass)
6. Check for naming conflicts in target directory
7. Move to {SKILL_DIR}/<name>/
8. Clean up temp files
9. File watcher auto-detects and registers

2.2 From ZIP Archive

Best for: Local skills, downloaded bundles, manual distribution.

Steps:

1. Extract ZIP to current working directory: unzip <file>.zip -d ./temp-<name>
2. Locate SKILL.md (search root, then 1-2 levels deep)
3. Extract name from frontmatter
4. Run validation script (must pass)
5. Check for naming conflicts in target directory
6. Move to {SKILL_DIR}/<name>/
7. Clean up temp files
8. File watcher auto-detects and registers

2.3 Manual Placement

Best for: Development, testing, quick prototyping.

Steps:

1. Create skill directory in working directory: mkdir ./<name>
2. Write ./<name>/SKILL.md with valid frontmatter
3. Optionally add scripts/, references/, assets/
4. Run validation script (must pass; run from this skill's resourceBase directory returned by skill_learn):

``bash node scripts/validate-skill.mjs ./<name> ``

1. Move to target directory: mv ./<name> {SKILL_DIR}/<name>/
2. File watcher auto-detects and registers

3. Verification

3.1 Confirm Registration

read({ path: "{SKILL_DIR}/<skill-name>/SKILL.md" })

Returns the full SKILL.md content if the skill exists and is valid.

3.2 Validation Error Reference

4. Updates

4.1 Hot-Reload (content change only)

Directly edit {SKILL_DIR}/<name>/SKILL.md. The file watcher detects the change and reloads the skill automatically.

4.2 Full Reinstall (renamed or moved)

Re-install using the same method. The file watcher handles old skill removal and new skill registration automatically.

4.3 Version Tracking

If the skill has a version field, the system tracks history in {SKILL_DIR}/.versions/versions.json.

5. Uninstall vs Disable

6. Troubleshooting