第一章：核心概念与架构设计

在开始配置之前，理解Claude Code的设计哲学至关重要。它并非简单的代码补全工具，而是一个基于终端的协作式AI代理。Skills（技能）则是将AI从“对话伙伴”转变为“自动化工程师”的关键。

1.1 什么是 Claude Code Skills？

Claude 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 安装与初步设置

  1. 安装 Claude Code：遵循 Anthropic 官方指南在你的终端中安装并授权 Claude Code。

  2. 配置文件结构：Claude Code 的配置主要存放在 ~/.claude/ 目录下。推荐使用版本控制系统（如 Git）来管理你的个人配置，以便追踪变更和回滚。

    bash

    mkdir -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.md

yaml

---
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

  1. 路径检查：确保 Skill 位于正确的目录（个人 ~/.claude/skills/ 或项目 .claude/skills/）。

  2. 功能测试：在项目目录中启动 claude，然后输入一个能触发该技能的请求，例如：“压缩当前目录下的 demo.mp4 到 720p”。

  3. 调试模式：如果技能未被触发或执行异常，可以开启调试模式查看 Claude 的加载和决策过程。

    bash

    DEBUG=claude:skills claude

第四章：内置技能与社区精选

无需从零开始造轮子，社区已经积累了海量优质 Skills。以下是几个值得关注的来源和分类。

4.1 官方与合作伙伴 Skills

  • Anthropic 官方 Skills 仓库：提供了从创意设计到文档处理的各类基础技能，例如 webapp-testing（Web应用测试）、pdf/docx 文档处理工具包。

  • 合作伙伴 Skills：如 Notion 官方提供的 Skills，可以实现与 Notion 数据库的深度交互。

4.2 社区精选：everything-claude-code

这是一个由黑客松获奖者整理的开箱即用配置集，覆盖了从基础规则到高级内存持久化的方方面面。

  • 核心功能：

    • Agents：architect, code-reviewer, security-reviewer 等子代理。

    • Skills：TDD 工作流、安全审查清单、前后端开发模式。

    • Commands：/tdd, /plan, /e2e, /code-review 等快捷命令。

    • Hooks：自动检测并提醒删除 console.log 的钩子。

  • 安装方式：

    bash

    # 通过插件市场安装
/plugin marketplace add affaan-m/everything-claude-code
/plugin install everything-claude-code@everything-claude-code

4.3 精选集：feiskyer/claude-code-settings

这个项目专注于提供“Vibe Coding”体验，包含了许多强大的自动化技能。

  • 值得关注的 Skills：

    • autonomous-skill：双代理模式（初始化器+执行器），可自动分解并跨会话执行长期、复杂的任务，如“构建一个 TODO 应用的 REST API”。

    • deep-research：多代理研究编排。将研究目标分解为并行子任务，生成结构化的研究报告。

    • youtube-transcribe-skill：自动提取 YouTube 视频字幕并保存为本地文本文件。

    • codex-skill：将任务交接给 OpenAI Codex 执行，实现模型间的协同。

第五章：高级工作流与团队协作

将 Skills 融入团队开发流程，可以极大地统一技术标准和提升效率。

5.1 团队标准工作流示例：Kiro Skill

Kiro 是一种结构化的、从想法到实现的渐进式特性开发流程。一个团队可以创建一个 kiro-skill，要求 Claude 在开发任何新功能时都必须遵循此流程。

skill.md 的核心流程定义：

  1. 需求 (Requirements)：与用户协作，以 EARS 格式编写用户故事，明确功能边界。

  2. 设计 (Design)：确定架构、组件、数据模型和 API 契约。

  3. 任务 (Tasks)：将设计拆解为可增量执行的、测试驱动的具体任务列表。

  4. 执行 (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 可以：

  1. 使用 filesystem MCP 服务器读取项目中的所有代码文件。

  2. 使用 greptile MCP 服务器进行代码库语义搜索和理解。

  3. 调用 execute 权限运行 npm audit 命令。

  4. 最后，使用 github MCP 服务器将发现的安全问题自动创建为 GitHub Issue。

上下文窗口管理警告：不要启用过多的 MCP 服务器。每个工具都会占用上下文窗口。官方建议将工具总数控制在 80 个以内，每个项目根据实际需要仅启用 10 个以内的核心 MCP，并通过 disabledMcpServers 配置项按项目禁用不需要的服务器。

第六章：安全与治理

在企业环境中引入 AI 工具，安全和可控性是首要考虑因素。

6.1 沙箱与权限隔离

Trail of Bits 的安全专家提供了一套企业级配置方案，核心在于深度防御。

  1. 权限最小化 (settings.json)：如前所述，通过 permissions.deny 规则，明确禁止 Claude 读取或修改敏感文件和目录。

  2. 启用内置沙箱 (/sandbox)：在会话中输入 /sandbox 命令，可以启用操作系统的隔离机制（macOS 的 Seatbelt，Linux 的 bubblewrap）。

    • 关键：权限拒绝规则在没有沙箱的情况下，只能阻止 Claude 的内置工具（如 FileReadTool），但无法阻止 Claude 生成的 Bash 命令。

    • 强化：/sandbox + permissions.deny 的组合可以确保即使 Claude 生成了 cat ~/.ssh/id_rsa 这样的命令，也会被操作系统拦截。

  3. 终极隔离 - 开发容器 (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 本身就是代码，应该像代码一样进行管理。

  1. 项目级 Skills：将团队共享的 Skills 放在项目的 .claude/skills/ 目录下，并提交到 Git 仓库。这是共享和版本化的最佳方式。当团队成员拉取代码时，他们也同时获得了最新的团队 Skills。

  2. 个人级 Skills：~/.claude/skills/ 下的 Skills 可以视为个人工具箱，通过你自己的 dotfiles 仓库进行管理。

  3. 插件市场：对于跨项目、可公开或内部共享的复杂 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 工具。

  • 解决：

    1. 精简 Skills：确保 skill.md 足够精简，将大量文本移至引用文件中。

    2. 按需启用 MCP：严格遵守“每个项目启用不超过 10 个 MCP”的原则。

    3. 使用 /compact 命令：该命令可以总结并压缩当前会话的上下文，释放空间。

总结

Claude Code Skills 代表了 AI 辅助开发的新范式——从被动的问答转向主动的、可编程的自动化。通过精心设计和配置，你可以将团队的 institutional knowledge（制度性知识）、复杂的开发流程和安全标准，封装成一套 AI 可以理解和严格执行的“能力库”。

# vim # 编辑器 # linux
Logo
亚马逊云科技技术品牌专区

更多推荐

cover

百万Token不是数字游戏：Kimi K3完整吞下10万行代码库后，我测出了它的真实理解力

avatar 亚马逊云科技技术品牌专区

洛雪音乐音源终极指南：免费获取全网无损音乐的完整方案

洛雪音乐音源项目为音乐爱好者提供了一个强大的开源解决方案，通过社区维护的多样化音源配置，让用户能够免费获取QQ音乐、网易云、酷狗、酷我、咪咕五大平台的音乐资源。这个项目不仅支持跨平台音乐聚合，还提供了无损音乐配置方案，确保用户能够享受到高品质的音频体验。## 🎯 为什么选择洛雪音乐音源？**核心优势解析**洛雪音乐音源项目经过多次测试和迭代，已经成为目前最稳定、最全面的开源音乐聚合方

avatar 亚马逊云科技技术品牌专区

为什么选择Warcraft Font Merger？轻量、快速、多功能的字体工具解析

Warcraft Font Merger是一款专为魔兽世界玩家打造的字体合并与补全工具，它能够帮助玩家轻松解决游戏中的字体显示问题，让游戏界面更加美观、易读。无论是中文显示乱码，还是特殊符号缺失，这款工具都能提供高效的解决方案。## 一、轻量级设计，不占用过多系统资源Warcraft Font Merger采用轻量级架构，整个工具包体积小巧，不会占用过多的硬盘空间和系统内存。这意味着即使在

avatar 亚马逊云科技技术品牌专区