大家已经不太问「Claude Code 是什么」「MCP 怎么安装」这种入门题更多是下面这种让人抓头发的问题Skill 明明装了为什么不触发MCP 明明注册了为什么 Claude Code 偏不用代码图谱接上了结果它照着旧地图改代码PDF Token 省下来了图表却答错了。这才是 AI 编程真正开始进阶的信号。047 那一辑我回答的是「怎么把 Claude Code 用起来」。这一辑回答的是「已经用了为什么还是不顺」。我把 061、062、066、067、071、072、073 几篇文章里反复出现的追问合并成 8 个问题不假装逐字引用某一位读者直接给结论和排障路径。先看速查表。你遇到的现象真正的根因先做什么Skill 装了却不触发发现、路由、执行三层有一层没通先显式调用再查 description 和路径全局和项目 Skill 打架同名 Skill 有两份来源只保留一个权威来源规则写了但 Claude 不听四层提示词职责混在一起把事实、流程、全局约束拆开追加 system prompt 后行为变怪把替换和追加、全局和临时规则混用了先用--help核对参数再只加边界MCP 注册了却不用工具能启动不等于 Agent 会选择查启动、描述、任务路由三层同一套 Skill 换 Agent 失效核心流程和宿主配置绑死了拆核心层和适配层代码图谱越用越错索引是缓存不是真相先校验更新时间再回源读代码PDF 省 Token 却答错图表文本检索绕过了视觉通道文字问题走 RAG图表问题走多模态1. Skill 装好了为什么 Claude Code 完全不触发这个问题最容易把锅甩给模型。你在~/.claude/skills里放了一个文件夹里面也有SKILL.md然后对 Claude Code 说「帮我按这个 Skill 做」它却像没听见一样。你再把 Skill 内容复制进对话事情立刻又能跑起来。这通常不是 Skill 内容不够长而是三层链路只通了一层。第一层是发现Claude Code 能不能在当前会话的 Skill 搜索范围里看到它。第二层是路由description有没有把「什么时候应该使用我」说清楚。第三层是执行Skill 里面的路径、命令和工具是不是当前环境真的存在。很多人只检查了第一层。看见目录在就以为完成了安装。一个能被正确路由的最小SKILL.md至少要把触发场景写具体。--- name: service-review description: Use when reviewing a backend service change, especially when the task touches database writes, retries, permissions, or idempotency. Do not use for simple formatting changes. --- # Service Review 先读取改动范围和相关测试再按数据一致性、重试、权限、可观测性四项检查。「帮我做代码审查」太宽了模型不知道什么时候该选它。写成「检查后端服务的数据库写入、重试、权限和幂等性」就不一样了触发条件、任务边界和不适用场景都有了。排障顺序也别反过来。先在对话里显式调用一次确认 Skill 本体能执行再看description是否具体最后才去怀疑模型能力。如果显式调用也失败问题在路径或执行层不在路由层。Skill 不触发时先查链路不要先改 Prompt。反例是把description写成一段产品宣传词再在正文里塞 500 行流程。模型连「什么时候选我」都没看懂后面写再多也只是躺在硬盘里的愿望。2. Skill 放全局还是项目里为什么越装越乱061 那篇里有个问题我很认同skills.sh的可编辑副本和 plugin 的只读订阅能不能混用。我的判断很简单能混不是重点同一个 Skill 到底谁是唯一真源才是重点。我把 Skill 分三类。类型推荐位置典型内容个人习惯用户级目录我的代码审查清单、个人提交习惯项目规则项目级目录当前仓库的测试命令、模块边界、发布流程团队能力团队仓库或固定 plugin所有人共享的审查流程和安全约束个人习惯放全局换项目也成立。项目规则放项目里离开这个仓库就不该继续生效。团队能力要有版本管理不能靠每个人电脑里一个手工复制的文件夹维持。最危险的组合是同名service-review同时出现在用户级目录、项目级目录和 plugin 里。你以为自己改的是这一份Claude Code 实际读到的可能是另一份。等它表现异常时排查半天最后发现不是模型变了是电脑里有三个「同事」抢着发言。skills.sh适合你想改造内容、保留本地控制权的场景。plugin 适合你只想订阅、跟着上游更新的场景。两者选一个作为权威来源另一个最多用于临时试验试完就删掉。这也是为什么我不建议把所有 Skill 都塞进全局目录。全局目录很方便但它会把项目 A 的工作流带进项目 B。项目越来越多之后Agent 不是更聪明而是背着一只装满旧规则的口袋。️投票你最常遇到哪种 Claude Code 卡点Skill 装了不触发MCP 注册了不调用Token 消耗压不住能执行但总是改错地方3. CLAUDE.md、Skill、system prompt到底该把什么放在哪里这三个东西最容易被写成一锅粥。我给它们各自安排一句话。system prompt 管全局行为CLAUDE.md 管项目事实Skill 管可复用流程。system prompt 更像驾驶规则告诉 Agent 怎么使用工具、怎么拆任务、什么时候需要确认。它不应该塞进某个项目的数据库表名。CLAUDE.md更像项目入职手册说明项目用什么技术栈、测试怎么跑、哪些目录不能碰。Skill 是操作手册说明遇到某类任务时应该按什么顺序完成检查、修改和验证。举个后端项目的例子。「不要在没有测试的情况下修改生产配置」是全局安全约束适合放在 system prompt 或稳定的全局规则里。「这个项目用 Gradle单测命令是./gradlew test订单状态由OrderStateMachine管理」是项目事实适合写进CLAUDE.md。「做数据库迁移时先生成方案再检查回滚脚本最后执行迁移测试」是工作流适合做成 Skill。把三类内容混在一起会出现两种坏结果。项目事实被全局规则污染换个仓库仍然带着旧表名。工作流被写进CLAUDE.md每次对话都加载一遍但你只是偶尔做数据库迁移Token 和注意力都被白白占用。Claude Code 四层上下文职责system prompt、CLAUDE.md、Skill 和当前对话的分工Claude Code 四层上下文职责system prompt、CLAUDE.md、Skill 和当前对话的分工判断放哪里有个很实用的问题你把这句话复制到另一个项目还成立吗。成立优先考虑全局规则。不成立放项目上下文。只有做某类任务才需要放 Skill。只对当前这一轮有效直接写进当前对话。规则不是越集中越好职责清楚才是省 Token。4.--append-system-prompt能不能当万能增强包不能。062 那篇拆过 system prompt 之后很多人第一反应是把所有「绝对不能错」的规则都追加进去。这个思路只对了一半。--append-system-prompt适合给一轮任务加稳定的全局边界比如本次会话只允许修改src/禁止执行发布命令任何删除动作必须先停下来确认。它不适合拿来替代项目文档、Skill 流程和测试。如果你的 CLI 版本支持这个参数可以先用帮助信息确认再按会话启动。复制claude --help | grep -E -- --(append-)?system-prompt claude --append-system-prompt $(cat .claude/guardrails.md)这里有两个坑。第一个坑--system-prompt和--append-system-prompt不是一回事。前者是替换默认系统提示词后者是在默认提示词后追加。你只是想补一条边界却把底层工具使用策略一起覆盖了模型行为变得奇怪不一定是它变笨了可能是你把方向盘拆了。第二个坑把互相冲突的约束全塞进去。比如一边要求「先规划再修改」一边又要求「收到任务后立即改文件」一边要求「任何命令都要确认」一边又想完全无人值守。模型最后只能在冲突里随机取舍。我更建议只追加三类内容安全边界、当前会话的权限范围、必须遵守的输出格式。项目知识写CLAUDE.md复杂流程写 Skill临时任务边界写当前 Prompt。system prompt 是护栏不是外挂。护栏越多车不一定跑得越稳。5. MCP 明明注册了Claude Code 为什么就是不用MCP 能启动不代表 Claude Code 会调用它。这是三个问题。第一服务器有没有真正启动。命令路径错、运行时版本不对、环境变量没有传进去都会让它停在注册表里。第二工具描述是否写清楚。工具名叫search描述只写「搜索内容」模型不知道什么时候该优先用它。第三当前任务有没有给出调用理由。你让 Agent「分析项目」它可能认为直接读文件就够了你明确要求「先用代码图谱查询调用链再打开命中的源文件」路由结果就会不同。我自己排 MCP先把它拆成四个动作。claude mcp list cat .mcp.json command -v node node --version第一条看有没有注册第二条看项目级配置后两条看运行时。不同版本的 CLI 命令可能略有变化最终以claude --help为准。不要一上来就重装 MCP那是把未知问题换成更大的未知问题。工具描述也要写「什么时候用」不能只写「我能做什么」。比如sense_graph不要只写「查询代码图谱」而要写「当任务涉及调用链、影响面、死代码或符号关系时优先使用本工具返回结果后仍需打开源文件和测试确认」。这句「仍需回源确认」很关键。MCP 返回的是证据线索不是最终答案。代码图谱、知识库、搜索服务都一样。MCP 不调用的四步排障流程从注册检查到任务路由MCP 不调用的四步排障流程从注册检查到任务路由反例是给 Agent 接 20 个 MCP然后期待它自动选得像一个经验丰富的架构师。工具越多选择空间越大描述越模糊误路由越频繁。先接少量高价值工具把描述和回归场景写清楚再逐步增加。6. 一套 Skill 能不能同时给 Claude Code、Codex 和 Cursor 用能复用但不能幻想「复制过去就完全一样」。最适合复用的是 Skill 的知识和流程比如审查清单、领域术语、验收步骤、示例输入输出。最不适合直接复用的是宿主绑定工具名称、配置目录、权限语法、调用命令和子 Agent 机制。我会把 Skill 拆成两层。核心层只写任务方法先收集什么信息按哪些风险检查什么条件算完成。适配层再写 Claude Code 的 MCP 名称、Codex 的调用方式、Cursor 的规则路径。核心层可以放在一个普通仓库里适配层各自只有几十行。内容是否跨 Agent 复用处理方式检查清单和领域术语高放核心 Skill文件路径和命令中根据项目改写MCP 工具名低每个宿主单独适配权限和确认机制低不要直接复制结果格式中先统一再按宿主调整071 那篇里两个 PPT Skill 的经验也是一样支持多个 Agent不等于所有 Agent 的运行体验一致。Claude Code 可能最顺手Codex 可能更适合脚本化Cursor 更靠近编辑器上下文。你真正要迁移的是能力边界不是目录结构。最常见的失败方式是把 Claude Code 专用的CLAUDE.md、MCP 工具名和权限配置原封不动塞给另一个 Agent然后得出「这个 Skill 不兼容」的结论。不是 Skill 不兼容是适配层没有拆出来。7. 代码图谱接上以后过期了Agent 按旧地图改错怎么办代码图谱最容易被误解成「代码真相」。其实它更像数据库索引。索引快但它永远有一个前提索引和源数据同步。文件刚改完图谱还没增量更新分支切换了索引仍然指向上一条分支生成目录被扫描进去了图谱里出现了根本不该参与分析的符号。这几种情况都会让 Agent 得到一个看起来很专业、其实已经过期的答案。所以我给代码图谱定了三条规矩。第一先查更新时间和当前分支再相信关系查询。第二图谱只负责缩小范围命中的文件必须回源读。第三涉及写操作、数据库迁移和权限改动时至少再看一遍测试和调用方不能只凭图谱的影响面结论动手。073 那篇实测里sense 的工具调用从 19 次降到 10 次Token 从 228K 降到 156K。这说明地图能减少 Agent 的盲翻但不代表它可以替代源代码。省下来的调用次数应该拿去做验证不是拿去省略验证。小项目也不要为了追热点强行上图谱。仓库只有几个模块人工读目录比维护索引更快。真正值得接入的是跨模块调用多、领域边界复杂、同名符号很多、Agent 经常反复翻源码的仓库。代码图谱是导航不是目的地。导航过期时回到源代码才是最短路径。8. PDF 检索省了 Token为什么图表问题反而答错这是 072 那篇最容易被忽略的边界。Token Saver 这类方案用文本抽取、关键词检索和语义检索把大 PDF 变成与问题最相关的几段文本。文字问题非常适合这条路径章节编号、条款原文、定义、接口参数都能少搬很多上下文。但图表不是文字。一张架构图里箭头方向、颜色分组、节点位置可能比旁边的说明更重要。文本抽取只能拿到几个节点名称拿不到「这个箭头从哪里指向哪里」。你让文本 RAG 回答图表它只能根据残缺信息补全答错不是偶然是输入通道已经丢了视觉信息。所以 PDF 问答要先分流。问题类型推荐路径原因条款、定义、章节、关键词本地 RAG文本检索精准输入小表格中的数字先文本检索再核对原页防止列错位和单位误读架构图、流程图、扫描件原生多模态必须保留版式和视觉关系既问正文又问图表两路结果合并文本和视觉各负责一半072 里提到的 92% 到 99% 节省是特定文档、特定问题和特定基准线下的结果不是「所有 PDF 都能省 99%」。如果你的任务主要看图、看财报、看扫描版合同优先保证信息完整别为了一个漂亮的节省率把视觉通道关了。省 Token 的前提是没有省掉答案需要的证据。一条命令把四层排障先跑一遍如果你不想每次靠记忆排查可以在项目里放一个只读检查脚本。它不修改配置只告诉你当前环境到底有哪些层。#!/usr/bin/env bash set -u project_dir$(pwd) echo project: ${project_dir} for path in ${HOME}/.claude/skills ${project_dir}/.claude/skills; do if [ -d ${path} ]; then echo skill-dir: ${path} find ${path} -maxdepth 2 -name SKILL.md -print else echo skill-dir-missing: ${path} fi done for config in ${HOME}/.claude.json ${project_dir}/.mcp.json ${project_dir}/.claude/settings.json; do if [ -f ${config} ]; then echo config: ${config} else echo config-missing: ${config} fi done if command -v claude /dev/null 21; then echo claude: $(claude --version 2/dev/null || true) claude mcp list 21 || true else echo claude: not-found fi保存成scripts/claude-code-doctor.sh后执行。chmod x scripts/claude-code-doctor.sh ./scripts/claude-code-doctor.sh它不能判断 Skill 的 description 写得好不好也不能替你决定工具该不该调用但能先把「目录不存在」「配置文件不在」「CLI 不在 PATH」「MCP 列表为空」这些低级问题筛出来。脚本显示一切正常Agent 仍然不触发时再回到任务描述和工具 description 查路由。常见问题QSkill 是不是越多越好。不是。Skill 的价值是减少重复决策不是往上下文里堆目录。先保留与你当前项目和任务稳定相关的少数 Skill能明确说出触发条件、输入和验收方式再考虑增加。QSkill 明确写了「必须调用 MCP」为什么还是不用。「必须」不是路由证据。把调用时机、工具能解决什么、调用后要怎么验证写进 tool description并在任务里点名第一步先查什么。必要时先显式调用一次确认工具链路通了再测试自动路由。Q代码图谱能不能替代CLAUDE.md。不能。图谱回答结构关系CLAUDE.md说明项目约定。一个告诉 Agent 谁调用谁一个告诉 Agent 哪些目录能改、测试怎么跑职责不同。QPDF 是不是都应该接 Token Saver。不是。反复追问长文本时值得接图表密集、扫描件为主或需要保留版式时先用原生多模态。工具要按问题类型选不要按标题里的节省率选。Q只有 Claude Code 才能用这些 Skill 吗。不一定。只要另一个 Agent 支持相近的 Skill 文件规范就能复用核心流程。但配置路径、工具名称、权限机制和调用习惯要做适配不能把宿主专用配置整包复制。我的判断Claude Code 用到第二阶段拼的已经不是「谁会背更多命令」而是谁能把上下文、工具和验证拆成几层各自只做该做的事。Skill 不触发先查路由MCP 不调用先查描述代码图谱给出结论回源确认PDF 检索省下 Token先确认有没有把图表证据一起省掉。把这四句话记住很多看起来像模型抽风的问题最后都会落回工程边界。我不太相信「再装一个 Skill 就会变聪明」这类说法。真正稳定的 AI 编程工作流通常不是工具越多越强而是每个工具的职责越窄、证据链越完整。下篇我打算把.mcp.json的项目级和用户级配置、环境变量注入、团队共享模板单独拆出来想看哪一块评论区留个关键词。公众号主页顺手点个星标后面这类 Claude Code 排障文不容易在信息流里沉下去。身边有人正被 Skill 和 MCP 配置折磨直接把这篇甩给他比一句「你再试试」有用。最后我们整理出这套 AI 大模型 突围资料包✅ 从零到一的 AI 学习路径图✅ 大模型调优实战手册附医疗/金融等大厂真实案例✅ 百度/阿里专家闭门录播课✅ 大模型当下最新行业报告✅ 真实大厂面试真题✅ 2025 最新岗位需求图谱所有资料 ⚡️ 朋友们如果有需要 《 AI大模型 入门进阶学习资源包》下方扫码获取~资料展示下面是我整理的AI大模型学习资料和工具包预览适合收藏后按主题逐步学习。需要这份AI大模型资料清单的话在评论区回复「清单」即可我会根据大家的问题继续补充对应的实战内容。