搜索 · 推荐 · 安装 · 创建 · 质检 · 诊断 — Agent Skill 全生命周期一站式管理。
┌─────────┐ ┌──────────────┐ ┌──────────────────────┐
│ 用户意图 │ ──→ │ ⛔ 前置检查 │ ──→ │ 意图路由（6 模块） │
└─────────┘ │ 首次使用引导 │ │ 搜索/推荐/安装/创建 │
└──────────────┘ │ 质检/诊断 │
└──────────────────────┘
┌─ config/sources.yaml (偏好 + 凭证)
├─ references/ (按需加载，含 best practices 全量参考)
└─ scripts/ (CPU 密集 + workspace/manifest 原子写)
> 用户：帮我找一个生成 PPT 的 skill
> → 前置检查 → 4 级关键词 → 多渠道宽窄并行搜索 → 跨源去重 + 推荐指数 → 编号菜单 → 三引擎安全扫描 → 完成
> 用户：审查这个 skill 是否符合 best practices
> → 路由到质检（[6.5] best_practices_only）→ 30 项 checklist 自动过 → 输出 ✅/❌ + 必修项 Top 3
> 用户：推荐适合我的 skill
> → 扫描已安装 + 项目特征 → 用户画像 → 能力缺口 → 个性化推荐 2-5 条
读取本 Skill 后，在执行任何用户意图之前，严格按以下顺序完成前置检查。跳过任何步骤 = 流程错误。
> ⚠️ 跳过前置检查是最常见的执行错误。直接搜索/安装将因缺少 API Token、未选择搜索源等问题导致失败，浪费用户时间。
扫描并清理废弃 / 需迁移的配置，让从旧版本升级的用户环境自动收敛到当前规范。按日期节流，避免每次使用都重复扫描。
0.1 是否需要本次检测（读 config/sources.yaml 的 preferences.maintenance.last_check_date）：
检测固定每日一次，无频率/开关选项。按 last_check_date 判断：
"" / 字段缺失 / maintenance 块缺失 → 视为从未检测，强制执行（块或字段缺失时顺带补全 maintenance: { last_check_date: ... }）0.2 执行检测清单（命中即用 Read→StrReplace 精准删除并写回，保持 YAML 缩进合法；幂等——无残留则跳过该条）：
| # | 检测项 | 命中位置 | 处理 |
|---|---|---|---|
| --- | -------- | --------- | ------ |
| 1 | Knot 渠道残留（已废弃，不支持第三方下载） | sources.yaml：platforms 下 name: knot 整条目 / preferences.dedup_strategy.prefer_channels 里的 knot / meta_schema 中 knot 相关枚举与注释（source.skillId、source.type/channel/installedVia 的 knot/knot-cli） / custom_sources 中指向 knot.woa.com 的源；.credentials.yaml（若存在）：顶层 knot: 段（含 api_token） | 全部删除，保留其他平台配置 |
| 2 | 废弃的检测开关 / 频率及自更新字段 | sources.yaml：preferences.maintenance 下的 check_frequency / enabled（含遗留 never 值）——本块只保留 last_check_date；preferences.self_update 整块（自更新机制已下线） | 全部删除 |
> 扩展点：未来新增「废弃字段下线」「配置项改名迁移」等自愈需求时，在本表追加一行即可，节流与执行逻辑复用本步骤，无需改动其他流程。
0.3 收尾：本次有实际清理 → 用一行告知用户（如「已清理废弃的 Knot 渠道配置」）；无论是否有清理，只要执行了检测就把 preferences.maintenance.last_check_date 更新为今天（ISO YYYY-MM-DD）。严禁因检测/清理失败而阻断用户原始意图——这是尽力而为的自愈，失败则静默跳过并继续步骤 1。
立即读取 config/sources.yaml 的 preferences.setup_completed 字段：
false 或不存在 → 停止。不执行任何后续操作。 转入 modules/setup.md 完成 4 步引导，完成后回到步骤 2true → 继续步骤 2根据用户输入分流到对应模块，严禁跳模块混合执行。
| 用户意图 | 路由模块 | 参考文件 |
|---|---|---|
| --------- | --------- | --------- |
| "搜一个 xxx skill" / "find skill for xxx" | 搜索 | modules/search.md |
| "推荐适合我的 skill" / "有什么好用的" | 推荐 | modules/recommend.md |
| "安装 xxx" / "帮我装这个 skill" | 安装 | modules/install.md |
| "创建 / 写一个 skill" / "create skill" | 创建 | modules/create.md |
| "审查 SKILL.md 是否符合 best practices" / "best practices 体检" | 质检（[6.5] best_practices_only） | modules/inspect.md + references/skill-md-checklist.md |
| "检查这个 skill 质量" / "skill 体检" | 质检 | modules/inspect.md |
| "动态评测 / 实测验证 / 跑测试看效果" | 质检（eval_mode=dynamic） | modules/inspect.md |
| "混合评测 / 静态加动态 / 正式评审" | 质检（eval_mode=hybrid） | modules/inspect.md |
| "扫描所有 skill / 全量体检 / 优化优先级" | 质检（mode=batch_baseline） | modules/inspect.md |
| "诊断 / 优化 / 重构这个 skill" / "迭代到收敛" / "帮我改进这个 skill" / "这个 skill 有问题" | 诊断（⚠️ 必须先执行策略确认，见下方「诊断/优化前置策略确认」） | modules/diagnose.md |
| "优化 description / 提升触发率 / 跑加速器 / trigger eval" | 诊断（Step 4.6 description 量化加速器） | modules/diagnose.md + references/description-optimizer.md |
| "生成成果卡片 / 出张图 / skill 优化战报" | 质检/诊断 报告后菜单触发 | references/result-card.md |
| "推荐一个 xxx skill" | 搜索（以 xxx 为关键词） | modules/search.md |
| "热门 skill" / "最受欢迎的 skill" | 搜索（Leaderboard 优先） | modules/search.md |
| "更新 skill" / "检查 skill 新版本" | 安装（更新流程） | modules/install.md |
| "相似 skill" / "类似 xxx 的 skill" | 搜索（相似搜索模式） | modules/search.md |
| "收藏 / star 这个 skill" | 推荐（收藏操作） | modules/recommend.md |
| "重新配置搜索偏好" / "reconfigure" | 引导 | modules/setup.md |
| 搜索无结果时 | 自动降级到推荐 + 引导创建 | modules/recommend.md |
| 安装前未扫描时 | 自动插入安装模块的安全扫描 | modules/install.md |
诊断/优化前置策略确认（⚠️ 强制，不可跳过）：
用户意图命中「诊断 / 优化 / 重构 / 改进 / 帮我看看这个 skill / 这个 skill 有什么问题」等任何优化类意图时，若用户未在原始输入中明确指定策略（如未说"直接修复"/"走棘轮"/"static"/"dynamic"/"hybrid"），第一步必须向用户展示策略选择：
您希望如何优化这个 Skill？
[1] 直接修复已知问题（快速，适合明确问题清单）
[2] 棘轮迭代流程（评测 → 诊断 → 修复 → 重新评测，适合全面提升）
└ 评测模式：[2a] 静态 [2b] 动态 [2c] 混合 [2d] 盲评混合
请选择后继续。
收到用户明确选择后，再路由到对应模块执行。"帮我优化"、"帮我看看"等模糊表达绝不视为已指定策略。
模糊意图兜底：用户说「帮我看看这个 skill」/「这个 skill 怎么样」/「有没有 skill 可以做 xxx」等模糊表达时：
复合意图处理：用户同时提到搜索+安装（"帮我找一个 xxx skill 并装上"），按顺序执行搜索 → 用户确认 → 安装。
提案式交互：每次搜索/推荐结果后，必须附带编号式下一步菜单（安装/详情/收藏/重搜）。
关键参数契约速查（详细定义见各 modules/*.md）：
| 模块 | 必填参数 | 可选参数 | 前置条件 |
|---|---|---|---|
| --- | --- | --- | --- |
| 搜索 | query(用户意图字符串) | strategy(speed/balanced/thorough，默认 balanced) | 无 |
| 安装 | skill_id(平台 ID 或仓库路径) | force(bool，默认 false) | 安全扫描通过 |
| 质检 | target(SKILL.md 路径) | eval_mode(static/dynamic/hybrid/blind_hybrid) | 建产物前先调 resolve_workspace.py 解析 workspace 路径 |
| 诊断 | target(SKILL.md 路径) | eval_mode, max_iterations(默认 3) | D10.1 ≥ 30（dynamic/hybrid 时）/ 建 workspace 前必走 W.0 |
| Description 加速器 | target | provider(claude/codebuddy/…) | D10.2 ≥ 30（需 trigger-queries.json） |
| 创建 | intent(用户意图) | path_mode(template/eval_driven，默认 template) | 必读 references/anthropic-best-practices.md |
Workspace 路径解析（W.0 强制规则）：建任何评测产物前必读 references/workspace-layout.md + 调 python3 scripts/resolve_workspace.py --skill ，不得手拼路径（manifest_io 写入时会拒绝非 skill-assistant-workspace/ 下的路径）。
| 信任等级 | 渠道示例 | 扫描策略 |
|---|---|---|
| --- | --- | --- |
| 高信任 | Anthropic 官方 / skills.sh 官方认证 | 跳过脚本扫描，仅 AI 软判断 |
| 中信任 | skills.sh 社区 / SkillHub / SkillsMP | 完整三引擎扫描 |
| 低信任 | 用户自带 URL / 私有仓库 / 未知作者 | 三引擎 + 人工确认后才安装 |
curl | bash、硬编码密钥、读 MEMORY.md）→ 立即中止，不询问用户；HIGH 风险 → 展示详情由用户决定MEMORY.md、USER.md、SOUL.md、IDENTITY.md 等 AI Agent 敏感文件的行为源分为平台型技能市场和GitHub 优质仓库两大类，通过 config/sources.yaml 统一配置。
| 场景 | 首选渠道 | 原因 |
|---|---|---|
| --- | --- | --- |
| 社区热门 skill | skills.sh（安装量降序） | 安装量是最真实的质量信号 |
| 国内加速 / 中英双语 | SkillHub（CLI） | OpenClaw 同源，国内 CDN 加速 |
| 最新/实验性 skill | GitHub（gh search repos） | 上架慢的平台常滞后 1-2 版本 |
| 公司私有 skill | 自定义源（sources.yaml） | 平台不收录内部 skill |
modules/*.md 中modules/search.md），固定规则拆到 references/ 按需加载preferences: + settings: 段（~70 行）references/ 中scripts/ 中maintenance.last_check_date 写入与命中残留/遗留字段时的清理外，所有读操作幂等--force 参数控制覆盖行为，默认检测已安装不重复安装> 完整 50+ 条 NEVER 清单按模块分组在 references/anti-patterns.md。本节只保留最致命的 5 条——违反这 5 条会直接破坏整个评测/搜索流程。
skill-assistant-workspace/，必须调 scripts/resolve_workspace.py 解析；27 个产物文件曾因手拼路径被迫迁移LAYOUT_NON_TABLEscripts/generate-full-report.mjs 落盘；Step 6 菜单只控制是否打开浏览器，不控制是否生成> ⚠️ 进入对应模块（search / install / inspect / diagnose）时必须读对应模块章节的 anti-patterns.md：包括搜索关键词与渠道并行、子 Agent 与 dry_run 评测（grading.json schema 等）、time-budget / 性能控制、盲评 Comparator 隔离等。
modules/setup.md首次使用引导（setup_completed: false 时强制触发）：搜索源选择（ClawHub/SkillHub 二选一，支持自定义仓库）→ 环境检查 + API Key 持久化 → 搜索策略（speed/balanced/thorough）→ 配置写入 sources.yaml。说"重新配置搜索偏好"可随时重进。
modules/search.md宽窄双路 × 多路并行（宽路 30 + 窄路 10）；多平台（skills.sh / SkillsMP / SkillHub）+ 优质仓库（gh）+ 全 GitHub；跨源去重 + 融合推荐；质量归一化（热度 40% + 权威 35% + 鲜度 25%）→ 统一推荐指数；搜索透明化（诊断头 + 11 条异常检测 + 5 个 refine 分支）。
modules/recommend.md多信号用户画像（已安装 Skill + 工作区特征 + README）→ 角色快查表 → 识别能力缺口 → 个性化推荐（业务价值优先，明确标注互补/增强/延伸关系）。含收藏/Star 管理系统。
modules/install.md统一安装入口（install_skill.sh v2，禁止 npx skills add）+ 三引擎安全审查（13 项硬扫描 / skills.sh audit / AI 软判断）+ _skill_meta.json 版本追踪。支持单/批量更新。
modules/create.mdSkill 创建全流程：模板启动 / Eval 驱动两条路径 → frontmatter 完整字段引导（含 license / compatibility / allowed-tools）→ description 三件事原则（WHAT + WHEN + Negative Boundaries）→ 5 个核心 pattern（Checklist / Validation Loop / Plan-Validate-Execute / Conditional Loading / Gotchas）→ Eval 驱动开发 + Claude A/B 模式 → 与 inspect/diagnose 闭环迭代。详见 references/anthropic-best-practices.md。
modules/inspect.md10 维度评分（D0-D9，对齐 OWASP LLM Top 10）+ D10 实测可验证性（附加）；eval_mode 五选一（preview / static / dynamic / hybrid / blind_hybrid）；mode=batch_baseline 全量扫描输出优先级排行榜；新增 [6.5] best_practices_only 入口跑 30 项 skill-md-checklist.md；输出 A-F 评分 + 改进建议 + 子 Agent 双跑实证。
modules/diagnose.md三维诊断（指令 40% / 约束 30% / 冗余 30%）→ Step 0-6 交互流程 → Step 4 棘轮迭代（独立子 Agent 评分 / git revert 防退步 / 体积守门 ≤ 1.5×）。Step 4.6 description 加速器（子 Agent 模拟 / CLI 保真双路径，60/40 split + 5 轮选优）；三角色子 Agent（Grader / Comparator / Analyzer）；产物落独立 workspace（manifest.yaml 管理）。
> 详细 9 条单源降级 + L1/L2/L3 三层兜底链全文在 references/fallback-rules.md。本节只声明核心原则。
| 层级 | 触发条件 | 处理策略 |
|---|---|---|
| --- | --- | --- |
| L1 单源失败 | 单个渠道/工具失败 | 按 fallback-rules.md L1 表 处理，输出标注「⚠️ 渠道/工具降级」 |
| L2 模块失败 | 同模块超过半数渠道全部失败 | 自动跨模块降级：搜索 → 推荐 → 创建引导 |
| L3 全部失败 | L2 后仍无结果 / 系统资源缺失 | 透明告知用户：列出已尝试路径 + 失败原因 + 3 条人工兜底 |
任何 L1/L2/L3 降级必须在输出中显式提示 ——不允许静默 fallback。降级路径写入诊断头的「环境/异常」段，让用户能定位偏差来源（违反触发 🚨 阻断级 SILENT_FALLBACK，重跑前必须修复）。
tests/golden-dataset/（位于 workspace 根，不在 skill 目录内）tests/run_golden_baseline.py（位于 workspace 根）共 4 个版本