--- title: "W04 常见问题：Skills 与可复用任务" --- # ❓ W04 常见问题 按遇到的先后排：电脑基础 → 装 Skill → 用 Skill → 取数与环境 → 沉淀与测试 → 导出与历史图 → 提交口径。 ## 一、电脑基础 ### 1. Tab 是哪个键？Ctrl、Esc 在哪？ - `Tab`：键盘左侧、字母 Q 左边，上面印着 `Tab` 或 `⇥`。在终端里输入文件名的前几个字再按 `Tab`，会自动补全；Claude Code 里输入 `/ht` 再按 `Tab`，会补成 `/html-slides`。 - `Ctrl`：键盘左下角。Mac 上写作 `control`，和 `command`（⌘）是两个键。本手册里的 `Ctrl + C` 在 Mac 上也是按 `control + C`。 - `Esc`：键盘左上角。Claude Code 干活时按一下让它停下。 - `Enter`：回车键，Mac 上写作 `return`。 ### 2. “建项目”是什么意思？ 建一个文件夹，把这件事要用的文件都放进去，再用 VS Code“文件 → 打开文件夹”打开它，在它的终端里运行 `claude`。在哪个文件夹启动 `claude`，它就把哪个文件夹当成项目：读哪份 `CLAUDE.md`、找哪个 `.claude/skills/`、Git 版本记录建在哪里，都看这个文件夹。 检查方法：Claude Code 欢迎界面第三行显示的路径，应当是你的项目文件夹。不是的，按两次 `Ctrl + C` 退出，用 VS Code 重新打开对的文件夹再启动。 ### 3. 电脑上没有 VS Code 先按 W01 安装手册装：。装好之前： - 启动 Claude Code：Mac 打开“终端”，Windows 打开 PowerShell；先输入 `cd ` （后面有空格），把项目文件夹从访达或资源管理器拖进终端窗口，路径会自动填上，回车；再输入 `claude`。 - 看文件、拖文件：用访达或资源管理器，先让隐藏文件夹显示出来（见第 6 条）。 ### 4. 下载的文件在哪？ 浏览器默认下载到“下载”文件夹：Mac 是 `/Users/你的用户名/Downloads`，Windows 是 `C:\Users\你的用户名\Downloads`。找不到时点浏览器右上角的下载图标，再点“在文件夹中显示”。 ### 5. 路径里的 `/`、`\`、`~` 是什么？ 路径是文件夹一层层的地址。Mac 用 `/` 分隔（`/Users/你的用户名/Documents/网页演示练习`），Windows 用 `\` 分隔（`C:\Users\你的用户名\Documents\网页演示练习`）。`~` 是你的用户文件夹的简写。对 Claude Code 说话时，写项目内的相对路径就行，例如 `素材/`、`.claude/skills/`。 ### 6. 找不到 `.claude` 文件夹 名字以点开头的文件夹默认隐藏，不是没有。 - Mac 访达：`Command + Shift + .`（句点），再按一次恢复隐藏。 - Windows 11 资源管理器：“查看 → 显示 → 隐藏的项目”；Windows 10：“查看”选项卡里勾选“隐藏的项目”。 - VS Code 文件栏默认就显示，在那里操作最方便。 - Mac 访达不让直接新建以点开头的文件夹：在 VS Code 文件栏里新建，或让 Claude Code 建。 ### 7. 看不到 `.txt`、`.md` 这些后缀，改名改不对 Windows 资源管理器：“查看 → 显示 → 文件扩展名”。Mac：访达“设置 → 高级 → 显示所有文件扩展名”。在 VS Code 文件栏里右键“重命名”，能看到完整文件名。把 `gitignore_白名单.txt` 改成 `.gitignore` 时，`.txt` 要一起删掉。 ## 二、下载与安装 Skill ### 8. GitHub 打不开，或者下载很慢 换一个网络（手机热点、校园网切换）再试；刷新几次。还不行，找助教或同学用 U 盘拷一份解压好的 `sysu-awesome-cc-main` 文件夹。 ### 9. Windows 上双击 ZIP，拖出来的文件夹不全 双击 ZIP 看到的是预览，不是解压。右键 ZIP →“全部解压缩…”→“提取”，再从解压出来的文件夹里拷。Windows 解压出来外面会多一层同名文件夹：`sysu-awesome-cc-main\sysu-awesome-cc-main\skills\…`，进到里面那层再找 `skills`。 ### 10. `/skills` 里看不到 `html-slides` 逐条查： 1. **路径**：必须是 `项目文件夹/.claude/skills/html-slides/SKILL.md`。常见放错：多了一层（`.claude/skills/sysu-awesome-cc-main/…`）、少了一层（`.claude/skills/SKILL.md`，外面没有 `html-slides` 文件夹）、`.claude` 放到了项目外面、文件夹名拼成了 `.claude/skill`（少个 s）。 2. **没有重开**：`.claude/skills/` 是 Claude Code 启动后才建的，要退出再启动一次。 3. **启动位置不对**：看欢迎界面第三行的路径是不是项目文件夹（第 2 条）。 4. **文件格式**：`SKILL.md` 第一行必须是 `---`，前面不能有空行；`name:` 与文件夹同名。直接从仓库拷来的不会有这个问题，自己改过的才会。 都对还是不行：直接问它“你有哪些技能可用”，或者用 `/html-slides` 点名试一次。 ### 11. 按两次 Ctrl + C 之后怎么办？重开是不是新对话？ - 按第一次：屏幕下方出现 `Press Ctrl-C again to exit`；紧接着按第二次：Claude Code 退出，回到命令行提示符。**这只是退出**，要再输入 `claude` 回车才是重新打开。 - 重新打开就是一个新会话：屏幕上没有上一次的对话，它重新读取项目规则和技能清单。旧对话没丢，存在你电脑上。 - 想接着上次聊：启动时输入 `claude --continue`（接最近一次）或 `claude --resume`（从列表里选）。 - `/clear` 是不退出、清空对话；第一次建技能文件夹后，统一用退出重开。 ### 12. 用 Codex，技能放哪？ 项目级放项目文件夹里的 `.agents/skills/`，个人级放 `~/.agents/skills/`。早期文档写的是 `.codex/skills`，目前仍能读取，但官方文档已改为 `.agents/skills`。Codex 里点名技能用 `$技能名`，例如 `$html-slides`。 ### 13. 我用的是 VS Code 里的 Claude 图形面板，不是终端 图形面板也能用 Skill，但有些命令只在终端里的命令行界面有。输入 `/export`、`/skills` 等看到 `isn't available in this environment` 的，打开 VS Code 终端（“终端 → 新建终端”）输入 `claude`，在那里做。图形面板里重开会话：关掉面板再打开，点“新对话”。 ## 三、用 Skill ### 14. 它要装 Playwright、要生成配图、要导出 PDF `html-slides` 正文里有配图、截图审阅、导出 PDF 这几步，要另装程序。本练习不需要：拒绝它的安装请求，再说一遍“不要配图，不做截图审阅，不导出 PDF，只做 HTML”。 ### 15. 自然说话时屏幕上没出现 `Skill(html-slides)` 它没想起这个技能，可能是你的话和描述对不上。两个办法：把话说得更像描述里写的（“做一份网页演示文稿”“做幻灯片”）；或者直接点名 `/html-slides 你的要求`。已经做出来但没用技能的，用点名重做一次。 ### 16. 双击 `index.html` 没反应，或者打开是一堆代码 打开是代码，说明是用文本编辑器打开的。右键 →“打开方式”→ 选 Chrome、Edge 或 Safari。VS Code 里点开 HTML 看到的也是代码，要到访达或资源管理器里双击。 ### 17. 改完了，浏览器里还是旧的 按 `F5`（Mac `Command + R`）刷新。还是旧的，确认打开的是它改的那个 `index.html`（有时它会新建一个文件夹）。 ## 四、取数与环境（练习二） ### 18. 第一次用 `macro-data`，它说要装 Python 或 AKShare 正常。第一次用时它会先检查你电脑上的环境，缺什么说什么：要装什么、装到哪里、大约多久。按提示确认后再装，每条命令都会请你批准；要你自己动手的地方（双击安装包、勾选某个选项），它会一步一步说。没说清楚的先问它，不懂就不批准。 ### 19. 输入 `python`，弹出了微软应用商店 那是 Windows 自带的占位程序，不是装好了。让它按 `macro-data` 的说明处理：通常改用 `py` 命令，或者从 python.org 装官方安装包（选 64 位的 “Windows installer (64-bit)”）。装完 Python 要把终端、VS Code 和 Claude Code 都关掉再重新打开（在 VS Code 终端里用 Claude Code 的，要关掉整个 VS Code，只关终端面板不够），新装的程序才找得到。 ### 20. 装包很慢或报错 把报错原文发给它，让它按 `macro-data` 里的排查表处理（换镜像、加 `--user`、关掉代理等）。Windows 上报 `Microsoft Visual C++ 14.0 is required`，或者 `mini-racer` 装不上，多半是装了 32 位 Python：让它先运行 `macro-data` 的环境检查，看“Python 位数”一行，是 32 位就卸掉，重装 “Windows installer (64-bit)”。装了很久还跑不通，不要一直耗着，改用材料包里的备用数据（手册练习二“取不到数怎么办”），在 `取数记录.md` 写清卡在哪一步、报的什么错。 ### 21. 它要装 Miniconda 或建 conda 环境 `macro-data` 的写法是：电脑上已有 conda 的用 conda，没有的用系统 Python 加 pip，不必为此装 conda。它要你新装 Miniconda 的，告诉它“我没有 conda，不装 conda，用系统 Python”。 ### 22. 取到的数据，最新一期是一年前的 有的接口会滞后很久，`macro-data` 的 `SKILL.md` 里写了这类坑。让它换一个接口重取，并在 `取数记录.md` 的“是否滞后”一栏写明。 ### 23. 取数时报代理错误、超时 国家统计局和 AKShare 都是国内网站。开着全局代理（翻墙软件）的，关掉再试；还不行把报错发给它。 ### 24. 两个来源的数对不上 先看口径：当月同比还是累计同比、初值还是修订值、官方 PMI 还是财新 PMI。以原发布（国家统计局、中国人民银行官网）为准，在“数据与口径”页写明用的哪个，在“局限”页写明差异。 ### 25. 取不到的指标能不能自己估一个？ 不能。写“未取到”，在“局限”页说明。用备用 CSV 补的，逐个标来源。 ### 25a. 取数记录是什么，一行怎么填？ `宏观数据/` 里的 CSV 保存数据，**每个指标一份 CSV**，每行数据带获取时间、来源机构、原始来源链接、发布标题、发布日期，经二手接口取的另写接口名。`协作记录/取数记录.md` 是这些数据的汇总说明，**每个指标汇总一行**，不是把 CSV 的每一行再抄一遍，也不能代替 CSV 里的逐行来源列。 下面按 `取数记录_模板.md` 的栏目示范一行。指标、机构、文件、日期和链接均为虚构占位，不是真实取数结果，不能当作自己的记录使用。 | 指标 | 类别 | 接口或文件 | 获取时间 | 来源机构 | 最新一期原发布链接 | 最新一期发布标题与日期 | 覆盖期间 | 最新一期 | 是否滞后 | 数据文件 | 来源列是否齐全 | 备注 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 示范景气指数（虚构） | 景气 | 示例接口名 | 20XX-09-10 10:30 | 示例发布机构 | `https://example.invalid/release` | 《示范指数发布》；20XX-09-09 | 20XX-01 至 20XX-08 | 20XX-08 | 待核验 | `宏观数据/示范景气指数.csv` | 待核验 | 格式示范，不含真实数据 | 实际填写时，从这次保存的数据文件、取数过程和原发布中逐项核对；“是否滞后”要把接口最新一期与原发布最新一期对照后再写，不能因为取数成功就填“否”。链接没找到写“未找到”，数据没取到写“未取到”，不凭空补齐。 给 AI 的取数指令可以换成自己的说法，但要保留四件事：每个指标一份 CSV；每行带来源信息；核对每个指标的最新一期；按模板汇总接口或文件、获取时间、来源机构、最新一期的原发布链接与标题日期、覆盖期间、最新一期和是否滞后等字段。不确定是否漏项，就回手册练习二第 3 步对照完整指令。 ## 五、沉淀与测试（练习三） ### 26. `skill-creator` 开始跑评测，停不下来 按 `Esc`，再说一遍“不要跑评测，先给我看草稿”。 ### 27. 用 Codex，新技能跑到了 `~/.codex/skills` 沉淀指令里没写位置。Codex 自带的 `skill-creator` 默认写到个人级旧路径。让它把整个文件夹移到项目的 `.agents/skills/macro-fundamentals-report/`，以后指令里写明位置。 ### 28. 新技能里写死了“某年某月 CPI 多少” 让它改成做法，例如“先确认每个指标最新一期是哪个月”“每条数据记下获取时间、来源机构、原发布链接和发布日期”。技能是下次用的，这次的数下次就过时了。 ### 29. 测试时它没用新技能，直接照抄了项目里已有的演示文稿 项目里已经有一份成品时，它可能照着旧文件改。先按第 30a 条确认新 Skill 能按预期自然触发，再换一个时间窗口或指标组合，输出到新文件夹，核对实际调用记录和取数过程，看它是不是从取数做起。做完可以问它“你按哪个技能的第几步做的”，但要对照记录核实，不能凭这句回答认定通过。 ### 30. 该来的没来 / 不该来的来了 先按第 30a 条确认新 Skill 已加载，再看触发结果是否符合预期，不把未调用直接归因于 `description`。 - 该来没来：检查 `description` 是否写清任务，以及你平时表达这个任务的说法；缺了就补上，在同项目的新会话里重测。 - 不该来却来了：检查描述的适用范围是否过宽；补一句“不用于只查一个数、不写投资建议”一类的边界，在新会话里重测。 ### 30a. 新 Skill 没被调用，按什么顺序排查？ 先检查加载和触发，再做完整任务，不用反复生成整份演示文稿来试。 1. **同项目、新会话，先看 `/skills`。** 留在练习二的 `宏观基本面汇报/` 项目里，退出后重新运行 `claude`，输入 `/skills`，找 `macro-fundamentals-report`。列表里有它，说明当前会话已识别这个 Skill，不表示已经执行了正文。新会话不等于新文件夹。 2. **列表没有，先查位置和文件。** 核对启动位置是不是原项目、路径是不是 `.claude/skills/macro-fundamentals-report/SKILL.md`，再检查文件名、开头的 `---`、`name` 和 `description` 是否写好；改后在同项目里退出重开，再看列表。用 Codex 的项目路径是 `.agents/skills/`，点名用 `$技能名`；这里的 `/skills` 与界面示例按终端版 Claude Code 写，面板提示不可用时见第 13 条。 3. **列表有了，再用自然说法测触发。** 不先要求它读 `SKILL.md`，也不点名 `/macro-fundamentals-report`；直接用手册练习三 C 的三句话分别测试，每句在一个新会话里说。观察是否出现 `Skill(macro-fundamentals-report)` 这样的实际调用记录，不能用它口头说“我用了”代替。看清触发结果后可按 `Esc` 停下，不必每句都生成成品。 4. **不符合预期，先排查、重测。** 有技能却没按预期调用，回第 30 条核对描述与任务边界；也可以在另一个会话里手动点名，区分“点名能不能用”和“自然说话会不会调用”。改过后重新开会话，用原来的自然说法重测；仍不符就保留测试句、列表与调用记录、报错原文，继续定位，不凭未核验的配置猜原因。 5. **触发测试通过后，再完整运行。** 两句应调用的调用了、一句不应调用的没调用，再换时间窗口或指标组合，把产物写到同项目的 `汇报_测试/`。核对它是否按新 Skill 从取数做起，以及数据来源、自检和演示文稿是否符合要求；不要把旧文件改个名字当成跑通。 四件事分开判断： | 看到什么 | 能说明什么 | 还不能说明什么 | | --- | --- | --- | | 你或 AI 读了 `SKILL.md` | 看到了文件内容 | 已被技能系统识别或自然触发 | | 手动点名 `/macro-fundamentals-report` 后调用成功 | 点名能调用 | 自然说话也会调用 | | 未点名的自然说法出现新 Skill 的实际调用记录 | 这句触发了新 Skill | 整个任务已按要求做完 | | 生成了 HTML，打开后有内容 | 文件生成了 | 用了新 Skill，或触发、取数、自检都通过了 | ### 31. 提交时把下载来的技能也提交了 用材料包里的白名单 `.gitignore`，它会让 `html-slides`、`macro-data`、`skill-creator` 三个下载来的文件夹不进版本记录，你自己造的技能照常记录。已经提交进去的，让它“把这三个文件夹从版本记录里移除，但保留文件”，它会用 `git rm --cached`，文件还在，先让它报告再放行。 ## 六、导出对话与历史图 ### 32. `/export` 不可用 - 看到 `/export isn't available in this environment.`：你是在非终端环境里输入的（VS Code 图形面板等）。打开 VS Code 终端，输入 `claude`，在终端里的 Claude Code 里输入 `/export`。要导出的是之前那次会话的，先 `claude --resume` 选中它，再 `/export`。 - 在终端里输入 `/export` 弹出了菜单：用方向键选“保存为文件”，回车；或者直接带文件名：`/export 协作记录/对话记录_练习二.txt`。 - 用 Codex 的：Codex 的会话记录按日期存在 `~/.codex/sessions/` 下；让 Codex 帮你找到这次会话的记录文件，拷一份进 `协作记录/`。 ### 33. 会话被压缩后导出不全 会话很长时，Claude Code 会自动压缩（屏幕上出现 `Conversation compacted`），把前面的对话换成摘要；你输入 `/compact` 也会压缩。压缩之后 `/export`，导出的是摘要加压缩之后的内容，压缩前的原话不在里面。 做到一半被压缩的：先 `/export` 导出当前这份记录；压缩之前导出过的那份也要交，压缩前后的记录都交。不要让 AI 回忆着把压缩前的内容补写出来。 压缩前的完整记录还在你电脑上，导出的不全时可以找回： - 屏幕上按 `Ctrl + O` 可以翻看完整历史。 - 完整记录存在 Claude Code 的会话文件里：用户文件夹下 `.claude/projects/` 里，以项目路径命名的那个文件夹中，扩展名是 `.jsonl`，一次会话一个文件。可以对 Claude Code 说：“找到这次会话在 `~/.claude/projects/` 下的 jsonl 记录文件，复制一份到 `协作记录/`。”这个文件是给程序读的格式，内容完整但不好读。 以后做长任务：每个练习做完就 `/export` 一次，别等到最后。 ### 34. 导出的文件放进项目后，Git 说有未提交的改动 白名单 `.gitignore` 只放行 `.md`、`.html`、`.csv`、`.py` 和技能文件夹，导出的 `.txt` 不会进版本记录，Git 不会提示。你用的不是白名单的，导出到 `协作记录/` 以外的地方，或者让它把这个文件加进 `.gitignore`。 ### 35. Git Graph 打不开 先分清两样东西： - **源代码管理图**：VS Code 自带。左侧点“源代码管理”图标（或 `Ctrl + Shift + G`，Mac 同样），面板下方有“源代码管理图”，折叠着的点标题展开。 - **Git Graph**：一个扩展，要先在 VS Code 扩展商店搜“Git Graph”安装。装好后，源代码管理面板顶部有它的图标；或者 `Ctrl + Shift + P`（Mac `Command + Shift + P`），输入 `Git Graph: View Git Graph`。 打不开、是空的，多半是下面几种： 1. VS Code 打开的不是项目文件夹（打开了上一级，或者只打开了一个文件）。用“文件 → 打开文件夹”重新打开项目文件夹。 2. 项目还没开启版本记录（没有 `.git` 文件夹）。让 Claude Code 先 `git init` 并提交一次。 3. Git Graph 没装。用自带的源代码管理图也可以。 ### 36. `git log --oneline` 在哪里运行？ 在终端里运行，不是在 Claude Code 的输入框里。VS Code 里再开一个终端（终端面板右上角的 `+`），或者先按两次 `Ctrl + C` 退出 Claude Code。也可以直接问 Claude Code：“运行 git log --oneline 给我看”。 ## 七、提交口径（李老师 2026-10-06 确认） ### 37. 练习二、练习三连续做，只导出了一份完整的交互记录，两个练习都能交吗？ 可以。同一份完整的交互记录，可以同时放进练习二和练习三的交互记录框，不用拆分。 ### 38. 练习二修改之前的版本没有存档，是用历史脚本重建的，能交吗？ 可以交。重建的文件要标明是重建稿：在文件里或 `协作记录/取数记录.md` 里写明“由历史脚本重建，非原始存档”。是否影响评价由老师逐份看，不作承诺。 ### 39. 演示文稿超过 8–10 页，可以吗？ 可以。页数是建议范围，不是硬性上限，练习二、练习三都一样。建议 8–10 页左右，是为了在做到交互要求、用上最佳实践的前提下，不让同学额外多花 tokens。已经做完、页数超出的，不要求删减或重做；不拼页数，页数多也不加分。练习三没有页数上限。