企业官网建设流程全解析

agentic-stack 技能系统揭秘：渐进式披露 + 自重写钩子，让 AI 技能库强大却不占用上下文

【免费下载链接】agentic-stackOne brain, many harnesses. Portable .agent/ folder (memory + skills + protocols) that plugs into Claude Code, Cursor, Windsurf, OpenCode, OpenClaw, Hermes, or DIY Python — and keeps its knowledge when you switch.项目地址: https://gitcode.com/gh_mirrors/ag/agentic-stack

agentic-stack是一个开源的 AI 智能体可移植记忆与技能系统：一个.agent/文件夹（记忆 + 技能 + 协议）可以插进 Claude Code、Cursor、Windsurf、OpenCode、Codex 等 13 种 AI 编程工具，换工具不丢知识。它最聪明的设计藏在技能系统里——渐进式披露让技能清单常驻上下文却几乎不占空间，自重写钩子让每个技能在使用中自我进化。今天带你彻底看懂这两大机制 💡

为什么 AI 技能库会"吃掉"上下文？

很多团队的 AI 智能体都会遇到同一个尴尬：技能越多，效果越差。

把 20 个SKILL.md全部塞进系统提示词，几轮对话后上下文就爆了，模型开始"失忆"、答非所问。但只给一两个技能，AI 又干不了复杂活。技能库和上下文预算，看似是一对死对头。

agentic-stack 的解法可以总结成一句话：平时只给目录，用时才给全文，用完还要自我改写。

渐进式披露：两级加载，常驻而不膨胀

官方在 docs/architecture.md 中把技能系统概括为三行：

_index.md和_manifest.jsonl永远在上下文里（极小）；完整SKILL.md只在触发词匹配当前任务时才加载；每个技能底部都带一个自重写钩子。

这正是"渐进式披露"（Progressive Disclosure）的完整落地：

第一级：常驻的轻量清单

每个技能目录下的SKILL.md头部有一段 YAML frontmatter（name、triggers、tools、constraints 等字段）。安装器会把这些字段抽出来，写成两行"目录页"：

• .agent/skills/_index.md —— 人类可读的技能注册表，每个技能一段简介 + 触发词
• .agent/skills/_manifest.jsonl —— 机器可读的清单，每个技能一行 JSON

以skillforge技能为例，它在清单里只占一行：触发词是create skill、new skill，约束是"不要重复已有技能"、"必须带自重写钩子"。十几个技能加起来也就几 KB——这就是常驻上下文的全部代价。

清单与技能文件解耦后，维护也变轻松了：改完任何SKILL.md的 frontmatter，跑一次./install.sh sync-manifest，harness_manager/skill_manifest.py 会自动重建_manifest.jsonl，永远不会漂移。

第二级：触发词命中才加载全文

AI 开始干活前先看清单：当前任务是"部署上线"？那只有deploy-checklist的触发词命中，于是只加载这一个技能的完整SKILL.md（加上它积累的KNOWLEDGE.md本地教训）。其余技能继续保持"隐身"状态。

效果是：技能库从 3 个涨到 30 个，上下文开销几乎不变——增长的是磁盘文件，而不是每轮对话的 token 消耗。

解剖一个技能：SKILL.md 的标准结构

agentic-stack 的规范文档 docs/writing-skills.md 定义了技能的最小解剖结构：

skills/<name>/ ├── SKILL.md # 指令正文：YAML frontmatter + 主体 └── KNOWLEDGE.md # （可选）该技能自己积累的经验教训

frontmatter 六个字段各有分工，且每个字段都有用途——清单生成器读取它们做匹配，工具调用前的钩子则强制校验constraints。以仓库内置的 .agent/skills/skillforge/SKILL.md 为例：

• triggers：["create skill", "new skill", ...]—— 渐进式披露的"开关"
• tools：技能允许动用的工具
• preconditions：执行前提（如git-proxy要求.git exists）
• constraints：硬约束，由 pre-tool-call 钩子强制执行

一个值得注意的设计哲学是：技能全文控制在 100 行以内。技能不是操作手册，而是"目的地 + 围栏"（destinations and fences）——告诉 AI"提交前必须测试通过、禁止git add -A"，而不是手把手写第 1 步第 2 步。因为工具会变，脚本会腐，但目标不会变。

自重写钩子：让技能在使用中自我进化

光"加载得聪明"还不够。模型能力在涨、项目环境在变，今天的好技能明年可能就是错的。agentic-stack 的答案是：每个技能文件末尾必须带一个Self-rewrite hook章节，规定它自己的"复盘机制"。

以 skillforge 为例，其钩子写着：每创建 5 个技能、或任何一次创建失败后，执行四步——

1. 读近期技能相关的情景记忆（episodic memory）
2. 出现新失败模式 → 追加到该技能的KNOWLEDGE.md
3. 违反全局约束 → 升级到semantic/LESSONS.md（全局教训库）
4. 提交一条skill-update: <name>, <一行原因>的记录

也就是说，技能库不是写一次就完稿的文档，而是一个持续自我修订的活系统：失败被记下来、教训被沉淀、文件被改写，而全过程都有 git 提交可审计。

失败即进化：on_failure 的"3 次 / 14 天"红线

自重写不靠自觉，还有硬触发。钩子 .agent/harness/hooks/on_failure.py 会在每次技能执行失败时写入情景记忆，并统计：同一技能在 14 天内失败 3 次以上，即打上"重写"标记。失败记录还带pain_score（疼痛分）和importance（重要度）权重，让夜间auto_dream.py压缩周期能分清"偶尔的小磕碰"和"反复翻车的大坑"。

这套闭环完整长这样：

1. 技能执行 → 每一步写入情景记忆
2. 失败 →on_failure计数，3+/14 天触发重写标记
3. 夜间周期聚类重复模式 → 生成候选教训
4. 宿主 AI 审查候选（graduate.py通过 /reject.py拒绝，必须写理由）
5. 毕业的教训进入LESSONS.md，未来会话自动召回
6. 技能文件本身按钩子约定自我改写并提交

写技能的正确姿势：目的地与围栏，而非行车路线

规范文档里给了一个经典的"坏 vs 好"对比，建议写技能前背下来：

前者一换工具链就失效，后者在重构中依然成立。文档把这叫做 bitter lesson——模型会越来越强，你的硬编码步骤不会。

内置 9 个种子技能一览

安装后你会直接获得 9 个示范级技能，每个都是上述规范的样板：

避免踩坑：技能系统的三大反模式

docs/writing-skills.md 明确列出了三条红线，前两条直接决定技能库的健康度：

1. 触发词重叠——两个技能抢同一个触发词，渐进式披露就失效了（AI 不知道该加载哪个，甚至加载两个）；
2. 写成逐步命令清单——用步骤编号堆砌命令，工具一变技能即死；
3. 让技能去改permissions.md——权限文件只允许人类编辑，技能碰都不许碰。

写在最后

agentic-stack 的技能系统给"AI 上下文管理"提供了一套可复用的工程范式：

• 渐进式披露：清单常驻 + 触发词命中加载全文，技能数量线性增长、上下文开销近乎恒定；
• 自重写钩子：5 次使用复盘一次、失败即复盘、3 次/14 天强制标重写，技能库随使用而进化；
• 可审计：所有教训沉淀、技能改写都落 git 提交，git log .agent/就是 AI 的自传。

如果你正在为 Claude Code 或 Cursor 维护一堆.md规则文件，不妨参考这套两级清单 + 自进化钩子的设计——让技能库变大的同时，让上下文保持干净，正是这套开源方案最值得抄作业的地方。

【免费下载链接】agentic-stackOne brain, many harnesses. Portable .agent/ folder (memory + skills + protocols) that plugs into Claude Code, Cursor, Windsurf, OpenCode, OpenClaw, Hermes, or DIY Python — and keeps its knowledge when you switch.项目地址: https://gitcode.com/gh_mirrors/ag/agentic-stack