English | 中文

Agentic Skills Best Practices

Best practices, examples, and training materials for building agent skills. Agent skills are folders of instructions, scripts, and resources that AI agents load dynamically to improve performance on specialized tasks.

Write once, run on any compatible agent. Every skill in this repo follows the open Agent Skills specification using only standard fields — no platform-private extensions. The same skill folder works, unmodified, on any platform that implements the spec: Kiro (IDE and CLI), Claude Code, Claude.ai, the Claude API, and other compatible agents. Skills from this repo have been verified end-to-end on both Kiro and Claude Code (see TESTING.md).

This repo is designed for AWS SAs and developers learning to build skills with Kiro as the primary environment, but nothing here locks you in — the instruction-only skills are fully portable, and the few skills that bundle executable scripts/ additionally require a platform that permits code execution and their listed dependencies.

Flagship Skills

Three skills with evidence behind them. The first two were validated end-to-end against real AWS infrastructure; the third is the only skill here that ships its own enforcement — a gate that can refuse a merge — together with the tests, signed releases, and documented limits that a control like that has to earn.

🏗️ agentcore-harness-builder — build AWS Bedrock AgentCore Harness agents

Builds production-ready AWS Bedrock AgentCore Harness agents end to end: declarative model + prompt, Memory, built-in Browser/Code Interpreter, Gateway/MCP tools, inline functions, Skills, Observability, Evaluations, Identity, Policy, and more. Battle-tested against the real AWS API — it encodes ~10 introspection-verified API gotchas (apiFormat, optionalValue per-field, allowedTools, opus-4.8 inference rules, …) plus the Live View human-in-the-loop SSO login workaround, so your agent works on the first deploy instead of the tenth.

🦊 gitlab-ci-kiro-pipeline — AI-powered GitLab CI/CD with Kiro CLI headless + MCP

Builds GitLab CI/CD pipelines (.gitlab-ci.yml) that run Kiro CLI in headless mode as an AI reviewer on every merge request: AI code review, config-drift detection, duplication-sync merge gating via machine-readable verdict lines, change-impact analysis — 12 job recipes with tested prompts and a complete pipeline template. Includes MCP server integration in CI (SonarQube SAST, AWS Knowledge, any customer MCP server): --require-mcp-startup fail-fast, @server tool trusting, and a no-infrastructure smoke test validated live in real MR pipelines. Complements the generic cicd-pipeline skill.

⚖️ ai-native-sdlc — an SDLC loop that is enforced, not merely advised

Most process skills tell an agent what good practice looks like and hope. This one runs a change as a loop of committed, machine-readable artifacts — intent.md → spec.md → plan.md → diff+tests → PR + REVIEW.md → bands.yaml → new intent.md — where each stage's output is the next stage's input, and then makes the ordering enforceable in two layers:

• a `PreToolUse` hook at write time, which fails open (a buggy gate must never stop you editing files), and
• a CI gate at merge time, which fails closed.

That asymmetry is deliberate and load-bearing: the local layer is a fast warning, the CI layer is the actual control. The gate refuses a skipped stage, an unfilled template placeholder, a source change no accepted plan names, and an artifact claiming approval without a distinct author and approver.

What makes it flagship is that the enforcement is held to the standard it imposes:

• Mutation-proven tests — 6 suites plus mutation_proof.py, which breaks the gate 36 different ways and requires a test to go red for each. This is not a coverage number: it caught a substring match that let not-accepted pass as accepted, and a cross-line regex that read the next line when a field was empty. A green suite nobody has watched fail is not evidence.
• Verifiable releases — the gate is a script granted authority over merges, so releases ship a CycloneDX SBOM, Sigstore keyless signatures and SLSA build provenance, and verify_gate_integrity.sh pins the expected signer to this repository's release workflow.
• A threat model for its own attack surfaces — references/threat-model.md covers the two it introduces: an LLM reading an attacker-controlled PR diff in CI, and a hook that runs on every write. Prompt injection is treated as contained by least privilege, not solved.
• Honest limits, up front — references/limitations.md states plainly what a green gate does not mean. Read it before adopting this as a compliance control: an administrator can still bypass the gate without an org-level ruleset, and no gate can judge whether an eval is any good. That one is a permanent limitation, not a roadmap item.

Also see COMPATIBILITY.md — because a tool whose output is a policy decision can start failing builds that were fine yesterday, breaking changes follow a warning-first release, a migration note, and a six-month support window.

Quickstart

New here? Follow the Kiro Skills Quickstart to go from zero to a working skill in 5 minutes.

To install skills from this repo into Kiro in one step:

./install.sh hello-world api-design git-workflow   # or ./install.sh --all

What's Inside

• Example Skills: Production-quality examples in skills/skills/ (creative, technical, enterprise)
• Hello World: Minimal working skill to verify your setup in skills/skills/hello-world/
• Skills Workshop: 6-hour hands-on training in skills-workshop/
• Skill Template: Starting point for new skills in skills/template/
• Software Engineering Skills: 8 practical workflow skills covering code review, Git workflow, API design, Docker Compose generation, database schema design, CI/CD pipelines, Terraform modules, and Python project setup
• Secure SDLC Skills: 5 Scrum + DevSecOps role skills (threat modeling, security/user story writing, sprint planning with security debt, sprint security review)
• FSI Compliance: compliance checker mapping changes to PCI-DSS v4.0 and MAS TRM controls, with domain-organized reference files
• Cloud Architecture: AWS Well-Architected review skill with per-pillar reference files (security, reliability, cost, performance, operations, sustainability)
• AI Adoption Skills: code-standards-adopter (make AI-written code match your team's style) and legacy-code-testing (characterization tests before refactoring)
• AWS AI Agent Infrastructure: agentcore-harness-builder — see Flagship Skills above
• Agentic CI/CD: gitlab-ci-kiro-pipeline — GitLab pipelines with Kiro CLI headless AI review jobs and MCP server integration; see Flagship Skills above
• Enforceable SDLC: ai-native-sdlc — the artifact loop plus a write-time hook and a merge-time CI gate that actually refuse out-of-order work, with mutation-proven tests, signed releases, and a published limitations file; see Flagship Skills above

Looking for the document skills (docx, pdf, pptx, xlsx)? Those are Anthropic's source-available (not open source) production skills. They were removed from this repo to keep all content under open-source licenses — find them in the official anthropics/skills repository.

Repository Structure

.
├── 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)

Learning Path

Platform Compatibility

Skills in this repo are portable by construction: they use only the standard fields of the Agent Skills specification (name, description, license, metadata) and no platform-private extensions. Any agent that implements the spec can load them. Platforms verified or documented:

Portability notes:

• Instruction-only skills (the Secure SDLC, FSI Compliance, Cloud Architecture, and most engineering skills) are fully portable — they are plain markdown and need nothing from the host beyond spec support.
• Skills bundling executable `scripts/` (e.g. test generators, webapp-testing) additionally require a platform that permits code execution and the dependencies each skill declares.
• Activation behavior can differ slightly per platform (each agent decides when a description matches); the trigger phrasing in our skill descriptions is tested on Claude Code and follows Kiro's guidance.

Kiro Features

Steering Files

Kiro supports steering files in the .kiro/steering/ directory at your project root. These are markdown files that define project-wide conventions, coding standards, and behavioral rules that Kiro follows whenever it works in your repository.

This repo uses .kiro/steering/conventions.md to enforce consistent formatting, naming, and structure across all contributions.

Project-Level Skills

Skills can be installed at two levels:

Project-level skills are version-controlled with your codebase and automatically available to everyone who clones the repo.

Kiro Web

Kiro Web provides browser-based access with two interaction modes:

• Vibe mode - Conversational iteration where you and Kiro go back and forth refining outputs
• Autonomous mode - Kiro works independently on tasks, reporting back when complete

Both modes support skills for enhanced, domain-specific assistance.

Contributing

See CONTRIBUTING.md for guidelines on adding new skills, code standards, and the pull request process.

Continuous Integration

GitHub Actions validates all skills on every push and pull request. The workflow checks SKILL.md frontmatter, required fields, and naming conventions. See .github/workflows/validate-skills.yml for details.

Testing

Skills are tested in four layers — static spec validation, blind trigger routing, independently graded task execution, and real-environment verification on Claude Code. See TESTING.md for the methodology and recorded results.

Reference Documentation

• Agent Skills Specification
• Kiro Skills Documentation
• Claude Skills Overview
• Claude Skills Best Practices
• Anthropic Skills Repository

Repository Guidelines

• No PDF, PPTX, DOCX, or other binary document files (gitignored)
• No PII or customer data
• No hardcoded credentials or secrets
• All content must be under an open-source license (MIT or Apache 2.0; see Licensing below)

Licensing

This repository contains content under two open-source licenses:

Anthropic's source-available document skills (docx, pdf, pptx, xlsx) are not included here; use the official anthropics/skills repository for those.