agent-skill-stack

构建 Agent 技能栈

围绕用户的实际目标，构建最小可用的技能栈。切勿把某个领域示例或固定生命周期强加到不同的请求上。

1. 选择面向用户的深度

默认使用通俗语言模式。假设用户无需理解路径、修订版本、哈希、清单、静态分析或运行时细节。

在通俗语言模式下，展示：

• 用户想要达成什么；
• 用日常语言表述的步骤；
• 哪些能力已经具备；
• 哪些技能是推荐的、可选的、重叠的或不适合的；
• 每个候选项的使用广泛程度；
• 它是否通过了安装安全检查和安全试用；
• 它可能需要哪些账号访问权限或外部操作。

将源路径、修订版本、文件指纹、原始评分、审计证据和依赖详细信息保留在内部记录中。仅当用户要求技术细节，或某项具体技术事实是知情同意所必需时，才展示它们。

2. 动态推导工作流

阅读 references/workflow-model.md。从用户想要的最终结果出发，而不是请求中的领域词汇。

只询问那些会实质性改变结果、访问边界、成本或技能栈的问题。从成功结果反向推导工作流，再从可用的起点正向验证它。

不要复用之前编号的流程。不要假设每个请求都需要研究、内容创作、发布、分析、存储或自动化。只有当用户的目标需要时，才添加某个步骤。

当一个步骤具有一个可理解的操作、一个主要结果、一个访问边界和一个可观察的成功条件时，就停止分解。将技术能力卡片保留在内部；向用户展示简短的通俗语言流程。

3. 先搜索本地索引

阅读 references/local-index-and-profiles.md。

如果存在当前的本地技能索引，请先搜索它，再搜索文件系统或互联网。如果索引缺失或已过期，则从相关的技能根目录重建它：

python3 scripts/skill_index.py build \
  --root ~/.codex/skills \
  --root ~/.codex/plugins/cache \
  --root .codex/skills \
  --root ~/.agents/skills \
  --root ~/.hermes/skills \
  --output ~/.codex/skill-index.json

索引存储名称、摘要、别名、范围、能力术语、更新时间和内部文件指纹。它从不执行技能，也不存储任何使用历史。

如果当前项目有 .codex/skill-stack.json，请将其中的活动技能和路由规则视为首选技能栈。仅在遇到未覆盖的能力或用户要求替代方案时，才在配置之外进行搜索。将来自不同本地根目录的同名条目视为待审核项；不要静默合并它们。

4. 映射能力，包括间接辅助能力

对于每个必要的步骤，在内部记录：

• 所需的输入、操作和输出；
• 约束、频率和规模；
• 本地/读取外部/写入外部的边界；
• 账号、权限和审批需求；
• 成功条件和回退方案；
• 前驱步骤和后继步骤。

然后仅在相关时考虑横切需求：质量/风格、准确性、合规性、隐私、本地化、数据质量、编排和可观测性。

按 输入 -> 操作 -> 输出 匹配技能，而不是按标题相似度匹配。这允许 Humanizer 匹配自然写作需求，即使其名称中从未出现用户的领域。

不要强制每个步骤对应一个技能。一个技能可以覆盖多个步骤；一个步骤可能需要工具、MCP、连接器或通用 Agent 能力，而不是另一个技能。

5. 用四个视角进行搜索

阅读 references/discovery-ranking.md。通过以下视角搜索每一项尚未覆盖的能力：

1. 直接需求：用户的领域和操作。
2. 底层操作：实际发生的转换或数据任务。
3. 支撑性成果：质量、安全、风格、合规、评估和监控。
4. 连接方式：命令行、MCP、API、连接器、浏览器自动化、存储和交接。

扩展中英文别名、动词、名词、输出以及相邻术语。尽可能搜索标题、描述、标题层级以及完整的 SKILL.md 内容。

使用多个来源，因为没有任何注册表是完整的：

• 本地 Skill 索引和已安装清单；
• GitHub 连接器或 GitHub 文件/仓库搜索；
• npx skills find <query> 和 skills.sh；
• agentskill.sh 或其他可用的注册表；
• OpenCLI，用于广泛的网络发现和特定平台调研。

按顺序运行由浏览器支持的 OpenCLI 搜索。未经用户批准，不要登录、添加凭据或启用连接器。

6. 验证并排列候选对象

将每一个搜索结果都视为候选对象，而非推荐结果。确定其规范仓库和确切的 Skill 路径。阅读完整的 Skill 以及安装后会变为可访问的每一个可执行文件。

在以下情况下拒绝或隔离候选对象：

• 其来源或所声称的能力无法验证；
• 其结构无法安装；
• 强制性依赖不兼容或不可用；
• 关键凭据访问、数据上传、提示词注入、破坏性操作或混淆行为仍未得到解释；
• 唯一可行的测试会发布、发送、购买、删除或更改真实账户；
• 许可证或平台条款使预期用途存在重大不确定性。

使用 references/discovery-ranking.md 中的评分标准对通过上述门槛的候选对象进行排列。实际采用情况和社区证据占评分的 25%。将未知值保留为未知。

优先选择能满足所有必需成功条件的最小技术栈。将候选对象分类为：

• 必需：完成成果所必需。
• 有帮助：提升质量、安全性或效率。
• 替代：互斥的替代方案。
• 不推荐：被阻止、冗余、不兼容或过于不确定。

7. 分析冲突与范围

阅读 references/security-installation.md。检查身份、激活、指令、资源、依赖、数据格式、权限和合规方面的冲突。

通过选择一个主 Skill、定义向辅助 Skill 的窄范围交接、保持替代方案互斥，或不安装冗余候选对象来解决重叠问题。

对于任务特定的能力，优先使用项目本地 Skill 和项目 Skill Stack Profile。仅对应当广泛可用的能力使用全局安装。

8. 用通俗语言呈现推荐

默认输出：

1. 你想达成的目标：用一句话简要复述。
2. 工作如何拆解：针对该请求推导出的简短编号流程。
3. 你已经具备什么：现有可用的 Skills 和未覆盖的缺口。
4. 推荐组合：必需、有帮助、可选、不建议。
5. 为什么选择这些：用日常语言说明契合度、采纳情况、安全检查、安全试跑和冲突。
6. 需要你决定什么：账户访问权限、付费服务、外部发布或安装选择。

使用诸如 已具备、推荐、可选、不建议、安全检查通过、安全试跑通过 和 最近确认可用 这样的标签。默认响应中不要显示哈希或本地路径。

在有用时提供 查看技术详情。技术视图可包含规范来源、修订版本、文件指纹、确切目标位置、原始证据、依赖项、权限和回滚详情。

当用户想要可复用的产物时，从结构化 JSON 创建可分享的推荐卡片：

python3 scripts/render_stack_card.py \
  --input /path/to/stack-card.json \
  --output /path/to/stack-card.svg

让卡片在没有技术路径或原始哈希的情况下也能理解。包含目标、选定的 Skills、各自的角色和状态、安全边界以及验证日期。

9. 仅在同意后安装

推荐并不授权安装。在用户选择后，遵循 references/security-installation.md。

默认采用分阶段安装。仅当每个选定的 Skill 都通过了硬性门槛、具有确切固定的身份、没有未解决的冲突、不会覆盖现有目标位置，且用户明确批准批量操作时，才允许一键批量安装。

对于已下载并检查过的 Skill 目录，先预览：

python3 scripts/stage_install.py \
  --source /path/to/skill-a \
  --dest ~/.codex/skills \
  --manifest ./skill-stack-lock.json

仅在批准后使用 --apply 重复执行。绝不要静默添加凭据、接受新权限、覆盖已安装的 Skill，或发布/发送/删除外部数据。

在用户选择技术栈后，提议以试运行模式创建项目配置：

python3 scripts/project_profile.py \
  --project /path/to/project \
  --name project-stack \
  --skill skill-a \
  --skill skill-b

仅在用户确认配置后使用 --apply。

10. 运行召回检查

在安装或配置变更后，运行召回检查，而不是性能基准测试：

1. 一个直接点名任务的请求；
2. 一个使用不同措辞的自然转述；
3. 一个应引入辅助能力（如写作质量、事实核查或合规）的支持性请求。

确认选出了正确的主要和辅助 Skills，且无关的 Skills 未被选中。报告一个简单结果，例如 3/3 种说法都能正确识别；将原始提示词和路由详情保留在技术视图中。

不要收集或存储用户提示词历史、命中/未命中日志或路由反馈。