Claude Code记不住进度？手搓一个进度Skill解决

前言：Skill与CLAUDE.md的分工

使用Claude Code开发项目时，你可能遇到过这样的痛点：每次开启新对话，AI就像失忆了一样，完全不记得上次做到哪里了。CLAUDE.md虽然能提供项目说明，但它是静态的，无法记录动态的开发进度。

这就是Skill的用武之地。简单来说：

CLAUDE.md 管的是「项目是什么」——项目规范、技术栈等静态信息，打开Claude Code时自动加载
Skill 管的是「一件事怎么做」——具体任务的流程和标准，需要时通过一句话触发

两者配合，Claude Code就不再是每次都需要重新交代的助手，而是越来越懂你项目的老搭档。

值得一提的是，CLAUDE.md实际上存在多层加载机制。Claude Code启动时会按优先级依次加载三个位置的CLAUDE.md：用户主目录下的~/.claude/CLAUDE.md（全局配置）、项目根目录下的CLAUDE.md（项目级配置）、以及当前工作子目录下的CLAUDE.md（模块级配置）。这三层配置会叠加生效，越靠近当前工作目录的配置优先级越高。这种设计借鉴了Git的配置分层理念（.gitconfig的system、global、local三级），让开发者可以在不同粒度上管理AI的行为规范。Git配置分层机制是软件工程中「约定优于配置」思想的经典实现——system级设定全局默认值，global级覆盖个人偏好，local级处理项目特殊需求。Claude Code借鉴这一模式，解决的是多项目、多模块场景下AI行为一致性与灵活性的平衡问题。例如，你可以在全局CLAUDE.md中声明通用代码风格偏好，在项目级声明特定框架约束，在子目录级针对微服务模块设定独立规范。

创建Skill文件夹

由于「进度」是一个通用Skill（不限于某个项目），我们将它建在用户目录下的 .claude 目录中。

具体操作：

进入用户目录下的 .claude 文件夹
新建一个名为 skills 的文件夹（注意拼写不能错）
在 skills 文件夹中，再新建一个名为 进度 的文件夹

Claude Code启动时会自动扫描 .claude/skills/ 下的所有文件夹，每一个文件夹就代表一个Skill。

需要了解的是，Skill文件夹可以存放在两个位置，对应不同的作用域。放在用户主目录的~/.claude/skills/下的Skill是全局Skill，对该用户的所有项目生效，适合存放通用工作流（如本文的进度管理）。放在项目根目录的.claude/skills/下的Skill是项目级Skill，仅对当前项目生效，适合存放与特定项目绑定的流程（如该项目特有的部署流程或代码规范检查）。当两个位置存在同名Skill时，项目级Skill会覆盖全局Skill，这与大多数配置系统的就近优先原则一致。

编写skill.md文件

在「进度」文件夹中新建一个Markdown文件，文件名必须是 skill.md（注意大小写，一个字母都不能错）。

skill.md文件结构

Skill的标准写法分为两个部分：元信息和具体指令。

---
name: 进度
description: 当用户说「保存进度」「记录一下」等含有保存进度意图的词时触发
---

## 上次进度

`cat 进度.md`

## 保存进度

保存内容包括：当前做了什么、卡在哪里、下一步计划等信息。
使用write工具覆盖（或创建）进度.md文件。

## 读取进度

读取进度.md的内容并展示。

元信息字段解析

两个 --- 之间的部分是元信息（这种格式在技术文档领域被称为YAML Front Matter，最早由静态网站生成器Jekyll推广，现已成为Markdown文件附加元数据的事实标准）：

YAML Front Matter最早由Ruby生态的Jekyll静态博客框架在2008年引入，用于在Markdown文件顶部嵌入结构化元数据。其语法规范是以三个短横线（---）作为起止标记，中间填写YAML格式的键值对。这一约定后来被Hugo、Hexo、Gatsby等几乎所有静态网站生成器采纳，也被Obsidian、Notion等知识管理工具支持。在Claude Code的Skill系统中，Front Matter承担的角色类似于函数签名——name是函数名，description是触发条件的自然语言描述。

name：Skill的名称
description：这是最关键的部分，它告诉大模型什么时候该触发这个Skill。当用户输入包含「保存进度」「记录一下」等意图的文字时，Claude会自动匹配并加载该Skill

description字段之所以关键，是因为它依赖大语言模型的语义理解能力进行意图匹配。这不是传统的关键词精确匹配，而是基于Transformer架构的语义相似度计算。当用户输入「记录一下当前状态」或「把进展存一下」这类表述时，即使没有出现「保存进度」四个字，模型也能通过上下文语义推断出用户意图，从而触发对应的Skill。这种机制本质上是将Skill的description作为系统提示词的一部分注入到模型的推理过程中，让模型在每次接收用户输入时都会与已注册的Skill描述进行语义比对。

从技术实现角度看，传统的命令匹配依赖正则表达式或关键词列表，存在明显的脆性——用户稍微换个说法就可能匹配失败。而Claude Code利用了大语言模型基于Transformer自注意力机制的语义理解能力，将用户输入和所有Skill的description编码为高维语义表示，通过计算语义接近程度完成匹配。这解释了为什么description的撰写质量直接影响触发精度：描述越具体、覆盖的表述变体越多，模型越容易建立准确的语义映射。

指令中的动态执行机制

指令部分中用反引号包裹的命令（如 `cat 进度.md`），其工作原理类似环境变量：在发送给大模型之前，系统会先执行这条命令，将执行结果替换到对应位置。如果进度.md存在，就会读出内容并填充进去。

更准确地说，这里采用的是预处理（Preprocessing）机制，与Shell脚本中的命令替换（Command Substitution）概念类似。在Skill被触发、内容发送给大模型之前，系统会先在本地环境中执行这些命令，并将标准输出（stdout）的结果直接替换到Markdown文本的对应位置。这意味着模型接收到的不是命令本身，而是命令的执行结果。这种设计使得Skill可以动态获取文件内容、环境变量、系统状态等实时信息，实现了静态模板与动态数据的结合。需要注意的是，这些命令的执行上下文是当前项目的工作目录，因此路径引用应基于项目根目录。

命令替换（Command Substitution）是Unix Shell的核心特性之一，在Bash中表现为$(command)或反引号`command`语法。Claude Code的Skill预处理借鉴了这一概念，但执行环境和安全模型有所不同——Shell命令替换发生在Shell解释器层面，而Skill中的命令执行发生在Claude Code的本地运行时环境中，权限受限于当前用户权限和Claude Code的沙箱策略。这种「先执行后注入」的模式在模板引擎领域也很常见，如Jinja2的宏机制或Ansible的facts收集阶段，核心思想都是将动态数据在模板渲染阶段提前解析。

验证Skill是否生效

在项目根目录运行Claude Code后，可以通过以下方式验证：

启动后直接查看是否显示「进度」Skill
输入 /skills 命令查看所有已加载的Skill列表
确认Skill状态为「on」（启用）

实战演示：保存与恢复开发进度

保存进度

假设你正在让Claude Code开发一个「按文件扩展名分类统计数量和大小」的分析模块，开发到一半需要中断。此时只需说「保存进度」：

Claude会识别到你的意图，触发「进度」Skill
询问你是否使用该Skill
确认后，Claude会将当前进展写入 进度.md 文件

首次使用时由于不存在 进度.md，系统会自动创建。

关于进度.md文件的管理，这里有一个实际的工程决策值得考虑：是否应该将它纳入Git版本控制。对于个人项目，将进度.md加入.gitignore通常是更好的选择，因为它记录的是个人开发状态而非项目文档。但在团队协作场景下，如果多人共用同一个Claude Code工作流，进度文件可能需要按开发者区分（如进度-张三.md），或者使用分支隔离策略。Skill设计为覆盖写入而非追加写入——每次保存的都是最新快照，避免文件无限膨胀。

恢复进度

关闭当前会话，开启一个全新的对话，只需输入「进度」两个字：

Claude会自动读取上次保存的进度文件
清晰展示：做了什么、卡在哪里、下一步是什么
还会主动询问是否继续上次的工作

关键在于：在新会话中你一个字都不需要额外解释，Skill帮你完成了所有上下文的恢复。

CLAUDE.md与Skill的对比

维度	CLAUDE.md	Skill
加载方式	自动加载	触发加载
管理内容	项目规范、技术栈	具体任务流程
信息类型	静态	动态
作用范围	项目级	任务级
存放层级	全局/项目/子目录三级	全局/项目两级
设计理念	声明式（描述「是什么」）	过程式（描述「怎么做」）

当这两样东西配合使用，Claude Code就具备了「项目记忆」能力——既知道项目的全貌，又能记住每次对话的进展。这才是真正高效的AI辅助开发体验。从软件工程的角度看，这种设计实际上实现了一种轻量级的会话状态持久化方案，解决了大语言模型因上下文窗口限制而无法跨会话保持记忆的根本问题。

大语言模型的无状态特性源于其推理架构：每次请求都是独立的前向传播过程，模型本身不存储任何会话历史。业界解决这一问题的方案主要有三类：一是扩大上下文窗口（如Claude的200K token），但成本高且仍有上限；二是RAG（检索增强生成），从外部知识库动态检索相关内容注入上下文；三是显式状态文件，即本文采用的方案。Skill的进度管理本质上是第三类方案的轻量实现——用文件系统作为持久化层，用预处理命令作为检索机制，用自然语言作为状态描述格式。相比RAG方案的复杂基础设施需求，这种方案胜在零依赖、即开即用，特别适合个人开发者的日常工作流。

小结

进度Skill的实现非常简洁，但解决了Claude Code使用中的一个核心痛点。你可以基于同样的思路，创建更多通用Skill，比如代码审查流程、部署检查清单等。Skill的本质就是把你的工作流程标准化，让AI按照你的规矩办事。

更进一步思考，Skill机制代表了一种人机协作的新范式：开发者不再需要每次都用自然语言详细描述需求，而是将重复性的工作流程封装为可复用的指令模板。这与软件开发中「不要重复自己」（DRY原则）的思想一脉相承。随着你积累的Skill越来越多，Claude Code实际上在逐步学习你的工作习惯和偏好，最终形成一套高度个性化的AI辅助开发体系。