timwukp/agent-skills-best-practice

**英文** | [中文](README.zh-CN.md) # Agentic Skills 最佳实践 构建 agent skill 的最佳实践、示例和培训材料。Agent skill 是由指令、脚本和资源组成的文件夹，AI agent 会动态加载它们以提高在专业任务上的性能。 **编写一次，即可在任何兼容的 agent 上运行。** 此仓库中的每个 skill 都遵循开放的 [Agent Skills 规范](https://agentskills.io/specification)，仅使用标准字段——不包含平台私有的扩展。同一个 skill 文件夹无需修改，即可在任何实现该规范的平台上运行：Kiro（IDE 和 CLI）、Claude Code、Claude.ai、Claude API 以及其他兼容的 agent。此仓库中的 skill 已在 Kiro 和 Claude Code 上完成了端到端的验证（参见 [TESTING.md](TESTING.md)）。 本仓库专为以 [Kiro](https://kiro.dev) 为主要环境学习构建 skill 的 **AWS SA 和开发者** 设计，但这里没有任何锁定——纯指令的 skill 是完全可移植的，而少数捆绑了可执行 `scripts/` 的 skill 则额外需要允许代码执行的平台及其声明的依赖项。 ## 旗舰 Skill 两款经过实战检验的 skill，均针对真实的 AWS 基础设施进行了端到端验证： ### 🏗️ [agentcore-harness-builder](skills/skills/agentcore-harness-builder/) — 构建 AWS Bedrock AgentCore Harness agent 端到端构建生产级 **AWS Bedrock AgentCore Harness** agent：声明式模型 + prompt、Memory、内置 Browser/Code Interpreter、Gateway/MCP 工具、内联函数、Skills、Observability、Evaluations、Identity、Policy 等。针对真实的 AWS API 进行了实战测试——它编码了约 10 个经内省验证的 API 陷阱（apiFormat、optionalValue per-field、allowedTools、opus-4.8 inference rules 等），以及 [Live View human-in-the-loop SSO 登录变通方案](skills/skills/agentcore-harness-builder/references/browser-auth.md)，确保你的 agent 在第一次部署时就能正常运行，而不是试到第十次才成功。 ### 🦊 [gitlab-ci-kiro-pipeline](skills/skills/gitlab-ci-kiro-pipeline/) — 使用 Kiro CLI headless + MCP 的 AI 驱动 GitLab CI/CD 构建 GitLab CI/CD pipeline（`.gitlab-ci.yml`），在每个 merge request 上以 **headless 模式运行 Kiro CLI** 作为 AI 审查者：AI 代码审查、config-drift 检测、通过机器可读的判定行进行 duplication-sync **merge gating**、变更影响分析——包含 12 个带有测试过 prompt 的作业配方和一个完整的 pipeline 模板。包括 **CI 中的 MCP server 集成**（SonarQube SAST、AWS Knowledge、任何客户 MCP server）：`--require-mcp-startup` fail-fast、`@server` 工具信任，以及在实际 MR pipeline 中实时验证的无基础设施冒烟测试。补充了通用的 [cicd-pipeline](skills/skills/cicd-pipeline/) skill。 ## 快速开始 **新来这里？** 请按照 [Kiro Skills 快速开始](QUICKSTART.md) 的指引，在 5 分钟内从零开始创建一个可用的 skill。 要将此仓库中的 skill 一步安装到 Kiro 中： ``` ./install.sh hello-world api-design git-workflow # or ./install.sh --all ``` ## 内容详情 - **示例 Skill**：`skills/skills/` 中的生产级示例（创意、技术、企业） - **Hello World**：`skills/skills/hello-world/` 中用于验证你设置的最小可用 skill - **Skills 研讨会**：`skills-workshop/` 中为期 6 小时的动手培训 - **Skill 模板**：`skills/template/` 中用于创建新 skill 的起点 - **软件工程 Skill**：8 项涵盖代码审查、Git 工作流、API 设计、Docker Compose 生成、数据库 schema 设计、CI/CD pipeline、Terraform 模块和 Python 项目设置的实用工作流 skill - **安全 SDLC Skill**：5 项 Scrum + DevSecOps 角色 skill（威胁建模、安全/用户故事编写、包含安全债务的 sprint 规划、sprint 安全审查） - **FSI 合规性**：合规性检查器，将变更映射到 PCI-DSS v4.0 和 MAS TRM 控制，并附带按领域组织的参考文件 - **云架构**：带有按支柱（安全、可靠性、成本、性能、运营、可持续性）划分的参考文件的 AWS Well-Architected 审查 skill - **AI 采用 Skill**：code-standards-adopter（让 AI 编写的代码符合你团队的风格）和 legacy-code-testing（重构前的特征化测试） - **AWS AI Agent 基础设施**：agentcore-harness-builder — 参见上文的[旗舰 Skill](#flagship-skills) - **Agentic CI/CD**：gitlab-ci-kiro-pipeline — 带有 Kiro CLI headless AI 审查作业和 MCP server 集成的 GitLab pipeline；参见上文的[旗舰 Skill](#flagship-skills) ## 仓库结构 ``` . ├── QUICKSTART.md # 5-minute quickstart guide ├── skills/ # Skills collection (from Anthropic) │ ├── skills/ # Individual skill folders │ │ ├── hello-world/ # Minimal example (start here) │ │ ├── skill-creator/ # Build skills with AI assistance │ │ ├── frontend-design/ # Example: creative skill │ │ ├── mcp-builder/ # Example: MCP integration │ │ ├── api-design/ # Example: engineering workflow skill │ │ └── ... │ ├── template/ # Blank skill template │ └── README.md # Skills collection docs ├── skills-workshop/ # Workshop training materials │ ├── 01-fundamentals/ # Progressive disclosure, YAML, structure │ ├── 02-planning-design/ # Use cases, descriptions, triggers │ ├── 03-testing-iteration/ # Testing strategies │ ├── 04-distribution-sharing/ │ ├── 05-patterns-troubleshooting/ │ ├── 06-resources-references/ │ └── hands-on-labs/ # 3 hands-on labs (beginner to advanced) ``` ## 学习路径 | 步骤 | 内容 | 时间 | |------|------|------| | 1 | [快速开始](QUICKSTART.md) — 复制 hello-world，查看其触发过程 | 5 分钟 | | 2 | [研讨会 第1章](skills-workshop/01-fundamentals/slides.md) — 了解渐进式信息披露 | 60 分钟 | | 3 | [实验 1](skills-workshop/hands-on-labs/LAB1-SIMPLE-SKILL.md) — 构建真实的 skill | 30 分钟 | | 4 | 浏览 `skills/skills/` — 研究生产模式 | 自定进度 | | 5 | [完整研讨会](skills-workshop/README.md) — 完成培训 | 6 小时 | ## 平台兼容性 此仓库中的 skill **在构建时就考虑了可移植性**：它们仅使用 [Agent Skills 规范](https://agentskills.io/specification)（`name`、`description`、`license`、`metadata`）的标准字段，且不包含平台私有扩展。任何实现该规范的 agent 都可以加载它们。已验证或有文档记录的平台： | 平台 | 安装位置 | 文档 | |----------|-----------------|------| | **Kiro IDE** | `~/.kiro/skills/`（全局）或 `.kiro/skills/`（工作区） | [kiro.dev/docs/skills](https://kiro.dev/docs/skills/) | | **Kiro CLI** | `~/.kiro/skills/` | [kiro.dev/docs/skills](https://kiro.dev/docs/skills/) | | **Claude Code** | `~/.claude/skills/` 或通过插件市场 | [skills/README.md](skills/README.md) — 已进行端到端验证，参见 [TESTING.md](TESTING.md) | | **Claude.ai** | 作为自定义 skill 上传 | [Claude Skills 指南](https://support.claude.com/en/articles/12512180-using-skills-in-claude) | | **Claude API** | 通过 Skills API | [Skills API 快速开始](https://docs.claude.com/en/api/skills-guide) | | **其他兼容规范的 agent** | 视平台而定 | [agentskills.io](https://agentskills.io/specification) | 可移植性注意事项： - **纯指令 skill**（安全 SDLC、FSI 合规性、云架构和大多数工程 skill）是完全可移植的——它们是纯粹的 markdown，除了规范支持外，不需要主机的任何东西。 - **捆绑可执行 `scripts/` 的 skill**（例如测试生成器、webapp-testing）额外需要允许代码执行的平台以及每个 skill 声明的依赖项。 - 激活行为可能因平台而略有不同（每个 agent 都会决定何时与描述匹配）；我们 skill 描述中的触发措辞已在 Claude Code 上经过测试，并遵循 Kiro 的指导。 ## Kiro 功能 ### Steering 文件 Kiro 支持项目根目录下 `.kiro/steering/` 目录中的 **steering 文件**。这些是 markdown 文件，用于定义 Kiro 在你的仓库中工作时所遵循的全项目约定、编码标准和行为规则。 此仓库使用 `.kiro/steering/conventions.md` 来强制执行所有贡献的一致格式、命名和结构。 ### 项目级 Skill Skill 可以在两个级别上安装： | 范围 | 位置 | 用例 | |-------|----------|----------| | **项目级** | `.kiro/skills/`（提交到仓库） | 与所有贡献者共享；项目特定的工作流 | | **全局** | `~/.kiro/skills/`（用户主目录） | 个人生产力 skill；跨项目工具 | 项目级 skill 随你的代码库进行版本控制，并自动提供给每个克隆该仓库的人。 ### Kiro Web [Kiro Web](https://kiro.dev) 提供基于浏览器的访问，具有两种交互模式： - **Vibe 模式** - 对话式迭代，你和 Kiro 来回交流以完善输出 - **Autonomous 模式** - Kiro 独立处理任务，完成后再向你报告 两种模式都支持 skill，以提供增强的、特定领域的协助。 ## 持续集成 GitHub Actions 会在每次推送和 pull request 时验证所有 skill。该工作流会检查 SKILL.md frontmatter、必填字段和命名约定。有关详细信息，请参见 `.github/workflows/validate-skills.yml`。 ## 测试 Skill 通过四个层次进行测试——静态规范验证、盲测触发路由、独立评分的任务执行，以及在 Claude Code 上的真实环境验证。请参见 [TESTING.md](TESTING.md) 了解方法论和记录的结果。 ## 参考文档 - [Agent Skills 规范](https://agentskills.io/specification) - [Kiro Skills 文档](https://kiro.dev/docs/skills/) - [Claude Skills 概述](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) - [Claude Skills 最佳实践](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) - [Anthropic Skills 仓库](https://github.com/anthropics/skills) ## 仓库指南 - 禁止 PDF、PPTX、DOCX 或其他二进制文档文件（已被 gitignored） - 禁止 PII 或客户数据 - 禁止硬编码的凭证或机密 - 所有内容必须在开源许可下（MIT 或 Apache 2.0；参见下文的许可说明） ## 许可说明 此仓库包含两个开源许可下的内容： | 内容 | 许可证 | |---------|---------| | 仓库文档、研讨会材料、工程 skill、工具 | [MIT](LICENSE) | | 从 [anthropics/skills](https://github.com/anthropics/skills) 导入的示例 skill（例如 skill-creator、mcp-builder、canvas-design） | Apache 2.0 — 参见每个 skill 的 `LICENSE.txt` | Anthropic 源代码可用的文档 skill（docx、pdf、pptx、xlsx）**未**包含在此处；请使用官方的 [anthropics/skills](https://github.com/anthropics/skills) 仓库获取这些内容。

标签：AI智能体, AWS, Claude, CVE检测, DevSecOps, DPI, SOC Prime, 上游代理, 开发工具, 提示词工程, 策略决策点