过去半年我和身边不少开发者都在尝试用 AI 辅助日常开发。最先感受到的变化是AI 确实能写代码、能查资料、能解释报错。但真到需要它独立完成一条完整任务链时比如把最近的 Git 提交整理成周报、把项目里的技术债标记全部扫出来并生成报告很多 AI 工具就会暴露出一个共性短板——它只会“回答”不会“干活”。如果你也有这种感受那说明你已经从“会用 AI”的阶段走到了该学习“开发 Agent”的阶段。这篇文章我打算完整拆解 Agent Skills 的概念、结构、实战用法并基于 Claude Code 和 Codex 两个工具带你从零打造一套可复用、可扩展的智能体技能体系。无论你是刚接触 AI 编程工具的初学者还是已经用了一段时间想进一步提效的开发者这篇文章都可以当作一份系统化教程来读。1. 背景与核心概念Agent 与 Agent Skills1.1 从“对话式 AI”到“可执行任务的 Agent”先理清一个容易混淆的概念普通聊天 AI 和 Agent 有什么区别普通聊天 AI 的核心能力是“生成内容”。你问它一个问题它给你一个答案。这个答案可能是代码、可能是文字、可能是表格但 AI 本身不会主动去执行命令、读写文件、运行脚本、根据结果继续调整方案。Agent 的核心能力是“完成任务”。它会把一个大目标拆解成多个子步骤然后通过调用工具逐步执行。比如你让 Agent“生成一份项目周报”它需要先读取 Git 日志、分析提交信息、整理成表格、再输出 Markdown 文件。这中间涉及命令执行、数据处理、文件写入等多个环节每一步都需要有对应的能力支撑。而 Agent Skills 就是支撑 Agent 完成具体任务的能力模块。你可以把它理解成 Agent 的“工具箱”或者“插件集”。1.2 什么是 Agent SkillsAgent Skills 是一个文件目录里面包含两部分核心内容技能描述文件告诉 Agent“这个技能是干什么的、什么时候该用、怎么用”。执行资源脚本、模板、参考文档等真正负责完成具体工作。以 Claude Code 为例官方推荐的技能目录结构大致如下~/.claude/skills/ ├── generate-report/ │ ├── SKILL.md │ └── scripts/ │ └── generate_report.py ├── code-audit/ │ ├── SKILL.md │ └── scripts/ │ └── scan_todos.py当 Agent 接收到用户的任务后会扫描技能目录里的描述文件。如果发现某个技能的描述与当前任务匹配就会读取该技能的完整说明并按照说明调用脚本、读取模板最终完成任务。这个过程最大的价值在于技能是可复用的。你不用每次都在对话里重复写一长串提示词只要在需求触发时让 Agent 自动加载对应技能即可。1.3 为什么选择 Claude Code 与 CodexClaude Code 是 Anthropic 推出的命令行 AI 编程工具它运行在终端里能够理解整个代码仓库的结构可以读取文件、执行命令行操作、修改代码并且支持通过技能目录扩展能力。Codex 是 OpenAI 推出的 CLI 编程工具同样定位在终端环境侧重自然语言驱动的编码任务。它支持项目级的指令文件可以约定项目中 Agent 的行为方式。选择这两个工具作为切入点一方面是因为它们在 AI 编程领域关注度较高、社区活跃另一方面是因为它们都具备“Agent 化”的扩展机制非常适合用来演示 Agent Skills 的完整开发流程。学习过程中你还会接触到一些周边工具比如 cc-switch、Ollama 等我会在后面结合实战场景说明。2. 环境准备与版本说明在开始写第一个 Skill 之前需要先把基础环境准备好。下面的版本信息以当前常见稳定版为例具体版本请根据你的实际环境调整。2.1 基础运行环境操作系统macOS 或 Linux 优先Windows 用户建议使用 WSL 2。Node.js建议 18 或更高版本Claude Code 和 Codex 官方 CLI 通常依赖 Node 环境。npm随 Node.js 一起安装用于全局安装 CLI 工具。Git技能脚本示例中需要读取 Git 提交记录。Python示例技能脚本使用 Python 3 编写建议 3.9 及以上版本。验证基础环境node -v npm -v git --version python3 --version如果命令能正常输出版本号说明基础环境没问题。2.2 安装 Claude CodeClaude Code 最常见的安装方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后查看版本号claude --version首次运行claude命令时工具会引导你完成身份验证。按照终端提示在浏览器中完成登录授权或者配置 API Key 即可。这里需要提醒一下Claude Code 功能迭代很快不同版本的配置方式可能有细微差别。遇到问题时优先查看官方文档不要照搬过时的教程。2.3 安装 Codex CLICodex CLI 的安装方式同样以官方文档为准。当前常见的 npm 安装命令是npm install -g openai/codex安装后验证codex --version首次运行时同样需要登录授权。Codex 会读取项目根目录下的AGENTS.md文件作为项目指令这一点在后面实战中会用到。2.4 安装 cc-switch 与 Ollama可选如果你希望在一台机器上管理多套 Claude Code / Codex 后端配置可以安装社区开源工具 cc-switch。它的作用是在多套 API Key、服务地址和模型名之间快速切换适合需要对比不同模型效果或使用本地模型的场景。安装方式参考其官方仓库说明通常提供命令行版本和桌面版本。如果你打算使用本地模型调试技能可以安装 Ollama。Ollama 可以在本地启动一个模型服务默认 API 地址是http://localhost:11434常用的代码模型可以这样拉取ollama pull qwen2.5-coder:7b然后启动服务ollama serve本地模型的好处是调试成本低、不消耗云端配额但也要注意小参数模型的指令理解能力有限复杂技能建议先用云端模型验证再在本地模型做兼容性测试。3. Agent Skills 核心机制拆解3.1 Skill 的目录结构与运行机制从文件层面看一个 Skill 就是一个目录。目录名就是技能名目录里包含描述文件、脚本和参考资料。一个典型的 Skill 目录结构skill-name/ ├── SKILL.md ├── scripts/ │ └── run.py ├── templates/ │ └── report_template.md └── reference/ └── docs.md各部分的职责如下SKILL.md技能说明书。这是 Agent 最先读取的文件包含技能的名称、描述、使用方式。scripts/可执行脚本。负责处理核心逻辑比如获取 Git 记录、扫描文件、生成报告。templates/模板文件。如果技能需要输出固定格式的内容可以在这里维护模板。reference/参考资料。当技能本身需要专业知识时可以把参考文档放在这里。Claude Code 默认读取用户级别的~/.claude/skills/目录也支持在项目根目录下创建.claude/skills/作为项目级技能目录。项目级技能适合放进代码仓库里随项目一起分发。3.2 SKILL.md 编写规范SKILL.md是技能能否被正确触发的关键。我建议至少包含以下部分YAML front matter定义技能元信息核心字段是name和description。技能目标用一段话说明这个技能解决什么问题。输入说明定义技能需要哪些输入参数。执行步骤告诉 Agent 按什么顺序执行。输出格式定义返回内容的格式要求。注意事项说明边界条件、前置依赖和风险操作。下面是一个最小可用的SKILL.md--- name: generate-report description: 根据 Git 提交记录生成周报适用于需要汇总开发成果、整理本周提交、编写工作汇报的场景。 --- # generate-report 根据当前 Git 仓库的提交记录生成一份 Markdown 格式的周报。 ## 输入 - 时间范围可选默认最近 7 天 - 仓库目录可选默认为当前目录 ## 执行步骤 1. 在目标仓库目录下执行 git log --since ... 获取提交记录。 2. 调用 scripts/generate_report.py 处理提交记录。 3. 将脚本输出整理为 Markdown 周报。 ## 输出格式 - 标题本周工作总结 - 统计信息提交数量、时间范围 - 明细表格提交号、作者、时间、提交说明 ## 注意事项 - 如果仓库没有提交记录需要提示用户。 - 脚本只读取 Git 提交信息不会修改仓库内容。注意description字段非常关键。Agent 判断“什么时候使用这个技能”主要就是靠这一段描述。写描述时要把可能触发该技能的用户意图都写进去比如“周报、总结、提交汇总、工作汇报”等关键词。3.3 Skill 的发现与执行流程Agent 使用技能的过程大致可以理解为用户提出任务 ↓ Agent 拆解任务判断是否需要技能 ↓ 扫描技能目录 → 读取 SKILL.md → 匹配 description ↓ 根据 SKILL.md 调用脚本/模板 ↓ 得到结果 → 整理成最终输出这个流程中最容易被忽视的是“匹配”这一步。如果SKILL.md的description写得太宽泛或者太抽象Agent 可能无法准确判断该在什么时候调用技能。因此描述要具体最好包含典型的使用场景和触发关键词。3.4 Skill 与普通提示词的区别对比维度普通提示词Skill复用性每次都要重新写文件封装按需调用可维护性难以版本管理可以测试和迭代自动化程度依赖用户引导Agent 自动发现和执行共享性复制文本以目录或仓库形式共享可编程性无法调用脚本可以执行任意脚本逻辑换句话说普通提示词解决的是“一次性的对话需求”Skill 解决的是“可重复执行的工程需求”。4. 实战案例一为 Claude Code 创建“周报生成”技能这一节我们完整实现一个“周报生成”技能。这个技能的逻辑很简单读取当前 Git 仓库最近七天的提交记录自动生成 Markdown 周报。4.1 需求分析技能的输入是“时间范围”输出是“周报 Markdown 内容”。需要完成的工作包括获取 Git 提交记录。解析提交的哈希值、作者、时间、提交说明。生成结构化的 Markdown 文档。这个技能在很多场景下都能复用比如每周写周报、项目阶段总结、个人工作汇报。4.2 创建技能目录与 SKILL.md在终端执行mkdir -p ~/.claude/skills/generate-report/scripts然后创建~/.claude/skills/generate-report/SKILL.md写入以下内容--- name: generate-report description: 根据 Git 提交记录自动生成周报。当用户需要写周报、汇总本周提交、整理开发成果、生成工作汇报时使用。 --- # generate-report 根据当前 Git 仓库的提交记录生成一份 Markdown 格式的周报。 ## 输入 - 时间范围可选默认最近 7 天 - 仓库目录可选默认为当前目录 ## 执行步骤 1. 在目标仓库目录下执行 git log --since ... 获取提交记录。 2. 调用 scripts/generate_report.py 处理提交记录。 3. 将脚本输出整理为 Markdown 周报。 ## 输出格式 - 标题本周工作总结 - 统计信息提交数量、时间范围 - 明细表格提交号、作者、时间、提交说明 ## 注意事项 - 如果仓库没有提交记录需要提示用户。 - 脚本只读取 Git 提交信息不会修改仓库内容。4.3 编写周报生成脚本接下来创建~/.claude/skills/generate-report/scripts/generate_report.py# 文件路径~/.claude/skills/generate-report/scripts/generate_report.py import subprocess import sys def get_git_log(since7 days ago): 获取指定时间范围内的 Git 提交记录 cmd [ git, log, --since, since, --prettyformat:%h|%an|%ad|%s, --dateformat:%Y-%m-%d %H:%M ] result subprocess.run( cmd, capture_outputTrue, textTrue, encodingutf-8 ) if result.returncode ! 0: raise RuntimeError(fgit log 执行失败: {result.stderr}) return result.stdout.strip().splitlines() def parse_log(lines): 解析 git log 的一行输出 commits [] for line in lines: if not line: continue parts line.split(|, 3) if len(parts) 4: commits.append({ hash: parts[0], author: parts[1], date: parts[2], message: parts[3] }) return commits def generate_report(commits): 生成 Markdown 格式的周报 if not commits: return 本周暂无提交记录。 lines [] lines.append(# 本周工作总结\n) lines.append(f- 提交数量{len(commits)}) lines.append(f- 时间范围{commits[-1][date]} 至 {commits[0][date]}\n) lines.append(| 提交号 | 作者 | 时间 | 提交说明 |) lines.append(| --- | --- | --- | --- |) for c in commits: safe_msg c[message].replace(|, \\|) lines.append( f| {c[hash]} | {c[author]} | {c[date]} | {safe_msg} | ) return \n.join(lines) if __name__ __main__: since sys.argv[1] if len(sys.argv) 1 else 7 days ago try: commits parse_log(get_git_log(since)) print(generate_report(commits)) except Exception as e: print(f生成周报失败{e}, filesys.stderr) sys.exit(1)这个脚本的核心逻辑分三步get_git_log负责执行git log命令把提交记录按哈希|作者|时间|说明的格式输出。parse_log负责把命令行输出解析成结构化字典列表。generate_report负责把字典列表渲染成 Markdown 表格。为了兼容中文提交信息脚本在调用subprocess时显式指定了encodingutf-8。如果你的仓库提交信息包含竖线字符脚本也会通过replace(|, \\|)做转义处理避免破坏 Markdown 表格结构。4.4 在 Claude Code 中验证技能进入一个真实的 Git 项目目录启动 Claude Codecd ~/your-project claude在对话中输入请帮我生成上周的周报如果技能被成功识别Claude Code 会加载generate-report技能的说明并调用scripts/generate_report.py获取结果。如果 Agent 没有自动触发可以显式指定技能名称请读取 generate-report 技能并执行它时间范围是最近 7 天4.5 运行结果说明脚本本身也可以脱离 Agent 单独运行。在项目目录下直接执行python3 ~/.claude/skills/generate-report/scripts/generate_report.py 7 days ago预期输出类似# 本周工作总结 - 提交数量6 - 时间范围2025-01-06 10:00 至 2025-01-12 18:30 | 提交号 | 作者 | 时间 | 提交说明 | | --- | --- | --- | --- | | a1b2c3d | zhangsan | 2025-01-12 18:30 | fix: 修复登录超时问题 | | e4f5g6h | lisi | 2025-01-11 15:20 | feat: 新增导出功能 | | ... | ... | ... | ... |在 Claude Code 中Agent 可能会对这个输出做进一步润色补充分类、总结或下一步建议但核心数据仍然来自技能脚本。这样周报的数据部分就变成了自动化产物你只需要在 Agent 输出的基础上做少量确认和调整即可。5. 实战案例二为 Codex 复用与扩展技能学会给 Claude Code 创建技能后我们看一个更通用的问题如何让同一个技能也能被 Codex 使用5.1 Codex 中的技能接入方式Claude Code 的技能目录是~/.claude/skills/而 Codex 的技能发现机制并不完全一样。Codex 更依赖项目级的指令文件AGENTS.md它会在项目启动时读取这个文件作为 Agent 的项目行为约定。我的建议是把技能脚本设计成“与工具无关”的命令行工具然后在AGENTS.md中告诉 Codex“什么时候调用哪个脚本”。这样同一个技能仓库既能被 Claude Code 加载也能被 Codex 通过AGENTS.md调用。5.2 创建“代码审计”技能我们创建一个“代码审计”技能它的作用是在指定代码目录中扫描TODO、FIXME、HACK等标记并输出统计结果。这个技能对代码审查、技术债清理、上线前检查非常实用。创建技能目录mkdir -p ~/.claude/skills/code-audit/scripts创建~/.claude/skills/code-audit/SKILL.md--- name: code-audit description: 对指定代码目录进行基础审计扫描 TODO、FIXME、HACK 标记统计文件分布适用于代码审查、清理技术债、上线前排查。 --- # code-audit 扫描指定目录中的源码文件查找 TODO、FIXME、HACK、XXX 等风险标记并生成审计报告。 ## 输入 - 待扫描目录可选默认为当前目录 ## 执行步骤 1. 调用 scripts/scan_todos.py 扫描源码目录。 2. 收集脚本输出的文件名、行号和风险标记。 3. 整理为 Markdown 审计报告按标记类型分类。 ## 输出格式 - 扫描统计文件数、标记总数 - 问题清单文件路径、行号、标记内容 - 处理建议对每条标记给出处理优先级 ## 注意事项 - 默认跳过 .git、node_modules、venv、__pycache__ 目录。 - 该技能只读扫描不修改任何文件。创建~/.claude/skills/code-audit/scripts/scan_todos.py# 文件路径~/.claude/skills/code-audit/scripts/scan_todos.py import os import sys def scan_file(path, patterns): 扫描单个文件中的风险标记 findings [] try: with open(path, r, encodingutf-8, errorsignore) as f: for line_no, line in enumerate(f, start1): for pattern in patterns: if pattern in line: findings.append((path, line_no, line.strip())) break except Exception as e: findings.append((path, -1, f读取失败: {e})) return findings def main(directory.): patterns [TODO, FIXME, HACK, XXX] all_findings [] file_count 0 for root, dirs, files in os.walk(directory): dirs[:] [ d for d in dirs if d not in {.git, node_modules, venv, __pycache__} ] for name in files: if name.endswith((.py, .js, .ts, .java, .go, .md, .sql)): path os.path.join(root, name) file_count 1 all_findings.extend(scan_file(path, patterns)) print(f扫描文件数{file_count}) print(f发现风险标记{len(all_findings)}\n) for path, line_no, text in all_findings[:50]: print(f{path}:{line_no}: {text}) if len(all_findings) 50: print(f\n... 还有 {len(all_findings) - 50} 条标记未展示。) if __name__ __main__: target sys.argv[1] if len(sys.argv) 1 else . main(target)这个脚本同样遵循“只读不写”原则只扫描文件内容并输出结果。对于没有权限读取的文件脚本会捕获异常并记录失败信息不会导致整个任务中断。5.3 通过 AGENTS.md 把技能暴露给 Codex在项目根目录创建AGENTS.md# 项目开发约定 ## 代码审计 当用户要求进行代码审计、扫描 TODO/FIXME、清理技术债、上线前代码检查时必须执行以下流程 1. 运行审计脚本 bash python3 ~/.claude/skills/code-audit/scripts/scan_todos.py .收集脚本输出。按标记类型输出 Markdown 审计报告并给出处理建议。技能完整说明位于~/.claude/skills/code-audit/SKILL.md。这样当你在该项目下启动 codex并输入“扫描一下这个项目的 TODO”时Codex 会读取 AGENTS.md发现代码审计的约定进而调用对应的 Python 脚本。 ### 5.4 使用 Ollama 与 cc-switch 进行本地调试 技能开发过程中频繁调用云端模型既慢又费配额。一个常见做法是先用本地模型验证脚本链路是否通畅再切回云端模型做最终验证。 具体思路是 1. 启动 Ollama 并拉取一个代码模型比如 qwen2.5-coder:7b。 2. 使用 cc-switch 新增一套本地配置将 API 地址指向http://localhost:11434/v13. 配置模型名并填写该后端要求的认证信息。本地服务通常不需要真实密钥但具体填写规则要以工具提示为准。 4. 切换到这套本地配置然后启动 Codex 或 Claude Code让 Agent 执行技能脚本。 本地模型的优势是网络开销小、隐私性好缺点是模型参数较小对复杂技能描述的理解能力不如云端大模型。如果你在本地模型下发现技能没有被正确触发先不要急着改技能结构可以先切回云端模型复现一次判断问题是出在模型理解还是技能本身。 ### 5.5 验证结果 在项目目录下启动 codex bash codex输入帮我做一次代码审计生成风险标记报告Codex 会读取AGENTS.md然后执行scan_todos.py。脚本输出会进入对话上下文Codex 再将其整理成有分类、有处理建议的审计报告。预期对话中会出现类似输出扫描文件数42 发现风险标记8 src/utils/auth.py:120: TODO: 需要补充 token 刷新逻辑 src/api/client.py:76: FIXME: 异常处理不完整 ...至此同一个技能脚本已经被 Claude Code 和 Codex 两个工具成功复用。核心经验是把技能拆成“描述文件 脚本”两部分再通过不同工具的目录或指令文件接入就能实现一套技能多处使用。6. 打造可复用、可扩展的技能体系当技能数量超过三个以后零散地把目录放在~/.claude/skills/里会变得难以维护。这时候就需要建立一个规范的技能仓库。6.1 用独立仓库管理技能建议创建一个独立的 Git 仓库来维护所有技能agent-skills/ ├── README.md ├── skills/ │ ├── generate-report/ │ ├── code-audit/ │ └── api-generator/ └── scripts/ └── install.shREADME.md可以说明仓库用途、技能列表、安装方法。install.sh负责把技能目录软链接到 Claude Code 的默认目录#!/bin/bash # 文件路径agent-skills/scripts/install.sh ln -sfn $(pwd)/skills/generate-report ~/.claude/skills/generate-report ln -sfn $(pwd)/skills/code-audit ~/.claude/skills/code-audit echo 技能安装完成使用软链接的好处是技能仓库可以继续用 Git 管理版本而 Claude Code 始终读取的是最新文件不需要每次改动后手动复制。6.2 参数化与模板化设计技能脚本要尽量避免硬编码路径和固定值。推荐通过命令行参数或环境变量传递输入值REPORT_OUTPUT_DIR./docs python3 scripts/generate_report.py 7 days ago在SKILL.md的执行步骤中也应该把参数说明清楚让 Agent 知道如何调用脚本、如何传入参数。对于输出格式固定的技能可以把模板文件放在templates/目录脚本只负责填充数据避免在代码中拼接大量 HTML 或 Markdown 片段。6.3 版本管理与团队共享技能本身也是代码建议遵循语义化版本管理v1.0.0稳定的初始版本。v1.1.0新增功能不影响已有调用方式。v2.0.0破坏性更新比如修改了脚本参数或输出格式。在技能目录中维护一个CHANGELOG.md记录每次变更的内容。团队共享时可以把技能仓库作为模板仓库分发也可以借助 Git 子模块或包管理工具同步到个人机器。6.4 技能自动化测试技能脚本建议编写简单的自动化测试。以周报脚本为例# 文件路径agent-skills/tests/test_generate_report.py import subprocess def test_generate_report(): output subprocess.run( [python3, skills/generate-report/scripts/generate_report.py, 1 day ago], capture_outputTrue, textTrue ) assert output.returncode 0 assert 本周工作总结 in output.stdout测试不仅可以验证脚本逻辑还能防止后续修改引入回归问题。当技能数量增加后可以进一步在 Git 仓库中接入 CI自动运行这些测试。7. 常见问题与排查思路实战过程中几乎每个开发者都会遇到下面几类问题。我整理了一份排查清单方便你对照处理。7.1 安装失败或没有权限问题现象常见原因解决思路npm 全局安装失败Node 版本过低、npm 源慢、权限不足升级 Node配置更快的 npm 镜像源使用 nvm 避免权限问题claude 命令找不到全局 bin 目录不在 PATH 中检查 npm 全局目录并加入 PATHcodex 命令找不到未正确安装或 PATH 未更新重新检查安装日志和全局目录7.2 登录与授权失败问题现象常见原因解决思路浏览器无法完成登录回调网络环境限制、回调端口被占用按官方文档检查回调方式更换网络环境后重试CLI 提示认证过期登录态过期重新执行登录流程确认账号权限403 或鉴权失败API Key 无效或额度不足核对 Key检查服务商控制台7.3 技能没有被 Agent 自动发现问题现象常见原因解决思路Agent 完全没有提到技能目录位置错误确认技能放在~/.claude/skills/或项目级.claude/skills/技能存在但未触发description不匹配用户意图把典型触发词都写进描述比如“周报”“总结”“汇报”技能名称冲突多个技能同名检查技能目录名保持唯一性7.4 技能脚本执行报错问题现象常见原因解决思路Python 模块找不到依赖未安装在 SKILL.md 中写明前置依赖必要时提供 requirements.txtgit log 命令失败当前目录不是 Git 仓库让 Agent 先确认仓库路径再调用脚本中文乱码编码未指定在脚本中显式使用encodingutf-8打开文件执行超时扫描目录过大在脚本中限制扫描范围跳过node_modules等大目录7.5 cc-switch 切换后 Codex 请求失败问题现象常见原因解决思路切换配置后 Codex 请求报错提示处理 Codex endpoint /responses 时本地服务地址连接失败配置中的服务地址不可达先访问健康检查接口确认服务可通请求返回模型不存在模型名填写错误核对后端实际提供的模型名称一直鉴权失败认证信息与后端不匹配检查 API Key 或登录态必要时重新登录这里的通用排查顺序是先确认服务启动状态再确认地址和端口最后核对模型名和认证信息。不要一上来就重装工具多数情况下是配置项的问题。7.6 技能输出格式不理想问题现象常见原因解决思路输出内容松散SKILL.md没有定义输出格式在描述文件中增加“输出格式”章节给出示例数据正确但排版混乱Agent 自由发挥过度明确要求“按脚本输出原样展示不要额外重构”漏掉部分数据脚本输出被截断分页输出或要求 Agent 将完整输出写入文件8. 最佳实践与工程建议技术方案跑通只是第一步真正重要的是把它做成一套可长期维护的工程体系。这里分享一些我在实践中沉淀下来的建议。8.1 从“写提示词”到“写技能”的思维升级普通提示词关注的是“这一次对话怎么回答”技能关注的是“这一类任务怎么执行”。判断一个任务是否适合做成技能可以问自己三个问题这个任务我是否每周都会重复做输入和输出是否明确是否可以通过脚本自动化一部分工作如果三个答案都是“是”那它就值得做成一个 Skill。8.2 技能质量评估标准一个高质量的技能应该满足以下几点可发现性description写的足够清楚Agent 能在正确时机找到它。可执行性脚本在干净环境中能直接运行不依赖本机私有配置。可维护性代码结构清晰参数不写死输出格式稳定。安全性脚本默认只读危险操作需要人工确认。8.3 安全边界与最小权限原则Agent 技能比普通提示词拥有更强的执行力因此安全问题必须提前考虑技能脚本默认应该只做“读”操作不做“写”和“删”。如果任务确实需要修改文件或执行远程命令必须在SKILL.md中注明“需要人工确认”不要写在自动执行链路里。API Key、Token 等敏感信息通过环境变量注入不要写死到SKILL.md或技能脚本里。在技能上线前先在测试仓库中跑一遍确认不会影响生产环境。如果涉及生产环境变更务必遵守更严格的流程先在测试环境验证、做好备份、遵循最小权限原则避免造成不可逆影响。8.4 团队协作与文档化技能本身就应该是“自文档化”的。SKILL.md不仅给 Agent 看也应该给团队成员看。推荐约定统一的技能命名规范比如“动词-对象”形式generate-reportcode-audittest-generatorrelease-notes命名统一后团队成员可以通过ls ~/.claude/skills/快速了解已有哪些能力避免重复建设。9. 总结与下一步学习路线这篇文章从一个很具体的痛点出发AI 能回答问题但难以自动完成任务。解决问题的路径是学习 Agent Skills把可复用的任务封装成“描述文件 脚本”的技能包再接入 Claude Code 和 Codex 这两个主流工具。在实战部分我们完成了两个技能一个是从 Git 提交记录生成周报一个是扫描代码中的风险标记。这两个技能虽然简单但完整覆盖了环境准备、目录结构、描述文件编写、脚本实现、Agent 调用、跨工具复用和本地调试的整套流程。如果你想从这篇文章带走一个行动项我的建议是挑一个你每周都要花 30 分钟以上重复做的事情把它做成你的第一个 Skill然后让 Claude Code 或 Codex 帮你自动跑一遍。跑通之后你才会真正感受到“会用 AI”和“会开发 Agent”之间的差别。下一步可以继续研究 MCP模型上下文协议让 Agent 技能可以连接外部数据库、API 和文件系统也可以学习多 Agent 协作把复杂任务拆给多个技能分工完成。但无论往哪个方向发展先把基础技能做扎实建立自己的技能仓库都是最值得投入的第一步。如果本文对你有帮助可以收藏备用。技能开发过程中遇到的具体报错和排查经验也欢迎在评论区一起交流。 AI编程进阶：用Claude Code与Codex开发Agent Skills实战教程
过去半年我和身边不少开发者都在尝试用 AI 辅助日常开发。最先感受到的变化是AI 确实能写代码、能查资料、能解释报错。但真到需要它独立完成一条完整任务链时比如把最近的 Git 提交整理成周报、把项目里的技术债标记全部扫出来并生成报告很多 AI 工具就会暴露出一个共性短板——它只会“回答”不会“干活”。如果你也有这种感受那说明你已经从“会用 AI”的阶段走到了该学习“开发 Agent”的阶段。这篇文章我打算完整拆解 Agent Skills 的概念、结构、实战用法并基于 Claude Code 和 Codex 两个工具带你从零打造一套可复用、可扩展的智能体技能体系。无论你是刚接触 AI 编程工具的初学者还是已经用了一段时间想进一步提效的开发者这篇文章都可以当作一份系统化教程来读。1. 背景与核心概念Agent 与 Agent Skills1.1 从“对话式 AI”到“可执行任务的 Agent”先理清一个容易混淆的概念普通聊天 AI 和 Agent 有什么区别普通聊天 AI 的核心能力是“生成内容”。你问它一个问题它给你一个答案。这个答案可能是代码、可能是文字、可能是表格但 AI 本身不会主动去执行命令、读写文件、运行脚本、根据结果继续调整方案。Agent 的核心能力是“完成任务”。它会把一个大目标拆解成多个子步骤然后通过调用工具逐步执行。比如你让 Agent“生成一份项目周报”它需要先读取 Git 日志、分析提交信息、整理成表格、再输出 Markdown 文件。这中间涉及命令执行、数据处理、文件写入等多个环节每一步都需要有对应的能力支撑。而 Agent Skills 就是支撑 Agent 完成具体任务的能力模块。你可以把它理解成 Agent 的“工具箱”或者“插件集”。1.2 什么是 Agent SkillsAgent Skills 是一个文件目录里面包含两部分核心内容技能描述文件告诉 Agent“这个技能是干什么的、什么时候该用、怎么用”。执行资源脚本、模板、参考文档等真正负责完成具体工作。以 Claude Code 为例官方推荐的技能目录结构大致如下~/.claude/skills/ ├── generate-report/ │ ├── SKILL.md │ └── scripts/ │ └── generate_report.py ├── code-audit/ │ ├── SKILL.md │ └── scripts/ │ └── scan_todos.py当 Agent 接收到用户的任务后会扫描技能目录里的描述文件。如果发现某个技能的描述与当前任务匹配就会读取该技能的完整说明并按照说明调用脚本、读取模板最终完成任务。这个过程最大的价值在于技能是可复用的。你不用每次都在对话里重复写一长串提示词只要在需求触发时让 Agent 自动加载对应技能即可。1.3 为什么选择 Claude Code 与 CodexClaude Code 是 Anthropic 推出的命令行 AI 编程工具它运行在终端里能够理解整个代码仓库的结构可以读取文件、执行命令行操作、修改代码并且支持通过技能目录扩展能力。Codex 是 OpenAI 推出的 CLI 编程工具同样定位在终端环境侧重自然语言驱动的编码任务。它支持项目级的指令文件可以约定项目中 Agent 的行为方式。选择这两个工具作为切入点一方面是因为它们在 AI 编程领域关注度较高、社区活跃另一方面是因为它们都具备“Agent 化”的扩展机制非常适合用来演示 Agent Skills 的完整开发流程。学习过程中你还会接触到一些周边工具比如 cc-switch、Ollama 等我会在后面结合实战场景说明。2. 环境准备与版本说明在开始写第一个 Skill 之前需要先把基础环境准备好。下面的版本信息以当前常见稳定版为例具体版本请根据你的实际环境调整。2.1 基础运行环境操作系统macOS 或 Linux 优先Windows 用户建议使用 WSL 2。Node.js建议 18 或更高版本Claude Code 和 Codex 官方 CLI 通常依赖 Node 环境。npm随 Node.js 一起安装用于全局安装 CLI 工具。Git技能脚本示例中需要读取 Git 提交记录。Python示例技能脚本使用 Python 3 编写建议 3.9 及以上版本。验证基础环境node -v npm -v git --version python3 --version如果命令能正常输出版本号说明基础环境没问题。2.2 安装 Claude CodeClaude Code 最常见的安装方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后查看版本号claude --version首次运行claude命令时工具会引导你完成身份验证。按照终端提示在浏览器中完成登录授权或者配置 API Key 即可。这里需要提醒一下Claude Code 功能迭代很快不同版本的配置方式可能有细微差别。遇到问题时优先查看官方文档不要照搬过时的教程。2.3 安装 Codex CLICodex CLI 的安装方式同样以官方文档为准。当前常见的 npm 安装命令是npm install -g openai/codex安装后验证codex --version首次运行时同样需要登录授权。Codex 会读取项目根目录下的AGENTS.md文件作为项目指令这一点在后面实战中会用到。2.4 安装 cc-switch 与 Ollama可选如果你希望在一台机器上管理多套 Claude Code / Codex 后端配置可以安装社区开源工具 cc-switch。它的作用是在多套 API Key、服务地址和模型名之间快速切换适合需要对比不同模型效果或使用本地模型的场景。安装方式参考其官方仓库说明通常提供命令行版本和桌面版本。如果你打算使用本地模型调试技能可以安装 Ollama。Ollama 可以在本地启动一个模型服务默认 API 地址是http://localhost:11434常用的代码模型可以这样拉取ollama pull qwen2.5-coder:7b然后启动服务ollama serve本地模型的好处是调试成本低、不消耗云端配额但也要注意小参数模型的指令理解能力有限复杂技能建议先用云端模型验证再在本地模型做兼容性测试。3. Agent Skills 核心机制拆解3.1 Skill 的目录结构与运行机制从文件层面看一个 Skill 就是一个目录。目录名就是技能名目录里包含描述文件、脚本和参考资料。一个典型的 Skill 目录结构skill-name/ ├── SKILL.md ├── scripts/ │ └── run.py ├── templates/ │ └── report_template.md └── reference/ └── docs.md各部分的职责如下SKILL.md技能说明书。这是 Agent 最先读取的文件包含技能的名称、描述、使用方式。scripts/可执行脚本。负责处理核心逻辑比如获取 Git 记录、扫描文件、生成报告。templates/模板文件。如果技能需要输出固定格式的内容可以在这里维护模板。reference/参考资料。当技能本身需要专业知识时可以把参考文档放在这里。Claude Code 默认读取用户级别的~/.claude/skills/目录也支持在项目根目录下创建.claude/skills/作为项目级技能目录。项目级技能适合放进代码仓库里随项目一起分发。3.2 SKILL.md 编写规范SKILL.md是技能能否被正确触发的关键。我建议至少包含以下部分YAML front matter定义技能元信息核心字段是name和description。技能目标用一段话说明这个技能解决什么问题。输入说明定义技能需要哪些输入参数。执行步骤告诉 Agent 按什么顺序执行。输出格式定义返回内容的格式要求。注意事项说明边界条件、前置依赖和风险操作。下面是一个最小可用的SKILL.md--- name: generate-report description: 根据 Git 提交记录生成周报适用于需要汇总开发成果、整理本周提交、编写工作汇报的场景。 --- # generate-report 根据当前 Git 仓库的提交记录生成一份 Markdown 格式的周报。 ## 输入 - 时间范围可选默认最近 7 天 - 仓库目录可选默认为当前目录 ## 执行步骤 1. 在目标仓库目录下执行 git log --since ... 获取提交记录。 2. 调用 scripts/generate_report.py 处理提交记录。 3. 将脚本输出整理为 Markdown 周报。 ## 输出格式 - 标题本周工作总结 - 统计信息提交数量、时间范围 - 明细表格提交号、作者、时间、提交说明 ## 注意事项 - 如果仓库没有提交记录需要提示用户。 - 脚本只读取 Git 提交信息不会修改仓库内容。注意description字段非常关键。Agent 判断“什么时候使用这个技能”主要就是靠这一段描述。写描述时要把可能触发该技能的用户意图都写进去比如“周报、总结、提交汇总、工作汇报”等关键词。3.3 Skill 的发现与执行流程Agent 使用技能的过程大致可以理解为用户提出任务 ↓ Agent 拆解任务判断是否需要技能 ↓ 扫描技能目录 → 读取 SKILL.md → 匹配 description ↓ 根据 SKILL.md 调用脚本/模板 ↓ 得到结果 → 整理成最终输出这个流程中最容易被忽视的是“匹配”这一步。如果SKILL.md的description写得太宽泛或者太抽象Agent 可能无法准确判断该在什么时候调用技能。因此描述要具体最好包含典型的使用场景和触发关键词。3.4 Skill 与普通提示词的区别对比维度普通提示词Skill复用性每次都要重新写文件封装按需调用可维护性难以版本管理可以测试和迭代自动化程度依赖用户引导Agent 自动发现和执行共享性复制文本以目录或仓库形式共享可编程性无法调用脚本可以执行任意脚本逻辑换句话说普通提示词解决的是“一次性的对话需求”Skill 解决的是“可重复执行的工程需求”。4. 实战案例一为 Claude Code 创建“周报生成”技能这一节我们完整实现一个“周报生成”技能。这个技能的逻辑很简单读取当前 Git 仓库最近七天的提交记录自动生成 Markdown 周报。4.1 需求分析技能的输入是“时间范围”输出是“周报 Markdown 内容”。需要完成的工作包括获取 Git 提交记录。解析提交的哈希值、作者、时间、提交说明。生成结构化的 Markdown 文档。这个技能在很多场景下都能复用比如每周写周报、项目阶段总结、个人工作汇报。4.2 创建技能目录与 SKILL.md在终端执行mkdir -p ~/.claude/skills/generate-report/scripts然后创建~/.claude/skills/generate-report/SKILL.md写入以下内容--- name: generate-report description: 根据 Git 提交记录自动生成周报。当用户需要写周报、汇总本周提交、整理开发成果、生成工作汇报时使用。 --- # generate-report 根据当前 Git 仓库的提交记录生成一份 Markdown 格式的周报。 ## 输入 - 时间范围可选默认最近 7 天 - 仓库目录可选默认为当前目录 ## 执行步骤 1. 在目标仓库目录下执行 git log --since ... 获取提交记录。 2. 调用 scripts/generate_report.py 处理提交记录。 3. 将脚本输出整理为 Markdown 周报。 ## 输出格式 - 标题本周工作总结 - 统计信息提交数量、时间范围 - 明细表格提交号、作者、时间、提交说明 ## 注意事项 - 如果仓库没有提交记录需要提示用户。 - 脚本只读取 Git 提交信息不会修改仓库内容。4.3 编写周报生成脚本接下来创建~/.claude/skills/generate-report/scripts/generate_report.py# 文件路径~/.claude/skills/generate-report/scripts/generate_report.py import subprocess import sys def get_git_log(since7 days ago): 获取指定时间范围内的 Git 提交记录 cmd [ git, log, --since, since, --prettyformat:%h|%an|%ad|%s, --dateformat:%Y-%m-%d %H:%M ] result subprocess.run( cmd, capture_outputTrue, textTrue, encodingutf-8 ) if result.returncode ! 0: raise RuntimeError(fgit log 执行失败: {result.stderr}) return result.stdout.strip().splitlines() def parse_log(lines): 解析 git log 的一行输出 commits [] for line in lines: if not line: continue parts line.split(|, 3) if len(parts) 4: commits.append({ hash: parts[0], author: parts[1], date: parts[2], message: parts[3] }) return commits def generate_report(commits): 生成 Markdown 格式的周报 if not commits: return 本周暂无提交记录。 lines [] lines.append(# 本周工作总结\n) lines.append(f- 提交数量{len(commits)}) lines.append(f- 时间范围{commits[-1][date]} 至 {commits[0][date]}\n) lines.append(| 提交号 | 作者 | 时间 | 提交说明 |) lines.append(| --- | --- | --- | --- |) for c in commits: safe_msg c[message].replace(|, \\|) lines.append( f| {c[hash]} | {c[author]} | {c[date]} | {safe_msg} | ) return \n.join(lines) if __name__ __main__: since sys.argv[1] if len(sys.argv) 1 else 7 days ago try: commits parse_log(get_git_log(since)) print(generate_report(commits)) except Exception as e: print(f生成周报失败{e}, filesys.stderr) sys.exit(1)这个脚本的核心逻辑分三步get_git_log负责执行git log命令把提交记录按哈希|作者|时间|说明的格式输出。parse_log负责把命令行输出解析成结构化字典列表。generate_report负责把字典列表渲染成 Markdown 表格。为了兼容中文提交信息脚本在调用subprocess时显式指定了encodingutf-8。如果你的仓库提交信息包含竖线字符脚本也会通过replace(|, \\|)做转义处理避免破坏 Markdown 表格结构。4.4 在 Claude Code 中验证技能进入一个真实的 Git 项目目录启动 Claude Codecd ~/your-project claude在对话中输入请帮我生成上周的周报如果技能被成功识别Claude Code 会加载generate-report技能的说明并调用scripts/generate_report.py获取结果。如果 Agent 没有自动触发可以显式指定技能名称请读取 generate-report 技能并执行它时间范围是最近 7 天4.5 运行结果说明脚本本身也可以脱离 Agent 单独运行。在项目目录下直接执行python3 ~/.claude/skills/generate-report/scripts/generate_report.py 7 days ago预期输出类似# 本周工作总结 - 提交数量6 - 时间范围2025-01-06 10:00 至 2025-01-12 18:30 | 提交号 | 作者 | 时间 | 提交说明 | | --- | --- | --- | --- | | a1b2c3d | zhangsan | 2025-01-12 18:30 | fix: 修复登录超时问题 | | e4f5g6h | lisi | 2025-01-11 15:20 | feat: 新增导出功能 | | ... | ... | ... | ... |在 Claude Code 中Agent 可能会对这个输出做进一步润色补充分类、总结或下一步建议但核心数据仍然来自技能脚本。这样周报的数据部分就变成了自动化产物你只需要在 Agent 输出的基础上做少量确认和调整即可。5. 实战案例二为 Codex 复用与扩展技能学会给 Claude Code 创建技能后我们看一个更通用的问题如何让同一个技能也能被 Codex 使用5.1 Codex 中的技能接入方式Claude Code 的技能目录是~/.claude/skills/而 Codex 的技能发现机制并不完全一样。Codex 更依赖项目级的指令文件AGENTS.md它会在项目启动时读取这个文件作为 Agent 的项目行为约定。我的建议是把技能脚本设计成“与工具无关”的命令行工具然后在AGENTS.md中告诉 Codex“什么时候调用哪个脚本”。这样同一个技能仓库既能被 Claude Code 加载也能被 Codex 通过AGENTS.md调用。5.2 创建“代码审计”技能我们创建一个“代码审计”技能它的作用是在指定代码目录中扫描TODO、FIXME、HACK等标记并输出统计结果。这个技能对代码审查、技术债清理、上线前检查非常实用。创建技能目录mkdir -p ~/.claude/skills/code-audit/scripts创建~/.claude/skills/code-audit/SKILL.md--- name: code-audit description: 对指定代码目录进行基础审计扫描 TODO、FIXME、HACK 标记统计文件分布适用于代码审查、清理技术债、上线前排查。 --- # code-audit 扫描指定目录中的源码文件查找 TODO、FIXME、HACK、XXX 等风险标记并生成审计报告。 ## 输入 - 待扫描目录可选默认为当前目录 ## 执行步骤 1. 调用 scripts/scan_todos.py 扫描源码目录。 2. 收集脚本输出的文件名、行号和风险标记。 3. 整理为 Markdown 审计报告按标记类型分类。 ## 输出格式 - 扫描统计文件数、标记总数 - 问题清单文件路径、行号、标记内容 - 处理建议对每条标记给出处理优先级 ## 注意事项 - 默认跳过 .git、node_modules、venv、__pycache__ 目录。 - 该技能只读扫描不修改任何文件。创建~/.claude/skills/code-audit/scripts/scan_todos.py# 文件路径~/.claude/skills/code-audit/scripts/scan_todos.py import os import sys def scan_file(path, patterns): 扫描单个文件中的风险标记 findings [] try: with open(path, r, encodingutf-8, errorsignore) as f: for line_no, line in enumerate(f, start1): for pattern in patterns: if pattern in line: findings.append((path, line_no, line.strip())) break except Exception as e: findings.append((path, -1, f读取失败: {e})) return findings def main(directory.): patterns [TODO, FIXME, HACK, XXX] all_findings [] file_count 0 for root, dirs, files in os.walk(directory): dirs[:] [ d for d in dirs if d not in {.git, node_modules, venv, __pycache__} ] for name in files: if name.endswith((.py, .js, .ts, .java, .go, .md, .sql)): path os.path.join(root, name) file_count 1 all_findings.extend(scan_file(path, patterns)) print(f扫描文件数{file_count}) print(f发现风险标记{len(all_findings)}\n) for path, line_no, text in all_findings[:50]: print(f{path}:{line_no}: {text}) if len(all_findings) 50: print(f\n... 还有 {len(all_findings) - 50} 条标记未展示。) if __name__ __main__: target sys.argv[1] if len(sys.argv) 1 else . main(target)这个脚本同样遵循“只读不写”原则只扫描文件内容并输出结果。对于没有权限读取的文件脚本会捕获异常并记录失败信息不会导致整个任务中断。5.3 通过 AGENTS.md 把技能暴露给 Codex在项目根目录创建AGENTS.md# 项目开发约定 ## 代码审计 当用户要求进行代码审计、扫描 TODO/FIXME、清理技术债、上线前代码检查时必须执行以下流程 1. 运行审计脚本 bash python3 ~/.claude/skills/code-audit/scripts/scan_todos.py .收集脚本输出。按标记类型输出 Markdown 审计报告并给出处理建议。技能完整说明位于~/.claude/skills/code-audit/SKILL.md。这样当你在该项目下启动 codex并输入“扫描一下这个项目的 TODO”时Codex 会读取 AGENTS.md发现代码审计的约定进而调用对应的 Python 脚本。 ### 5.4 使用 Ollama 与 cc-switch 进行本地调试 技能开发过程中频繁调用云端模型既慢又费配额。一个常见做法是先用本地模型验证脚本链路是否通畅再切回云端模型做最终验证。 具体思路是 1. 启动 Ollama 并拉取一个代码模型比如 qwen2.5-coder:7b。 2. 使用 cc-switch 新增一套本地配置将 API 地址指向http://localhost:11434/v13. 配置模型名并填写该后端要求的认证信息。本地服务通常不需要真实密钥但具体填写规则要以工具提示为准。 4. 切换到这套本地配置然后启动 Codex 或 Claude Code让 Agent 执行技能脚本。 本地模型的优势是网络开销小、隐私性好缺点是模型参数较小对复杂技能描述的理解能力不如云端大模型。如果你在本地模型下发现技能没有被正确触发先不要急着改技能结构可以先切回云端模型复现一次判断问题是出在模型理解还是技能本身。 ### 5.5 验证结果 在项目目录下启动 codex bash codex输入帮我做一次代码审计生成风险标记报告Codex 会读取AGENTS.md然后执行scan_todos.py。脚本输出会进入对话上下文Codex 再将其整理成有分类、有处理建议的审计报告。预期对话中会出现类似输出扫描文件数42 发现风险标记8 src/utils/auth.py:120: TODO: 需要补充 token 刷新逻辑 src/api/client.py:76: FIXME: 异常处理不完整 ...至此同一个技能脚本已经被 Claude Code 和 Codex 两个工具成功复用。核心经验是把技能拆成“描述文件 脚本”两部分再通过不同工具的目录或指令文件接入就能实现一套技能多处使用。6. 打造可复用、可扩展的技能体系当技能数量超过三个以后零散地把目录放在~/.claude/skills/里会变得难以维护。这时候就需要建立一个规范的技能仓库。6.1 用独立仓库管理技能建议创建一个独立的 Git 仓库来维护所有技能agent-skills/ ├── README.md ├── skills/ │ ├── generate-report/ │ ├── code-audit/ │ └── api-generator/ └── scripts/ └── install.shREADME.md可以说明仓库用途、技能列表、安装方法。install.sh负责把技能目录软链接到 Claude Code 的默认目录#!/bin/bash # 文件路径agent-skills/scripts/install.sh ln -sfn $(pwd)/skills/generate-report ~/.claude/skills/generate-report ln -sfn $(pwd)/skills/code-audit ~/.claude/skills/code-audit echo 技能安装完成使用软链接的好处是技能仓库可以继续用 Git 管理版本而 Claude Code 始终读取的是最新文件不需要每次改动后手动复制。6.2 参数化与模板化设计技能脚本要尽量避免硬编码路径和固定值。推荐通过命令行参数或环境变量传递输入值REPORT_OUTPUT_DIR./docs python3 scripts/generate_report.py 7 days ago在SKILL.md的执行步骤中也应该把参数说明清楚让 Agent 知道如何调用脚本、如何传入参数。对于输出格式固定的技能可以把模板文件放在templates/目录脚本只负责填充数据避免在代码中拼接大量 HTML 或 Markdown 片段。6.3 版本管理与团队共享技能本身也是代码建议遵循语义化版本管理v1.0.0稳定的初始版本。v1.1.0新增功能不影响已有调用方式。v2.0.0破坏性更新比如修改了脚本参数或输出格式。在技能目录中维护一个CHANGELOG.md记录每次变更的内容。团队共享时可以把技能仓库作为模板仓库分发也可以借助 Git 子模块或包管理工具同步到个人机器。6.4 技能自动化测试技能脚本建议编写简单的自动化测试。以周报脚本为例# 文件路径agent-skills/tests/test_generate_report.py import subprocess def test_generate_report(): output subprocess.run( [python3, skills/generate-report/scripts/generate_report.py, 1 day ago], capture_outputTrue, textTrue ) assert output.returncode 0 assert 本周工作总结 in output.stdout测试不仅可以验证脚本逻辑还能防止后续修改引入回归问题。当技能数量增加后可以进一步在 Git 仓库中接入 CI自动运行这些测试。7. 常见问题与排查思路实战过程中几乎每个开发者都会遇到下面几类问题。我整理了一份排查清单方便你对照处理。7.1 安装失败或没有权限问题现象常见原因解决思路npm 全局安装失败Node 版本过低、npm 源慢、权限不足升级 Node配置更快的 npm 镜像源使用 nvm 避免权限问题claude 命令找不到全局 bin 目录不在 PATH 中检查 npm 全局目录并加入 PATHcodex 命令找不到未正确安装或 PATH 未更新重新检查安装日志和全局目录7.2 登录与授权失败问题现象常见原因解决思路浏览器无法完成登录回调网络环境限制、回调端口被占用按官方文档检查回调方式更换网络环境后重试CLI 提示认证过期登录态过期重新执行登录流程确认账号权限403 或鉴权失败API Key 无效或额度不足核对 Key检查服务商控制台7.3 技能没有被 Agent 自动发现问题现象常见原因解决思路Agent 完全没有提到技能目录位置错误确认技能放在~/.claude/skills/或项目级.claude/skills/技能存在但未触发description不匹配用户意图把典型触发词都写进描述比如“周报”“总结”“汇报”技能名称冲突多个技能同名检查技能目录名保持唯一性7.4 技能脚本执行报错问题现象常见原因解决思路Python 模块找不到依赖未安装在 SKILL.md 中写明前置依赖必要时提供 requirements.txtgit log 命令失败当前目录不是 Git 仓库让 Agent 先确认仓库路径再调用脚本中文乱码编码未指定在脚本中显式使用encodingutf-8打开文件执行超时扫描目录过大在脚本中限制扫描范围跳过node_modules等大目录7.5 cc-switch 切换后 Codex 请求失败问题现象常见原因解决思路切换配置后 Codex 请求报错提示处理 Codex endpoint /responses 时本地服务地址连接失败配置中的服务地址不可达先访问健康检查接口确认服务可通请求返回模型不存在模型名填写错误核对后端实际提供的模型名称一直鉴权失败认证信息与后端不匹配检查 API Key 或登录态必要时重新登录这里的通用排查顺序是先确认服务启动状态再确认地址和端口最后核对模型名和认证信息。不要一上来就重装工具多数情况下是配置项的问题。7.6 技能输出格式不理想问题现象常见原因解决思路输出内容松散SKILL.md没有定义输出格式在描述文件中增加“输出格式”章节给出示例数据正确但排版混乱Agent 自由发挥过度明确要求“按脚本输出原样展示不要额外重构”漏掉部分数据脚本输出被截断分页输出或要求 Agent 将完整输出写入文件8. 最佳实践与工程建议技术方案跑通只是第一步真正重要的是把它做成一套可长期维护的工程体系。这里分享一些我在实践中沉淀下来的建议。8.1 从“写提示词”到“写技能”的思维升级普通提示词关注的是“这一次对话怎么回答”技能关注的是“这一类任务怎么执行”。判断一个任务是否适合做成技能可以问自己三个问题这个任务我是否每周都会重复做输入和输出是否明确是否可以通过脚本自动化一部分工作如果三个答案都是“是”那它就值得做成一个 Skill。8.2 技能质量评估标准一个高质量的技能应该满足以下几点可发现性description写的足够清楚Agent 能在正确时机找到它。可执行性脚本在干净环境中能直接运行不依赖本机私有配置。可维护性代码结构清晰参数不写死输出格式稳定。安全性脚本默认只读危险操作需要人工确认。8.3 安全边界与最小权限原则Agent 技能比普通提示词拥有更强的执行力因此安全问题必须提前考虑技能脚本默认应该只做“读”操作不做“写”和“删”。如果任务确实需要修改文件或执行远程命令必须在SKILL.md中注明“需要人工确认”不要写在自动执行链路里。API Key、Token 等敏感信息通过环境变量注入不要写死到SKILL.md或技能脚本里。在技能上线前先在测试仓库中跑一遍确认不会影响生产环境。如果涉及生产环境变更务必遵守更严格的流程先在测试环境验证、做好备份、遵循最小权限原则避免造成不可逆影响。8.4 团队协作与文档化技能本身就应该是“自文档化”的。SKILL.md不仅给 Agent 看也应该给团队成员看。推荐约定统一的技能命名规范比如“动词-对象”形式generate-reportcode-audittest-generatorrelease-notes命名统一后团队成员可以通过ls ~/.claude/skills/快速了解已有哪些能力避免重复建设。9. 总结与下一步学习路线这篇文章从一个很具体的痛点出发AI 能回答问题但难以自动完成任务。解决问题的路径是学习 Agent Skills把可复用的任务封装成“描述文件 脚本”的技能包再接入 Claude Code 和 Codex 这两个主流工具。在实战部分我们完成了两个技能一个是从 Git 提交记录生成周报一个是扫描代码中的风险标记。这两个技能虽然简单但完整覆盖了环境准备、目录结构、描述文件编写、脚本实现、Agent 调用、跨工具复用和本地调试的整套流程。如果你想从这篇文章带走一个行动项我的建议是挑一个你每周都要花 30 分钟以上重复做的事情把它做成你的第一个 Skill然后让 Claude Code 或 Codex 帮你自动跑一遍。跑通之后你才会真正感受到“会用 AI”和“会开发 Agent”之间的差别。下一步可以继续研究 MCP模型上下文协议让 Agent 技能可以连接外部数据库、API 和文件系统也可以学习多 Agent 协作把复杂任务拆给多个技能分工完成。但无论往哪个方向发展先把基础技能做扎实建立自己的技能仓库都是最值得投入的第一步。如果本文对你有帮助可以收藏备用。技能开发过程中遇到的具体报错和排查经验也欢迎在评论区一起交流。