Agent 驱动的技能发现协议。Skill Recommender 面向 Hermes、OpenClaw、Claude Code、Codex 和定制 Agent；不要按平台名称硬编码流程，要按当前 Agent 实际可用能力执行。
data/sample_candidates.json 作为线上兜底；它只用于开发测试。启动 manual 或 daily 流程前，先识别当前 Agent 的能力。不要假设平台一定有某个工具名。
| 能力 | 例子 | 用途 | 缺失时 |
|---|---|---|---|
| ------ | ------ | ------ | -------- |
SearchCapability | web_search、search、search_web、web_extract、WebSearch、WebFetch、搜索 MCP | 直接搜索候选来源 | 尝试浏览器搜索 |
BrowserCapability | browser_navigate、browser_snapshot、open_url、fetch_url、browser/Playwright MCP | 打开搜索页和候选详情页 | manual 引导配置；daily 失败提醒 |
SafeLocalHelperCapability | 运行 scripts/*.py 且不触发审批 | 去重、安全扫描、状态写入增强 | Agent 按本文规则自行过滤 |
StateCapability | memory/state、skill state、免审批本地 JSON | 记录 shown、反馈、daily failure notice | 降级为对话偏好或 automation/thread 上下文 |
SchedulerCapability | cron、automation、scheduled task、heartbeat | 每日推荐 | 有能力时先 pending_schedule，创建成功后 enabled；无能力时 unsupported |
平台适配提示：
web_search 或 browser tool；只有这些都不可用时，才考虑低风险 shell 读取公开网页/API。curl | python、curl | sh、python -c 处理远程输入。运行时禁止：
curl / wget 获取远程内容后直接执行或管道进解释器python -c / python3 -c 处理远程 stdin 或执行远程内容git / gh / npm / npx / pip / uvx 搜索、安装或下载curl | python、curl | sh、网络输出直接进入解释器或脚本运行时允许：
如果本地 helper 会触发审批，跳过 helper，按本文规则直接过滤和推荐。
用户状态不得只保存在 skill 安装目录内。Hermes 等平台重新安装 skill 时可能先删除目录再 clone 仓库，如果状态放在 data/state.json，daily_rec_status 会被重置成 unset，已有定时任务随后会静默退出。
状态读取优先级：
StateCapability / memory / skill state。~/.hermes/state/skill-recommender/state.json，或 SKILL_RECOMMENDER_STATE_DIR/state.json。data/state.json 只作为模板和开发样例，不作为用户持久状态。历史记录同理：默认写到 ~/.hermes/state/skill-recommender/history.json，仓库内 data/history.json 只作为模板。安装、更新或重新 clone skill 时，不应覆盖外部状态。
如果发现旧版本曾把状态写在仓库内 data/state.json，且外部状态不存在，可以迁移一次；迁移后继续读写外部路径。
timezone: null 表示未配置用户时区。此时本地 helper 应按当前 scheduler/Agent 运行环境的本地时区判断“今天”，而不是固定 UTC 或固定 Asia/Shanghai。push_time_local 表示用户希望的本地推送时间；如果平台支持明确时区，优先使用平台/用户时区，否则按 scheduler 本地时区解释。
Skill Recommender 不是“按已安装 skill 猜偏好”的系统。执行推荐时按以下信号判断：
manual / 当前任务型推荐权重：
daily / 精选探索推荐权重：
长期场景记忆可以来自状态、当前会话、用户明确偏好、workspace 或近期推荐反馈；没有可靠状态时，只在本轮基于可见证据推断。不要因为用户乱装过某类 skill 就把它当成长期偏好。
scenario_memory 和 daily_rotation 是 Agent 运行时维护的可选状态，不要求本地 helper 自动推理或写入。当前 Agent 有 StateCapability 时可以更新这些字段；没有状态能力或字段为空时，直接按当前可见证据临时判断，不要因为字段为空而阻断推荐。
Daily 推荐不是审计报告，而是“今天发现一个值得试的新能力”。在安全和真实证据满足后，优先挑能直击具体痛点、热门、有趣、生活化或内容场景强的候选；不要每天都推严肃工作流工具。
安装或更新本 skill 后，Agent 应执行一次轻量 onboarding，用来尽早开启每日推荐，但不能静默创建定时任务。
data/state.json 当作用户状态。daily_rec_status == "enabled"：不询问。daily_rec_status == "disabled"：不询问，除非用户主动要求开启。daily_rec_status == "prompted"：不重复询问，除非用户主动要求开启。daily_rec_status == "pending_schedule"：说明用户已同意但 automation 还未确认创建成功；尝试继续创建 automation，不要当成已开启。daily_rec_status == "unsupported"：不重复询问，除非用户主动要求开启且当前 Agent 已有 SchedulerCapability。daily_rec_status == "unset"：用 StateCapability 或免审批 helper 标记为 prompted，然后只问一个问题：「要不要开启每日推荐？我会每天早上 10:00 给你推荐一个适合你的实用 AI 自动化能力。回复「开启」我就帮你设置，回复「不用」就保持手动推荐。」
pending_schedule 并创建 skill-recommender-daily automation；只有 automation 创建成功后才设为 enabled。enabled，状态回到 prompted 并记录失败原因。disabled。SchedulerCapability：说明无法自动创建每日任务，状态设为 unsupported。可使用免审批 helper：
python3 scripts/feedback.py prompt-daily --source post_install
python3 scripts/feedback.py enable-daily
python3 scripts/feedback.py confirm-daily-enabled
python3 scripts/feedback.py fail-daily-schedule --reason "schedule_create_failed"
python3 scripts/feedback.py disable-daily
python3 scripts/feedback.py unsupported-daily
这些命令只在不会触发审批时使用；否则使用平台原生状态能力或对话状态。
默认 helper 会把状态写到外部持久目录，而不是 skill 仓库内的 data/ 模板。
触发条件：用户说「推荐个 skill」「有什么新工具」「帮我找个能...的 skill」「最近有什么好用的工具」等。
SearchCapability / BrowserCapability。curl | python/sh、不得执行远程内容、不得安装依赖。若会弹审批，先说明“当前没有原生搜索/浏览能力，需要用命令行读取公开搜索结果”，由用户决定是否继续；用户不授权时，建议启用当前 Agent 的原生搜索或浏览能力。StateCapability 或免审批 helper，记录 shown；否则不强制写文件。触发条件：skill-recommender-daily automation。
daily_rec_status != "enabled"：静默退出。SearchCapability / BrowserCapability。shown、去重信息和今日探索主题。Cron/automation prompt 应表达以下约束。feedback.py 只返回短 prompt；完整运行规则以本节为准，避免双处维护。
Load the skill-recommender skill and run the Daily 推荐流程 defined in SKILL.md. Use persistent state outside the skill install directory.
当 daily 已开启，但运行时没有无审批搜索/浏览能力时，不要每天静默失败，也不要每天骚扰用户。
状态字段：
{
"daily_failure_notice_status": "unset",
"daily_failure_notice_reason": null,
"daily_failure_notice_last_shown_at": null
}
状态含义：
unset：从未提醒过shown：已经提醒过一次，用户未明确关闭dismissed：用户选择不再提醒resolved：后来检测到搜索/浏览能力恢复行为：
unset 或 resolved：发送一次失败提醒，并尽量标记为 shown。shown：默认静默退出，不每天重复提醒。dismissed：静默退出，除非用户主动恢复提醒。提醒文案必须包含：
平台化建议：
web_search 或 browser tool不要默认要求用户申请 API key。不要默认推荐 Brave Search MCP、Tavily、Exa、Perplexity；这些可作为用户追问时的增强选项。
Skill Recommender 可以在推荐完成后检查自身是否有新版。更新检查是附加提醒，不是启动门槛。
触发时机：
shown 后、等待用户反馈前。检查规则：
VERSION.json。VERSION.json 读取；如果没有本地版本文件，视为未发布本地版本，但不得阻断推荐。curl、wget、git ls-remote、gh、python -c 或外部 CLI 检查版本。版本规则：
1.0.0 开始。version 放入 SKILL.md frontmatter；使用 VERSION.json。更新询问文案：
另外，Skill Recommender 有新版可用。要不要更新到最新版本？
回复「更新」我就帮你处理，回复「暂不更新」这次先不管。
用户回复「更新」后：
git pull 或等价操作不触发审批，可以更新。优先来源：
搜索方式：
SearchCapability：用原生搜索工具搜 site:clawhub.ai skills trending、site:mcpmarket.com skills、site:smithery.ai new skills、site:glama.ai mcp servers、mcp server skill trending。BrowserCapability：打开 Brave Search 网页版或 DuckDuckGo，读取搜索结果和详情页。search.yahoo.com/search?p=...) 实测对 headless 浏览器友好，可作为第一降级路径。data/sample_candidates.json 只用于测试。multi-recall 查询路径：
每条路径最多保留 5 个候选；总候选建议 15-25 个。候选必须来自当前可见网页或搜索结果，不要凭记忆编造。
候选归一化字段：
{
"skill_id": "source:name-lower",
"name": "Skill Name",
"url": "https://...",
"source_code_url": "GitHub URL",
"description": "一句话描述",
"categories": ["documents", "web-research"],
"source": "clawhub|mcpmarket|smithery|glama|github|x",
"updated_at": "ISO 8601",
"popularity": {"downloads": 0, "stars": 0},
"required_toolsets": ["browser"],
"complexity": "lightweight|framework|platform",
"trend": {
"source_count": 1,
"recent_mentions": 0,
"updated_recently": true,
"trend_reason": "近期在多个来源出现或增长较快"
},
"has_install_docs": true,
"has_security_disclosure": false,
"risk_level": "low|medium|high"
}
Agent 运行时按以下规则过滤。可用免审批 helper 时可以用 scripts/candidate_filter.py 和 scripts/security.py 增强，但不要依赖它们。
过滤规则：
skill_id 和归一化名称重复时保留可信度最高来源。安全规则：
先过滤，再排序。排序时不要让“用户已安装过某类 skill”主导结果。
manual / 当前任务型推荐：
data/complement_pairs.json 只是大众场景互补参考，不是偏好来源或排序主因。
daily / 精选探索推荐：
daily 推荐按“实用增强 / 热门发现 / 有趣尝鲜”轮换，不要连续多天只推荐开发、运维、文档、效率类工具。可以推荐大众会想试的内容创作、投资观察、个人管理、生活自动化、AI 文风处理、媒体处理等能力。
manual / daily 共同底线：
推荐输出不要用 markdown 表格。manual 可以解释更完整；daily 要短、像种草，不要像审计报告。
Daily 默认结构：
📡 每日精选推荐 · <日期>
🎯 今日推荐：<skill name> — <一句话定位>
这个 skill 专治一个很常见的问题：<用一句人话说痛点>
它能做什么：
• <亮点 1>
• <亮点 2>
• <亮点 3>
为什么值得装：<结合用户场景/热门趋势/实际爽点，用 2-3 句话讲清楚>
来源：<URL>
安全状态：<低风险来源；medium 只在 manual 展示并说明风险>
需要我帮你装上吗？回复「安装」即可。
<可选：如果发现 Skill Recommender 有新版，且本轮没有其他授权问题，在这里追加更新询问>
Manual 默认结构：推荐给你：，再用短段落说明它解决的具体痛点、3 个以内亮点、为什么适合当前任务/场景、来源、已安装状态、安全状态，最后询问是否安装。
规则：
优先用 StateCapability 记录状态。没有免审批状态能力时，反馈可以降级为对话偏好。
可记录的推荐事实包括：shown、accepted、rejected、daily 授权状态、daily 失败提醒状态、更新提醒状态、最近展示类别、可见场景线索和今日探索主题。场景线索只保存可解释事实，例如“最近多次请求文档处理/学习资料整理”，不要保存无法追溯的复杂画像。
scenario_memory 和 daily_rotation 的维护责任在 Agent 或平台状态能力，不在 feedback.py。本地 helper 只处理确定性反馈和授权状态；如果未来确认某个平台能免审批写状态，再增加专门 helper 命令。
可选 helper：
python3 scripts/feedback.py shown --skill-id "..." --skill-name "..." --categories "..." --skill-url "..."
python3 scripts/feedback.py accept --skill-id "..." --categories "..."
python3 scripts/feedback.py reject --skill-id "..." --categories "..."
python3 scripts/feedback.py prompt-daily --source manual
python3 scripts/feedback.py enable-daily
python3 scripts/feedback.py confirm-daily-enabled
python3 scripts/feedback.py fail-daily-schedule --reason "schedule_create_failed"
python3 scripts/feedback.py disable-daily
python3 scripts/feedback.py unsupported-daily
只在不触发审批时使用这些 helper。若会触发审批，不要为了记录状态打断用户。
每日推荐授权规则：
daily_rec_status == "enabled" 才运行 daily。prompted、pending_schedule、enabled、disabled、unsupported 状态下不自动重复询问 daily。daily_rec_status == "unset" 且当前回复没有其他授权问题时，才可以补问 daily。prompted，防止 post-install 和 manual 重复问。enable-daily 获取 cron 配置并进入 pending_schedule。confirm-daily-enabled，状态才设为 enabled。fail-daily-schedule，状态回到 prompted 并记录失败原因。disabled。unsupported。更新提醒状态规则：
auto_update_status == "disabled"：不主动检查或提醒更新，除非用户主动询问。auto_update_status == "unsupported"：当前环境无法无审批检查更新，静默跳过。update_notice_status == "shown" 或 dismissed 且 last_seen_remote_version 未变化：不重复提醒。last_seen_remote_version 更新为该版本，并将 update_notice_status 设为 shown。dismissed。accepted，再进入用户确认后的更新执行流程。| 脚本 | 用途 | 类型 |
|---|---|---|
| ------ | ------ | ------ |
scripts/candidate_filter.py | 去重 + 冷却 + 已安装过滤 | 可选 helper |
scripts/security.py | 来源可信度 + 元数据 + 模式扫描 | 可选 helper |
scripts/feedback.py | 处理用户反馈和 daily 状态 | 可选 helper |
scripts/state_store.py | 状态/历史 JSON 读写 | 可选 helper |
这些脚本不得联网、安装依赖或调用外部命令。如果当前 Agent 会为本地脚本弹审批，跳过脚本并按本文规则执行。
scripts/feedback.py 默认读写外部持久状态目录；scripts/candidate_filter.py 如需传入状态文件，应优先传外部状态路径。
curl | python/sh、安装依赖或执行远程内容。data/state.json；用户授权状态必须在外部持久状态或平台 state 中。daily_rec_status == "enabled" 和当前 Agent 的 scheduler/automation 状态。共 1 个版本