timwukp/agent-skills-best-practice

# GitHub Repository: timwukp/agent-skills-best-practice

**URL:** https://github.com/timwukp/agent-skills-best-practice
**Author:** timwukp
**Description:** 35 portable agent skills (Agent Skills spec) for Kiro & Claude Code: Scrum DevSecOps roles, PCI-DSS/MAS TRM compliance, AWS Well-Architected reviews — each with evals and a 4-layer tested methodology
**Homepage:** 
**Language:** Python

## Stats
- Stars: 10
- Forks: 3
- Open Issues: 0
- Commits: 118
- Created: 2026-03-09T13:46:36Z
- Updated: 2026-09-05T04:22:21Z
- Pushed: 2026-09-05T04:22:18Z

## README
**English** | [中文](README.zh-CN.md)

# 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](https://agentskills.io/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](TESTING.md)).

This repo is designed for **AWS SAs and developers** learning to build skills with [Kiro](https://kiro.dev) 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](skills/skills/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](skills/skills/agentcore-harness-builder/references/browser-auth.md), so your agent works on the first deploy instead of the tenth.

### 🦊 [gitlab-ci-kiro-pipeline](skills/skills/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](skills/skills/cicd-pipeline/) skill.

### ⚖️ [ai-native-sdlc](skills/skills/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`](skills/skills/ai-native-sdlc/scripts/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`](skills/skills/ai-native-sdlc/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`](skills/skills/ai-native-sdlc/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`](skills/skills/ai-native-sdlc/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](QUICKSTART.md) to go from zero to a working skill in 5 minutes.

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

```bash
./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](#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](#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](#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](https://github.com/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

| Step | What | Time |
|------|------|------|
| 1 | [Quickstart](QUICKSTART.md) — copy hello-world, see it trigger | 5 min |
| 2 | [Workshop Ch.1](skills-workshop/01-fundamentals/slides.md) — understand progressive disclosure | 60 min |
| 3 | [Lab 1](skills-workshop/hands-on-labs/LAB1-SIMPLE-SKILL.md) — build a real skill | 30 min |
| 4 | Browse `skills/skills/` — study production patterns | self-paced |
| 5 | [Full Workshop](skills-workshop/README.md) — complete training | 6 hours |

## Platform Compatibility

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

| Platform | Install Location | Docs |
|----------|-----------------|------|
| **Kiro IDE** | `~/.kiro/skills/` (global) or `.kiro/skills/` (workspace) | [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/` or via plugin marketplace | [skills/README.md](skills/README.md) — verified end-to-end, see [TESTING.md](TESTING.md) |
| **Claude.ai** | Upload as custom skill | [Claude Skills Guide](https://support.claude.com/en/articles/12512180-using-skills-in-claude) |
| **Claude API** | Via Skills API | [Skills API Quickstart](https://docs.claude.com/en/api/skills-guide) |
| **Other spec-compatible agents** | Per platform | [agentskills.io](https://agentskills.io/specification) |

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:

| Scope | Location | Use Case |
|-------|----------|----------|
| **Project-level** | `.kiro/skills/` (checked into repo) | Shared with all contributors; project-specific workflows |
| **Global** | `~/.kiro/skills/` (user home) | Personal productivity skills; cross-project utilities |

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

### Kiro Web

[Kiro Web](https://kiro.dev) 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](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](TESTING.md) for the methodology and recorded results.

## Reference Documentation

- [Agent Skills Specification](https://agentskills.io/specification)
- [Kiro Skills Documentation](https://kiro.dev/docs/skills/)
- [Claude Skills Overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
- [Claude Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
- [Anthropic Skills Repository](https://github.com/anthropics/skills)

## 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:

| Content | License |
|---------|---------|
| Repository docs, workshop materials, engineering skills, tooling | [MIT](LICENSE) |
| Example skills imported from [anthropics/skills](https://github.com/anthropics/skills) (e.g. skill-creator, mcp-builder, canvas-design) | Apache 2.0 — see each skill's `LICENSE.txt` |

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