如果你也和我一样大半的工作时间都泡在终端里那对 Claude Code 这类命令行 AI 助手一定不陌生。它最迷人的地方不是能陪你聊天、帮你写代码而是它真的会在你的机器上动手干活跑命令、改文件、查日志、调接口。可默认状态下的 Claude Code 其实是个相当“克制”的执行者——你给它权限它才知道能碰什么你给它描述了工具它才懂得怎么用。而“Claude Code Mods”这个概念就是把这种克制打破通过本地脚本、自定义指令、钩子配置和工具集合给 Claude 加工具在终端画界面把一套通用 AI 助手改造成专属于你的工作台。这篇文章适合谁如果你每天都在用终端觉得 Claude Code“能干活但不够顺手”如果你手上有一堆重复性巡检、报表、批处理任务想交给 AI 自动完成甚至你只是好奇“在终端里画界面”到底是怎么实现出来的这篇内容都会给你一套可对照执行的思路。我不会只放概念会把每一步怎么拆、为什么这么做、踩过哪些坑都交代清楚。1. 先搞清楚 Mods 到底在改哪一层1.1 原生对话和工具调用是两码事先说一个最容易误解的点很多人以为“让 Claude 做事”就是纯靠自然语言对话你描述需求它直接行动。实际上Claude Code 是一个带工具调用的 Agent 循环。你让它“把项目里的 TODO 注释汇总一下”它不会凭空读你的代码而是要先决定调用某个命令或者脚本再根据返回结果继续判断。Mods 的介入点就在这里。你不去修改 Claude Code 本身的程序而是给它补充“可调用清单”和“行为边界”有哪些工具存在、每个工具接收什么参数、输出什么格式、什么时候该用。这就像给一个新人配了一套带说明书的工具箱他才知道遇到什么零件去开哪个抽屉。所有 Mod 的核心都是在影响这个“开抽屉”的决策过程。1.2 Claude Code 常见的几个扩展位结合我自己的使用经验Mods 主要落在下面这几类位置上扩展位作用形态本地工具让 Claude 可以执行你写的脚本或命令可执行文件、命令字符串技能指令告诉 Claude 某种任务的标准做法说明文档 示例自定义命令用户手动触发形成快捷方式一条带参数的指令模板钩子在任务生命周期特定节点插入行为前置/后置处理脚本外部工具集通过标准协议挂接一组工具服务本地或远程的服务配置这里面的“技能指令”特别值得一说。它不是可执行程序更像是一份“操作手册”。比如我给自己建过一个小技能内容写着当收到项目月度总结任务时先看哪几个文件、用什么口径统计数据、输出格式按哪套模板来。Claude 看到任务匹配后就会自动加载这份手册再配合脚本工具去执行。1.3 为什么叫“Mods”而不是“插件”“插件”这个词会让人联想到复杂的安装器和接口规范但 Claude Code 的很多扩展其实更接近“Mod”把某个文件夹或脚本拷贝进规定的目录放在那里就能生效。和游戏 Mod 的思路一样——把一个“修改包”塞进去行为就变了。我用“Mods”泛指这些方式还有一个原因它们不需要改主程序彼此之间可以自由组合。你装了十个 Mods它们通常会同时生效也更容易做到按项目、按目录、按任务动态切换。理解这一点你就不会把 Claude Code 当成“一个单一软件”而是看作“一个可拼装的环境”。2. 给 Claude 加工具核心是建立接口感2.1 工具本质上是“一次函数调用”别被“工具”两个字吓到。站在 Claude 的视角一个工具无非就是工具名、一句话的功能描述、参数定义、返回值。它调用你的脚本和你调用一个函数没有本质区别。例如我想让 Claude 能快速计算相对日期就写了一个脚本接收一个--days参数输出目标日期。Claude 看到描述后用户说“三天后是什么日子”它就会自己拼出命令去执行。真正的关键不在于脚本多复杂而在于描述够不够清楚、参数够不够稳定。2.2 一个最小可用工具长什么样这里给出一个最简脚本示例逻辑非常简单却很适合做第一个 Mod#!/usr/bin/env python3 import argparse import datetime def main(): parser argparse.ArgumentParser( description计算相对今天的日期并附带星期信息 ) parser.add_argument(--days, typeint, requiredTrue, help相对今天的天数负数表示过去) parser.add_argument(--format, default%Y-%m-%d, help日期输出格式) args parser.parse_args() target datetime.date.today() datetime.timedelta(daysargs.days) print(target.strftime(args.format) f ({target.strftime(%A)})) if __name__ __main__: main()把它保存为relative_date.py加上可执行权限自己先跑两遍python3 relative_date.py --days 3确认输出正常。然后再把它登记进 Claude 的工具清单配上一段类似“计算相对今天的日期输入正数未来、负数过去输出日期和星期”的描述。一个 Mod 工具就成了。2.3 给 Claude 描述工具的三条经验第一描述要写明“输入约束”和“输出格式”。如果你不说Claude 可能传一个你脚本根本不认识的参数。第二工具输出最好保持纯文本别输出进度条、清屏指令、花哨交互否则 Claude 读取到的内容是混乱的。第三错误信息写到 stderr不要把错误堆到 stdout 里这样 Claude 才能区分“工具跑成功了”和“工具报错了”。2.4 我建议不要做成工具的东西做成工具前我会先问自己三个问题这个操作是否不可逆是否涉及敏感信息是否会对环境产生外溢影响像“删除文件”“批量改权限”“读取密钥文件”这类操作我一般只会加一个带--dry-run默认参数的脚本或者干脆不开放给 Claude。工具越危险越要多一道保险这一点后面调试章节还会提到。3. 在终端里画界面三种玩法按需选3.1 最轻量让 Claude 直接用文本画界面很多人一听到“在终端画界面”就以为要高深的前端技术。其实终端界面最初就是一种排版艺术只要输出有结构、有颜色人眼看着就是“界面”。最简单的方式是让 Claude 直接输出 Markdown 表格、纯文本块再加点 ANSI 颜色码。比如一个巡检结果普通输出是一行字稍微画一画就变成一个分段区块标题区域、数据表格、状态指示。Claude Code 完全能胜任这种排版因为它本质是文本生成。这个方法不依赖任何库也无须额外开发你只需要在技能手册里写清“要按什么模板输出”。3.2 正式一点的 TUI用脚本画仪表盘如果想让界面更丰富比如实时进度、彩色面板、动态刷新那就得靠脚本自己来画了。我常用的做法是写一个 Python 脚本借助 Rich 这类终端渲染库生成表格和面板。脚本本身是独立的Claude 只负责调用它并把它的输出当作文本读取。下面是一段简化版仪表盘脚本#!/usr/bin/env python3 import subprocess from rich.console import Console from rich.table import Table from rich.panel import Panel def git_branch() - str: out subprocess.run( [git, branch, --show-current], capture_outputTrue, textTrue ) return out.stdout.strip() or unknown def main(): console Console() table Table(titleProject Snapshot) table.add_column(Item, stylecyan) table.add_column(Value, stylegreen) table.add_row(Branch, git_branch()) table.add_row(Status, clean) console.print(Panel(table, titleLocal Dashboard, border_stylemagenta)) if __name__ __main__: main()你在终端里跑这个脚本看到的是漂亮的面板Claude 调用这个脚本读到的则是纯文本形式的表格内容。界面给人看数据给模型用两边不冲突。3.3 快照模式让 Claude 拿到“界面状态”还有一种很实用的玩法是我自己常用到的工具负责把一套界面即时渲染成“快照文本”Claude 再对这个快照做进一步分析。比如一个监控面板脚本平时是人看彩色界面当 Claude 要判断系统状态时就执行一个--json参数版本的脚本拿到结构化数据。也就是说同一个脚本可以面向人输出彩色界面面向模型输出纯文本 JSON。在给 Claude 加工具时我几乎都会给脚本加一个--json选项成本很低但后面的扩展空间大得多。4. 实战搭一个“项目巡检仪表盘”Mod4.1 目标和设计取舍我的常用脚手架是这样一个场景我在的某个长期维护项目散落着很多待办标记和临时代码隔几天就要检查一次。典型的检查内容有三块Git 状态、待办标记数量、最近的测试结果。如果每次都人工翻太麻烦如果都让 Claude 自由发挥它每次可能用不同方式找。更好的做法是把这三块内容固定封装成一个仪表盘脚本再将它登记为 Mod让 Claude 在用户要求“看看项目状态”的时候直接调用这个脚本把结果返回。4.2 写核心脚本我写了一个约几十行的 Python 脚本思路很简单针对项目根目录递归扫描TODO、FIXME标记执行git status --short获取变更文件再读取最近一次测试输出文件。脚本默认输出适合终端阅读的纯文本 format也提供--json参数供 Claude 获取结构化结果。#!/usr/bin/env bash # 简单封装示例dashboard.sh python3 /path/to/your/project_dashboard.py --dir $PWD $这里有个容易踩的坑Claude 执行命令时的当前目录不一定是项目根目录。所以脚本里必须显式接收--dir参数绝对路径优先别依赖“当前目录”。4.3 把脚本登记成 Claude 可用的 Mod我采用的做法是建一个技能目录比如在项目根目录下创建.claude/skills/project-dashboard/SKILL.md内容大致如下--- name: project-dashboard description: 总结项目当前状态包括 git 分支、变更文件、TODO/FIXME 数量、测试结果 --- 当用户请求查看项目状态或巡检时运行 project_dashboard 脚本 dashboard.sh --dir {project_dir} 默认输出人眼友好的格式如果用户要求统计数据可追加 --json。这样Mod 同时包含了两层能力脚本负责执行SKILL 文档负责告诉 Claude“什么时候用、怎么用”。我还会在文档里写明“结果超过 100 行时要先汇总再输出”避免工具输出过长得不到真正有用的部分。4.4 调试过程里我最常遇到的三件事脚本写完不等于 Mod 生效。第一件常遇到的事是终端里看着正常的彩色输出到了 Claude 那边变成一堆\x1b[31m转义字符。后来我在脚本里加了--no-color选项检测到输出目标不是终端时自动关掉颜色。第二件事是 chmod 权限被漏掉Claude 调用后返回 “Permission denied”而我自己手动跑完全正常。第三件事是脚本里写死了相对路径Claude 从别的目录调用时找不到文件。这三类问题都很蠢但几乎每个做 Mod 的人都会碰到。5. 常见问题与排查技巧实录5.1 症状速查表下面这张表基本覆盖了我用过大量 Mods 后总结出的高频问题症状常见原因解决思路Claude 完全不调用工具工具描述太笼统任务没被识别给 SKILL 文档补上具体触发条件调用后报权限错误脚本没有执行权限检查并在脚本所在目录执行并确认权限设置返回内容乱码ANSI 色码/编码问题给脚本增加纯文本或 JSON 输出开关找不到文件依赖当前目录而非显式路径工具接收--dir参数传绝对路径工具执行很久没结果长任务碰上超时限制脚本内部拆小步骤先输出阶段性结果输出太长被截断信息无优先级脚本里做汇总只返回关键行连续执行造成副作用脚本没有幂等设计默认加--dry-run先预览后生效Claude 总用错参数描述里没写约束在说明中明确“不支持什么”也同样重要5.2 三个好用的调试习惯先说第一个习惯任何新 Mod先手动执行一次再让 Claude 执行一次。如果手动正常而 Claude 调用不正常立刻用同样的命令、同样的参数在终端里复现切一半的排查时间能省下来。第二个习惯在脚本里加一个--debug开关把关键路径、参数、临时文件都打印到 stderr。这个开关不需要复杂几行就能搞定却能在 Claude 说“工具出错”的时候让你立刻知道是哪一行出了问题。第三个习惯让 Claude 自己解释“它打算怎么调用工具”。我通常会在 SKILL 文档里写一行调用前先复述要执行的命令。这能逼着模型暴露它的意图很多“为什么它跑偏了”的问题在这一步就暴露了。6. 什么时候值得上 Mod什么时候别硬上6.1 适合用 Mods 的场景最适合 Mods 的是那些“流程稳定、规则清晰、重复出现”的任务。比如项目巡检、固定格式的周报生成、文件批量整理、定时抓取某类数据并汇总。这类任务里人类的价值在定义规则规则一旦定好交给 Claude 反复执行就非常稳定。它还适合那些你在终端里已经有一套熟练工作流的情况。把脚本包一层接口给 Claude等于把你自己的经验注入到智能体里。以后不用再逐步发命令一句话就能触发整条链路。6.2 不适合硬上的场景反过来如果你需要的是一个实时刷新、交互极其频繁的图形界面或者一个需要复杂布局和鼠标操作的应用那就别硬往 Mods 上靠。终端界面的优势是简单、快、可编程但它不适合做复杂视觉设计。另外如果任务本身高度依赖实时对话和模糊语境每几次都要重新调整那也不适合封装成工具。工具一旦封装好它就倾向于稳定的输入输出频繁改需求反而会让 Mod 维护成本变高。我先想明白“哪部分是稳定的”再决定要不要做成 Mod。最后再分享一个我自己始终坚持的小习惯所有给 Claude 用的脚本一定支持--dry-run和--json两个参数。前者保证改文件、删文件、批量操作这类高风险动作可以先预览后者保证 Claude 能拿到结构化数据而不是从人看的彩色排版里猜。这个习惯在我做了二十几个 Mods 之后依然没觉得多余反而救过我太多次。如果你准备开始折腾 Mods我建议你也先把这两个参数加进去。