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

npx skills

command as a Global installation, specifying the three Agents: Reasonix / Claude Code / OpenCode.

• "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"

1. 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".
2. Attempt Method A —

   npx skills update

   (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
3. Attempt Method B —

   npx skills add

   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
4. Attempt Method C —

   npx skills add

   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
5. 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.
6. 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.

1. Check if the user explicitly specified a file path in the task. If yes, use it directly.
2. If the user did not specify, search for default paths in the following priority:

   • ./skill-list.md

     (current working directory)

   • ./skills/skill-list.md

   • ./sandbox/dev/skill-list.md

   • references/Reasonix-skill-list-v2.md

     (Skill built-in list file)
3. Use the

   read_file

   tool to read the file content. If the file does not exist, search for the next priority path.
4. If all paths do not exist, ask the user to provide the file path.

1. 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
2. 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)
3. 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.

• Lines starting with

  ## Origin URL:

  → 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

  N. <skill-name>

  (without installation command) → Extract name, mark installCmd=null
• Blank lines or non-matching lines → Skip

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>"

1. Run the following command to get the global installation list:
   powershell

   npx skills ls -g --json

   If the command has no response (stuck) within 15s, terminate with Ctrl+C and skip (mark as "Failed to get installation list").
2. Read lock file to get version information:
   powershell

   Get-Content "$env:USERPROFILE\.agents\.skill-lock.json" | ConvertFrom-Json

   Or use the MCP

   read_file

   tool to directly read

   ~/.agents/.skill-lock.json

   .
3. Extract the following information for each installed skill:

   • name

     — Skill name

   • agents

     — List of installed agents

   • skillFolderHash

     — Git commit SHA at installation (used for version comparison)

   • sourceUrl

     /

     skillPath

     — Source information

Checking: [Repository Name] (N skills)...

git ls-remote

$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

web_fetch

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)"

1. List file annotation: If a skill name appears near another skill entry in

   Reasonix-skill-list-v2.md

   with dependency instructions, use it directly
2. Skill's own metadata: Read the frontmatter of the to-be-installed skill's

   SKILL.md

   , check

   related_skills

   ,

   dependencies

   ,

   requires

   fields
3. Known dependency patterns (no network required, built-in judgment directly):

   • default

     → Depends on

     brainstorming

     ,

     planning-with-files-zh

     ,

     skill-standard-harness

   • github-project-replication

     → Depends on

     brainstorming

     ,

     planning-with-files-zh

     ,

     skill-standard-harness

   • academic-pipeline

     → Depends on

     academic-paper

     ,

     academic-paper-reviewer

     ,

     deep-research

   • ieee-mg-writing

     /

     ieee-mg-polishing

     /

     ieee-mg-reviewer

     → Depends on

     ieee-mg-share

   • nature-*

     series → Depends on

     nature-shared

     (or homologous

     _shared

     )

   • grill-me

     → Depends on

     grilling

     (same repository, must be installed together)

   • zh-quotes

     → Depends on

     docx

     (as a sub-skill of docx)

   • pptx

     → Text extraction requires

     markitdown

     (pip package, install together if markitdown skill is in the list)

   • researchwrite

     → Depends on

     brainstorming

     ,

     docx

     (

     professor

     /

     avoid-ai-writing

     are design inspirations, not runtime dependencies, not included)

1. Parse the set of prerequisite skills for each pending skill
2. 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

     pendingDeps

     ), and mark the source skill
3. 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
4. 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 ✅)

npx skills add

npx skills update

npx skills add

Unified Agent Parameters (Whitelist): All

npx skills add

commands uniformly use

-a reasonix -a claude-code -a opencode -a codex

(install all four Agents, agent names are all lowercase hyphenated:

reasonix

,

claude-code

,

opencode

,

codex

). Do not install GitHub Copilot (

github-copilot

) and Kimi Code CLI (

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

-a reasonix

single Agent.

Installing: [skill-name] (Source: [origin-url])...

$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

URL Conversion: https://github.com/owner/repo → git@github.com:owner/repo.git

$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

npx skills add

1. Get repository default branch:

   web_fetch: https://api.github.com/repos/{owner}/{repo}

   Extract

   default_branch

   (usually main or master)
2. 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.
3. 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

     bash

     (

     New-Item

     +

     Set-Content

     ) or MCP Filesystem

     write_file

     to write
4. 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"

5. Register skill (optional): After manual installation, if

   npx skills

   is available, run:
   powershell

   npx skills experimental_sync -y

   If

   npx skills

   is still unavailable, inform the user that the skill files have been written but need manual registration.

npx skills update

Updating: [skill-name]...

npx skills update

npx skills update {name} -g -y

• Successful (returns within 15s) → ✅ Record success (update)
• Timeout or failed → Fallback to Attempt B

npx skills add

npx skills add "{url}" --skill "{name}" -g -a reasonix -y

• Successful → ✅ Record success (add)
• Timeout → Fallback to Attempt C

URL Conversion: https://github.com/owner/repo → git@github.com:owner/repo.git

npx skills add "git@github.com:{owner}/{repo}.git" --skill "{name}" -g -a reasonix -y

• Successful → ✅ Record success (ssh)
• Timeout → Fallback to Attempt D

1. 🔗 pendingDeps Pre-dependency Skills (Install first, prerequisites for other skills must be installed first)
2. 🆕 Newly Added Skills (Install next, ensure new skills are available as soon as possible)
3. ❌ Missing Skills (Install next)
4. 🔄 Updatable Skills (Update last)

git ls-remote

• 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

User: Help me sync my skills

npx skills update skill-install-manager -g -y

1. Read updated built-in list file

   references/Reasonix-skill-list-v2.md

2. Old and new comparison: Compare with old summary, find 2 newly added skills → Mark as 🆕
3. Agent parses: 7 sources, 38 skills

4. npx skills ls -g --json

   → Read installation status
5. Compare versions per repository with

   git ls-remote

   (15s timeout set)
   • anthropics/skills → Successful, skill-creator is updatable
   • Yuan1z0825/nature-skills → Timeout, web_fetch fallback successful
6. Execute installation/update:
   • 🆕 Newly added skills → Install via

     npx skills add

   • Outdated skills → Prioritize update via

     npx skills update

7. Output report

User: Help me install xx-skill, the list is in ./my-list.md

1. Read

   ./my-list.md

2. Parse and find xx-skill and its source URL
3. Check if installed → Not installed

4. npx skills add <url> --skill xx-skill -g -a reasonix -y

   (30s timeout)
5. Successful → ✅ Output report

User: Update all installed skills to the latest version

1. Read list file
2. Get global installation status
3. Comparative analysis → Identify outdated skills
4. For each outdated skill:

   • npx skills update <name> -g -y

     (15s timeout) → Successful ✅
   • Fallback to

     npx skills add

     if failed
5. Output update report

1. Parse list, determine the list of skills to install
2. For all skills, directly proceed with manual download process

3. web_fetch

   GitHub API → Get file tree

4. web_fetch

   raw content → Write to

   ~/.agents/skills/

5. Update lock file
6. Inform user that files are in place

1. Timeout Design: All shell commands use

   Start-Job

   +

   Wait-Job -Timeout

   to control timeout and avoid long-term stuck.

   git ls-remote

   has 15s timeout,

   npx skills update

   has 15s timeout,

   npx skills add

   has 30s timeout.
2. Fallback Path: Each step has a clear fallback path: shell timeout → web_fetch fallback → manual file operation. No feedback failure is allowed.
3. Progress Visibility: After processing each repository/skill, must output progress markers (

   ✅

   /

   ⚠️

   /

   ❌

   ), no long-term silence allowed.
4. Network Environment: GitHub API (

   api.github.com

   ) and raw files (

   raw.githubusercontent.com

   ) may require proxy. If all methods fail, report specific situation to the user.
5. File Path: Backslashes in Windows paths need to be wrapped in double quotes, or use single quotes in PowerShell.

6. skillFolderHash

   : This is the git commit SHA (40-bit hexadecimal) recorded in

   .skill-lock.json

   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

   web_fetch

   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

   git ls-remote

   , compare-skills.js will classify them as

   unknown

   (with

   refreshHint

   ) instead of false reporting

   outdated

   ; comparison can be restored after executing

   npx skills update

   to refresh the lock record.

7. skippable

   Category: Special entries in the list (such as

   _shared

   shared resource directory) have no installation command, skip processing.

8. npx skills update

   Priority: For installed skills, prioritize using

   npx skills update <skill-name> -g -y

   (15s timeout) instead of re-adding. This is faster than

   npx skills add

   (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.
9. 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).
10. Path Case Sensitivity: Paths like

    MarecGents

    are case-sensitive, be sure to use the exact path confirmed by

    pwd

    .
11. Agent Name Case and Whitelist: The agent names in the

    -a

    parameter of

    npx skills add

    are case-sensitive, and must use lowercase hyphenated form. Reasonix is

    reasonix

    , Claude Code is

    claude-code

    , OpenCode is

    opencode

    , Codex is

    codex

    . Using display names (

    Reasonix

    /

    Claude Code

    /

    OpenCode

    ) will result in

    Invalid agents

    error. The installation whitelist for this machine is limited to the above 4 agents — do not install

    github-copilot

    (GitHub Copilot) and

    kimi-code-cli

    (Kimi Code CLI).