planning-with-files 技能因 YAML frontmatter 错误无法加载怎么排查？-港品优选

planning-with-files 技能因 YAML frontmatter 错误无法加载怎么排查？

【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files

planning-with-files 以 SKILL.md 文件的形式安装到 Claude Code 或其他 Agent 中，文件的开头是一段 YAML frontmatter（---包裹的元数据块）。当这段 frontmatter 不是合法 YAML 时，技能加载会失败，模型触发的description字段也会一并损坏。这篇文章基于项目文档给出排查路径：定位 SKILL.md、逐项检查 frontmatter、修复或重装，最后验证技能恢复加载。

先确认症状属于 frontmatter 问题

文档中记录过两种典型现象，都指向 frontmatter 解析失败：

技能无法加载，YAML 加载器报mapping values are not allowed here。这是 v3.1.2 实际发生过的回归：该版本把 description 刷新为包含": "（冒号加空格）的文本，而英文 SKILL.md 的description字段没有加引号，YAML 把:读成嵌套 mapping 后拒绝整段 frontmatter（详见 CHANGELOG v3.1.3 与 frontmatter 校验测试）。
技能描述显示成乱码片段：如果 frontmatter 里的 hook 命令字符串含有---分隔符，部分按字面---切分 frontmatter 的解析器会把第一个---当成结束围栏，description 变成 hook 命令的尾部片段（CHANGELOG 中记录过该问题）。

如果你的现象是"技能列表里没有这个技能"或"调试日志出现 skill loading 错误"，再往下走。

定位需要检查的 SKILL.md

先确认你的安装方式，文件位置不同（docs/troubleshooting.md）：

# 插件安装路线：查看已装版本与组件 claude plugin list # 独立技能安装路线：技能目录 ls ~/.claude/skills/planning-with-files/

插件安装的运行时文件位于~/.claude/plugins/cache/下，由 Claude Code 管理——不要直接编辑缓存里的副本，缓存副本有问题时走重装路线。需要手工改 frontmatter 的只有独立安装路线的~/.claude/skills/planning-with-files/SKILL.md。

按文档顺序检查 frontmatter 三项

docs/troubleshooting.md 的 "YAML frontmatter errors" 一节给出三个检查点：

缩进必须用空格，不能用 tab。文档中的反例是hooks:下用 tab 缩进的PreToolUse:，正确写法是空格缩进：
```
hooks: PreToolUse:
```
第一行必须恰好是---，其前面不能有空行。
整段 frontmatter 必须能通过 YAML 校验。文档建议把 frontmatter 内容拿到 YAML 校验器里验证（原文建议在线校验器）。

项目仓库里还有一条更具体的依赖无关规则，来自 tests/test_skill_frontmatter_valid.py：没有加引号的description值里不能出现": "；带引号的标量可以安全包含冒号。对照检查你的 SKILL.md：

# 错误：未加引号的 description 含 ": "，会被解析成 mapping description: Manus-style persistent file-based planning for AI coding agents: keeps ... # 正确：值包在双引号内 description: "Manus-style persistent file-based planning for AI coding agents: keeps ..."

v3.1.2 的官方修复正是把 description 包进双引号，解析后的值不变、模型触发行为不变，只消除 YAML 报错（CHANGELOG v3.1.3）。

修复：改文件或升级到已修复版本

两条路径按你的情况选一条：

你用的是 v3.1.2 这类已知的发布版本：不要手改，直接升级/重装。插件路线的清理重装命令（docs/troubleshooting.md，v2.1.2 起模板缺失类问题的同样解法）：
```
/plugin uninstall planning-with-files@planning-with-files /plugin marketplace add OthmanAdi/planning-with-files /plugin install planning-with-files@planning-with-files
```
重装后完全重启 Claude Code，让缓存刷新。
你是独立安装或自行维护 SKILL.md：按上一节的检查点修 frontmatter——把未加引号且含": "的值加上双引号，把 tab 缩进改成空格，确认首行是---。注意插件路线的 hook 命令标量本身较长，改动时保持引号配对完整。

验证技能恢复加载

用调试模式看技能加载错误（docs/troubleshooting.md 中 Hooks not triggering 一节的同款手段）：
```
claude --debug
```
在输出中找 skill loading 相关错误。frontmatter 修复前，这里能看到解析失败信息；修复后应不再出现。
跑项目自带的自检脚本。如果你在项目根目录有本仓库的脚本，安装文档给出的验证方式是运行 doctor，它一次性报告 plan 解析、hook 注入和时延（docs/installation.md、commands/plan-doctor.md）：
```
sh scripts/plan-doctor.sh
```
输出按 PASS/WARN/FAIL 行逐条阅读。注意 doctor 是诊断工具，不做自动修复；它检查的是 hook 注入、plan 解析这类"静默失败"机制，输出 FAIL 时按脚本提示的对应项处理，而不是期待它替你改 SKILL.md。
技能列表与描述：在 Claude Code 里确认 planning-with-files 重新出现在技能列表中，且 description 是完整的一句话而不是 hook 命令的尾部片段——后者说明还有解析器按---切分 frontmatter 的问题残留。

限制与边界

插件缓存目录（~/.claude/plugins/cache/）下的文件不可就地编辑，缓存类问题只能走卸载重装。
doctor 各机制在异常时按设计静默退出 0，因此"看起来和没有 plan 一样"是常见假象；判断修复是否生效要以claude --debug中的加载错误是否消失、doctor 的 FAIL 是否转 PASS 为准。
仓库的 frontmatter 校验测试（tests/test_skill_frontmatter_valid.py）是针对仓库内所有 SKILL.md 的回归防护，用于验证仓库发布物，不直接作用于你机器上的安装副本。

如果按上述检查点修复后claude --debug仍有技能加载错误，而你的 SKILL.md 首行、缩进、引号三项都合规，说明问题超出了本文档覆盖的范围，建议按 docs/troubleshooting.md 的 "Still stuck?" 一节带上claude --version、操作系统、执行的命令和完整报错去提 issue。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析