【与我学 ClaudeCode】规划与协调篇 之 Skills：按需加载的领域知识框架

作者逆境不可逃技术永无止境希望我的内容可以帮助到你大家吼 ! 我是 逆境不可逃 今天给大家带来文章《【与我学 ClaudeCode】规划与协调篇 之 Skills按需加载的领域知识框架》.Learn-Claude-Code 官方地址 :https://github.com/shareAI-lab/learn-claude-codeSkills 是迭代的第 5 个版本s05核心解决系统提示词臃肿、知识加载效率低的问题。它用「两层注入 按需加载」的方式让 Agent 只在需要时加载特定领域的知识既保证了提示词缓存效率又避免了无关知识的 token 浪费。学习路线s01 s02 s03s04 s05 s06 | s07 s08 s09 s10 s11 s12一、问题根源为什么直接塞系统提示会越用越慢当你希望 Agent 遵循特定领域的工作流时如 Git 约定、测试模式、代码审查清单传统做法是把所有规则全塞进系统提示词10 个 Skill每个 2000 token直接占用 20,000 token大部分知识跟当前任务毫无关系比如修复 Python Bug 时Kubernetes 部署的规则完全没用每次新增 / 修改 Skill 都会改变系统提示词导致 Anthropic、OpenAI 的 prompt caching 失效API 调用成本飙升、响应变慢二、三大核心设计决策图片内容详解Skills 框架通过三个关键设计完美解决了上述问题每个决策都对比了替代方案的缺陷。1. Skill 通过tool_result注入而非系统提示词核心设计当 Agent 调用load_skill工具时Skill 的完整内容SKILL.md正文会作为tool_result在用户消息中返回而不是直接注入系统提示词。两大关键优势保持系统提示词可缓存系统提示词在各轮对话中保持静态API 提供商的 prompt caching 可以正常工作大幅降低成本和延迟按需注入知识只有 Agent 需要的 Skill 才会被加载到上下文中无关知识不会占用 token 空间替代方案的致命缺陷把 Skill 直接注入系统提示词实现更简单也能让模型优先关注这些知识但会破坏 prompt caching每次加载新 Skill 都会生成新的系统提示词变体而且随着 Skill 增多系统提示词会越来越臃肿。tool_result方案牺牲了一点点注意力优先级换来了缓存友好和 token 效率。2. 按需加载 Skill而非预加载核心设计Skill 不会在 Agent 启动时加载初始只在系统提示词中保留 Skill 的名称和简短描述来自 YAML frontmatter。当 Agent 判断需要特定 Skill 时再调用load_skill工具加载完整内容。解决的核心问题保持初始提示词的精简避免无关知识浪费上下文窗口让 Agent 「用什么、拿什么」修复 Python Bug 时不会加载 Kubernetes 部署的 Skill既省 token 又避免模型被无关指令干扰替代方案的致命缺陷预加载所有 Skill 能保证模型随时获取所有知识但会在无关技能上浪费大量 token甚至可能超出上下文限制推荐系统模型建议技能、人工审批会增加延迟。懒加载按需加载让模型在需要时自助获取知识是最务实的方案。3.SKILL.md采用 YAML Frontmatter Markdown 正文核心设计每个SKILL.md文件分为两部分YAML frontmatter存储元数据名称、描述、标签、适用文件 glob 模式作为「Skill 注册表」的数据源Markdown 正文存储完整的技能指令、工作流、最佳实践是按需加载的有效负载这种分离让你可以列出 100 个 Skill每个仅需几字节的 frontmatter而不必一次性加载 100 套完整指令集每套可能数千 token。替代方案的致命缺陷用单独的元数据文件skill.yamlskill.md也能实现但会让文件数量翻倍把元数据嵌入 Markdown作为标题或注释需要解析整个文件才能提取元数据。Frontmatter 是 Jekyll、Hugo 等静态站点生成器广泛采用的成熟约定能让元数据和内容共存同时又能被单独解析。三、系统整体架构与工作原理1. 核心架构两层注入模型System prompt (Layer 1 -- always present): -------------------------------------- | You are a coding agent. | | Skills available: | | - git: Git workflow helpers | ~100 tokens/skill | - test: Testing best practices | -------------------------------------- When model calls load_skill(git): -------------------------------------- | tool_result (Layer 2 -- on demand): | | skill namegit | | Full git workflow instructions... | ~2000 tokens | Step 1: ... | | /skill | --------------------------------------第一层低成本系统提示词中只放 Skill 的名称和简短描述每个仅需约 100 token让模型知道「有什么可用」第二层按需加载当模型需要时通过load_skill工具在tool_result中注入完整的 Skill 内容仅在需要时占用 token2. 关键组件与工作流程(1) SkillLoader技能加载与解析器class SkillLoader: def __init__(self, skills_dir: Path): self.skills_dir skills_dir self.skills {} self._load_all() def _load_all(self): 递归扫描所有 SKILL.md 文件解析 frontmatter 和正文 if not self.skills_dir.exists(): return for f in sorted(self.skills_dir.rglob(SKILL.md)): text f.read_text() meta, body self._parse_frontmatter(text) name meta.get(name, f.parent.name) self.skills[name] {meta: meta, body: body, path: str(f)} def _parse_frontmatter(self, text: str) - tuple: 解析 YAML frontmatter--- 之间的部分 match re.match(r^---\n(.*?)\n---\n(.*), text, re.DOTALL) if not match: return {}, text try: meta yaml.safe_load(match.group(1)) or {} except yaml.YAMLError: meta {} return meta, match.group(2).strip() def get_descriptions(self) - str: 第一层生成系统提示词中的技能列表仅元数据 if not self.skills: return (no skills available) lines [] for name, skill in self.skills.items(): desc skill[meta].get(description, No description) tags skill[meta].get(tags, ) line f - {name}: {desc} if tags: line f [{tags}] lines.append(line) return \n.join(lines) def get_content(self, name: str) - str: 第二层返回完整的技能正文用于 tool_result skill self.skills.get(name) if not skill: return fError: Unknown skill {name}. Available: {, .join(self.skills.keys())} return fskill name\{name}\\n{skill[body]}\n/skill(2) 系统提示词初始化# 第一层技能元数据注入系统提示词 SYSTEM fYou are a coding agent at {WORKDIR}. Use load_skill to access specialized knowledge before tackling unfamiliar topics. Skills available: {SKILL_LOADER.get_descriptions()}(3) 工具注册load_skill工具TOOL_HANDLERS { # 基础工具bash、read_file 等 bash: lambda **kw: run_bash(kw[command]), read_file: lambda **kw: run_read(kw[path], kw.get(limit)), write_file: lambda **kw: run_write(kw[path], kw[content]), edit_file: lambda **kw: run_edit(kw[path], kw[old_text], kw[new_text]), # 新增的技能加载工具 load_skill: lambda **kw: SKILL_LOADER.get_content(kw[name]), } TOOLS [ # 其他工具略 {name: load_skill, description: Load specialized knowledge by name., input_schema: {type: object, properties: {name: {type: string, description: Skill name to load}}, required: [name]}}, ](4) Agent 主循环处理工具调用def agent_loop(messages: list): while True: response client.messages.create( modelMODEL, systemSYSTEM, messagesmessages, toolsTOOLS, max_tokens8000, ) messages.append({role: assistant, content: response.content}) if response.stop_reason ! tool_use: return results [] for block in response.content: if block.type tool_use: handler TOOL_HANDLERS.get(block.name) try: output handler(**block.input) if handler else fUnknown tool: {block.name} except Exception as e: output fError: {e} print(f {block.name}:) print(str(output)[:200]) results.append({type: tool_result, tool_use_id: block.id, content: str(output)}) messages.append({role: user, content: results})(5) 执行流程四、与 Subagents04的关键变更对比组件之前s04 Subagent之后s05 Skills工具集5 个工具基础 task5 个工具基础 load_skill系统提示词静态字符串新增 Skill 描述列表元数据知识库无skills/*/SKILL.md文件集合知识注入方式无两层模型系统提示词元数据tool_result正文核心优化上下文隔离按需知识加载、提示词缓存友好五、核心优势与创新点极致的 token 效率初始提示词仅加载元数据完整知识只在需要时注入大幅降低平均 token 消耗缓存友好的系统提示词系统提示词保持静态充分利用 API 提供商的 prompt caching降低成本和延迟可扩展的知识管理新增 / 修改 Skill 只需添加 / 编辑skills/目录下的文件无需修改代码也不会破坏缓存结构清晰的技能定义YAML frontmatter Markdown 正文的模式兼顾了元数据的可解析性和内容的可读性模型自主性与可控性平衡模型根据任务需求自主决定加载哪些 Skill系统不强制注入无关知识同时避免了预加载的臃肿问题六、运行示例假设用户输入提交本次修改到 Git遵循项目的提交规范Agent 的典型执行流程模型查看系统提示词中的技能列表看到有git技能描述为「Git workflow helpers」模型判断需要加载git技能调用load_skill(git)工具SkillLoader返回git/SKILL.md的完整内容包含提交规范、Git 命令模板等作为tool_result加入上下文模型根据加载的 Git 技能内容执行git add、git commit等命令输出符合规范的提交信息后续对话中git技能的内容会保留在上下文中无需重复加载直到对话重置七、可扩展方向技能依赖管理在 frontmatter 中添加depends_on字段实现技能之间的依赖加载如部署技能依赖于 Git 技能技能版本控制为每个 Skill 添加版本号Agent 可指定加载特定版本的技能技能过滤根据当前任务类型如bugfix/feature自动推荐相关技能减少模型选择成本技能缓存将常用技能的正文缓存到内存避免重复读取文件