AI-Research-SKILLs npm 包设计与实现用 npx 一键为编码 Agent 安装 AI 研究技能【免费下载链接】AI-Research-SKILLsComprehensive open-source library of AI research and engineering skills for any AI model. Package the skills and your claude code/codex/gemini agent will be an AI research agent with full horsepower. Maintained by Orchestra Research.项目地址: https://gitcode.com/gh_mirrors/ai/AI-Research-SKILLs本文系统梳理 AI-Research-SKILLs 仓库中orchestra-research/skillsnpm/npx 包的设计方案docs/npm-package-plan.md涵盖包架构、CLI 命令体系、多 Agent 支持、canonical storage symlink 存储策略、锁文件与注册表机制并结合仓库中已落地的实现packages/ai-research-skills给出源码级印证。读完本文你将掌握如何将一个目录树式的技能库打包成可被任何编码 Agent 调用的安装器并理解从设计文档到可运行 CLI 的完整转化路径。一、为什么要做 npm 包从技能库到一键安装器AI-Research-SKILLs 仓库本身是一棵按数字前缀分类组织的技能树如01-model-architecture、06-post-training、20-ml-paper-writing每个技能由SKILL.md加references/、templates/组成供 Claude Code、Cursor、Codex、Gemini CLI 等编码 Agent 读取。但直接把整个仓库 clone 下来手动复制存在三个痛点用户需要在每个 Agent 的 skills 目录如~/.claude/skills/里手动放置技能技能更新无法追踪无法知道哪些技能装到了哪个 Agent不同 Agent 的配置目录路径不同记忆与维护成本高。因此设计文档提出创建一个 npm/npx 包让用户用一条命令即可完成技能下载 → 分类归置 → 按 Agent 目录建链 → 锁文件记录的全流程。这个目标与仓库主 README 的定位一致——把技能打包后任何 AI 模型驱动的编码 Agent 都能立刻变成满血的 AI 研究 Agent。二、包名选择与发布形态设计文档给出了三个候选包名候选名评价orchestra-research/skills推荐。scoped 命名专业、不冲突ai-research-skills简单直白但可能与既有 npm 包冲突orchestra-skills简短、有品牌感从仓库实际落地看最终发布名定为orchestra-research/ai-research-skills见 packages/ai-research-skills/package.json当前版本 1.7.1既保留了orchestra-research的 scoped 前缀又用ai-research-skills明确了用途。该包声明type: module、bin: { ai-research-skills: ./bin/cli.js }Node 版本要求18.0.0。用户有两种使用方式# 全局安装后调用 npm install -g orchestra-research/ai-research-skills # 或直接 npx 免安装调用推荐文档原型为 orchestra-research/skills npx orchestra-research/skills command三、架构设计核心组件与目录结构设计文档规划的包内结构如下orchestra-research/skills/ ├── bin/ │ └── cli.js # CLI entry point ├── src/ │ ├── agents/ # Agent-specific handlers │ │ ├── claude.js # .claude/skills/ │ │ ├── cursor.js # .cursor/skills/ │ │ ├── codex.js # .codex/skills/ │ │ ├── windsurf.js # .windsurf/skills/ │ │ ├── copilot.js # .github/copilot-instructions.md │ │ └── index.js # Agent registry │ ├── commands/ │ │ ├── install.js # Install skills │ │ ├── list.js # List available/installed skills │ │ ├── update.js # Update skills │ │ ├── remove.js # Remove skills │ │ └── detect.js # Detect installed agents │ ├── storage/ │ │ ├── canonical.js # ~/.orchestra-skills/ management │ │ ├── lock.js # Lock file management │ │ └── symlink.js # Symlink utilities │ ├── registry/ │ │ └── skills.json # Skill manifest (or fetch from GitHub) │ └── utils/ │ ├── fetch.js # Download skills from GitHub │ └── format.js # Format for different agents ├── package.json └── README.md落地后的实现做了一次扁平化重构职责划分更直接以 packages/ai-research-skills/src 为准bin/cli.js真正的 CLI 入口main().catch(...)兜底错误并process.exit(1)src/index.js主流程控制器负责交互式流程与直接命令模式两条路径的分发src/agents.jsAgent 注册表与检测逻辑对应设计中的agents/index.jssrc/installer.js下载、canonical 存储、symlink、锁文件、本地安装对应设计中的storage/utils/fetch.jssrc/prompts.js分类清单、交互式提问与参数解析对应设计中的commands/ inquirer 交互src/ascii.js欢迎屏、检测结果屏、成功屏等终端 UI。从源码结构看设计文档中的每类命令一个文件演进为按能力域划分模块但核心边界——Agent 处理、存储、注册表、工具函数——完全对应。四、支持的 Agent从 7 个规划到 10 个实现设计文档基于调研确认了 7 个支持 SKILL.md 统一格式的 AgentAgentConfig LocationSkills LocationClaude Code~/.claude/.claude/skills/Cursor~/.cursor/.cursor/skills/Codex (OpenAI)~/.codex/.codex/skills/Windsurf~/.windsurf/.windsurf/skills/Gemini CLI~/.gemini/.gemini/skills/Kilo Code~/.kilocode/.kilocode/skills/Qwen Code~/.qwen/.qwen/skills/实际实现src/agents.js扩展到了10 个 Agent并补充了全局路径/本地路径分离的字段设计——configDir/skillsDir是全局~/.{agent}/下路径localConfigDir/localSkillsDir是项目内./{agent}/路径两者可以不同例如 OpenClaw 本地路径直接落在项目根skills/Agent ID名称全局配置目录本地配置目录claudeClaude Code.claude.claudecursorCursor.cursor.cursorcodexCodex.codex.codexgeminiGemini CLI.gemini.geminiqwenQwen Code.qwen.qwenopencodeOpenCode.config/opencode.opencodeopenclawOpenClaw.openclaw.项目根agentsShared Agents.agents.agentshermesHermes Agent.hermes.hermesqoderQoder.qoder.qoder检测逻辑本身很简单但实用src/agents.js遍历SUPPORTED_AGENTS检查~/{configDir}是否存在存在即视为已安装并推导出skillsPath。这正是设计文档中detect命令的底层实现——Check~/.claudeexists → Claude Code detected。五、CLI 命令体系安装、查询、更新、卸载设计文档给出了完整命令面这里全部继承并标注与源码的对应关系# Detect installed coding agents npx orchestra-research/skills detect # List all available skills npx orchestra-research/skills list # List skills by category npx orchestra-research/skills list --category post-training # List available categories npx orchestra-research/skills categories # Install all skills for detected agents npx orchestra-research/skills install --all # Install specific category (user selects from list) npx orchestra-research/skills install --category post-training # Install multiple categories npx orchestra-research/skills install --category post-training,fine-tuning,inference # Install specific skill npx orchestra-research/skills install verl # Install for specific agent only npx orchestra-research/skills install verl --agent claude # Install to project scope (current directory) npx orchestra-research/skills install verl --scope project # Install to global scope (home directory) npx orchestra-research/skills install verl --scope global # Interactive mode - prompts user to select categories/skills npx orchestra-research/skills install --interactive # Update all skills npx orchestra-research/skills update # Remove a skill npx orchestra-research/skills remove verl # Show skill info npx orchestra-research/skills info verl落地实现对其做了收敛src/prompts.js 的parseArgs支持install、list、update、uninstall四个子命令以及--all/-a、--local/-l、--agent、--category四个选项无任何选项时自动进入交互式流程src/index.js。--scope在实现中演化为--local项目级安装。注意detect不再作为独立子命令——Agent 检测被内化到交互式流程的第一步。交互式安装流程设计文档规划的install --interactive交互过程? What would you like to install? ○ All skills (86 skills) ○ Select by category ○ Select individual skills ? Select categories to install: (Space to select, Enter to confirm) ◉ 01-model-architecture (6 skills) ◯ 02-tokenization (2 skills) ◯ 03-fine-tuning (5 skills) ◉ 06-post-training (8 skills) ◯ 20-ml-paper-writing (1 skill) ... ? Confirm installation of 14 skills to Claude Code, Cursor, Gemini CLI? (Y/n)实现版在此基础上扩展为多级菜单导航src/index.js欢迎与 Agent 检测 → 主菜单安装新技能 / 项目本地安装 / 查看已装 / 更新 / 卸载 / 退出→ 安装方式选择Everything / Quick start / 按分类 / 按单个技能→ 目标 Agent 选择 → 安装摘要确认 → 执行安装。每级都支持← Back返回与Exit退出交互状态机通过带标签的while(true)循环实现例如step2_menu、step3_choice、step4_categories。安装选项还额外提供了Quick start 精选包src/prompts.js内置 15 个核心技能GRPO、verl、TRL、Axolotl、Unsloth、vLLM、SGLang、DeepSpeed、Flash Attention、WB、lm-eval-harness、DSPy、Chroma、ML Paper Writing、Autoresearch。六、存储策略Canonical Storage Symlink 锁文件这是整个设计的技术核心。设计文档推荐canonical storage单一事实源 软链接方案~/.orchestra-skills/ # Canonical storage ├── .lock.json # Lock file for versioning ├── 01-model-architecture/ │ ├── megatron-core/ │ │ └── SKILL.md │ └── litgpt/ │ └── SKILL.md ├── 06-post-training/ │ ├── verl/ │ │ ├── SKILL.md │ │ └── references/ │ ├── slime/ │ └── ... └── ... ~/.claude/skills/ # Symlinks to canonical ├── verl - ~/.orchestra-skills/06-post-training/verl ├── slime - ~/.orchestra-skills/06-post-training/slime └── ... ~/.cursor/skills/ # Same symlinks ├── verl - ~/.orchestra-skills/06-post-training/verl └── ...这种设计的收益很明确技能文件只存一份多个 Agent 通过 symlink 共享更新时只需重写 canonical 目录所有 Agent 同步生效。实现版将 canonical 目录定为~/.orchestra/skillssrc/installer.js并增加了降级兜底createSymlinks中若symlinkSync失败典型场景如 Windows 未开启开发者模式自动回退为cpSync复制整个技能目录src/installer.js保证跨平台可用性。卸载时则通过lstatSync只删除指向 canonical 目录的 symlink不误删 Agent 自己的其他文件src/installer.js。锁文件格式设计文档定义的.lock.json结构{ version: 1.0.0, lastUpdated: 2025-01-28T00:00:00Z, skills: { verl: { version: 1.0.0, category: 06-post-training, installedAt: 2025-01-28T00:00:00Z, agents: [claude, cursor] } }, agents: { claude: { detected: true, scope: global, path: ~/.claude/skills } } }实现版将 skills 从以名称为键的映射简化为数组并新增installedAt时间戳src/installer.js// 实际写入结构installSkills 中 lock.version 1.0.0; lock.installedAt new Date().toISOString(); lock.skills skills; // [{ category, skill, standalone }] lock.agents agents.map(a a.id); writeLock(lock);锁文件承担三重职责版本追踪version/installedAt、已装清单skills含 standalone 标记、目标 Agent 记录agents。更新命令正是读取锁文件 → 重下载相同技能 → 重建 symlink → 重写锁的闭环updateInstalledSkills。七、技能组织模式两种结构都要兼容设计文档指出仓库存在两种技能组织模式安装器必须同时兼容Pattern 1嵌套技能大多数分类XX-category/ ├── skill-name-1/ │ ├── SKILL.md │ └── references/ ├── skill-name-2/ │ └── SKILL.md └── ...例如 06-post-training/verl/SKILL.md。Pattern 2独立技能单个技能即分类XX-category-name/ ├── SKILL.md ├── references/ └── templates/例如 20-ml-paper-writing/SKILL.md分类本身就是技能。下载器用该分类目录下是否直接存在SKILL.md来判别两种模式src/installer.jsconst standaloneSkillPath join(categoryPath, SKILL.md); if (existsSync(standaloneSkillPath)) { // 独立技能整个分类复制为单个技能 copyDirectoryContents(categoryPath, targetCategoryPath); skills.push({ category: categoryId, skill: categoryId, standalone: true }); } else { // 嵌套技能遍历子目录逐个识别 SKILL.md for (const entry of readdirSync(categoryPath, { withFileTypes: true })) { if (entry.isDirectory() existsSync(join(categoryPath, entry.name, SKILL.md))) { copyDirectoryContents(join(categoryPath, entry.name), targetSkillPath); skills.push({ category: categoryId, skill: entry.name, standalone: false }); } } }standalone标记贯穿全链路symlink 命名skill.categoryvsskill.skill、卸载清理、锁文件读写都依赖它区分两种结构这是设计文档必须处理两种模式要求的完整落地。八、技能注册表内嵌 Manifest 与远程拉取设计文档给出两种注册表方案Option A内嵌更简单—— 把技能清单打进 npm 包随版本发布更新{ version: 1.0.0, categories: { 01-model-architecture: { name: Model Architecture, skills: [megatron-core, litgpt, mamba, rwkv, nanogpt] }, 06-post-training: { name: Post-Training (RLHF/DPO/GRPO), skills: [trl, grpo, openrlhf, simpo, verl, slime, miles, torchforge] } }, skills: { verl: { name: verl, category: 06-post-training, description: Volcano Engine RL for LLM post-training, tags: [Reinforcement Learning, RLHF, GRPO, PPO] } } }Option B远程拉取更灵活—— 每次运行从 GitHub API 拉取最新 manifestconst REPO orchestra-research/AI-research-SKILLs; const MANIFEST_URL https://api.github.com/repos/${REPO}/contents/skill-manifest.json; async function fetchSkillManifest() { const response await fetch(MANIFEST_URL); return JSON.parse(atob(response.content)); }设计文档的结论是先内嵌起步再把远程拉取作为更新机制。实现版走了第三条路——manifest 直接写死在代码里CATEGORIES、INDIVIDUAL_SKILLS常量见 src/prompts.js共登记23 个分类、98 个技能而技能内容本身则通过git clone --depth 1实时从仓库拉取src/installer.js克隆到~/.orchestra/.temp-clone临时目录选中分类复制进 canonical 目录后即清理。这样既避免了维护 JSON manifest 的双份同步问题又保证技能内容始终最新同时--depth 1控制了下载体积。九、安装流程全景四步走设计文档将安装流程抽象为四个阶段npx orchestra-research/skills install verl │ ▼ ┌──────────────────────────────────────────────┐ │ 1. Detect installed agents │ │ - Check ~/.claude exists → Claude Code │ │ - Check ~/.cursor exists → Cursor │ │ - Check ~/.codex exists → Codex │ └──────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────┐ │ 2. Download skill to canonical storage │ │ - Fetch: AI-research-SKILLs/06-post-training/verl │ │ - Save: ~/.orchestra-skills/06-post-training/verl │ │ - Update lock file │ └──────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────┐ │ 3. Create symlinks for each detected agent │ │ - ~/.claude/skills/verl → canonical/verl │ │ - ~/.cursor/skills/verl → canonical/verl │ └──────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────┐ │ 4. Output success message │ │ ✓ Installed verl for: Claude Code, Cursor │ └──────────────────────────────────────────────┘源码中的主安装函数installSkillssrc/installer.js完全对应这四步downloadSkills完成步骤 12克隆 按分类复制 写锁createSymlinks完成步骤 3逐 Agent 建链并统计数量最后打印结果。installSpecificSkills是面向单技能verl的变体差异仅在下载粒度。整个链路都有oraspinner 提示当前阶段失败时spinner.fail并向上抛出错误。十、Agent 特定处理统一注册表 统一安装函数设计文档强调所有 7 个现 10 个Agent 都遵循相同的SKILL.md格式和 symlink 模式因此可以用一份注册表 一个通用安装函数覆盖全部 Agent// src/agents/index.js设计原型 export const agents { claude: { name: Claude Code, configDir: ~/.claude, skillsDir: ~/.claude/skills, projectSkillsDir: .claude/skills }, cursor: { name: Cursor, configDir: ~/.cursor, skillsDir: ~/.cursor/skills, projectSkillsDir: .cursor/skills }, codex: { name: Codex (OpenAI), configDir: ~/.codex, skillsDir: ~/.codex/skills, projectSkillsDir: .codex/skills }, windsurf: { name: Windsurf, configDir: ~/.windsurf, skillsDir: ~/.windsurf/skills, projectSkillsDir: .windsurf/skills }, gemini: { name: Gemini CLI, configDir: ~/.gemini, skillsDir: ~/.gemini/skills, projectSkillsDir: .gemini/skills }, kilo: { name: Kilo Code, configDir: ~/.kilocode, skillsDir: ~/.kilocode/skills, projectSkillsDir: .kilocode/skills }, qwen: { name: Qwen Code, configDir: ~/.qwen, skillsDir: ~/.qwen/skills, projectSkillsDir: .qwen/skills }, }; // Common install function for all agents function installSkill(agent, skillName, canonicalPath, scope) { const targetDir scope project ? agent.projectSkillsDir : expandHome(agent.skillsDir); fs.ensureDirSync(targetDir); fs.symlinkSync(canonicalPath, path.join(targetDir, skillName)); }实现版沿用了这个思想注册表与安装逻辑完全解耦installer.js中的createSymlinks(agent, skills, spinner)对任意 Agent 配置对象都成立src/installer.js新增 Agent 只需在agents.js的SUPPORTED_AGENTS数组里追加一条记录。设计文档中的kiloKilo Code与windsurf在实现中被替换/扩充为 OpenCode、OpenClaw、Hermes、Qoder、Shared Agents 等更常见的 Agent体现了注册表驱动架构的扩展性。十一、项目级本地安装从 symlink 到复制设计文档仅在命令列表中一笔带过--scope project而实现版把它做成了与全局安装并列的完整能力--local。两者的本质区别全局安装默认技能存 canonical~/.orchestra/skillsAgent 目录放 symlink本地安装--local技能直接复制进项目内的 Agent 目录可提交到 git 与团队共享。my-project/ ├── .claude/skills/ # Claude Code picks these up │ ├── grpo-rl-training/ │ └── vllm/ ├── .cursor/skills/ # Cursor picks these up │ ├── grpo-rl-training/ │ └── vllm/ ├── .orchestra-skills.json # 项目级锁文件追踪已装技能 └── ...实现版将项目级锁文件命名为.orchestra-skills.jsonsrc/installer.js与全局.lock.json分离。本地安装走installSkillsLocal/installSpecificSkillsLocal同样先临时克隆仓库但复制目标是projectDir/{agent.localConfigDir}/skills/{skill}通过buildLocalAgentTargets计算且不建 symlink、不写全局锁只更新项目锁文件src/installer.js。命令形态npx orchestra-research/ai-research-skills install --all --local npx orchestra-research/ai-research-skills install --category post-training --local npx orchestra-research/ai-research-skills list --local npx orchestra-research/ai-research-skills update --local npx orchestra-research/ai-research-skills uninstall --local本地安装的三个收益按项目定制不同项目只装所需技能、版本可控可提交 git全团队共享同一技能集、可复现锁文件精确记录已装内容。十二、用户体验设计首次运行、安装与列表设计文档用三个终端示例定义了 CLI 的 UX 基调检测结果用 ✓/✗ 符号、安装过程显示进度、列表用 ●/○ 区分已装/未装。首次运行detect$ npx orchestra-research/skills detect Detecting installed coding agents... ✓ Claude Code ~/.claude ✓ Cursor ~/.cursor ✗ Codex not found ✗ Windsurf not found ✓ GitHub Copilot available for projects Found 2 global agents, 1 project-only agent. Run npx orchestra-research/skills install --all to install all skills.安装技能$ npx orchestra-research/skills install post-training Installing post-training skills... Downloading skills from GitHub... ✓ trl (1.2 KB) ✓ grpo (15.3 KB) ✓ openrlhf (8.7 KB) ✓ simpo (4.2 KB) ✓ verl (12.1 KB) ✓ slime (18.4 KB) ✓ miles (9.8 KB) ✓ torchforge (11.2 KB) Creating symlinks... ✓ Claude Code: 8 skills installed ✓ Cursor: 8 skills installed ✨ Done! Installed 8 skills for 2 agents. Skills are stored in: ~/.orchestra-skills/06-post-training/ Symlinks created in: ~/.claude/skills/, ~/.cursor/skills/列出技能$ npx orchestra-research/skills list AI Research Skills (81 total) Model Architecture (5) ○ megatron-core Megatron-Core for large-scale model training ○ litgpt LitGPT for efficient LLM development ○ mamba Mamba state space models ○ rwkv RWKV linear attention models ○ nanogpt NanoGPT for learning/prototyping Post-Training (8) ● verl Volcano Engine RL for LLM post-training ● slime Megatron-SGLang RL training framework ● miles Enterprise-grade RL for large MoE models ● torchforge PyTorch-native agentic RL library ○ trl Transformer Reinforcement Learning ○ grpo Group Relative Policy Optimization ○ openrlhf OpenRLHF training framework ○ simpo Simple Preference Optimization ● installed, ○ available实现版用chalkora 大型 ASCII LOGO 强化了这一风格src/ascii.js欢迎屏展示技能/分类/Agent 统计数字安装完成屏输出✓ Installation CompletelistInstalledSkills通过扫描 canonical 目录的真实目录结构生成列表而非依赖锁文件并自动识别 standalone 技能标注(standalone)src/installer.js。十三、实施阶段规划与依赖清单设计文档规划了三周迭代节奏Phase 1MVP第 1 周用 commander.js 搭 CLI 骨架Agent 检测Claude、Cursor、Codex从 GitHub 下载技能向检测到的 Agent 建 symlink基础 list / install 命令Phase 2完整功能第 2 周canonical storage 锁文件update / remove 命令分类过滤项目级 vs 全局作用域Copilot 特殊处理Phase 3打磨第 3 周交互模式inquirer.js 提示进度条与更好 UX错误处理与恢复文档与 READMEnpm 发布 GitHub Actions 自动化发布设计文档给出的依赖规划实现版已收敛为 3 个见 packages/ai-research-skills/package.json// 设计文档规划 { dependencies: { commander: ^12.0.0, // CLI framework chalk: ^5.3.0, // Colored output ora: ^8.0.0, // Spinners fs-extra: ^11.2.0, // File utilities node-fetch: ^3.3.0, // HTTP requests inquirer: ^9.2.0 // Interactive prompts (optional) } }实现版实际使用chalk 5.6.2彩色输出、inquirer 9.3.8交互提示、ora 8.2.0spinnercommander 被自研的parseArgs取代fs-extra与node-fetch被 Node 内置的fsAPI 与git clone取代依赖更精简。发布命令# Login to npm npm login # Publish scoped package (public) npm publish --access public十四、替代方案对比与取舍设计文档评估了三种替代方案并给出结论方案结论理由Shell 脚本PR #6 思路拒绝能力受限、无跨平台支持、UX 差Python 包pipx install orchestra-skills备选可行但 npm/npx 更贴近开发者工具生态Homebrew Formulabrew install未来可加可为 Mac 用户提供 brew 安装入口十五、设计落地对照与下一步从 docs/npm-package-plan.md 到 packages/ai-research-skills 的演进可以看到一份设计文档落地时常见的收敛与扩展收敛命令面从 15 条收敛为 4 个子命令 交互式流程依赖从 6 个收敛为 3 个锁文件结构简化扩展Agent 从 7 个扩到 10 个新增--local项目级安装与 Quick start 精选包新增全局/本地双路径的 Agent 配置模型下载方式从GitHub API manifest改为浅克隆 目录复制。设计文档的 Next Steps 在仓库中已有大部分进展npm 包目录已建立packages/ai-research-skills/MVP 与完整功能Phase 1/2已实现主 README 已补充npx orchestra-research/ai-research-skills安装说明待推进项包括批量发布自动化、跨平台回归测试特别是 symlink 回退复制路径、以及设计文档提到的 Homebrew 入口。对于想在自己的项目里复刻这套方案的读者关键启示是用注册表驱动 canonical 存储 统一 symlink的架构可以把任何目录化的知识库/技能库低成本地包装成多 Agent 可用的安装器——Agent 配置是数据SUPPORTED_AGENTS数组、安装逻辑是通用函数createSymlinks、状态可追踪锁文件、内容实时可更新浅克隆四者组合即为完整闭环。【免费下载链接】AI-Research-SKILLsComprehensive open-source library of AI research and engineering skills for any AI model. Package the skills and your claude code/codex/gemini agent will be an AI research agent with full horsepower. Maintained by Orchestra Research.项目地址: https://gitcode.com/gh_mirrors/ai/AI-Research-SKILLs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考