agent-skills AGENTS.md

AGENTS 指南

这个文件为在本仓库中工作的 AI 编码代理（Claude Code、Cursor、Copilot、Antigravity 等）提供指引。

仓库概览

这是一个面向资深软件工程师的 Claude.ai / Claude Code skills 集合。Skills 是被打包好的说明和脚本，用来扩展 Claude 以及其他编码代理的能力。

创建一个新技能

目录结构

skills/
  {skill-name}/           # kebab-case directory name
    SKILL.md              # Required: skill definition
    scripts/              # Required: executable scripts
      {script-name}.sh    # Bash scripts (preferred)
  {skill-name}.zip        # Required: packaged for distribution

命名约定

• Skill 目录：使用 kebab-case，例如 web-quality
• SKILL.md：必须全大写，文件名必须严格是这个
• Scripts：使用 kebab-case.sh，例如 deploy.sh、fetch-logs.sh
• Zip 包：文件名必须与目录名完全一致，即 {skill-name}.zip

SKILL.md 格式

---
name: {skill-name}
description: {一句话说明这个 skill 何时使用。应包含类似 "Deploy my app"、"Check logs" 这样的触发短语。}
---

# {Skill Title}

{用简短文字说明这个 skill 的作用。}

## How It Works

{编号列表，解释这个 skill 的工作流程}

## Usage

```bash
bash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]

Arguments:

• arg1 - Description (defaults to X)

Examples: {展示 2-3 个常见用法}

Output

{展示用户会看到的输出示例}

Present Results to User

{给 Claude 的呈现模板，说明应该如何把结果展示给用户}

Troubleshooting

{常见问题与解决方式，尤其是网络 / 权限类错误}

### 上下文效率最佳实践

Skills 是按需加载的：启动时只会加载 skill 的名称和描述；只有当代理判断这个 skill 相关时，完整的 `SKILL.md` 才会进入上下文。为了尽量节省上下文：

- **将 `SKILL.md` 控制在 500 行以内**，详细参考资料拆到单独文件
- **描述写得更具体**，让代理更容易判断何时激活这个 skill
- **使用渐进式披露**，把 supporting files 设计成只在需要时才读取
- **优先用脚本，不要把大段代码直接写进文档**，脚本执行本身不消耗上下文，只消耗输出
- **文件引用只适合一层深度**，从 `SKILL.md` 直接链接 supporting files

### 脚本要求

- 使用 `#!/bin/bash` shebang
- 使用 `set -e`，让脚本在出错时快速失败
- 状态信息写到 stderr，例如：`echo "Message" >&2`
- 机器可读输出，例如 JSON，写到 stdout
- 包含临时文件清理的 trap
- 脚本路径应写为 `/mnt/skills/user/{skill-name}/scripts/{script}.sh`

### 创建 ZIP 包

创建或更新一个 skill 后：

```bash
cd skills
zip -r {skill-name}.zip {skill-name}/

给最终用户安装

需要给用户说明这两种安装方式：

Claude Code：

cp -r skills/{skill-name} ~/.claude/skills/

claude.ai： 把 skill 加入项目知识库，或者直接把 SKILL.md 内容粘贴到对话中。