引言

技能（Skill）是一套指令——以简单文件夹的形式打包——用于教会 Claude 如何处理特定任务或工作流。技能是自定义 Claude 以满足特定需求的最强大方式之一。无需在每次对话中重复解释您的偏好、流程和领域专业知识，技能让您一次性教会 Claude，并在每次使用中获益。

当您拥有可重复的工作流时，技能尤为强大：从规格生成前端设计、采用一致方法开展研究、创建符合团队风格指南的文档，或编排多步骤流程。它们与 Claude 的内置功能（如代码执行和文档创建）配合良好。对于构建 MCP 集成的开发者而言，技能提供了另一强大层，帮助将原始工具访问转化为可靠、优化的工作流。

本指南涵盖构建有效技能所需的一切知识——从规划和结构到测试与分发。无论您是为自己、团队还是社区构建技能，都能在其中找到实用模式和真实案例。

您将学到：

• 技能结构的技术要求与最佳实践
• 独立技能与 MCP 增强工作流的模式
• 我们在不同用例中观察到的有效模式
• 如何测试、迭代和分发您的技能

适用人群：

• 希望 Claude 始终遵循特定工作流的开发者
• 希望 Claude 始终遵循特定工作流的进阶用户
• 希望在整个组织内标准化 Claude 使用方式的团队

本指南的两种阅读路径

构建独立技能？ 请重点阅读「基础知识」、「规划与设计」以及第 1-2 类用例。

增强 MCP 集成？ 请重点阅读「技能 + MCP」部分以及第 3 类用例。

两种路径共享相同的技术要求，您可根据实际用例选择相关内容。

本指南的学习成果： 学习结束后，您将能够在一次会话中构建一个功能完整的技能。预计使用 skill-creator 构建并测试您的首个可用技能仅需 15–30 分钟。

让我们开始吧。

第 1 章：基础知识

什么是技能？

技能是一个包含以下内容的文件夹：

• SKILL.md（必需）：带有 YAML 前置元数据的 Markdown 指令
• scripts/（可选）：可执行代码（Python、Bash 等）
• references/（可选）：按需加载的文档
• assets/（可选）：输出中使用的模板、字体、图标

核心设计原则

渐进式披露（Progressive Disclosure）

技能采用三级系统：

• 第一级（YAML 前置元数据）： 始终加载到 Claude 的系统提示中。仅提供足够信息，让 Claude 知道何时应使用每个技能，而无需将其全部加载到上下文中。
• 第二级（SKILL.md 正文）： 当 Claude 认为该技能与当前任务相关时加载。包含完整指令和指导。
• 第三级（链接文件）： 捆绑在技能目录中的其他文件，Claude 可根据需要选择导航和发现。

这种渐进式披露可在保持专业知识的同时最大限度减少 token 使用量。

可组合性（Composability）

Claude 可以同时加载多个技能。您的技能应能与其他技能良好协作，而非假定自己是唯一可用的功能。

可移植性（Portability）

技能在 Claude.ai、Claude Code 和 API 中表现完全一致。只需创建一次技能，即可在所有界面上正常运行（前提是环境支持技能所需的任何依赖项）。

面向 MCP 构建者：技能 + 连接器

注意： 构建不含 MCP 的独立技能？请跳至「规划与设计」——您随时可以返回此处。

如果您已经拥有可正常运行的 MCP 服务器，那么最困难的部分已经完成。技能是顶层的知识层——捕捉您已知的工作流和最佳实践，从而让 Claude 能够始终如一地应用它们。

厨房类比

• MCP 提供专业厨房：访问工具、食材和设备。
• 技能提供食谱：创建有价值成果的逐步指令。

两者结合，使用户无需自行梳理每一步即可完成复杂任务。

它们如何协同工作

为什么这对您的 MCP 用户很重要

没有技能时：

• 用户连接您的 MCP 后不知道下一步该做什么
• 支持工单询问「如何用您的集成完成 X」
• 每次对话都从零开始
• 结果不一致，因为用户每次提示方式不同
• 用户将问题归咎于您的连接器，而实际原因是缺少工作流指导

有技能时：

• 预构建的工作流在需要时自动激活
• 一致、可靠的工具使用
• 最佳实践嵌入每次交互
• 降低您的集成的学习曲线

第 2 章：规划与设计

从用例开始

在编写任何代码之前，请确定您的技能应支持的 2–3 个具体用例。

良好的用例定义：

用例： 项目冲刺规划

触发条件： 用户说「帮我规划这个冲刺」或「创建冲刺任务」

步骤：

1. 从 Linear 获取当前项目状态（通过 MCP）
2. 分析团队速度和容量
3. 建议任务优先级
4. 在 Linear 中创建带有正确标签和估算的任务

结果： 完成规划的冲刺，任务已创建

自问：

• 用户希望完成什么？
• 这需要哪些多步骤工作流？
• 需要哪些工具（内置或 MCP）？
• 应嵌入哪些领域知识或最佳实践？

常见技能用例类别

在 Anthropic，我们观察到三种常见用例：

第 1 类：文档与资产创建

用途： 创建一致、高质量的输出，包括文档、演示文稿、应用、设计、代码等。

真实示例： frontend-design 技能（另见 docx、pptx、xlsx 和 ppt 技能）

「创建具有高设计质量的独特、生产级前端界面。适用于构建 Web 组件、页面、工件、海报或应用程序。」

关键技巧：

• 嵌入样式指南和品牌标准
• 用于一致输出的模板结构
• 最终确定前的质量检查清单
• 无需外部工具——使用 Claude 的内置功能

第 2 类：工作流自动化

用途： 受益于一致方法的多步骤流程，包括跨多个 MCP 服务器的协调。

真实示例： skill-creator 技能

「创建新技能的交互式指南。引导用户完成用例定义、前置元数据生成、指令编写和验证。」

关键技巧：

• 带验证关卡的逐步工作流
• 常见结构的模板
• 内置审查和改进建议
• 迭代优化循环

第 3 类：MCP 增强

用途： 增强 MCP 服务器提供的工具访问的工作流指导。

真实示例： sentry-code-review 技能（来自 Sentry）

「使用 Sentry 的错误监控数据（通过其 MCP 服务器）自动分析并修复 GitHub Pull Request 中检测到的错误。」

关键技巧：

• 按顺序协调多个 MCP 调用
• 嵌入领域专业知识
• 提供用户原本需要指定的上下文
• 常见 MCP 问题的错误处理

定义成功标准

如何判断您的技能是否正常工作？

这些是理想目标——粗略基准而非精确阈值。目标是严谨，但接受存在基于「感觉」的评估成分。我们正在积极开发更稳健的测量指南和工具。

定量指标：

• 技能在 90% 的相关查询中触发
  • 测量方法： 运行 10–20 个应触发您技能的测试查询。跟踪自动加载次数与需要显式调用的次数。
• 在 X 个工具调用内完成工作流
  • 测量方法： 比较启用和未启用技能时的相同任务。统计工具调用次数和消耗的 token 总量。
• 每个工作流 0 次失败的 API 调用
  • 测量方法： 在测试运行期间监控 MCP 服务器日志。跟踪重试率和错误代码。

定性指标：

• 用户无需提示 Claude 下一步做什么
  • 评估方法： 测试期间记录您需要重定向或澄清的频率。向 Beta 用户征求反馈。
• 工作流无需用户修正即可完成
  • 评估方法： 对同一请求运行 3–5 次。比较输出的结构一致性和质量。
• 跨会话结果一致
  • 评估方法： 新用户能否在首次尝试时仅需最少指导即可完成任务？

技术要求

文件结构

your-skill-name/
├── SKILL.md              # 必需 - 主技能文件
├── scripts/              # 可选 - 可执行代码
│   ├── process_data.py   # 示例
│   └── validate.sh       # 示例
├── references/           # 可选 - 文档
│   ├── api-guide.md      # 示例
│   └── examples/         # 示例
└── assets/               # 可选 - 模板等
    └── report-template.md # 示例

关键规则

SKILL.md 命名：

• 必须精确为 SKILL.md（区分大小写）
• 不接受任何变体（SKILL.MD、skill.md 等）

技能文件夹命名：

• 使用 kebab-case：notion-project-setup ✅
• 不能有空格：Notion Project Setup ❌
• 不能有下划线：notion_project_setup ❌
• 不能有大写：NotionProjectSetup ❌

无 README.md：

• 不要在技能文件夹内包含 README.md
• 所有文档应放在 SKILL.md 或 references/ 中
• 注意： 通过 GitHub 分发时，您仍需为人类用户准备仓库级 README —— 详见「分发与共享」。

YAML 前置元数据：最重要的部分

YAML 前置元数据是 Claude 决定是否加载您技能的方式。请务必正确设置。

最小必需格式

---
name: your-skill-name
description: 技能功能描述。适用于用户询问 [特定短语] 时。
---

仅需如此即可开始。

字段要求

• name（必需）：

  • 仅限 kebab-case
  • 不能有空格或大写字母
  • 应与文件夹名称一致

• description（必需）：

  • 必须同时包含：
    • 技能的功能
    • 何时使用（触发条件）
  • 少于 1024 字符
  • 不能包含 XML 标签（< 或 >）
  • 包含用户可能说的具体任务
  • 如适用，提及文件类型

• license（可选）：

  • 若技能开源则使用
  • 常见：MIT、Apache-2.0

• compatibility（可选）：

  • 1–500 字符
  • 指示环境要求，例如：目标产品、所需系统包、网络访问需求等

• metadata（可选）：

  • 任何自定义键值对
  • 建议：author、version、mcp-server
  • 示例：

    metadata:
      author: ProjectHub
      version: 1.0.0
      mcp-server: projecthub
    

安全限制

前置元数据中禁止：

• XML 尖括号（< >）
• 名称中包含 “claude” 或 “anthropic” 的技能（保留字）

原因： 前置元数据会出现在 Claude 的系统提示中。恶意内容可能注入指令。

编写有效的技能

description 字段

根据 Anthropic 工程博客所述：「此元数据……仅提供足够信息，让 Claude 知道何时应使用每个技能，而无需将其全部加载到上下文中。」这是渐进式披露的第一级。

结构：

[技能功能] + [何时使用] + [关键能力]

优质 description 示例：

# 优质 - 具体且可操作
description: 分析 Figma 设计文件并生成开发者交接文档。适用于用户上传 .fig 文件、询问「设计规格」、「组件文档」或「设计转代码交接」时。

# 优质 - 包含触发短语
description: 管理 Linear 项目工作流，包括冲刺规划、任务创建和状态跟踪。适用于用户提及「sprint」、「Linear tasks」、「project planning」或要求「create tickets」时。

# 优质 - 清晰价值主张
description: PayFlow 的端到端客户入职工作流。处理账户创建、支付设置和订阅管理。适用于用户说「onboard new customer」、「set up subscription」或「create PayFlow account」时。

劣质 description 示例：

# 过于模糊
description: Helps with projects.

# 缺少触发条件
description: Creates sophisticated multi-page documentation systems.

# 过于技术化，无用户触发短语
description: Implements the Project entity model with hierarchical relationships.

编写主指令

在前置元数据之后，用 Markdown 编写实际指令。

推荐结构：

请根据您的技能调整此模板。将方括号部分替换为具体内容。

---
name: your-skill
description: [...]
---

您的技能名称

指令

步骤 1：[第一个主要步骤]

清晰说明发生什么。

示例：

python scripts/fetch_data.py --project-id PROJECT_ID

预期输出：[描述成功时的样子]

（根据需要添加更多步骤）

示例

示例 1：[常见场景]

用户说：「Set up a new marketing campaign」

操作：

1. 通过 MCP 获取现有营销活动
2. 使用提供的参数创建新营销活动

结果： 营销活动已创建，附带确认链接

（根据需要添加更多示例）

故障排除

错误： [常见错误消息]

原因： [发生原因]

解决方案： [如何修复]

（根据需要添加更多错误情况）

指令编写最佳实践

具体且可操作

✅ 优质：

运行 `python scripts/validate.py --input {filename}` 检查数据格式。

如果验证失败，常见问题包括：
- 缺少必填字段（请添加到 CSV 中）
- 日期格式无效（请使用 YYYY-MM-DD）

❌ 劣质：

在继续之前验证数据。

包含错误处理

## 常见问题

### MCP 连接失败

如果看到「Connection refused」：

1. 确认 MCP 服务器正在运行：检查「设置 > 扩展」
2. 确认 API 密钥有效
3. 尝试重新连接：设置 > 扩展 > [您的服务] > 重新连接

清晰引用捆绑资源

在编写查询前，请查阅 references/api-patterns.md 以了解：

• 速率限制指南
• 分页模式
• 错误代码及处理方法

使用渐进式披露

保持 SKILL.md 聚焦核心指令。将详细文档移至 references/ 并链接到它。（详见「核心设计原则」了解三级系统的工作原理。）

第 3 章：测试与迭代

技能可根据您的需求以不同严谨程度进行测试：

• 在 Claude.ai 中手动测试 —— 直接运行查询并观察行为。迭代速度快，无需设置。
• 在 Claude Code 中脚本化测试 —— 自动化测试用例，以便在更改后进行可重复验证。
• 通过 skills API 进行程序化测试 —— 构建针对定义测试集系统运行的评估套件。

请选择与您的质量要求和技能可见度相匹配的方法。内部小团队使用的技能与部署给数千企业用户的技能，测试需求不同。

专业提示： 先针对单个任务迭代，再扩展

我们发现最有效的技能创建者会先针对单个具有挑战性的任务进行迭代，直到 Claude 成功，然后将获胜方法提取到技能中。这利用了 Claude 的上下文学习能力，比广泛测试提供更快信号。一旦拥有可靠基础，再扩展到多个测试用例以实现覆盖。

推荐测试方法

根据早期经验，有效的技能测试通常涵盖三个领域：

1. 触发测试

目标： 确保您的技能在正确时机加载。

测试用例：

• ✅ 在明显任务上触发
• ✅ 在改写请求上触发
• ❌ 在无关主题上不触发

示例测试套件：

应触发：

• “Help me set up a new ProjectHub workspace”
• “I need to create a project in ProjectHub”
• “Initialize a ProjectHub project for Q4 planning”

不应触发：

• “What’s the weather in San Francisco?”
• “Help me write Python code”
• “Create a spreadsheet”（除非 ProjectHub 技能处理表格）

2. 功能测试

目标： 验证技能产生正确输出。

测试用例：

• 生成有效输出
• API 调用成功
• 错误处理正常
• 覆盖边缘情况

示例：

测试： 创建包含 5 个任务的项目

给定： 项目名称「Q4 Planning」、5 个任务描述

当： 技能执行工作流

则：

• ProjectHub 中已创建项目
• 5 个任务已创建且属性正确
• 所有任务已关联到项目
• 无 API 错误

3. 性能对比

目标： 证明技能相比基线有所改进。

使用「定义成功标准」中的指标。以下是可能的对比示例。

基线对比：

无技能时：

• 用户每次都提供指令
• 15 次往返消息
• 3 次失败的 API 调用需要重试
• 消耗 12,000 tokens

有技能时：

• 自动执行工作流
• 仅 2 个澄清问题
• 0 次失败的 API 调用
• 消耗 6,000 tokens

使用 skill-creator 技能

skill-creator 技能——可在 Claude.ai 的插件目录中使用，或下载用于 Claude Code——可帮助您构建和迭代技能。如果您拥有 MCP 服务器并知道前 2–3 个工作流，通常可在一次会话中（约 15–30 分钟）构建并测试一个功能完整的技能。

创建技能：

• 从自然语言描述生成技能
• 生成带前置元数据的格式正确的 SKILL.md
• 建议触发短语和结构

审查技能：

• 标记常见问题（模糊描述、缺少触发条件、结构问题）
• 识别潜在的过度/不足触发风险
• 根据技能所述目的建议测试用例

迭代改进：

• 使用技能后遇到边缘情况或失败时，将这些示例带回 skill-creator
• 示例：「使用本次对话中识别的问题与解决方案，改进技能处理 [特定边缘情况] 的方式」

使用方法：

「Use the skill-creator skill to help me build a skill for [您的用例]」

执行问题：

• 结果不一致
• API 调用失败
• 需要用户修正

注意： skill-creator 帮助您设计和改进技能，但不执行自动化测试套件或生成定量评估结果。

解决方案： 改进指令，添加错误处理

根据反馈迭代

技能是动态文档。请根据以下内容规划迭代：

触发不足信号：

• 技能未在应触发时加载
• 用户手动启用
• 关于何时使用的支持问题

解决方案： 在 description 中添加更多细节和细微差别——可能包括技术术语的关键字

过度触发信号：

• 技能为无关查询加载
• 用户禁用
• 对用途感到困惑

解决方案： 添加否定触发条件，更具体

第 4 章：分发与共享

技能让您的 MCP 集成更完整。当用户比较连接器时，带有技能的连接器能更快实现价值，为您带来超越仅 MCP 替代方案的优势。

当前分发模式（2026 年 1 月）

个人用户获取技能的方式：

1. 下载技能文件夹
2. 压缩文件夹（如果需要）
3. 通过「设置 > 功能 > 技能」上传到 Claude.ai
4. 或放置在 Claude Code 技能目录中

组织级技能：

• 管理员可工作区范围部署技能（2025 年 12 月 18 日上线）
• 自动更新
• 集中管理

通过 API 使用技能

对于程序化用例——例如构建利用技能的应用、代理或自动化工作流——API 提供对技能管理和执行的直接控制。

关键功能：

• /v1/skills 端点用于列出和管理技能
• 通过 container.skills 参数将技能添加到 Messages API 请求
• 通过 Claude Console 进行版本控制和管理
• 与 Claude Agent SDK 配合构建自定义代理

何时使用 API vs Claude.ai：

注意： API 中的技能需要 Code Execution Tool 测试版，该测试版提供技能运行所需的安全环境。

开放标准

我们已将 Agent Skills 发布为开放标准。与 MCP 类似，我们相信技能应跨工具和平台可移植——无论您使用 Claude 还是其他 AI 平台，同一技能都应正常工作。不过，某些技能旨在充分利用特定平台的能力；作者可在技能的 compatibility 字段中注明。我们一直在与生态系统成员合作制定该标准，并对早期采用感到兴奋。

今日推荐方法

首先在 GitHub 上托管您的技能，使用公开仓库、清晰的 README（供人类访问者使用——这与您的技能文件夹分开，后者不应包含 README.md）以及带截图的使用示例。然后在您的 MCP 文档中添加一节，链接到该技能，解释同时使用两者的价值，并提供快速入门指南。

技能定位

您如何描述技能决定了用户是否理解其价值并真正尝试使用。在编写技能相关内容（README、文档或营销材料）时，请牢记以下原则。

关注结果而非功能：

✅ 优质：

「ProjectHub 技能让团队能够在几秒钟内设置完整的项目工作区——包括页面、数据库和模板——而非手动设置花费 30 分钟。」

❌ 劣质：

「ProjectHub 技能是一个包含 YAML 前置元数据和 Markdown 指令的文件夹，用于调用我们的 MCP 服务器工具。」

突出 MCP + 技能的故事：

「我们的 MCP 服务器让 Claude 能够访问您的 Linear 项目。我们的技能教会 Claude 您团队的冲刺规划工作流。两者结合，实现 AI 驱动的项目管理。」

安装指南（推荐结构）

1. 托管在 GitHub 上

   • 面向开源技能的公开仓库
   • 清晰的安装说明 README
   • 使用示例和截图

2. 在您的 MCP 仓库中记录

   • 从 MCP 文档链接到技能
   • 解释同时使用两者的价值
   • 提供快速入门指南

3. 创建安装指南

   安装 [您的服务] 技能

   1. 下载技能：
      • 克隆仓库：git clone https://github.com/yourcompany/skills
      • 或从 Releases 下载 ZIP
   2. 在 Claude 中安装：
      • 打开 Claude.ai > 设置 > 技能
      • 点击「上传技能」
      • 选择技能文件夹（已压缩）
   3. 启用技能：
      • 开启 [您的服务] 技能
      • 确保您的 MCP 服务器已连接
   4. 测试：
      • 询问 Claude：「Set up a new project in [您的服务]」

第 5 章：模式与故障排除

这些模式来自早期采用者和内部团队创建的技能。它们代表我们观察到的有效常见方法，而非规定性模板。

选择方法：问题优先 vs 工具优先

将其想象成 Home Depot。您可能带着问题走进商店——「我需要修理厨房柜子」——员工会为您指出正确的工具。或者您可能先挑选一把新钻头，然后询问如何用于特定工作。

技能的工作方式相同：

• 问题优先： 「我需要设置项目工作区」→ 您的技能按正确顺序编排正确的 MCP 调用。用户描述结果；技能处理工具。
• 工具优先： 「我已连接 Notion MCP」→ 您的技能教会 Claude 最优工作流和最佳实践。用户拥有访问权限；技能提供专业知识。

大多数技能偏向一个方向。了解哪种框架适合您的用例，有助于您选择下方合适的模式。

模式 1：顺序工作流编排

适用场景： 用户需要按特定顺序执行的多步骤流程。

示例结构：

# 工作流：新客户入职

## 步骤 1：创建账户

调用 MCP 工具：`create_customer`
参数：name, email, company

## 步骤 2：设置支付

调用 MCP 工具：`setup_payment_method`
等待：支付方式验证

## 步骤 3：创建订阅

调用 MCP 工具：`create_subscription`
参数：plan_id, customer_id（来自步骤 1）

## 步骤 4：发送欢迎邮件

调用 MCP 工具：`send_email`
模板：welcome_email_template

关键技巧：

• 明确的步骤顺序
• 步骤之间的依赖关系
• 每阶段验证
• 失败回滚指令

模式 2：多 MCP 协调

适用场景： 工作流跨越多个服务。

示例： 设计到开发交接

# 阶段 1：设计导出（Figma MCP）

1. 从 Figma 导出设计资产
2. 生成设计规格
3. 创建资产清单

# 阶段 2：资产存储（Drive MCP）

1. 在 Drive 中创建项目文件夹
2. 上传所有资产
3. 生成可共享链接

# 阶段 3：任务创建（Linear MCP）

1. 创建开发任务
2. 将资产链接附加到任务
3. 分配给工程团队

# 阶段 4：通知（Slack MCP）

1. 在 #engineering 发布交接摘要
2. 包含资产链接和任务引用

关键技巧：

• 清晰的阶段分离
• MCP 之间的数据传递
• 进入下一阶段前的验证
• 集中错误处理

模式 3：迭代优化

适用场景： 输出质量通过迭代提升。

示例： 报告生成

# 迭代报告创建

## 初始草稿

1. 通过 MCP 获取数据
2. 生成第一版报告
3. 保存到临时文件

## 质量检查

1. 运行验证脚本：`scripts/check_report.py`
2. 识别问题：
   - 缺少章节
   - 格式不一致
   - 数据验证错误

## 优化循环

1. 解决每个已识别问题
2. 重新生成受影响章节
3. 重新验证
4. 重复直到达到质量阈值

## 最终确定

1. 应用最终格式
2. 生成摘要
3. 保存最终版本

关键技巧：

• 明确的质

关键技巧：

• 明确的质

量标准

• 迭代改进
• 验证脚本
• 知道何时停止迭代

模式 4：上下文感知的工具选择

适用场景： 相同结果，不同上下文使用不同工具。

示例： 文件存储

# 智能文件存储

## 决策树

1. 检查文件类型和大小
2. 确定最佳存储位置：
   - 大文件（>10MB）：使用云存储 MCP
   - 协作文档：使用 Notion/Docs MCP
   - 代码文件：使用 GitHub MCP
   - 临时文件：使用本地存储

## 执行存储

根据决策：
- 调用相应的 MCP 工具
- 应用特定于服务的元数据
- 生成访问链接

## 向用户提供上下文

解释为何选择该存储方式

关键技巧：

• 清晰的决策标准
• 回退选项
• 选择透明度

模式 5：领域特定智能

适用场景： 您的技能添加了超出工具访问的专门知识。

示例： 金融合规

# 带合规的支付处理

## 处理前（合规检查）

1. 通过 MCP 获取交易详情
2. 应用合规规则：
   - 检查制裁名单
   - 验证管辖区允许范围
   - 评估风险级别
3. 记录合规决策

## 处理

如果合规通过：
  - 调用支付处理 MCP 工具
  - 应用适当的欺诈检查
  - 处理交易
否则：
  - 标记待审核
  - 创建合规案例

## 审计轨迹

- 记录所有合规检查
- 记录处理决策
- 生成审计报告

关键技巧：

• 逻辑中嵌入领域专业知识
• 操作前合规
• 全面文档
• 清晰治理

故障排除

技能无法上传

错误： “Could not find SKILL.md in uploaded folder”

原因： 文件未精确命名为 SKILL.md

解决方案：

• 重命名为 SKILL.md（区分大小写）
• 使用 ls -la 验证应显示 SKILL.md

错误： “Invalid frontmatter”

原因： YAML 格式问题

常见错误：

# 错误 - 缺少分隔符
name: my-skill
description: Does things

# 错误 - 未闭合引号
name: my-skill
description: "Does things

# 正确
---
name: my-skill
description: Does things
---

错误： “Invalid skill name”

原因： 名称包含空格或大写字母

# 错误
name: My Cool Skill

# 正确
name: my-cool-skill

技能未触发

症状： 技能从未自动加载

修复： 修改您的 description 字段。参阅「description 字段」中的优质/劣质示例。

快速检查清单：

• 是否过于通用？（“Helps with projects” 无法工作）
• 是否包含用户实际会说的触发短语？
• 如适用，是否提及相关文件类型？

调试方法：

询问 Claude：「When would you use the [skill name] skill？」Claude 会引用 description 内容。根据缺失部分进行调整。

技能触发过于频繁

症状： 技能为无关查询加载

解决方案：

1. 添加否定触发条件

   description: Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration (use data-viz skill instead).
   

2. 更加具体

   # 过于宽泛
   description: Processes documents
   
   # 更具体
   description: Processes PDF legal documents for contract review
   

3. 澄清范围

   description: PayFlow payment processing for e-commerce. Use specifically for online payment workflows, not for general financial queries.
   

指令未被遵循

症状： 技能加载但 Claude 不遵循指令

常见原因：

1. 指令过于冗长

   • 保持指令简洁
   • 使用项目符号和编号列表
   • 将详细参考移至单独文件

2. 指令被埋没

   • 将关键指令放在顶部
   • 使用 ## Important 或 ## Critical 标题
   • 必要时重复关键点

3. 语言模糊

   # 劣质
   Make sure to validate things properly
   
   # 优质
   CRITICAL: Before calling create_project, verify:
   - Project name is non-empty
   - At least one team member assigned
   - Start date is not in the past
   

   高级技巧： 对于关键验证，考虑捆绑一个以编程方式执行检查的脚本，而非依赖语言指令。代码是确定性的；语言解释则不是。参阅 Office 技能中的此模式示例。

4. 模型「偷懒」 —— 添加明确鼓励：

   ## Performance Notes
   
   - Take your time to do this thoroughly
   - Quality is more important than speed
   - Do not skip validation steps
   

   注意： 将此添加到用户提示中比放在 SKILL.md 中更有效

MCP 连接问题

症状： 技能加载但 MCP 调用失败

检查清单：

1. 验证 MCP 服务器已连接

   • Claude.ai：设置 > 扩展 > [您的服务]
   • 应显示「Connected」状态

2. 检查身份验证

   • API 密钥有效且未过期
   • 已授予适当权限/范围
   • OAuth 令牌已刷新

3. 独立测试 MCP

   • 要求 Claude 直接调用 MCP（不使用技能）
   • “Use [Service] MCP to fetch my projects”
   • 如果失败，问题出在 MCP 而非技能

4. 验证工具名称

   • 技能引用正确的 MCP 工具名称
   • 检查 MCP 服务器文档
   • 工具名称区分大小写

大上下文问题

症状： 技能响应缓慢或质量下降

原因：

• 技能内容过大
• 同时启用的技能过多
• 加载了全部内容而非渐进式披露

解决方案：

1. 优化 SKILL.md 大小

   • 将详细文档移至 references/
   • 链接到 references 而非内联
   • 保持 SKILL.md 少于 5,000 字

2. 减少启用的技能

   • 评估是否同时启用了超过 20–50 个技能
   • 建议选择性启用
   • 考虑为相关功能创建技能「包」

第 6 章：资源与参考

如果您正在构建首个技能，请先从「最佳实践指南」开始，然后根据需要参考 API 文档。

官方文档

Anthropic 资源：

• 最佳实践指南
• 技能文档
• API 参考
• MCP 文档

博客文章：

• 介绍 Agent Skills
• 工程博客：为真实世界装备代理
• 技能详解
• 如何为 Claude 创建技能
• 为 Claude Code 构建技能
• 通过技能改进前端设计

示例技能

公开技能仓库：

• GitHub: anthropics/skills
• 包含 Anthropic 创建的技能，您可以自定义

skill-creator 技能：

• 内置于 Claude.ai 并可用于 Claude Code
• 可从描述生成技能
• 提供审查和建议
• 使用：「Help me build a skill using skill-creator」

验证：

• skill-creator 可评估您的技能
• 询问：「Review this skill and suggest improvements」

获取支持

技术问题：

• 一般问题：Claude 开发者 Discord 社区论坛

错误报告：

• GitHub Issues: anthropics/skills/issues
• 请包含：技能名称、错误消息、重现步骤

参考 A：快速检查清单

使用此检查清单在上传前后验证您的技能。如果希望更快开始，请使用 skill-creator 技能生成初稿，然后逐项检查以确保无遗漏。

开始前

• 已确定 2–3 个具体用例
• 已确定工具（内置或 MCP）
• 已阅读本指南和示例技能
• 已规划文件夹结构

开发期间

• 文件夹名称使用 kebab-case
• SKILL.md 文件存在（精确拼写）
• YAML 前置元数据有 --- 分隔符
• name 字段：kebab-case，无空格，无大写
• description 包含「做什么」和「何时用」
• 任何位置无 XML 标签（< >）
• 指令清晰且可操作
• 包含错误处理
• 提供示例
• 清晰链接 references

上传前

• 已测试在明显任务上触发
• 已测试在改写请求上触发
• 已验证在无关主题上不触发
• 功能测试通过
• 工具集成正常（如适用）
• 已压缩为 .zip 文件

上传后

• 在真实对话中测试
• 监控触发不足/过度情况
• 收集用户反馈
• 迭代 description 和指令
• 更新 metadata 中的版本

参考 B：YAML 前置元数据

必需字段

---
name: skill-name-in-kebab-case
description: 技能功能描述及使用时机。包含具体触发短语。
---

所有可选字段

name: skill-name
description: [必需描述]
license: MIT                    # 可选：开源许可证
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"  # 可选：限制工具访问
metadata:                       # 可选：自定义字段
  author: Company Name
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]
  documentation: https://example.com/docs
  support: support@example.com

安全说明

允许：

• 任何标准 YAML 类型（字符串、数字、布尔值、列表、对象）
• 自定义 metadata 字段
• 长描述（最多 1024 字符）

禁止：

• XML 尖括号（< >）——安全限制
• YAML 中的代码执行（使用安全 YAML 解析）
• 名称以 “claude” 或 “anthropic” 为前缀的技能（保留字）

参考 C：完整技能示例

以下是展示本指南中模式的完整、生产就绪技能：

• 文档技能 —— PDF、DOCX、PPTX、XLSX 创建
• 示例技能 —— 各种工作流模式
• 合作伙伴技能目录 —— 查看来自 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等合作伙伴的技能

这些仓库会保持更新，并包含本指南未涵盖的更多示例。克隆它们，根据您的用例修改，并将其用作模板。

claude.ai

但是话又说回来，其实 Edit 的使用场景比较尴尬，如果是和轻量的那一档去比，那不如Vim，和大型编辑器比不如 VS Code、Zed 这些，甚至写这篇文章的时候我都快忘记 Edit 有哪些功能了，当然如果你想要一个打开即用的终端可视化编辑器，Edit 也是个不错的选择。

PowerShell 的出现是为了弥补 CMD 的不足，它在 2006 年由 Windows Vista 推出，核心点在于采用面向对象架构，每个命令返回的是包含属性和方法的对象，通过管道操作符，用户可以直接操作对象的具体某一属性。同理 PowerShell 也存在一些缺陷，比如命令非常难记，跟 bash 差别很大，学习成本高。

一句话总结，CMD 的基础命令适合日常快速任务，PowerShell 更适用于复杂环境下的系统自动化。

下载那天的印象，启动非常快，界面干净，没有像 VS Code 一样的厚重感，这才是一个编辑器该有的样子。

但有些槽点，比如插件生态，扩展太少了，跟 VS Code 完全比不了，虽然官方内置的已经足够用了，但是如果用户想要一些其他编辑器独有的插件，那就做不到，主题也是，热门的那几个我都不太喜欢，好在后面找到Nightfox，就是有些细节还需打磨，比如文本选中状态和背景是统一颜色，这个太搞了。

最难受的是Markdown 预览，这个甚至都不如Windows记事本自带的预览好看，特别离谱，Markdown 渲染的时候，行间的空行会自动删除，导致所有东西全部挤在一起，效果给我的感觉不如我直接看Markdown 源格式，至少层次分明一点，后续估计 Zed 会针对这个单独优化。

其他的没什么了，Git 集成不错，自研的ACP也还可以，就是配置藏的很深，有点逼着用户用Zed AI，至于哪次更新让我惊喜，没有，因为我觉得 Zed 一开始就把大部分事情完成了，后续就是优化迭代，也就是1.0版本推出的Agent对话历史切换和Git Graph支持让我眼前一亮。

至于是否取代 VS Code，那肯定是不可能的，就只论插件生态这方面，Zed 几年内都追不上。

总结下，Zed 是一款优秀的编辑器，基于 Rust 开发，足够快，内存占用少，开箱即用，如果你让我推荐一个新手使用的IDE，毫无疑问是Zed。

This theme was developed during my free time, and the documentation may not be comprehensive enough, but I will try my best to explain it.

Prerequisite

Before starting, ensure you have the following tools installed in your development environment:

• Node.js - Required for running the development environment.
• pnpm - Our preferred package manager for dependency management.
• Git - For version control and project management.
• VS Code - Recommended code editor with excellent development experience.

Startup project

There are two ways to do this:

• Fork the repository
• Use this template - In the future, content-free branches will be launched, which do not require deleting and replacing content.

After you have your own repository, you can clone it to your local machine.

Update Theme

When the theme releases a new version, you can pull the latest changes without losing your content by following these steps:

1. Add upstream remote (only needed once)

git remote add upstream https://github.com/Dnzzk2/Litos.git

2. Fetch and merge the latest theme

git fetch upstream
git merge upstream/main --no-edit

3. Resolve conflicts (if any)

Conflicts typically only occur in files you have modified, such as src/config.ts. In that case, just keep your own configuration and accept the rest of the theme updates.

End

The following documents will be divided into pages, such as readme, posts…

The following files are compatible with this document:

• src/pages/index.astro - readme page.
• src/config.ts - readme page config.
• src/components/base - most of the components come from here.

Site Config

Configure basic site information:

export const SITE: Site = {
  title: 'Litos',
  description: 'Litos is a blog theme built with Astro.js and Dnzzk2.',
  website: 'https://litos.vercel.app/',
  lang: 'en',
  base: '/',
  author: 'Dnzzk2',
  ogImage: '/og-image.jpg',
}

Header Links

Top jump link component configuration:

export const HEADER_LINKS: Link[] = [
  {
    name: 'Posts',
    url: '/posts',
  },
]

Footer Links

Footer link component configuration:

export const FOOTER_LINKS: Link[] = [
  {
    name: 'Readme',
    url: '/',
  },
]

Social Links

In the readme page, you can see a string of icons below the theme introduction, which can be configured below. Icons are from Iconify.

export const SOCIAL_LINKS: SocialLink[] = [
  {
    name: 'github',
    url: 'https://github.com/yourname',
    icon: 'icon-[ri--github-fill]',
    count: 11,
  },
  {
    name: 'twitter',
    url: 'https://x.com/yourname',
    icon: 'icon-[ri--twitter-x-fill]',
  },
]

Spotlight

export const GITHUB_CONFIG: GithubConfig = {
  ENABLED: true,
  GITHUB_USERNAME: 'Dnzzk2',
  TOOLTIP_ENABLED: true,
}

Skills

On the readme page, you can see a skill display area where you can showcase your skills by configuring the following code:

export const SKILLSSHOWCASE_CONFIG: SkillsShowcaseConfig = {
  SKILLS_ENABLED: true,
  SKILLS_DATA: [
    {
      direction: 'left',
      skills: [
        {
          name: 'JavaScript',
          icon: 'icon-[mdi--language-javascript]',
        },
        {
          name: 'CSS',
          icon: 'icon-[mdi--language-css3]',
        },
        {
          name: 'HTML',
          icon: 'icon-[mdi--language-html5]',
        },
        {
          name: 'TypeScript',
          icon: 'icon-[mdi--language-typescript]',
        },
      ],
    },
  ],
}

Posts

Here, we mainly display pinned posts. If there are no pinned posts, we will display the latest number of size posts based on POSTS_CONFIG.

The following files are compatible with this document:

• src/pages/posts/[...id].astro - post specific content display page.
• src/pages/posts/[...page].astro - post list page.
• src/content/posts - posts collection
• src/content.config.ts - posts dataset and frontmatter configuration.
• ec.config.mjs - expressiveCode config.
• plugins/index.ts - remark and rehype plugins.
• src/config.ts - posts page config.
• src/components/posts - most of the components come from here.

Posts Page Config

The posts page config is configured in the following code:

export const POSTS_CONFIG: PostConfig = {
  title: 'Posts',
  description: 'Posts by Dnzzk2',
  introduce: 'Here, I will share the usage instructions for this theme to help you quickly use it.',
  author: 'Dnzzk2',
  homePageConfig: {
    size: 3,
    type: 'compact',
  },
  postPageConfig: {
    size: 10,
    type: 'minimal',
  },
  tagsPageConfig: {
    size: 10,
    type: 'time-line',
  },
  ogImageUseCover: false,
  postType: 'metaOnly',
  imageDarkenInDark: true,
  readMoreText: 'Read more',
  prevPageText: 'Previous',
  nextPageText: 'Next',
  tocText: 'On this page',
  backToPostsText: 'Back to Posts',
  nextPostText: 'Next Post',
  prevPostText: 'Previous Post',
  recommendText: 'REC',
}

There are a few configuration attributes, please refer to the table below for details.

Type & PostType

In the above document, we mentioned configurable types for configuring the display style of list data on the readme page, posts page, and tags page, as well as configurable postTypes for displaying metadata at the top of the posts content page.

Here is the specific style display of type:

Here is the specific style display of postType:

Frontmatter

After discussing the external list and overall design of the post, let’s take a look at the content of the post together. These contents are all in the src/content/posts folder.

Below is the frontmatter of the post content:

---
title: 'Litos: Posts Page Config'
description: ''
pubDate: 2025-08-13
author: 'Dnzzk2'
recommend: true
tags: ['Litos', 'Documentation']
---

You can configure the frontmatter of the post content in the following code:

const posts = defineCollection({
  loader: glob({
    pattern: '**/*.{md,mdx}',
    base: './src/content/posts',
  }),
  schema: ({ image }) =>
    z
      .object({
        title: z.string(),
        description: z.string(),
        pubDate: z.date(),
        tags: z.array(z.string()).optional(),
        updatedDate: z.date().optional(),
        author: z.string().default(POSTS_CONFIG.author),
        cover: image().optional(),
        ogImage: image().optional(),
        recommend: z.boolean().default(false),
        postType: z.custom<PostType>().optional(),
        coverLayout: z.custom<CoverLayout>().optional(),
        pinned: z.boolean().default(false),
        draft: z.boolean().default(false),
      })
      .transform((data) => ({
        ...data,
        ogImage: data.ogImage ? data.ogImage : POSTS_CONFIG.ogImageUseCover && data.cover ? data.cover : undefined,
      })),
})

Syntax and Code Style

This guide will show you how to format text using Markdown through a 3-day city trip itinerary. Learn Markdown while planning your journey!

Heading Levels

For travel notes, multiple heading levels help organize days, time blocks, and tips:

# 3-Day City Trip Itinerary

## Day 1: Arrival & Old Town

### Morning Plan

#### Coffee Stops

##### Metro Tips

###### Notes

Text Formatting

When writing travel notes, highlight important info:

Must-see spots should be bold Flexible time uses italics Critical cautions can use both Optional detours use strikethrough

**Must-see spots** should be bold
_Flexible time_ uses italics
**_Critical cautions_** can use both
~~Optional detours~~ use strikethrough

Packing List (Unordered List)

• Passport, visa
• Camera, extra battery
  • Bring a fast charger
  • Spare SD card
• Refillable water bottle
• Public transport card

- Passport, visa
- Camera, extra battery
  - Bring a fast charger
  - Spare SD card
- Refillable water bottle
- Public transport card

Day 1 Schedule (Ordered List)

1. Airport → hotel check-in
2. Old Town walking tour
3. Evening river cruise
   1. Arrive 15 min early
   2. Queue at Gate B
   3. Window seats recommended

1. Airport → hotel check-in
2. Old Town walking tour
3. Evening river cruise
   1. Arrive 15 min early
   2. Queue at Gate B
   3. Window seats recommended

Blockquotes

Traveler tip: Buy a 24‑hour metro pass if you plan 3+ rides in a day.

Save the hotel address in offline maps for quick access.

> Traveler tip: Buy a 24‑hour metro pass if you plan 3+ rides in a day.
>
> Save the hotel address in offline maps for quick access.

Code Blocks

Use simple code to estimate budget:

type Budget = { flight: number; hotel: number; meals: number; transport: number }
export const total = (b: Budget) => b.flight + b.hotel + b.meals + b.transport

console.log(total({ flight: 1200, hotel: 450, meals: 180, transport: 60 })) // 1890

Tables

Sample schedule:

Links and Images

More tips: Official Tourism Board

Trip photo:

Horizontal Rule

Inline Code

Metro line A runs every 5-7 minutes during peak hours.

Math Formulas

Daily budget estimation: budget=hotel+meals+transportbudget = hotel + meals + transportbudget=hotel+meals+transport

Total trip:

Task Lists

Pre-trip checklist:

• Book flights
• Reserve hotel
• Buy metro pass
• Download offline maps

Footnotes

This itinerary draws on local travel guides(click to the footnote) ¹.

Expressive-code config

In Markdown documents, we use code blocks to display code snippets and other content. This document explains how to customize the code block configuration.

The code blocks in this theme are configured using Expressive Code with all configuration options defined in the ec.config.mjs file. Below is the main configuration options:

import { defineEcConfig } from 'astro-expressive-code'
import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'

export default defineEcConfig({
  defaultLocale: 'zh-CN',
  defaultProps: {
    wrap: false,
    collapseStyle: 'collapsible-auto',
    showLineNumbers: false,
    preserveIndent: true,
  },
  minSyntaxHighlightingColorContrast: 0,

  styleOverrides: {
    uiFontFamily: 'GeistMono, Input Mono, Fira Code, ShangguSansSCVF, monospace',
    uiFontSize: '1em',
    codeFontFamily: 'GeistMono, Input Mono, Fira Code, ShangguSansSCVF, monospace',
    codeFontSize: '14px',
    codeLineHeight: '1.4',
    borderRadius: '0',
    codePaddingBlock: '0.8571429em',
    codePaddingInline: '1.1428571em',
    borderColor: ({ theme }) => (theme.type === 'dark' ? '#24273a' : '#e6e9ef'),

    frames: {
      frameBoxShadowCssValue: false,
      inlineButtonBackgroundActiveOpacity: '0.2',
      inlineButtonBackgroundHoverOrFocusOpacity: '0.1',
    },
    textMarkers: {
      backgroundOpacity: '0.2',
      borderOpacity: '0.4',
    },
  },

  plugins: [
    pluginCollapsibleSections({
      defaultCollapsed: false,
    }),
    pluginLineNumbers(),
  ],

  themes: ['catppuccin-macchiato', 'catppuccin-latte'],
  themeCssSelector: (theme) => (theme.name === 'catppuccin-macchiato' ? '.dark' : ':root:not(.dark)'),
  useDarkModeMediaQuery: false,
  useStyleReset: false,
})

You can go to the website to view the configuration options of expressive-code.

Comment System (Gitalk)

The theme has a built-in Gitalk comment system that uses GitHub Issues as the comment backend. Each post automatically gets its own issue for comments.

Prerequisites

You need to create a GitHub OAuth App first:

1. Go to GitHub Developer Settings → OAuth Apps → New OAuth App.
2. Fill in the form:
   • Application name: Any name (e.g. My Blog Comments)
   • Homepage URL: Your site URL (e.g. https://yourdomain.com)
   • Authorization callback URL: Same as your site URL
3. After creation, copy the Client ID and generate a Client Secret.
4. Create a public repository on GitHub to store comment issues (e.g. blog-comments).

Configuration

Configure the comment system in src/config.ts:

export const COMMENT_CONFIG: CommentConfig = {
  enabled: true,
  system: 'gitalk',
  gitalk: {
    clientID: import.meta.env.PUBLIC_GITHUB_CLIENT_ID,
    clientSecret: import.meta.env.PUBLIC_GITHUB_CLIENT_SECRET,
    repo: 'blog-comments',
    owner: 'YourGitHubUsername',
    admin: ['YourGitHubUsername'],
    language: 'en-US',
    perPage: 5,
    pagerDirection: 'last',
    createIssueManually: false,
    distractionFreeMode: false,
    enableHotKey: true,
  },
}

Then set the environment variables. Create a .env file in the project root (refer to .env.example):

PUBLIC_GITHUB_CLIENT_ID=your-github-client-id
PUBLIC_GITHUB_CLIENT_SECRET=your-github-client-secret

Config Properties

This guide has made slight changes based on the markdown-mdx-extended-features.

Callouts

Supported by the rehype-callouts , you can configure the plugin in plugins/index.ts.

If you change the theme configuration (default: 'vitepress'), you will also need to update the imported CSS file in src/styles/pro.css (@import 'rehype-callouts/theme/yourconfig').

<!-- Callout type names are case-insensitive: 'Note', 'NOTE', and 'note' are equivalent. -->

<!-- vitepress -->

<!-- This is a _non-collapsible_ callout -->

> [!note]
> Note content.

> [!tip]
> Tip content.

> [!important]
> Important content.

> [!warning]
> Warning content.

> [!caution]
> Caution content.

> [!caution]- This is a **collapsible** callout
> Caution content.

> [!note]+ This is a **collapsible** callout
> Note content.

Fully-featured Code Blocks

Supported by astro-expressive-code with @expressive-code/plugin-collapsible-sections and @expressive-code/plugin-line-numbers plugins to add styling and extra functionality for code blocks.

To customize code block themes or functionality, modify the ec.config.mjs file at the project root after reviewing the Configuring Expressive Code, such as change themes, enable word wrap, or toggle line numbers.

Here’s a quick preview of what’s possible. Check the detailed guide for more info.

Syntax highlighting

console.log('This code is syntax highlighted!')

ANSI colors:
- Regular: Red Green Yellow Blue Magenta Cyan
- Bold:    Red Green Yellow Blue Magenta Cyan
- Dimmed:  Red Green Yellow Blue Magenta Cyan

256 colors (showing colors 160-177):
160 161 162 163 164 165
166 167 168 169 170 171
172 173 174 175 176 177

Full RGB colors:
ForestGreen - RGB(34, 139, 34)

Text formatting: Bold Dimmed Italic Underline

Code editor frames

// Use `title="my-test-file.js"`
console.log('Title attribute example')

// src/content/index.ts
// Use `// src/content/index.ts`
console.log('File name comment example')

Terminal frames

echo "This terminal frame has no title"

Write-Output "This one has a title!"

Marking full lines & line ranges

// Line 1 - targeted by line number
// Line 2
// Line 3
// Line 4 - targeted by line number
// Line 5
// Line 6
// Line 7 - targeted by range "7-8"
// Line 8 - targeted by range "7-8"

Selecting line marker types (mark, ins, del)

function demo() {
  console.log('this line is marked as deleted')
  // This line and the next one are marked as inserted
  console.log('this is the second inserted line')

  return 'this line uses the neutral default marker type'
}

Adding labels to line markers

// labeled-line-markers.jsx
<button role="button" {...props} value={value} className={buttonClassName} disabled={disabled} active={active}>
  {children && !active && (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

Adding long labels on their own lines

// labeled-line-markers.jsx
<button role="button" {...props} value={value} className={buttonClassName} disabled={disabled} active={active}>
  {children && !active && (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

Using diff-like syntax

+this line will be marked as inserted
-this line will be marked as deleted
this is a regular line

  function thisIsJavaScript() {
    // This entire block gets highlighted as JavaScript,
    // and we can still add diff markers to it!
-   console.log('Old code to be removed')
+   console.log('New and shiny code!')
  }

Marking individual text inside lines

// Plaintext search strings
function demo() {
  // Mark any given text inside lines
  return 'Multiple matches of the given text are supported'
}

Marking individual text inside lines

// Regular expressions
console.log('The words yes and yep will be marked.')

# Regular expressions
echo "Test" > /home/test.txt

// Regular expressions
If you only want to mark certain parts matched by your regular expression, you can use capture groups.

For example, the expression `/ye(s|p)/` will match yes and yep, but only mark the character s or p:

// Regular expressions
To prevent this special treatment of capture groups, you can convert them to non-capturing groups by adding ?: after the opening parenthesis. For example:

This block uses `/ye(?:s|p)/`, which causes the full
matching words "yes" and "yep" to be marked.

// Selecting inline marker types (mark, ins, del)
function demo() {
  console.log('These are inserted and deleted marker types')
  // The return statement uses the default marker type
  return true
}

Configuring word wrap per block

// Example with wrap
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with wrap=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Configuring indentation of wrapped lines

// Example with preserveIndent (enabled by default)
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with preserveIndent=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Collapsible sections

// All this boilerplate setup code will be collapsed
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// This part of the code will be visible by default
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
  // You can have multiple collapsed sections
  const a = 1
  const b = 2
  const c = a + b

  // This will remain visible
  console.log(`Calculation result: ${a} + ${b} = ${c}`)
  return c
}

// All this code until the end of the block will be collapsed again
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: 'End of example boilerplate code' })

Displaying line numbers per block

// This code block will show line numbers
console.log('Greetings from line 2!')
console.log('I am on line 3')

// Line numbers are disabled for this block
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')

// Changing the starting line number
console.log('Greetings from line 5!')
console.log('I am on line 6')

Image Caption & Link

Use the :::image directive from remark-directive-sugar to wrap images in a container for captions, clickable links, and more. Customize via the image option in plugins/index.ts (remarkDirectiveSugar) and style under /* :::image */ in src/styles/pro.css.

image-figure

:::image-figure[caption]{<figcaption> attrs}: The square brackets define the <figcaption> text (defaults to the alt text from ![]() if omitted), while the curly braces are used for inline styles or supported attributes to the generated <figcaption> element.

![alt](image path)(<img> attrs): Standard Markdown image with optional attributes in parentheses, enabled by remark-imgattr, for customizing the generated <img> element.

:::image-figure[caption]{<figcaption> attrs}: The square brackets define the <figcaption> text (defaults to the alt text from ![]() if omitted), while the curly braces are used for inline styles or supported attributes to the generated <figcaption> element.

![alt](image path)(<img> attrs): Standard Markdown image with optional attributes in parentheses, enabled by remark-imgattr, for customizing the generated <img> element.

:::image-figure[This Is a **Figcaption** with _`<figure>` Attrs_]{style="text-align:center;color:orange"}
![](assets/cover.png)
:::

:::image-figure[This is a **figcaption** with _`<img>` attrs_.]
![](assets/cover.png)(style: width:600px;)
:::

<!-- 💡 Use `(class:no-zoom)` to disable zoom -->

:::image-figure[This is a **figcaption** with `class:no-zoom`.]
![](assets/cover.png)(class:no-zoom)
:::

<!-- 💡 If no `[caption]`, use `[alt]` as figcaption. -->

:::image-figure
![If `[caption]` not set, the alt text from `![]()` will be used as the figcaption.](assets/cover.png)
:::

<!-- 💡 Images for light (img-light) and dark (img-dark) modes -->
<!-- ⚠️ At least one line must separate two image syntaxes (![]()), or won't work. -->

:::image-figure[This example shows different images for light (add `class:img-light`) and dark (add `class:img-dark`) modes.]
![](assets/image-16-9-light.png)(class:img-light)

![](assets/image-16-9-light.png)(class:img-dark)
:::

<!-- ❌ If no text is available for the figcaption, it won't work.  -->

:::image-figure
![](assets/cover.png)
:::

image-a

The custom directive wraps an image inside a link, making it clickable.

:::image-a{<a> attrs}: Define the link (href), styles, or classes in the curly braces for <a> element.

![alt](image path)(<img> attrs): Same as above.

:::image-a{href="https://github.com/Dnzzk2/Litos"}
![OG image](assets/cover.png)
:::

:::image-a{href="https://github.com/Dnzzk2/Litos" style="display:block" .custom-class}
![OG image](assets/cover.png)(style: margin-bottom: -1rem; transform:scaleX(1.1) scaleY(1.1);, loading: eager)
:::

::::image-a{href="https://github.com/Dnzzk2/Litos"}
:::image-figure[This example shows `:::image-a` wraps around `:::image-figure` (both are interchangeable).]
![OG image](assets/cover.png)
:::
::::

<!-- ❌ No external links provided, it won't work.-->

:::image-a
![OG image](assets/cover.png)
:::

image-figure-polaroid

Polaroid style images with a border and shadow.

In order to ensure the style size on the phone, I have set a minimum width of 300px, and you can modify and expand the style in src/styles/picture.css.

:::::image-div-polaroid
:::image-figure-polaroid[This is a **figcaption** with _`<img>` attrs_.]
![OG image](assets/cover.png)
:::
:::::

:::::image-div-polaroid
:::image-figure-polaroid
![OG image](assets/cover.png)

cover.png
:::
:::::

:::::image-div-polaroid
:::image-figure-polaroid
![OG image](assets/cover.png)
:::
:::::

<!-- change style -->

:::::image-div-polaroid
:::image-figure-polaroid{style="width:500px;"}
![OG image](assets/cover.png)
:::
:::::

This is a figcaption with <img> attrs.

cover.png

GitHub Card

Congratulations from oopsunix

::github{repo="Dnzzk2/Litos"}

Video Embedding

Use the ::video directive from remark-directive-sugar for consistent video embedding across different platforms. Customize via the video option in plugins/index.ts and style under /* ::video */ in src/styles/pro.css.

Say example.md contains:

<!-- Embed a YouTube video -->

::video-youtube{#gxBkghlglTg}

<!-- Embed a Bilibili video with a custom `title` attr -->

::video-bilibili[custom title]{id=BV1MC4y1c7Kv}

<!-- Embed a Vimeo video with class `no-scale` to disable scaling -->

::video-vimeo{id=912831806 class='no-scale'}

<!-- ::video-vimeo{id=912831806 .no-scale} -->

<!-- Embed a custom video URL (must use `id`, not `#`) -->

::video{id=https://www.youtube-nocookie.com/embed/gxBkghlglTg}

Then example.mdx renders as:

Styled Link（:link）

Use the :link directive from remark-directive-sugar to add links with avatars or favicons for GitHub, npm, or custom URLs. Customize via the link option in plugins/index.ts and style under /* :link */ in src/styles/pro.css.

Link to a GitHub user or organization (prepend id with @)

Example 1: :link[Dnzzk2]{#@Dnzzk2} links to the GitHub profile of the project maintainer, Dnzzk2.

Example 2: Vite links to the GitHub profile of the Vite organization.

Example 3: :link{#@Dnzzk2 tab=repositories} links directly to the repositories tab of the GitHub user, like Dnzzk2. For GitHub users, valid tab options: 'repositories','projects', 'packages', 'stars', 'sponsoring', 'sponsors'.

Example 4: :link{#@vitejs tab=org-people} links directly to the people section of a GitHub organization, like vitejs. For GitHub organizations, valid tab options: 'org-repositories', 'org-projects', 'org-packages', 'org-sponsoring', and 'org-people'.

Link to a GitHub repository

Example 5: :link[Astro]{#withastro/astro} or Astro creates a link to Astro repo.

Link to an npm package

Example 6: :link{#remark-directive-sugar} links to the npm homepage of the remark-directive-sugar.

Example 7: :link{id=remark-directive-sugar tab=dependencies} links to the dependencies section of the remark-directive-sugar on npm. For npm package, valid tab options: 'readme', 'code', 'dependencies', 'dependents', and 'versions'.

Link to a custom URL (must use id, not #)

Example 8: :link{id=https://developer.mozilla.org/en-US/docs/Web/JavaScript} creates an external link to the developer.mozilla.org/en-US/docs/Web....

Example 9: Google creates an external link to the Google.

Customization

Example 10: Vite creates a Vite to https://vite.dev/ instead of https://github.com/vitejs by using the url.

Example 11: Vite creates a Vite that displays a custom logo by using the img.

Example 12: :link{id=Dnzzk2/Litos class=github} creates a Dnzzk2/Litos with class=github (or .github) to override the default style of a GitHub repository.

Example 13: Litos Themes fully customizes a link. Litos Themes

Badges

Use the :badge directive from remark-directive-sugar to display small pieces of information, such as status or category.

The theme provides the following one predefined badges. You can customize them via the badge option in plugins/index.ts and style them under /* :badge */ in src/styles/pro.css.

• badge-n: NEW

Additionally, you can direct use :badge[text]{attrs} for easy visual customization of badges. For example: :badge[ISSUE]{style="background-color: #bef264"} will display as ISSUE. If no color is specified, the default appearance will look like This.

Details Dropdown

:::details
::summary[Details Dropdown]

- List item 1
- List item 2
- List item 3
- List item 4
  :::

• List item 1
• List item 2
• List item 3
• List item 4

Additionally, it also supports usage similar to the examples in remark-directive.

Due to the small size of the Project and tag page configurations, they are merged into one document.

The following files are compatible with this document:

• src/pages/projects/index.astro - project page.
• src/pages/tags/index.astro - tag statistics page.
• src/pages/tags/[tag]/[...page].astro - specific tag display post list page.
• src/config.ts - project and tag page config.
• src/components/base - most of the components come from here.

Project Page Config

Configure page texts:

export const PROJECTS_CONFIG: ProjectConfig = {
  title: 'Projects',
  description: 'The examples of my projects.',
  introduce: 'The examples of my projects.',
}

Project content

The content displayed on the project page comes from /src/content/projects.

Its writing style is similar to posts: one MDX file represents one project.

Project frontmatter

Example (src/content/projects/Litos/index.mdx):

---
name: 'Litos'
description: 'A Simple & Modern Blog Theme for Astro.'
githubUrl: 'https://github.com/Dnzzk2/Litos'
website: 'https://litos.vercel.app/'
type: 'image'
icon: '../../../../public/projects/litos.png'
imageClass: 'w-10 h-10'
star: 32
fork: 7
---

Tag Page Config

export const TAGS_CONFIG: TagsConfig = {
  title: 'Tags',
  description: 'All tags of Posts',
  introduce: 'All the tags for posts are here, you can click to filter them.',
}

This document describes the current implementation of the Photos page.

Current file structure

• src/pages/photos/index.astro
  • Reads page text from PHOTOS_CONFIG
  • Reads timeline data from PhotosList
• src/config.ts
  • Stores PHOTOS_CONFIG
• src/lib/photos.ts
  • Stores PhotosList
  • Auto-imports photo files
  • Converts one folder of images into Photo[] with getPhotos()
• src/types.ts
  • Defines PhotoData, Photo, and PolaroidVariant
• src/components/photos/PolaroidCard.tsx
  • Maps each variant to the actual card size

Page text

The page title and intro text come from src/config.ts.

export const PHOTOS_CONFIG: PhotosConfig = {
  title: 'Photos',
  description: 'Here I will record some photos taken in daily life.',
  introduce: 'Here I will record some photos taken in daily life.',
}

src/pages/photos/index.astro renders the page like this:

---
import { PHOTOS_CONFIG } from '~/config'
import { PhotosList } from '~/lib/photos'

const { title, description, introduce } = PHOTOS_CONFIG
---

<Layout {title} {description}>
  <PageTitle {title} {introduce} />
  <PhotoTimeline photoData={PhotosList} />
</Layout>

PhotosList

PhotosList is defined in src/lib/photos.ts. Each item is one timeline entry.

export const PhotosList: PhotoData[] = [
  {
    title: 'Ningbo - Botanical Garden',
    icon: { type: 'emoji', value: '🌼' },
    description: 'It was early spring, so I went to see the cherry blossoms.',
    date: '2026-03-07',
    travel: '',
    photos: getPhotos(
      '2026-03-07-botanicalGarden',
      'Early spring cherry blossoms at the botanical garden',
      ['3x4', '3x4', '3x4', '3x4', '3x4', '3x4']
    ),
  },
]

PhotoData fields

How getPhotos() works

Current implementation:

function getPhotos(dir: string, alt: string, variants: PolaroidVariant[]): Photo[] {
  return Object.entries(photoModules)
    .filter(([path]) => path.includes(`/${dir}/`))
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([, mod], index) => {
      const img = mod.default
      return {
        src: img,
        alt,
        width: img.width,
        height: img.height,
        variant: variants[index] || '4x3',
      }
    })
}

Parameter meaning

Important behavior

1. getPhotos() first filters all imported images by folder name.
2. It then sorts the matched file paths with localeCompare.
3. It creates the final Photo[] in that sorted order.
4. variants[index] is applied to the photo at the same index.
5. If one index is missing in variants, that photo falls back to '4x3'.

How the third parameter is matched

The third parameter is not random metadata. It is position-based.

For this code:

photos: getPhotos(
  '2026-03-07-botanicalGarden',
  'Early spring cherry blossoms at the botanical garden',
  ['3x4', '3x4', '3x4', '3x4', '3x4', '3x4']
)

Assume the folder src/assets/photos/2026-03-07-botanicalGarden/ contains these files after sorting:

01.webp
02.webp
03.webp
04.webp
05.webp
06.webp

Then the mapping is:

So if you want the first photo in the folder to use 3x4, the first item in the third array must be 3x4.

If you want mixed ratios, write them in the same order as the sorted files:

photos: getPhotos('2025-03-01-dongqianhu', 'Ningbo - Dongqian Lake', ['4x5', '1x1', '4x3'])

That means:

• first sorted image -> 4x5
• second sorted image -> 1x1
• third sorted image -> 4x3

If the folder contains more photos than the array length:

photos: getPhotos('example-folder', 'Example alt', ['3x4', '4x5'])

Then:

• first sorted image -> 3x4
• second sorted image -> 4x5
• third sorted image and later -> default 4x3

Supported variants

PolaroidVariant is currently:

export type PolaroidVariant = '1x1' | '4x5' | '4x3' | '3x4' | '9x16'

Current size mapping in src/components/photos/PolaroidCard.tsx:

const polaroidVariants: Record<PolaroidVariant, string> = {
  '1x1': 'w-20 h-20',
  '4x5': 'w-20 h-24',
  '4x3': 'w-20 h-16',
  '3x4': 'w-[4.5rem] h-24',
  '9x16': 'w-20 h-32',
}

How to add a new timeline entry

1. Create a folder under src/assets/photos/, for example 2026-04-01-spring-walk.
2. Put image files into that folder.
3. Make sure the file names are in the order you want after sorting.
4. Add one item to PhotosList in src/lib/photos.ts.
5. Pass the third argument to getPhotos() in the same order as the sorted files.

Example:

{
  title: 'Spring Walk',
  icon: { type: 'emoji', value: '🌿' },
  description: 'A short walk with a camera.',
  date: '2026-04-01',
  travel: '',
  photos: getPhotos(
    '2026-04-01-spring-walk',
    'Photos from a spring walk',
    ['3x4', '4x3', '4x5', '4x3']
  ),
}

Notes

• alt is applied to every photo returned from the same folder.
• The order is determined by sorted file path, not by import order in the editor.
• If you rename files, the sort order may change, and the variants array will then map to different photos.