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-filesplanning-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.mdv2.1.2 起模板缺失类问题的同样解法/plugin uninstall planning-with-filesplanning-with-files /plugin marketplace add OthmanAdi/planning-with-files /plugin install planning-with-filesplanning-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.mdsh 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。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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-filesplanning-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.mdv2.1.2 起模板缺失类问题的同样解法/plugin uninstall planning-with-filesplanning-with-files /plugin marketplace add OthmanAdi/planning-with-files /plugin install planning-with-filesplanning-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.mdsh 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。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考