skill-install-manager
Skill Installation Manager — Automatically reads skill list files, compares them with currently globally installed skills, identifies uninstalled or updatable skills, and performs one-click installation/update. Supports three-level fallback: HTTPS → SSH → direct fetch via MCP/GitHub API. Install using the
command as a Global installation, specifying the three Agents: Reasonix / Claude Code / OpenCode.
Trigger Conditions
Trigger when users express any of the following intentions. Even if only implying or indirectly mentioning skill installation/management tasks, this skill should be used:
- "Check and install missing skills" / "See which skills are not installed"
- "Sync skill list" / "Sync skills" / "skill sync"
- "Update all skills to the latest version" / "Check for updates" / "skill update"
- "Skill management" / "skill manager" / "Manage skills"
- "Batch install skills" / "Install these skills" / "One-click installation"
- "Install from skill list" / "Install according to list"
- "Help me organize skills" / "Skill status" / "Check skills"
- "Install new skills" / "Fill in missing skills"
- "npx skills" / "skills add" / "Skill repository"
Execution Mode Description
This Skill adopts a dual-mode design of Agent direct execution (main path) + JS script (optional auxiliary):
| Mode | Applicable Scenario | Features |
|---|
| 🟢 Agent Direct Execution | Default mode, recommended | Progress visible at each step, timeout controllable, automatic fallback after timeout |
| 🔵 JS Script Auxiliary | When batch formatted output is required | Quickly outputs structured JSON, but may get stuck due to network issues |
Core Principle: All shell commands have strict timeouts (15-30s). After timeout, the Agent uses its own tools to execute in a degraded manner; long-term unresponsiveness is not allowed.
Workflow Overview
Step 0: Self-update (Update skill-install-manager itself first)
│ ├─ npx skills update 15s → Skip if successful
│ └─ Failed → Fallback to npx skills add
│
▼
Step 1: Read list file (Read from updated list file)
│
▼
Step 2: Compare old and new lists (Record old list summary before update, mark new skills after comparison)
│
▼
Step 3: Parse list (Agent parses during reasoning, or calls compare-skills.js for formatting)
│
▼
Step 4: Get installation status (Agent directly runs npx skills ls + read_file to read lock file)
│
▼
Step 5: Comparative analysis (Agent compares one by one, each repository's git ls-remote has 15s timeout, shared query for the same repository)
│ ├─ Success → Mark as outdated/upToDate
│ └─ Timeout → Fallback to web_fetch GitHub API → Mark as unknown
│
▼
Step 5.5: Dependency Pre-check (New! Check if prerequisite skills are installed before installation/update, add missing ones to installation queue and install first)
│
▼
Step 6: Execute installation/update
│ ├─ Installation order: Prerequisites → Newly added → Missing → Updates
│ ├─ Installed skills: npx skills update → add → SSH → Manual
│ ├─ Uninstalled skills: npx skills add → SSH → Manual (unchanged)
│ └─ Newly added skills: Mark as to be installed
│
▼
Step 7: Generate report (Agent directly formats output, including dependency handling instructions)
Detailed Execution Steps
Step 0: Self-update (Update skill-install-manager itself)
Before processing the skill list, first update skill-install-manager to the latest version. This ensures the skill list file is up-to-date and includes all new skills.
Execution Flow
-
Read old list summary: Before executing the update, read the current skill list file
references/Reasonix-skill-list-v2.md
and record the set of all skill names as the "old list summary".
-
Attempt Method A — (15s timeout):
powershell
npx skills update skill-install-manager -g -y
- Successful (returns within 15s) → ✅ Self-update successful, jump to Step 3
- Timeout or failed → Fallback to Method B
-
Attempt Method B — HTTPS (30s timeout):
powershell
npx skills add https://github.com/MarecGents/marec-agent-skills --skill skill-install-manager -g -a reasonix -y
- Successful → ✅ Self-update successful (add)
- Timeout → Fallback to Method C
-
Attempt Method C — SSH (30s timeout):
powershell
npx skills add git@github.com:MarecGents/marec-agent-skills.git --skill skill-install-manager -g -a reasonix -y
- Successful → ✅ Self-update successful (ssh)
- Timeout → Fallback to Method D
-
Attempt Method D — Manual download (refer to Method C in Step ⑥):
Directly download the latest files of skill-install-manager from GitHub and overwrite the local installation.
-
Read new list after update: Re-read
references/Reasonix-skill-list-v2.md
and record the latest content for subsequent steps.
Note: If all update methods fail, do not block the subsequent process — continue execution using the current old version. Record the failure reason in the final report.
Progress Report: ⏫ Self-update: Success/Failure (Method X)
Step 1: Determine skill list file path
- Check if the user explicitly specified a file path in the task. If yes, use it directly.
- If the user did not specify, search for default paths in the following priority:
- (current working directory)
./sandbox/dev/skill-list.md
references/Reasonix-skill-list-v2.md
(Skill built-in list file)
- Use the tool to read the file content. If the file does not exist, search for the next priority path.
- If all paths do not exist, ask the user to provide the file path.
Step 2: Compare old and new lists
After self-update is completed, compare the updated skill list with the "old list summary" recorded before the update.
-
Compare the skill name sets of the old and new lists:
- Skills present in the new list but not in the old list → Mark as 🆕 Newly Added Skills
- Skills present in the old list but not in the new list → Mark as 🗑️ Removed Skills (retain installed ones, do not uninstall)
- Skills present in both lists → Mark as ➡️ Continued Skills
-
Special handling for 🆕 Newly Added Skills:
- Skip version check in subsequent Step ⑤ (Comparative Analysis) since they are brand new, directly mark as missing (to be installed)
- Prioritize installing these newly added skills in subsequent Step ⑥ (Execute Installation)
-
Output comparison results:
📋 Skill List Changes:
🆕 Added: xxx-skill, yyy-skill (N items)
🗑️ Removed: zzz-skill (N items) — No impact on installed skills
➡️ Continued: M items
Note: If self-update fails (using old version), the result of the old and new list comparison is empty (no changes), skip this step directly.
Step 3: Parse list file
Agent Direct Execution (Main Path): Directly parse file content during reasoning
Process each line according to the following rules:
- Lines starting with → Extract URL and start a new source section
- Lines in the format
N. <skill-name>: npx skills add ...
→ Extract skill name and installation command
- Lines in the format (without installation command) → Extract name, mark installCmd=null
- Blank lines or non-matching lines → Skip
Store the parsing results in a temporary structure, formatted as follows:
Source 1: https://github.com/owner/repo
├── skill-a → npx skills add ...
├── skill-b → npx skills add ...
Source 2: https://github.com/another/repo
├── skill-c → npx skills add ...
🔵 JS Script Auxiliary: If structured JSON output is required, run the following script (optional, not mandatory):
powershell
node "<skill-path>\scripts\compare-skills.js" --parse-only --list "<list-file>"
Progress Report: ✅ Parsing completed: N sources, M skills
Step 4: Get current global installation status
Agent Direct Execution (Main Path):
-
Run the following command to get the global installation list:
If the command has no response (stuck) within 15s, terminate with Ctrl+C and skip (mark as "Failed to get installation list").
-
Read lock file to get version information:
powershell
Get-Content "$env:USERPROFILE\.agents\.skill-lock.json" | ConvertFrom-Json
Or use the MCP
tool to directly read
~/.agents/.skill-lock.json
.
-
Extract the following information for each installed skill:
- — Skill name
- — List of installed agents
- — Git commit SHA at installation (used for version comparison)
- / — Source information
Progress Report: ✅ Global installation status read: N installed skills
Step 5: Comparative analysis
Agent Direct Execution (Main Path) — Compare one by one during reasoning, report progress at each step:
5.1 Process by source grouping
Group the origins list parsed in Step ③ by URL, process skills from the same repository together.
5.2 Version check per repository
For each source repository (Query once per repository only, multiple skills in the same repository share the query result to avoid repeated network requests):
Checking: [Repository Name] (N skills)...
Method A (Priority) — Quick Check:
powershell
$job = Start-Job -ScriptBlock { git ls-remote https://github.com/{owner}/{repo}.git HEAD }
$result = $job | Wait-Job -Timeout 15
if ($result) {
$sha = (Receive-Job $job).Trim().Split()[0]
Remove-Job $job
} else {
Stop-Job $job; Remove-Job $job
# Fallback to Method B
}
- Successful (returns within 15s) → Extract SHA, compare with lock file → Mark as outdated/upToDate
- Timeout (no response within 15s) → Fallback to Method B
Method B (Fallback) — GitHub API Query:
web_fetch: https://api.github.com/repos/{owner}/{repo}/commits?per_page=1
- Successful → Extract latest_commit.sha from returned JSON
- Failed → Mark as "Status unknown (network unreachable)"
5.3 Classification summary
After processing each repository, output progress in real-time (skills in the same repository share the same commit query result, consistent results):
📦 anthropics/skills (7 skills):
✅ Latest commit of repository 9d2f1a... (1 query, shared by 7 skills)
✅ skill-creator → Updatable (hash: 7e3c9c... → 9d2f1a...)
📦 obra/superpowers (2 skills):
⚠️ git ls-remote timeout → Fallback to web_fetch → Latest commit d884ae...
✅ brainstorming → Updatable
✅ systematic-debugging → Up to date
... (etc)
Step 5.5: Dependency Pre-check (Before installation/update)
Before executing installation/update, first check if prerequisite skills for pending skills (missing / 🆕 / outdated) are installed to avoid skills being installed but unable to work due to missing prerequisites.
5.5.1 Judgment Basis
Find the prerequisite dependency declaration of skills in the following priority (as long as any source is hit):
- List file annotation: If a skill name appears near another skill entry in
Reasonix-skill-list-v2.md
with dependency instructions, use it directly
- Skill's own metadata: Read the frontmatter of the to-be-installed skill's , check , , fields
- Known dependency patterns (no network required, built-in judgment directly):
- → Depends on , ,
github-project-replication
→ Depends on , ,
- → Depends on , ,
- / / → Depends on
- series → Depends on (or homologous )
- → Depends on (same repository, must be installed together)
- → Depends on (as a sub-skill of docx)
- → Text extraction requires (pip package, install together if markitdown skill is in the list)
- → Depends on , (/ are design inspirations, not runtime dependencies, not included)
5.5.2 Processing Flow
- Parse the set of prerequisite skills for each pending skill
- Compare with the "current installed list" (result of Step ④):
- Prerequisite installed → No processing needed, continue
- Prerequisite not installed → Add the prerequisite skill to the installation queue (record in ), and mark the source skill
- Dependency queuing rules:
- If the prerequisite skill exists in the list file (has installCmd) → Add to installation queue directly
- If the prerequisite skill is not in the list file → Report to the user, ask whether to add the installation command of the prerequisite skill to the list file before installation
- Prerequisite skills from the same repository (e.g., grill-me → grilling) → Prioritize installation in the same repository to reduce network requests
- Output dependency pre-check results:
🔗 Dependency Pre-check:
grill-me → Depends on grilling (same repository, added to installation queue)
default → Depends on brainstorming/planning-with-files-zh/skill-standard-harness (all installed ✅)
ieee-mg-writing → Depends on ieee-mg-share (installed ✅)
Step 6: Execute installation/update
For missing, outdated and 🆕 newly added skills, install or update according to the following rules:
6.1 Judge skill status
Select installation method based on skill status:
| Status | Installation Method |
|---|
| missing (not installed) | → SSH → Manual download |
| outdated (installed and updatable) | → → SSH → Manual download |
| 🆕 Newly Added (added to list) | Equivalent to missing, marked as to be installed |
| pendingDeps (added via dependency pre-check) | Equivalent to missing, but installed prior to all other statuses |
Unified Agent Parameters (Whitelist): All
commands uniformly use
-a reasonix -a claude-code -a opencode -a codex
(install all four Agents,
agent names are all lowercase hyphenated:
,
,
,
).
Do not install GitHub Copilot () and Kimi Code CLI () — this is the confirmed installation whitelist for this machine, no installation/update command shall include these two agents. If errors occur due to some Agents not being installed, fallback to
single Agent.
6.2 For missing / 🆕 newly added skills: Execute installation
Installing: [skill-name] (Source: [origin-url])...
Attempt A — HTTPS Installation (30s timeout):
powershell
$job = Start-Job -ScriptBlock { npx skills add "{url}" --skill "{name}" -g -a reasonix -a claude-code -a opencode -a codex -y }
$result = $job | Wait-Job -Timeout 30
if ($result) {
$output = Receive-Job $job
Remove-Job $job
# Installation successful → ✅
} else {
Stop-Job $job; Remove-Job $job
# Timeout → Fallback to Attempt B
}
- Successful (returns within 30s) → ✅ Record success
- Timeout (no response within 30s) → Fallback to Attempt B
Attempt B (Fallback) — SSH Installation (30s timeout):
URL Conversion: https://github.com/owner/repo → git@github.com:owner/repo.git
powershell
$job = Start-Job -ScriptBlock { npx skills add "git@github.com:{owner}/{repo}.git" --skill "{name}" -g -a reasonix -y }
$result = $job | Wait-Job -Timeout 30
- Successful → ✅ (ssh) Record success
- Timeout → Fallback to Attempt C
Attempt C (Final Fallback) — Agent direct manual download installation:
When
is completely unavailable, the Agent uses its own tools to complete installation:
-
Get repository default branch:
web_fetch: https://api.github.com/repos/{owner}/{repo}
Extract
(usually main or master)
-
Get file tree, locate skill directory:
web_fetch: https://api.github.com/repos/{owner}/{repo}/git/trees/{default_branch}?recursive=1
Find the path containing the skill name in the file tree to determine the base path.
-
Download all files one by one:
For each blob file under the base path:
web_fetch: https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{filepath}
Write the content to
~/.agents/skills/{skill-name}/{relative-path}
.
- Use ( + ) or MCP Filesystem to write
-
Update lock file:
powershell
$lock = Get-Content "$env:USERPROFILE\.agents\.skill-lock.json" | ConvertFrom-Json
$lock.skills."{name}" = @{
source = "{owner}/{repo}"
sourceType = "github"
sourceUrl = "https://github.com/{owner}/{repo}.git"
skillPath = "{base-path}"
skillFolderHash = "{tree-sha}"
installedAt = (Get-Date -Format o)
updatedAt = (Get-Date -Format o)
}
$lock | ConvertTo-Json -Depth 10 | Set-Content "$env:USERPROFILE\.agents\.skill-lock.json"
-
Register skill (optional):
After manual installation, if
is available, run:
powershell
npx skills experimental_sync -y
If
is still unavailable, inform the user that the skill files have been written but need manual registration.
6.3 For outdated (installed and updatable) skills: Execute update
For installed and updatable skills,
prioritize using instead of re-adding.
Updating: [skill-name]...
Attempt A (Priority) — (15s timeout):
powershell
npx skills update {name} -g -y
- Successful (returns within 15s) → ✅ Record success (update)
- Timeout or failed → Fallback to Attempt B
Attempt B — HTTPS (30s timeout):
powershell
npx skills add "{url}" --skill "{name}" -g -a reasonix -y
- Successful → ✅ Record success (add)
- Timeout → Fallback to Attempt C
Attempt C — SSH Installation (30s timeout):
URL Conversion: https://github.com/owner/repo → git@github.com:owner/repo.git
powershell
npx skills add "git@github.com:{owner}/{repo}.git" --skill "{name}" -g -a reasonix -y
- Successful → ✅ Record success (ssh)
- Timeout → Fallback to Attempt D
Attempt D — Manual download (same process as Attempt C in 6.2)
6.4 Installation Order
Install in the following priority (Dependencies first, ensure prerequisites are in place first):
- 🔗 pendingDeps Pre-dependency Skills (Install first, prerequisites for other skills must be installed first)
- 🆕 Newly Added Skills (Install next, ensure new skills are available as soon as possible)
- ❌ Missing Skills (Install next)
- 🔄 Updatable Skills (Update last)
Skills from the same repository should be processed consecutively as much as possible (share one
and clone cache) to reduce network requests. Installation failure of dependency skills
does not block the installation of dependent skills, but clearly mark unmet dependencies in the final report.
Step 7: Generate report
Agent Direct Execution (Main Path) — Directly format output:
╔════════════════════════════════════════════╗
║ Skill Installation/Update Report ║
╚════════════════════════════════════════════╝
📊 Summary:
Total : 36 skills
Installed : 36 skills
Missing : 0 skills
Updatable : 5 skills (Updated: 3, Failed: 2)
Up to date: 28 skills
Unknown status: 3 skills
Dependencies filled: 1 (grilling, added due to grill-me dependency)
🔗 Dependency Handling:
✅ grill-me → grilling (installed together)
✅ ieee-mg-writing → ieee-mg-share (installed)
❌ pptx → markitdown (pip package, need to manually run pip install "markitdown[pptx]")
📦 anthropics/skills:
✅ skill-creator → Updated (HTTPS)
📦 imbad0202/academic-research-skills:
✅ academic-paper → Updated (SSH fallback)
❌ academic-pipeline → Update failed: Manual download timeout
📦 MarecGents/marec-agent-skills:
⏭️ check-reasonix-update → Unknown status (lock file data missing)
JS Auxiliary Scripts (Optional)
This skill comes with JS scripts as optional auxiliary tools, not core workflow dependencies:
| Script | Purpose | Trigger Method |
|---|
| Shared tool module | Referenced by other scripts |
scripts/compare-skills.js
| Quickly output structured JSON | node "<path>\scripts\compare-skills.js" --list "<file>"
|
| Batch installation with three-level fallback | node "<path>\scripts\install-skill.js" --name "<name>" --url "<url>"
|
Usage Scenario: Use when quick formatted JSON output is needed (e.g., integration into other toolchains). Agent direct execution mode is recommended for daily workflows.
Reference Files
references/Reasonix-skill-list-v2.md
— Built-in skill list file, containing all Origin URLs and corresponding Skills
references/skill-list-format.md
— Format description of skill list files
Usage Examples
Example 1: Full Sync
User: Help me sync my skills
Execution Flow:
0.
Self-update:
npx skills update skill-install-manager -g -y
→ Successful, get new version list
- Read updated built-in list file
references/Reasonix-skill-list-v2.md
- Old and new comparison: Compare with old summary, find 2 newly added skills → Mark as 🆕
- Agent parses: 7 sources, 38 skills
- → Read installation status
- Compare versions per repository with (15s timeout set)
- anthropics/skills → Successful, skill-creator is updatable
- Yuan1z0825/nature-skills → Timeout, web_fetch fallback successful
- Execute installation/update:
- 🆕 Newly added skills → Install via
- Outdated skills → Prioritize update via
- Output report
Example 2: Install Specific Skill
User: Help me install xx-skill, the list is in ./my-list.md
Execution Flow:
- Read
- Parse and find xx-skill and its source URL
- Check if installed → Not installed
npx skills add <url> --skill xx-skill -g -a reasonix -y
(30s timeout)
- Successful → ✅ Output report
Example 3: Update Installed Skills
User: Update all installed skills to the latest version
Execution Flow:
0. Self-update skill-install-manager → Get latest skill list
- Read list file
- Get global installation status
- Comparative analysis → Identify outdated skills
- For each outdated skill:
npx skills update <name> -g -y
(15s timeout) → Successful ✅
- Fallback to if failed
- Output update report
Example 4: Fully Offline Installation (npx unavailable)
- Parse list, determine the list of skills to install
- For all skills, directly proceed with manual download process
- GitHub API → Get file tree
- raw content → Write to
- Update lock file
- Inform user that files are in place
Notes
- Timeout Design: All shell commands use + to control timeout and avoid long-term stuck. has 15s timeout, has 15s timeout, has 30s timeout.
- Fallback Path: Each step has a clear fallback path: shell timeout → web_fetch fallback → manual file operation. No feedback failure is allowed.
- Progress Visibility: After processing each repository/skill, must output progress markers (//), no long-term silence allowed.
- Network Environment: GitHub API () and raw files (
raw.githubusercontent.com
) may require proxy. If all methods fail, report specific situation to the user.
- File Path: Backslashes in Windows paths need to be wrapped in double quotes, or use single quotes in PowerShell.
- : This is the git commit SHA (40-bit hexadecimal) recorded in at installation time. If this field is missing in the lock file, the skill will be marked as "unknown status", and the Agent will try to get the remote version via GitHub API as reference. Old version installers (before v2.2) may write 64-bit blob/tree SHA — such records cannot be compared with the commit SHA from , compare-skills.js will classify them as (with ) instead of false reporting ; comparison can be restored after executing to refresh the lock record.
- Category: Special entries in the list (such as shared resource directory) have no installation command, skip processing.
- Priority: For installed skills, prioritize using
npx skills update <skill-name> -g -y
(15s timeout) instead of re-adding. This is faster than (only updates installed skills, no need to re-clone the entire repository) and does not duplicate file copying. Only fallback to add when update fails.
- Dependency Pre-check Mandatory: The dependency pre-check in Step ⑤.5 cannot be skipped. Whenever installing/updating missing or newly added skills, must first check their prerequisites; missing dependencies will cause skills to be installed but unavailable (e.g., only grill-me without grilling).
- Path Case Sensitivity: Paths like are case-sensitive, be sure to use the exact path confirmed by .
- Agent Name Case and Whitelist: The agent names in the parameter of are case-sensitive, and must use lowercase hyphenated form. Reasonix is , Claude Code is , OpenCode is , Codex is . Using display names ( / / ) will result in error. The installation whitelist for this machine is limited to the above 4 agents — do not install (GitHub Copilot) and (Kimi Code CLI).