# Agent Creator 深度调研报告 (Knowhow v1) > 调研目标:为 Agent Creator (HR & Skill Master) 提供一套可复制、可落地的技能装配 SOP,确保新员工从"空壳"到"全副武装"的每一步都有章可循。 > 输出时间:2026-04-09 > 调研者:Hunter --- ## 1. Agent Creator 角色定义与核心职责 ### 1.1 身份定位 **Agent Creator** 是 LemonAI 组织中的「人事与技能装配大师」。当 CTO 通过 `company hire` 创建了一个空壳 Agent 后,Agent Creator 负责为其: - **搜索并获取** 匹配岗位需求的开源技能 (Skill) - **安装与绑定** 技能到目标 Agent 的工作目录 - **处理授权缺失** 时的人工请援流程 - **发起进化请求** 将初代技能移交给 Innovator 进行 RL 训练与优化 ### 1.2 核心职责清单 | 职责 | 说明 | |------|------| | **Skill Hunting** | 利用网络搜索、GitHub、包管理器等渠道,找到与岗位描述匹配的技能代码 | | **Skill Binding** | 将获取的技能代码放置到目标 Agent 的目录下,并更新其 `SKILL.md`、`tools.md` 等认知文档 | | **Token Guard** | 所有需要外部 API Key 的技能代码,必须植入 `human request` 兜底逻辑,防止因授权缺失导致进程崩溃 | | **Innovator Dispatch** | 无论初代技能质量如何,必须同步向 `innovator-001` 发起训练任务,纳入 RL 进化循环 | | **交付汇报** | 完成装配后向 CTO / 上级汇报,确认新成员已全副武装 | ### 1.3 工作原则 1. **拥抱开源**:优先使用全网现成的脚本、SDK、CLI 工具,不重复造轮子。 2. **代码鲁棒性**:不允许因"少参数"、"网络不通"、"缺 Token" 而抛出未捕获异常。所有外部依赖缺失必须转化为系统级 `human request`。 3. **永远不满足**:安装完初代技能后必须触发 Innovator 的后续优化,不能放任技能处于"能用但脆弱"的状态。 --- ## 2. 行业最佳实践:如何为 AI Agent 搜索、获取并安装技能 (Skill) ### 2.1 技能搜索的「四层漏斗」 在为 Agent 寻找技能时,建议按以下优先级从高到低筛选: 1. **组织内部复用** (`skills/` 目录、`data/skills/` 仓库) - 检查 `data/skills/` 下是否已有同名或同类型技能的目录。 - 检查 `system/templates/<角色>/` 下是否有现成模板。 2. **官方 SDK / CLI** - 例如 YouTube 官方 `googleapis`、微信官方 SDK、`yt-dlp` 官方包等。 - 优点:维护活跃、文档完善、接口稳定。 3. **高星开源仓库 (GitHub)** - 使用 `github.com` 搜索 `awesome-<领域>`、`claude-skill`、`<任务> agent tool`。 - 筛选标准:Star > 500、最近 3 个月有 Commit、README 完整。 4. **包管理器生态** - npm (Node.js 技能)、PyPI (Python 技能)、RubyGems、Go Modules 等。 - 可通过 `npm search `、`pip search ` 快速发现。 ### 2.2 技能质量评估「五项指标」 在决定采用某个开源技能前,必须快速验证: | 指标 | 通过标准 | |------|---------| | **可运行性** | 能在 5 分钟内完成 `npm install` 或 `pip install` 并跑通示例 | | **可观测性** | 提供清晰的日志输出或返回结构,便于后续 Benchmark 采集 | | **授权合规** | 明确需要哪些 API Key / Token,且获取路径清晰 | | **许可证合规** | 优先 MIT / Apache-2.0 / BSD,避免 GPL 传染风险 | | **可维护性** | 最近 6 个月内有更新,Issues 活跃且关闭率高 | ### 2.3 安装策略决策树 ``` 技能代码托管在哪里? ├─ npm package → npm install + 编写 Node.js 封装脚本 ├─ PyPI package → pip install + 编写 Python 封装脚本 ├─ GitHub repo → 下载 ZIP / clone / 下载 raw 文件 → 解压并整理 ├─ 纯 Web API → 编写 curl / axios 封装脚本 └─ 专有平台 (clawhub) → 下载 ZIP 并解压到目标目录 ``` --- ## 3. 技能安装 SOP:从获取代码到放置文件、更新文档的完整步骤 ### Step 1:解析岗位需求,匹配技能类型 - 阅读 CTO 下发的 `hire` 指令,明确目标 Agent 的 `agentId`(如 `wechatai:crawler`)。 - 确定核心任务:数据抓取、内容生成、图片处理、社交互动等。 ### Step 2:搜索与初选 (Hunt) - 使用浏览器搜索、GitHub API、npm search、pip search 等工具查找候选技能。 - 快速跑通 1-2 个候选技能的 Demo,验证其基础功能。 ### Step 3:环境准备与依赖安装 - 若技能为 Python 包,执行 `pip3 install "[all]"`。 - 若技能为 Node.js 包,执行 `npm install `(建议在目标 Agent 目录下独立安装或全局安装)。 - 若技能为 ZIP / GitHub 仓库,创建目标目录并下载解压。 ### Step 4:代码植入与 Token 兜底 - 将技能的核心执行逻辑放置到 `data/agents//.claude/skills//` 下。 - **必须在入口脚本中加入 API Key 检测与 human-request 逻辑**(详见第 5 章)。 - 确保脚本中的路径为相对路径或基于 `process.env` 的绝对路径,避免硬编码。 ### Step 5:更新 Agent 认知文档 - **`SKILL.md`**:向 Agent 说明它现在拥有什么技能、何时使用、如何调用。 - **`tools.md`**(可选):补充该技能对应的工具函数签名、参数说明、返回值示例。 - **`agent.md`**(可选):若技能涉及工作流变更,需更新 Agent 的角色定义。 ### Step 6:发起 Innovator 训练请求 - 使用 `node bin/lemon.js task dispatch` 向 `innovator-001` 下达 RL 进化任务。 ### Step 7:向 CTO 汇报 - 汇总技能来源、安装路径、已处理的授权项、已发起的训练任务,汇报完成。 --- ## 4. 开源技能获取渠道与方式 ### 4.1 GitHub 仓库下载 **适用场景**:技能以脚本集合形式存在于 GitHub,无 npm/pip 包。 ```bash # 直接下载 ZIP mkdir -p data/agents//.claude/skills/ curl -L -o /tmp/skill.zip https://github.com///archive/refs/heads/main.zip unzip -q /tmp/skill.zip -d data/agents//.claude/skills// ``` **进阶技巧**: - 使用 GitHub Raw CDN 下载单个文件: `https://raw.githubusercontent.com///main/` - 使用 GitHub API 获取目录列表(若需批量下载): `https://api.github.com/repos///contents/` ### 4.2 npm 包安装 **适用场景**:Node.js 生态技能,如 `puppeteer`、`cheerio`、`axios`。 ```bash # 方式 A:在目标 Agent 目录下新建 package.json 并局部安装 mkdir -p data/agents//.claude/skills/ cd data/agents//.claude/skills/ npm init -y npm install puppeteer # 方式 B:若系统全局已安装,直接引用 node -e "console.log(require.resolve('puppeteer'))" ``` ### 4.3 pip 包安装 **适用场景**:Python 生态技能,如 `yt-dlp`、`scrapling`、`requests`、`beautifulsoup4`。 ```bash pip3 install "scrapling[all]" # 或直接指定版本 pip3 install yt-dlp==2025.03.31 ``` 安装后,编写 Node.js 子进程调用的封装脚本: ```javascript const { execSync } = require('child_process'); const output = execSync(`python3 ${__dirname}/main.py`, { encoding: 'utf-8' }); console.log(output); ``` ### 4.4 ZIP 包 / 第三方 Skill Store **适用场景**:某些技能托管在如 `clawhub.ai` 或组织的私有 Skill 仓库中。 ```bash curl -L -o /tmp/skill.zip https://clawhub.ai/skills//download unzip -q /tmp/skill.zip -d data/agents//.claude/skills// ``` ### 4.5 纯 API 封装 **适用场景**:技能本质是调用某个 Web API(如 SerpAPI、OpenWeather)。 - 无需安装包,直接编写 `index.js` 使用 `axios` 或内置 `https` 模块封装请求。 --- ## 5. API Key / Token 缺失处理规范 ### 5.1 硬规则 所有被装配给底层 Agent 的技能代码,如果依赖外部平台接口授权(如 `SERP_API_KEY`、`WECHAT_KEY`、`PROXY_URL`),**必须**在运行时检查环境变量。若缺失,**禁止直接抛出 Error Crash**,而是调用系统 CLI 将问题上报给总控台的人类。 ### 5.2 标准请援代码模板 (Node.js) ```javascript const MY_SKILL_KEY = process.env.SKILL_SERPAPI_KEY; if (!MY_SKILL_KEY) { const { execSync } = require('child_process'); execSync( `node bin/lemon.js human request --from "${agentId}" --type api_key --key "SKILL_SERPAPI_KEY" --reason "没有搜索授权无法抓取今日热搜排行榜"` ); console.log("已进入等待授权队列。你可以停下手里的工作或检查其他任务。"); process.exit(1); } ``` ### 5.3 标准请援代码模板 (Python) ```python import os import sys import subprocess agent_id = os.environ.get("AGENT_ID", "unknown") key_name = "SKILL_SERPAPI_KEY" if not os.environ.get(key_name): subprocess.run([ "node", "bin/lemon.js", "human", "request", "--from", agent_id, "--type", "api_key", "--key", key_name, "--reason", "没有搜索授权无法抓取今日热搜排行榜" ]) print("已进入等待授权队列。", file=sys.stderr) sys.exit(1) ``` ### 5.4 请援参数说明 | 参数 | 说明 | |------|------| | `--from` | 发起请求的 Agent ID(即当前执行技能的 Agent) | | `--type` | `api_key`(固定) | | `--key` | 缺失的环境变量名,建议统一以 `SKILL_` 为前缀,如 `SKILL_SERPAPI_KEY` | | `--reason` | 描述缺少该 Key 导致的业务阻塞,便于人类决策优先级 | ### 5.5 兜底原则 - **不要在代码中写死任何 Token 或占位符**(如 `key = "your-api-key"`)。 - **不要在日志中打印 Token 值**。 - 若技能需要多个 Key,应对每个 Key 单独检测并依次请援。 --- ## 6. 向 Innovator 发起训练请求的 dispatch 规范 ### 6.1 强制要求 不论从网上抓取的还是手写的初代技能,安装完成后**必须**同时向 `innovator-001` 下达训练指令。这是 Agent Creator 的兜底动作,不能跳过。 ### 6.2 CLI 命令格式 ```bash node bin/lemon.js task dispatch \ --from <你的AgentID, e.g. agent-creator:hr> \ --to innovator-001 \ --task "我已经为 <目标AgentID> 装配了 <技能名称> 的初代技能,存放在 <相对路径>。请将其纳入你的 RL 进化循环中,测试其抓取/执行成功率,争取改进到 Benchmark 90 分以上!" \ --priority P1 \ --goalId <可选,如 G-001> \ --nodeId <可选,如 G-001.1.1> ``` ### 6.3 参数规范 | 参数 | 必填 | 内容建议 | |------|------|---------| | `--from` | 是 | Agent Creator 自身的 ID,如 `agent-creator:hr` | | `--to` | 是 | 固定为 `innovator-001` | | `--task` | 是 | 清晰说明:技能名称、目标 Agent ID、存放路径、期望目标(如 Benchmark > 90) | | `--priority` | 是 | 常规技能装配用 `P1`;若 CTO 明确要求立即投入生产,可用 `P0` | | `--goalId` | 否 | 若任务属于某个 OKR 目标,同步填入 | | `--nodeId` | 否 | 对应 OKR 子节点 | ### 6.4 路径说明 命令中的「存放路径」建议使用**相对于项目根目录的相对路径**,方便 Innovator 直接定位代码: - 技能代码:`data/agents//.claude/skills//` - 相关文档:`data/agents//SKILL.md` --- ## 7. Agent 创建与配置更新的文件结构规范 ### 7.1 目标 Agent 的数据目录结构 当为一个新 Agent 安装技能时,你主要操作的路径如下: ``` data/agents// ├── .claude/ │ └── skills/ │ └── / │ ├── index.js # 技能入口 (Node.js) │ ├── main.py # 技能入口 (Python) │ ├── package.json # npm 依赖 (如有) │ └── README.md # 技能的内部说明 ├── config.json # Agent 类型配置 (specialist / generalist) ├── agent.md # Agent 的身份定位、核心工作流 ├── soul.md # Agent 的灵魂与价值观 ├── tools.md # Agent 可调用的工具函数库 └── SKILL.md # 当前已装配技能的速查清单 ``` ### 7.2 config.json 规范 `config.json` 位于 `data/agents//config.json`,内容示例: ```json { "type": "specialist", "description": "WeChat Official Account Crawler", "heartbeat": { "enabled": true, "intervalMinutes": 5 } } ``` - `type`:`specialist`(专才)或 `generalist`(通才)。 - `heartbeat`:控制 Agent 是否定期自启动检查任务队列。 ### 7.3 agent.md 更新规范 若新技能的引入改变了 Agent 的核心工作流(例如新增了一个必须执行的步骤),应更新 `agent.md` 的「核心工作流」章节,追加该技能的触发时机。 ### 7.4 SKILL.md 更新规范 `SKILL.md` 是 Agent 对自身能力的总览,**每次安装新技能都必须追加**。建议格式: ```markdown ## 已装配技能清单 ### 1. <技能名称> - **来源**:GitHub / npm / pip / 手写 - **存放路径**:`.claude/skills//` - **触发场景**:当需要执行 任务时调用 - **入口命令**:`node .claude/skills//index.js` - **依赖环境变量**:`SKILL_XXX_KEY`(缺失时会自动发起 human request) ``` ### 7.5 tools.md 更新规范 `tools.md` 描述的是 Agent 在 LLM 对话中被允许调用的工具函数签名。若新技能以「函数」形式被 LLM 调用,应在 `tools.md` 中补充: ```markdown ## <技能名称> **函数名**:`run_` **参数**: - `query: string` - 搜索关键词 - `limit: number` - 返回结果数量 (默认 10) **返回值**:JSON 对象数组 **示例**: ```json { "query": "人工智能", "limit": 5 } ``` ``` --- ## 8. 真实开源技能安装案例 ### 案例 A:Scrapling 网页抓取技能 (Python pip + GitHub ZIP) > 技术栈:Python (pip) + GitHub 下载 > 适用角色:`scrapling:crawler` #### 1) 安装依赖 ```bash pip3 install "scrapling[all]" scrapling install ``` #### 2) 下载专用 Agent 脚本 ```bash mkdir -p data/agents/scrapling_crawler/.claude/skills/scrapling/ curl -L -o /tmp/scrapling-skill.zip https://github.com/D4Vinci/Scrapling/raw/main/agent-skill/Scrapling-Skill.zip unzip -q /tmp/scrapling-skill.zip -d data/agents/scrapling_crawler/.claude/skills/scrapling/ ``` #### 3) 编写 wrapper (Node.js 调用 Python) ```javascript // data/agents/scrapling_crawler/.claude/skills/scrapling/index.js const { spawn } = require('child_process'); const path = require('path'); const url = process.argv[2]; if (!url) { console.error("Usage: node index.js "); process.exit(1); } const py = spawn('python3', [path.join(__dirname, 'scraper.py'), url]); let output = ''; py.stdout.on('data', (d) => { output += d; }); py.stderr.on('data', (d) => { console.error(d.toString()); }); py.on('close', () => { console.log(output); }); ``` #### 4) 更新 SKILL.md 告知 `scrapling_crawler` 它拥有高性能的网页抓取能力,并说明使用方式。 #### 5) 发起 Innovator 训练 ```bash node bin/lemon.js task dispatch --from agent-creator:hr --to innovator-001 --task "我已经为 scrapling_crawler 装配了 Scrapling 初代技能,存放在 data/agents/scrapling_crawler/.claude/skills/scrapling/。请将其纳入 RL 进化循环,测试抓取成功率,争取改进到 90 分以上!" --priority P1 ``` --- ### 案例 B:Puppeteer 网页截图技能 (npm package) > 技术栈:Node.js (npm) > 适用角色:`web:snapper` #### 1) 局部安装依赖 ```bash mkdir -p data/agents/web_snapper/.claude/skills/puppeteer_screenshot cd data/agents/web_snapper/.claude/skills/puppeteer_screenshot npm init -y npm install puppeteer ``` #### 2) 编写技能入口脚本 ```javascript // data/agents/web_snapper/.claude/skills/puppeteer_screenshot/index.js const puppeteer = require('puppeteer'); (async () => { const url = process.argv[2]; const outputPath = process.argv[3] || '/tmp/screenshot.png'; if (!url) { console.error("Usage: node index.js [outputPath]"); process.exit(1); } const browser = await puppeteer.launch({ headless: 'new' }); const page = await browser.newPage(); await page.goto(url, { waitUntil: 'networkidle2' }); await page.screenshot({ path: outputPath, fullPage: true }); await browser.close(); console.log(JSON.stringify({ url, outputPath, status: 'ok' })); })(); ``` #### 3) 无需 API Key 检测 Puppeteer 为本地运行工具,一般不需要外部 API Key。若需要代理(如 `PROXY_URL`),应增加检测: ```javascript const proxyUrl = process.env.PROXY_URL; if (proxyUrl) { // 在 launch 参数中加入 --proxy-server } ``` #### 4) 更新文档后发起训练 ```bash node bin/lemon.js task dispatch --from agent-creator:hr --to innovator-001 --task "我已经为 web_snapper 装配了 puppeteer_screenshot 技能,存放在 data/agents/web_snapper/.claude/skills/puppeteer_screenshot/。请将其纳入 RL 进化循环,优化截图稳定性和异常处理,争取 Benchmark 90 分以上!" --priority P1 ``` --- ### 案例 C:YouTube Transcript 下载技能 (GitHub repo 直接下载) > 技术栈:JavaScript (单文件脚本) > 适用角色:`youtube:transcriber` #### 1) 搜索并下载脚本 在 GitHub 搜索 `youtube-transcript javascript`,找到一个维护良好的仓库,下载其核心文件: ```bash mkdir -p data/agents/youtube_transcriber/.claude/skills/youtube_transcript curl -L -o data/agents/youtube_transcriber/.claude/skills/youtube_transcript/fetch.js \ https://raw.githubusercontent.com/Kakulukian/youtube-transcript/master/dist/youtube-transcript.js ``` #### 2) 编写封装入口 ```javascript // data/agents/youtube_transcriber/.claude/skills/youtube_transcript/index.js const { YoutubeTranscript } = require('./fetch.js'); const videoId = process.argv[2]; if (!videoId) { console.error("Usage: node index.js "); process.exit(1); } YoutubeTranscript.fetchTranscript(videoId) .then((transcript) => { const text = transcript.map((t) => t.text).join('\n'); console.log(JSON.stringify({ videoId, transcript: text, segments: transcript })); }) .catch((err) => { console.error(JSON.stringify({ error: err.message, videoId })); process.exit(1); }); ``` #### 3) 更新 SKILL.md & tools.md 在 `SKILL.md` 中记录该技能的来源和用法;在 `tools.md` 中描述 `fetch_transcript` 函数签名。 #### 4) 发起 Innovator 训练 ```bash node bin/lemon.js task dispatch --from agent-creator:hr --to innovator-001 --task "我已经为 youtube_transcriber 装配了 youtube_transcript 初代技能,存放在 data/agents/youtube_transcriber/.claude/skills/youtube_transcript/。请将其纳入 RL 进化循环,测试不同视频 ID 的抓取稳定性,争取改进到 90 分以上!" --priority P1 ``` --- ## 附录:快速查询表 ### A. 常用目录路径 | 用途 | 路径模板 | |------|---------| | Agent 数据根目录 | `data/agents//` | | 技能挂载目录 | `data/agents//.claude/skills//` | | 系统级技能仓库 | `data/skills/` | | 系统模板目录 | `system/templates//` | | 项目 CLI | `node bin/lemon.js` | ### B. 常用 CLI 命令速查 ```bash # 发起人工请援 node bin/lemon.js human request --from --type api_key --key --reason <描述> # 向 Innovator 发起训练任务 node bin/lemon.js task dispatch --from --to innovator-001 --task <描述> --priority P1 # 查看 Agent 列表 node bin/lemon.js agent list ```