任务技能包：本体层中的可执行知识¶
核心结论¶
Anthropic 关于 Claude Code Skills 的经验，对 Harness 有价值，但不能机械照搬。
我们采纳的是其中的“任务包”思想：把高频、可复用、容易踩坑、需要验证的工作流，沉淀成轻量任务技能包。
在最新架构里，任务技能包不是 L1/L2 旁边的辅助资料，而是 Ontology 本体层中的 可执行知识对象。它需要和任务、工具、证据、权限、验证、使用日志和 writeback 发生关系。
这也是“研用测一体”的具体载体：研究结论进入包，真实使用调用包，测试验证写进包，失败样例再反向更新包。
外部参考¶
Anthropic 在 Lessons from building Claude Code: How we use skills 中总结了内部使用 Claude Code Skills 的经验。文章指出，Skill 不是单个 Markdown，而是可以包含指令、脚本、资源、配置、hooks 和记忆的文件夹；有效 Skill 应聚焦单一任务，重视 gotchas、渐进披露、验证脚本和使用度量。
我们只抽取与 Harness 路线相关的原则，不把 Anthropic 的内部分类直接搬成路线图。
在 Harness 中的位置¶
| 本体关系 | 任务技能包承担什么 |
|---|---|
| Object | 一个可识别、可引用、可版本化的能力对象 |
| Relationship | 关联任务类型、适用项目、相关工具、证据来源和维护 owner |
| Rule | 声明触发条件、禁用条件、权限、适用边界和人工确认要求 |
| Action | 指导 Agent 执行 search、read、ask、review、promote、verify 等动作 |
| Artifact | 包含 gotchas、runbook、模板、参考链接、验证命令和失败样例 |
| Writeback | 把触发、误触发、漏触发、成本和人工纠正写入 usage log |
任务技能包应该让 Agent 更好地使用本体和运行时投影，而不是把所有上下文塞进一个包里。
采纳原则¶
小而聚焦¶
一个任务技能包只解决一个高频任务。比如知识摄取、文档发布、检索 benchmark、主动询问 review、Tool Gateway 安全验证。
过宽的包会带来三个问题：
- Agent 不知道什么时候触发。
- 包内上下文太多，增加 token 和误导。
- 维护责任不清楚。
Gotchas 优先¶
不要写 Agent 默认已经知道的通用步骤。高价值内容是：
- 本团队已经踩过的坑。
- 字段名、术语、目录和权限边界。
- 哪些结果看起来成功但其实没有通过验证。
- 哪些材料只能用于当前任务，不能进入正式知识库。
- 哪些操作必须走 Tool Gateway 或人工确认。
渐进披露¶
入口文件只写：
- 什么时候触发。
- 这个包能做什么、不能做什么。
- 应该读取哪些参考文件。
- 必须运行哪些验证。
详细 API、模板、脚本、案例和失败样例放到子文件或资产目录。这样 Agent 可以先读最小上下文，必要时再下探。
验证内建¶
重要任务包必须包含验证信号：
- 命令：
python scripts/vault_lint.py、python -m mkdocs build --strict、pytest、benchmark。 - 断言：权限泄漏为 0、review 状态保留、证据可追溯。
- 成本：token、调用次数、延迟、人工接管次数。
- 失败样例：误召回、旧新冲突、ask_router 问错人、发布导航缺失。
从使用中生长¶
任务包不应先被设计成庞大框架。第一版可以只有：
- 一段触发描述。
- 三到五条 gotcha。
- 一个模板。
- 一个验证命令。
只有当它被重复使用、反复暴露失败模式后，才加入更多参考资料、脚本、hooks 或 memory。
不采纳的做法¶
- 不把所有 wiki 页面改造成 Skill。
- 不现在建设 plugin marketplace。
- 不把 Skill memory 当作组织事实源。
- 不让包内脚本绕过权限、审计和 Tool Gateway。
- 不把 Anthropic 的九类 Skill 变成 Harness 的模块拆分。
P0 候选任务包¶
| 候选包 | 目标 | P0 验证方式 |
|---|---|---|
harness_knowledge_ingest |
用户丢资料后进入 inbox/raw/wiki/ADR/docs | 检查来源、敏感信息、log、索引是否更新 |
harness_docs_publish |
从 vault 到 MkDocs 发布 | MkDocs strict build、导航检查、发布链接检查 |
agentic_search_benchmark |
对比 Postgres、OpenSearch/ES、渐进披露 | Recall、权限泄漏、lifecycle、成本、rank log |
ask_router_review |
主动询问前做候选人和问题质量检查 | Top1/Top3、节流、消息契约、knowledge card |
tool_gateway_safety |
验证 MCP/Connector 调用边界 | schema hash、审批、审计、输出净化、注入样例 |
project_status_dashboard |
更新结构化项目状态和研发进度页 | project_status 校验、生成器 --check、MkDocs build |
已落地的最小包结构¶
text
framework/task_skills/packages/<package-id>/
manifest.json
SKILL.md
references/
gotchas.md
templates/
当前已实体化四个 P0 最小包：
| 包 | 用途 | 关键验证 |
|---|---|---|
harness_knowledge_ingest |
用户资料进入 inbox/raw/wiki/docs 的知识沉淀流程 | vault_lint、项目状态生成检查 |
agentic_search_benchmark |
检索方案、SearchConnector、rank log、安全和成本评测 | 选型 benchmark、任务包 eval、SearchConnector 单测 |
project_status_dashboard |
结构化项目状态和研发进度页生成 | dashboard --check、MkDocs strict build |
ask_router_review |
主动询问前检查 owner、消息契约、节流、scope 和 pending knowledge card | Ask Router 单测、Context Management Eval、manifest lint |
任务包 manifest 校验命令：
bash
python scripts/task_skill_package_lint.py
P0 仍不做 marketplace。当前目标是先让高频工作流变成可测试、可复用、可打包的本地资产；后续再决定导出到 Claude Code Skill、Codex Skill 或企业微信 Agent workflow。
风险和验证¶
| 风险 | 失败信号 | 验证方法 |
|---|---|---|
| 误触发 | Agent 在不相关任务中读包 | 记录触发 query 和人工纠正 |
| 低触发 | 本该使用却没用 | 对照任务日志和期望触发 |
| 上下文膨胀 | 包内容越来越大 | 统计 token、拆分入口和 references |
| 内容过期 | gotcha 与当前方案冲突 | lint 过时链接、ADR supersedes、review owner |
| 脚本越权 | 包内脚本绕过安全边界 | 所有工具调用进入 Tool Gateway |
| memory 污染 | 临时结果变成事实 | memory 只做运行记录，事实必须回到 vault/docs |
路线影响¶
任务技能包会进入本体层，成为高频 workflow 的可执行知识对象。运行时使用时，它通常出现在 D1/D2：
text
D1 入口索引发现适用 Skill
-> D2 读取 Skill 的 gotchas、模板和验证要求
-> D3 SearchConnector 提供规模化召回
-> D4 Connector / Evidence 回查权威来源
-> D5 Ask Router 补足组织知识缺口
-> usage log / eval fixture 反写本体
第一轮评测结果¶
当前已完成 task_skill_package_eval 第一轮。它用 9 个合成任务和 8 个候选包，对比了 all-in、标题关键词、manifest 和 guarded manifest 四种触发策略。
关键结果：
| 策略 | Precision | Recall | Passed | 平均上下文 token | 主要问题 |
|---|---|---|---|---|---|
always_load_all |
10% | 100% | 0% | 14020.0 | 大量误触发、过期包、不安全脚本和无验证包暴露 |
keyword_title_only |
58% | 100% | 56% | 1776.7 | 包名/标题会混淆 docs publish、dashboard、benchmark |
progressive_manifest |
50% | 100% | 33% | 2601.1 | 没有 guard 时仍会触发 deprecated 泛化包 |
progressive_manifest_guarded |
100% | 100% | 100% | 766.7 | 当前样例通过 |
这轮结论不是“任务技能包天然可靠”，而是：任务技能包必须有 manifest、negative_terms、status、verify 和安全字段。否则它会变成另一个上下文膨胀源。
下一步开发不应先做 marketplace。当前已经接入第一版使用日志、dashboard 和本地 runtime：
- Task Skill Usage Log 记录触发次数、误触发、漏触发、平均 tokens 和人工纠正。
scripts/task_skill_runtime.py可以在本地按 manifest、negative_terms、status 和 verify guard 自动选择包，并追加 usage event。- 当前 12 个本地研用测事件的 precision/recall 均为 91.7%，人工纠正率为 16.7%。
- 本地 runtime 已接入
orgreorg_demo；后续要接入线上 Agent / 企微 / Web runtime，并把纠正样例反写到task_skill_package_evalfixture。 ask_router_review已实体化并进入 usage dashboard；tool_gateway_safety已完成第一轮，后续把结果纳入 usage dashboard 和真实 Connector 接入验证。
参考¶
- Anthropic: Lessons from building Claude Code: How we use skills
- 决策记录：ADR-015：引入轻量任务技能包作为 L1/L2 治理单元
- 本体驱动上下文架构：本体驱动上下文架构
- 运行时渐进披露：运行时渐进披露与上下文访问路径