播面

根据 Anthropic 发布的 Agent Skills 开放标准（agentskills.io，目前已被 Claude Code、LangChain、OpenAI Codex 等广泛采用），一个标准且功能完善的 Agent Skill 本质上就是一个结构化的文件夹。

它的设计哲学是“渐进式披露（Progressive Disclosure）”：核心文件保持精简，辅助资源按需读取。

一个标准的、生产级别的 Agent Skill 文件夹通常包含以下核心结构：

my-awesome-skill/          # 技能的根目录（通常放在项目的 .claude/skills/ 下）
├── SKILL.md               # 【必填】技能的“大脑”，包含元数据和核心指令
├── scripts/               # 【可选】技能的“双手”，存放可执行的自动化脚本
│   ├── process_data.py
│   └── validate.sh
├── references/            # 【可选】技能的“外脑”，存放长篇的参考文档和上下文
│   ├── api-guide.md
│   └── coding-standards.md
└── templates/             # 【可选】技能的“模具”，存放静态资源或输出模板
    └── report_template.html

以下是各个文件和子目录的详细功能解析：

1. SKILL.md（核心必填文件：大脑与路由）

这是整个技能中唯一必不可少的文件。大模型通过读取它来决定是否调用技能，以及如何执行技能。它分为两部分：

• YAML 前言（Frontmatter）：这是技能的“身份证”。系统启动时只会加载这一小段元数据。
  • name: 技能的唯一标识符（例如 code-review）。
  • description: 最重要的字段。用自然语言描述这个技能的作用。大模型完全依靠这段描述来“自动感知”何时该触发此技能。
• Markdown 正文（Body）：这是技能的“SOP（标准作业程序）”。当技能被触发时，系统会加载这部分内容。你通常会在这里编写：
  • 执行步骤（Workflow）：例如“第1步：运行测试；第2步：分析报错；第3步：修改代码”。
  • 约束条件（Constraints）：例如“切勿修改数据库结构”、“保持日志输出格式不变”。
  • 资源指针：告诉 AI 在什么情况下应该去读取 scripts/ 或 references/ 目录下的辅助文件。

2. scripts/ 目录（可选：可执行代码与工具）

纯文本提示词的局限在于“只能说不能做”，而 scripts/ 目录赋予了 Agent 行动能力。
你可以在这里放入 Python、Bash 或 Node.js 脚本。在 SKILL.md 中，你可以指令 AI 去执行这些脚本。

• 典型场景：
  • validate.py：AI 修改完代码后，必须运行该脚本，如果不通过则自我纠错重试。
  • fetch_jira.js：一个用来调用内部 API 获取工单详情的脚本，AI 可以运行它来获取动态上下文。

3. references/ 目录（可选：知识库与长文本）

这是解决大模型“上下文窗口爆满”和“幻觉”的关键设计。不要把几万字的 API 手册直接贴在 SKILL.md 里。

• 如何运作：你把又长又复杂的文档（如 company_ui_guidelines.md 或 stripe_api_v2.md）放在这个目录下。
• 按需加载：在 SKILL.md 中写明：“如果你需要编写前端样式，请使用 read_file 工具读取 references/company_ui_guidelines.md。” 这样，AI 只有在真正需要时才会加载这些厚重的文档，极大节省了 Token 且提高了专注度。

4. templates/ 或 assets/ 目录（可选：静态资源）

当你希望 AI 的输出符合某种严格的物理格式时，可以使用此目录。

• 典型场景：
  • 存放一个 monthly_report.csv 的空表头模板，要求 AI 分析完数据后，按照这个模板的列格式生成最终文件。
  • 存放公司的 PPT 模板或标准 HTML 骨架文件。

💡 最佳实践建议

1. 控制 SKILL.md 的长度：业界经验是尽量将 SKILL.md 保持在 500 行以内。如果超过这个长度，说明你的指令太冗长了，应该将细节拆分到 references/ 目录下，让 AI 按需阅读。
2. 相对路径引用：在 SKILL.md 中引用辅助脚本或文档时，一律使用相对于技能文件夹的相对路径（例如 python3 scripts/validate.py），这确保了你的技能包可以直接打成 .zip 压缩包分享给同事，或者无缝上传到云端使用。
3. 闭环自测（Self-healing）：一个高级的技能结构，总是会在 scripts/ 里带上验收脚本，并在 SKILL.md 里强行规定 AI 必须完成自测才能结束任务，这是区分“玩具 Prompt”和“企业级 Agent Skill”的分水岭。