第一章核心概念与架构设计在开始配置之前理解Claude Code的设计哲学至关重要。它并非简单的代码补全工具而是一个基于终端的协作式AI代理。Skills技能则是将AI从“对话伙伴”转变为“自动化工程师”的关键。1.1 什么是 Claude Code SkillsClaude Code Skills 是一套结构化、可复用、可共享的能力定义。它不同于一次性的对话提示Prompt而是一种持久化的“知识封装”。从提示到能力传统的提示是 ephemeral短暂的每次都需要重新描述。Skills 将特定的工作流如“代码审查”、“TDD开发”固化为一个 Claude 可以随时调用的能力。可执行性高级 Skills 不仅能提供建议还能通过调用脚本如 Node.js、Python、Shell在本地环境真实地执行任务例如运行 FFmpeg 命令处理视频、启动测试套件或部署应用。渐进式加载这是 Skills 的核心性能设计。Claude 启动时只会读取每个 Skill 目录下skill.md文件中的元数据名称和描述。只有当你的请求与该技能意图匹配时Claude 才会加载该技能的完整指令和相关资源从而极大地节省了宝贵的上下文窗口Context Window。1.2 Skills 在 Claude Code 生态系统中的位置Claude Code 的功能由多层次配置构成理解它们之间的关系有助于你更好地组织工作流组件作用与特点存储位置示例调用/生效方式核心代理 (Core Agent)Claude 本身的基础能力。内置自然语言对话系统规则 (Rules)始终生效的全局约束如代码风格、安全规范。~/.claude/rules/或项目级.claude/rules/自动所有会话生效项目指南 (CLAUDE.md)项目级别的“README for Claude”包含命令、架构、约定。项目根目录./CLAUDE.md进入项目目录时自动加载钩子 (Hooks)在特定事件如工具调用前后自动执行的脚本用于安全检查或自动化准备。配置在~/.claude/settings.json中事件触发时自动执行斜杠命令 (Commands)手动触发特定工作流的快捷方式通常是对复杂 Skills 的封装。~/.claude/commands/用户在会话中输入/command子代理 (Sub-agents)为特定任务如架构师、代码审查员预设的、拥有独立指令的代理模式。~/.claude/agents/通过命令或 Skill 委派MCP 服务器让 Claude 能够与外部世界浏览器、数据库、API交互的协议服务器。配置在~/.claude.json或项目.mcp.json由 Claude 在需要时调用对应工具第二章环境搭建与基础配置2.1 安装与初步设置安装 Claude Code遵循 Anthropic 官方指南在你的终端中安装并授权 Claude Code。配置文件结构Claude Code 的配置主要存放在~/.claude/目录下。推荐使用版本控制系统如 Git来管理你的个人配置以便追踪变更和回滚。bashmkdir -p ~/.claude/{skills,agents,commands,rules}2.2 核心配置文件settings.json~/.claude/settings.json是 Claude Code 的行为总控开关。一个经过优化的配置可以大幅提升安全性和可用性。json{ // 建议开启 JSON Schema 支持获得编辑器的自动补全和校验 $schema: https://configuration.claude.ai/settings/schema.json, // 环境变量配置隐私与实验功能 env: { // 隐私设置禁用非必要的遥测和错误上报避免数据外泄 DISABLE_TELEMETRY: 1, DISABLE_ERROR_REPORTING: 1, CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY: 1, // 注意避免使用 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC它会同时禁用自动更新 // 实验功能启用多代理团队模式如有需要 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1 }, // 权限控制核心安全防线 permissions: { deny: [ // 阻止读取敏感信息 read: ~/.ssh/**, read: ~/.aws/**, read: ~/.npmrc, // 阻止修改 Shell 配置文件防止植入恶意命令 edit: ~/.bashrc, edit: ~/.zshrc, edit: ~/.git-credentials ] }, // 钩子在工具执行前后进行干预 hooks: { preToolUse: [ { tool: Bash, // 阻止危险的删除命令 command: if [[ $(echo \{{command}}\ | grep -c rm -rf /) -gt 0 ]]; then echo Dangerous command blocked; exit 1; fi }, { tool: Bash, // 阻止直接推送到主分支 command: if [[ \{{command}}\ *\git push origin main\* ]]; then echo Direct push to main is blocked. Use PR.; exit 1; fi } ] }, // 项目级 MCP 服务器默认不自动启用防止恶意仓库自动加载有害工具 enableAllProjectMcpServers: false, // 清理周期保留会话历史的天数设为较长值便于后期分析 cleanupPeriodDays: 365, // 始终开启深度思考模式适用于复杂任务会增加延迟和成本 alwaysThinkingEnabled: true }2.3 全局指南~/.claude/CLAUDE.md这个文件定义了你在所有项目中的通用工作哲学和标准。Claude 会在每次会话开始时自动将其加载到上下文中。markdown# 全局开发指南 ## 核心原则 - **增量修改**永远不要在现有代码上做大规模的、未经请求的重构。 - **拒绝臆测**不要添加“未来可能用到”的抽象或功能。 - **测试先行**所有新功能或 Bug 修复必须附带测试。 - **安全第一**永远不要将敏感信息密钥、密码写入代码或日志。 ## 代码质量标准 - **函数长度**单个函数不超过 50 行。 - **圈复杂度**函数复杂度不得超过 10。 - **注释**解释“为什么”而不是“是什么”。复杂逻辑必须注释。 ## 通用工具链 - **Python**: 使用 uv 管理环境ruff 进行格式化与 Lint。 - **Node.js/TypeScript**: 使用 pnpm 安装依赖oxlint 进行快速 Lint。 - **Git**: 提交信息遵循约定式提交规范feat, fix, docs, chore...。第三章Skills 配置实战本章将带你从零创建一个实用的 Skill并介绍社区中的优秀预置技能。3.1 Skill 的标准结构一个 Skill 本质上是一个目录其核心是skill.md文件。text~/.claude/skills/ffmpeg-video-compressor/ # Skill 目录名通常采用 kebab-case ├── skill.md # 元数据和核心指令 (必需) ├── scripts/ # 辅助脚本目录 (可选) │ └── compress.js # 实际执行压缩的 Node.js 脚本 ├── templates/ # 模板文件 (可选) │ └── compression-presets.json └── README.md # 对开发者友好的说明 (可选)3.2 编写skill.md遵循“渐进式披露”原则skill.md是 Claude 理解和使用该技能的入口。它必须包含 YAML 格式的 Frontmatter 和 Markdown 格式的指令。关键设计原则skill.md要短。它只是一个索引告诉 Claude 这个技能是干什么的以及当需要更深入的信息时去哪里找。详细的操作步骤、脚本调用方法应放在其他引用文件中。示例ffmpeg-video-compressor/skill.mdyaml--- name: ffmpeg-video-compressor description: 使用 FFmpeg 将视频文件压缩到指定的分辨率或码率。当用户请求“压缩视频”、“减小视频体积”时激活。 version: 1.0.0 author: your-name tags: [ffmpeg, video, media, automation] --- # FFmpeg 视频压缩技能 ## 核心任务 当用户提供一个视频文件并要求压缩时你需要使用本技能关联的脚本安全地调用 FFmpeg 完成任务。 ## 执行流程 1. **识别需求**确认用户提供的输入视频路径、期望分辨率如 720p或目标码率。 2. **定位脚本**查看同目录下的 scripts/compress.js 文件了解其参数和使用方法。 3. **执行压缩**运行 node .claude/skills/ffmpeg-video-compressor/scripts/compress.js 并传入正确的参数。 4. **返回结果**将生成的压缩文件路径告知用户。 ## 安全警告 - **永远不要覆盖源文件**确保输出文件名与输入文件不同。 - **检查文件大小**在执行前确认磁盘有足够空间。3.3 实现可执行逻辑scripts/compress.js这是 Skill 的“大脑”包含了精确的、可重复执行的逻辑。通过将逻辑从提示词中剥离并放入脚本我们彻底消除了 LLM “幻觉”命令的可能性。javascript#!/usr/bin/env node // scripts/compress.js const { execSync } require(child_process); const fs require(fs); const path require(path); const [inputFile, target] process.argv.slice(2); if (!inputFile || !target) { console.error(Usage: compress.js inputFile target); console.error(Target can be: 720p, 480p, or a bitrate like 1M); process.exit(1); } if (!fs.existsSync(inputFile)) { console.error(Error: File ${inputFile} not found.); process.exit(1); } const outputFile inputFile.replace(/(\.[\w])$/, _compressed$1); let ffmpegCommand; if (target.endsWith(p)) { // 分辨率压缩 const scale target.replace(p, ); ffmpegCommand ffmpeg -i ${inputFile} -vf scale-2:${scale} -c:v libx264 -crf 23 -c:a aac ${outputFile} -y; } else { // 码率压缩 ffmpegCommand ffmpeg -i ${inputFile} -b:v ${target} -c:v libx264 -c:a aac ${outputFile} -y; } console.log(Executing: ${ffmpegCommand}); try { execSync(ffmpegCommand, { stdio: inherit }); console.log(✅ Compression complete. Output: ${outputFile}); } catch (error) { console.error(❌ Compression failed:, error.message); process.exit(1); }3.4 测试与调试 Skill路径检查确保 Skill 位于正确的目录个人~/.claude/skills/或项目.claude/skills/。功能测试在项目目录中启动claude然后输入一个能触发该技能的请求例如“压缩当前目录下的 demo.mp4 到 720p”。调试模式如果技能未被触发或执行异常可以开启调试模式查看 Claude 的加载和决策过程。bashDEBUGclaude:skills claude第四章内置技能与社区精选无需从零开始造轮子社区已经积累了海量优质 Skills。以下是几个值得关注的来源和分类。4.1 官方与合作伙伴 SkillsAnthropic 官方 Skills 仓库提供了从创意设计到文档处理的各类基础技能例如webapp-testingWeb应用测试、pdf/docx文档处理工具包。合作伙伴 Skills如 Notion 官方提供的 Skills可以实现与 Notion 数据库的深度交互。4.2 社区精选everything-claude-code这是一个由黑客松获奖者整理的开箱即用配置集覆盖了从基础规则到高级内存持久化的方方面面。核心功能Agentsarchitect,code-reviewer,security-reviewer等子代理。SkillsTDD 工作流、安全审查清单、前后端开发模式。Commands/tdd,/plan,/e2e,/code-review等快捷命令。Hooks自动检测并提醒删除console.log的钩子。安装方式bash# 通过插件市场安装 /plugin marketplace add affaan-m/everything-claude-code /plugin install everything-claude-codeeverything-claude-code4.3 精选集feiskyer/claude-code-settings这个项目专注于提供“Vibe Coding”体验包含了许多强大的自动化技能。值得关注的 Skillsautonomous-skill双代理模式初始化器执行器可自动分解并跨会话执行长期、复杂的任务如“构建一个 TODO 应用的 REST API”。deep-research多代理研究编排。将研究目标分解为并行子任务生成结构化的研究报告。youtube-transcribe-skill自动提取 YouTube 视频字幕并保存为本地文本文件。codex-skill将任务交接给 OpenAI Codex 执行实现模型间的协同。第五章高级工作流与团队协作将 Skills 融入团队开发流程可以极大地统一技术标准和提升效率。5.1 团队标准工作流示例Kiro SkillKiro 是一种结构化的、从想法到实现的渐进式特性开发流程。一个团队可以创建一个kiro-skill要求 Claude 在开发任何新功能时都必须遵循此流程。skill.md的核心流程定义需求 (Requirements)与用户协作以 EARS 格式编写用户故事明确功能边界。设计 (Design)确定架构、组件、数据模型和 API 契约。任务 (Tasks)将设计拆解为可增量执行的、测试驱动的具体任务列表。执行 (Execute)逐一实现任务每完成一个任务都运行测试并提交。5.2 通过CLAUDE.md实现项目级规范在项目根目录下创建.claude/CLAUDE.md或./CLAUDE.md可以覆盖全局设置为特定项目提供精确指引。markdown# [项目名] 开发指南 ## 快速开始 - **安装依赖**: pnpm install - **运行开发服务器**: pnpm dev - **运行测试**: pnpm test (确保在提交前所有测试通过) - **Lint 代码**: pnpm lint:fix ## 项目架构 - **前端**: Next.js App Router, 位于 src/app/ - **后端 API**: Next.js Route Handlers, 位于 src/app/api/ - **数据库**: Prisma PostgreSQL, Schema 在 prisma/schema.prisma ## 测试策略 - **单元测试**: 使用 Vitest与源码放在同一目录下命名为 *.test.ts。 - **E2E 测试**: 使用 Playwright位于 e2e/ 目录。 - **覆盖率要求**: 核心业务逻辑src/lib/的单元测试覆盖率不得低于 80%。 ## 特定约束 - **API 修改**: 任何对现有 API 响应的修改都必须被视为破坏性变更需要更新 API 文档并通知前端团队。 - **数据库迁移**: 所有数据库 Schema 变更必须通过 pnpm prisma migrate dev 生成新的迁移文件并提交到代码库。当 Claude 在此项目目录下工作时它会自动遵循上述所有规则大幅减少沟通成本和人为失误。5.3 利用 MCP 服务器扩展技能Skills 可以与 MCP 服务器无缝集成让 Claude 能够与外部世界交互。例如一个security-audit-skill可以使用filesystemMCP 服务器读取项目中的所有代码文件。使用greptileMCP 服务器进行代码库语义搜索和理解。调用execute权限运行npm audit命令。最后使用githubMCP 服务器将发现的安全问题自动创建为 GitHub Issue。上下文窗口管理警告不要启用过多的 MCP 服务器。每个工具都会占用上下文窗口。官方建议将工具总数控制在 80 个以内每个项目根据实际需要仅启用 10 个以内的核心 MCP并通过disabledMcpServers配置项按项目禁用不需要的服务器。第六章安全与治理在企业环境中引入 AI 工具安全和可控性是首要考虑因素。6.1 沙箱与权限隔离Trail of Bits 的安全专家提供了一套企业级配置方案核心在于深度防御。权限最小化 (settings.json)如前所述通过permissions.deny规则明确禁止 Claude 读取或修改敏感文件和目录。启用内置沙箱 (/sandbox)在会话中输入/sandbox命令可以启用操作系统的隔离机制macOS 的 SeatbeltLinux 的 bubblewrap。关键权限拒绝规则在没有沙箱的情况下只能阻止 Claude 的内置工具如FileReadTool但无法阻止 Claude 生成的Bash 命令。强化/sandboxpermissions.deny的组合可以确保即使 Claude 生成了cat ~/.ssh/id_rsa这样的命令也会被操作系统拦截。终极隔离 - 开发容器 (Devcontainer)对于极高风险的任务或处理不受信任的代码库强烈建议在 Devcontainer 中运行 Claude。这样 Claude 只能访问容器内的文件系统与宿主机完全隔离。6.2 为生产环境打造“防幻觉”技能在生产环境中AI 的“创造力”需要被严格约束。以下原则可以帮助你构建更可靠的 Skills将逻辑编码到脚本中不要依赖 LLM 去“回忆”或“推理”复杂的、有确切步骤的流程如数据库迁移命令、复杂的构建脚本。将这些步骤写入可执行的脚本.sh,.js,.py然后在skill.md中指示 Claude 去执行这个脚本而不是生成脚本中的命令。使用确定性指令在skill.md中使用清单Checklist和明确的是/否则If/Else逻辑。例如“在部署前必须按顺序执行以下操作1. 运行测试2. 若测试通过则构建3. 若构建成功则执行部署脚本。”输入验证在脚本中对用户通过 Claude 传递的参数进行严格验证防止意外或恶意的输入。6.3 版本控制与团队共享Skills 本身就是代码应该像代码一样进行管理。项目级 Skills将团队共享的 Skills 放在项目的.claude/skills/目录下并提交到 Git 仓库。这是共享和版本化的最佳方式。当团队成员拉取代码时他们也同时获得了最新的团队 Skills。个人级 Skills~/.claude/skills/下的 Skills 可以视为个人工具箱通过你自己的 dotfiles 仓库进行管理。插件市场对于跨项目、可公开或内部共享的复杂 Skill可以打包成插件并发布到市场。团队成员只需一条/plugin install命令即可安装。第七章常见问题与排错指南7.1 技能未被触发原因 1描述不清晰skill.md中的description字段未能覆盖用户的自然语言请求。解决在描述中包含更多关键词和同义词。例如对于压缩技能可以写“用于压缩文件、减小体积、生成 ZIP、解压等”。原因 2目录位置错误Claude 只会在特定的目录中查找 Skills。解决运行ls ~/.claude/skills/your-skill-name/SKILL.md或ls .claude/skills/your-skill-name/SKILL.md确认文件存在。原因 3上下文冲突当前会话上下文已满或 CLAUDE.md 中的其他指令优先级更高。解决尝试在干净的会话中测试或使用/clear命令清理上下文。7.2 脚本执行失败原因 1依赖缺失脚本依赖了未安装的工具如示例中的 FFmpeg。解决在skill.md的执行流程中或者在脚本开头加入检查依赖的逻辑并给出清晰的安装提示。原因 2路径错误脚本中使用了相对路径但 Claude 执行时的当前工作目录与预期不符。解决在脚本中使用__dirname或path.resolve()基于脚本自身位置构建绝对路径或者要求 Claude 在执行脚本前先cd到项目根目录。原因 3权限不足脚本没有执行权限。解决在skill.md中指示 Claude 在运行脚本前执行chmod x scripts/your-script.js。7.3 上下文窗口溢出症状Claude 开始忽略指令或者响应速度极慢甚至报错。原因加载了过多的技能或启用了太多的 MCP 工具。解决精简 Skills确保skill.md足够精简将大量文本移至引用文件中。按需启用 MCP严格遵守“每个项目启用不超过 10 个 MCP”的原则。使用/compact命令该命令可以总结并压缩当前会话的上下文释放空间。总结Claude Code Skills 代表了 AI 辅助开发的新范式——从被动的问答转向主动的、可编程的自动化。通过精心设计和配置你可以将团队的 institutional knowledge制度性知识、复杂的开发流程和安全标准封装成一套 AI 可以理解和严格执行的“能力库”。