一句话调起复用提示词：claude-code-from-scratch技能系统（Skills）实战教程

一句话调起复用提示词：claude-code-from-scratch技能系统（Skills）实战教程

【免费下载链接】claude-code-from-scratchBuild your own Claude Code from scratch. 🔍 Claude Code 开源了 50 万行代码，读不动？用 ~5000 行 TypeScript / Python 从零复现核心架构，11 章分步教程带你理解 coding agent 精髓项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch

claude-code-from-scratch用约 5000 行 TypeScript / Python 从零复现了 Claude Code 的核心架构，其中的**技能系统（Skills）**是本期主角：把一段反复使用的提示词（比如"读 diff 并写 commit message"）打包成一个 Markdown 文件，之后只需输入/commit一句话，就能把整套提示词调起来执行。本文将带你理解 Skills 的设计思路，并手把手创建自己的第一个技能。

为什么需要 Skills 技能系统？

日常使用 AI 编程助手时，你经常会重复输入类似的话：

• "读一下 git diff，帮我写一个规范的 commit message"
• "审查这个文件，检查安全漏洞"
• "用 conventional commits 格式提交代码"

每次手打一遍既繁琐，又容易前后不一致。Skills 技能系统的解法是：把这些提示词存成文件，像 shell 脚本一样即装即用。

💡 官方教程称之为"AI Shell 脚本"——把 AI 工作流模板化，一次定义，反复复用。详见 docs/09-skills.md。

快速上手：三步创建第一个技能

无需写任何代码，一个技能就是一个文件。三步走：

第 1 步：创建技能目录

在项目中创建.claude/skills/commit/目录（用户级可放在~/.claude/skills/）。

第 2 步：写入 SKILL.md

目录里放一个SKILL.md文件，前半部分是元信息，后半部分就是提示词本身。项目里自带了两个示例技能，可直接参考：

• 示例一：test/skills/commit/SKILL.md
• 示例二：test/skills/greet/SKILL.md

第 3 步：一句话调起

启动 CLI 后输入/commit，技能立刻生效：

$ mini-claude /commit feat: add the new thing

运行演示不需要 API key：

node steps/run.mjs 9

这条命令对应仓库里的可执行场景 steps/scenarios/invoke-skill.json。

SKILL.md 文件格式详解

SKILL.md 由两部分组成：frontmatter 元信息+提示词正文。

--- name: commit description: Create a git commit with a descriptive message when_to_use: When the user asks to commit changes or says "commit" allowed-tools: run_shell, read_file user-invocable: true --- Look at the current git diff and staged changes. Write a clear, concise commit message following conventional commits format. The user's request: $ARGUMENTS

各字段的作用一目了然：

解析逻辑集中在 src/skills.ts（Python 版对应 python/mini_claude/skills.py），parseSkillFile负责把文件拆成元信息与模板，容错处理了逗号分隔和 JSON 数组两种allowed-tools写法。

两种调用方式：手动 /name 与模型自动触发

Skills 支持双路径调用，两条路最终汇合到同一个解析函数resolveSkillPrompt()：

路径一：用户手动调用

输入以/开头的内容，CLI 就会去技能目录里找同名文件。逻辑见 src/cli.ts：

/commit fix types → 加载 commit 技能，参数 "fix types" 替换进模板

路径二：模型自动调用

你只需自然地说"帮我提交代码"。此时系统提示词中已经列出了所有可用技能及when_to_use触发条件（由 src/prompt.ts 中的buildSkillDescriptions()注入），模型判断匹配后会调用内置的skill工具，工具返回的是展开后的提示词文本——本质是一个"元工具"：返回值不是数据，而是指令。

🎯 双路径设计的原因：手动调用保证你精确控制触发时机；自动调用则让模型在你忘记技能存在时也能主动用上。

模板变量：让技能接收参数

提示词正文中支持两个内置变量：

• $ARGUMENTS：替换为你调起技能时传入的参数。比如/commit 修复登录 bug，"修复登录 bug" 就会被注入到模板中
• ${CLAUDE_SKILL_DIR}：替换为技能所在目录路径。这样技能可以在目录里附带模板、配置等文件，提示词中引用即可

替换逻辑只有几行，见 src/skills.ts 的resolveSkillPrompt函数（L116-L123）。

inline 与 fork：两种执行模式

选 fork 的核心好处：保持主对话上下文干净。子 Agent 的工具还受allowed-tools白名单约束，且默认排除agent工具防止递归。实现位于 src/agent.ts 的executeSkillTool方法。

技能加载优先级：项目级覆盖用户级

技能从两个来源加载，同名时项目级优先：

1. ~/.claude/skills/—— 用户级（低优先级，个人所有项目通用）
2. .claude/skills/—— 项目级（高优先级，当前项目专用，会覆盖同名用户技能）

加载顺序写死在 python/mini_claude/skills.py 的discover_skills（L33-L49）中：先加载 user，再加载 project，用 Map 去重自然实现"后者覆盖前者"。解析结果还会缓存，避免重复读盘。

想更深入？核心源码与文档清单

常见问题 FAQ

Q1：技能必须用代码写吗？不需要。技能本体就是自然语言 Markdown，会写提示词就会写技能。

Q2：为什么用 Markdown 而不用 JSON/YAML 存提示词？因为技能的本体是大段自然语言。Markdown 正文直接就是提示词，JSON 存储反而要转义换行符和引号，可读性差。

Q3：如何验证技能被正确加载？在 CLI 中输入/skills，会列出所有已发现的技能及其描述；输入No skills found则说明目录或文件命名有问题（必须是技能名/SKILL.md的目录结构）。

Q4：本地怎么跑起来试试？

git clone https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch cd claude-code-from-scratch npm install && npm run build node steps/run.mjs 9

小结

Skills 技能系统用一个 Markdown 文件解决了"提示词复用"问题：

• ✅ 一句话/name手动调起，或让模型按when_to_use自动触发
• ✅$ARGUMENTS参数化，同一技能适配不同输入
• ✅allowed-tools+user-invocable提供安全与权限边界
• ✅ inline / fork 双模式，兼顾轻量任务与重型任务的上下文隔离

对照真实 Claude Code，mini-claude 还简化了技能来源（2 个而非 6 个）和 token 预算控制，但核心架构完全一致——理解了这几百行源码，你就掌握了 Skills 的精髓。下一章可以继续 docs/10-plan-mode.md，看看"先想清楚再动手"的 Plan Mode。

【免费下载链接】claude-code-from-scratchBuild your own Claude Code from scratch. 🔍 Claude Code 开源了 50 万行代码，读不动？用 ~5000 行 TypeScript / Python 从零复现核心架构，11 章分步教程带你理解 coding agent 精髓项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch