Amazon Q Customization Hub

A modular skill framework for Amazon Q Developer — because an AI coding assistant is only as good as the discipline you give it.

Overview

This repository is a customization hub for Amazon Q Developer. It extends Amazon Q with structured skill packs that enforce disciplined engineering practices through rules, execution scripts, and prompt patterns.

Each skill pack lives in .amazonq/ and follows a consistent tripartite structure:

.amazonq/
├── rules/{skill}.md              # Golden Rules — what the skill enforces
├── scripts/{skill}/execute.sh    # Execution Scripts — what the user runs
├── prompts/{skill}.md            # Structured Prompts — how to invoke each skill
└── setup.sh                      # Symlinks prompts to ~/.aws/amazonq/prompts/

Current skill packs:

| Pack | Skills | Status | |-----------------------------|-------------------------------------------------------------|-------------| | Superpowers | 14 skills — TDD, debugging, planning, code review, and more | ✅ Installed |

Quick Start

# 1. Clone
git clone <repo-url> && cd amazonq

# 2. Install prompts globally
bash .amazonq/setup.sh

# 3. Verify installation
bash .amazonq/setup.sh --check

Then in Amazon Q chat:

I want to use the brainstorming superpower

How It Works

Amazon Q Developer reads rules and prompts but cannot run scripts directly in IDE chat. The framework bridges this gap with the Script Handoff Pattern:

┌──────────────────────────────────────────────────┐
│  User: "I want to use the {skill} superpower"    │
└──────────────────────┬───────────────────────────┘
                       ▼
        ┌─────────────────────────────┐
        │  Amazon Q reads:            │
        │  1. .amazonq/rules/{skill}  │  ← Golden Rules
        │  2. Current project context │  ← Files, imports, tests
        │  3. Generates structured    │
        │     plan + code changes     │
        └──────────────┬──────────────┘
                       ▼
        ┌─────────────────────────────┐
        │  "Execution Handoff"        │
        │                             │
        │  bash .amazonq/scripts/     │  ← User copies + runs
        │    {skill}/execute.sh       │
        │                             │
        │  User pastes output back    │  ← Amazon Q continues
        └─────────────────────────────┘

Superpowers

Ported from obra/superpowers — an agentic skills framework originally built for Claude Code, adapted for Amazon Q Developer's rule/script/prompt pattern.

Design & Planning

| Skill | What it enforces | Invocation | |---------------------|---------------------------------------------------|----------------------------------------| | Brainstorming | No code without an approved design | "use the brainstorming superpower" | | Writing Plans | 2-5 min RED-GREEN-REFACTOR tasks, no placeholders | "use the writing plans superpower" | | Executing Plans | Follow steps exactly, stop when blocked | "use the executing plans superpower" |

Quality & Testing

| Skill | What it enforces | Invocation | |------------------------------------|---------------------------------------------------|---------------------------------------------| | Test-Driven Development | No production code without a failing test first | "use the TDD superpower" | | Systematic Debugging | Four-phase root cause investigation before fixing | "use the systematic debugging superpower" | | Verification Before Completion | Evidence-based claims — no "should work" | "use the verification superpower" |

Collaboration

| Skill | What it enforces | Invocation | |----------------------------|--------------------------------------------------------------|-----------------------------------------------| | Requesting Code Review | Review after each major step with precise context | "use the requesting code review superpower" | | Receiving Code Review | Technical evaluation, not performative agreement | "use the receiving code review superpower" | | Finishing a Branch | Structured 4-option completion (merge / PR / keep / discard) | "use the finishing branch superpower" |

Orchestration

| Skill | What it enforces | Invocation | |-------------------------|----------------------------------------------|----------------------------------------| | Subagent-Driven Dev | Fresh agent per task with two-stage review | "use the subagent superpower" | | Parallel Agents | One agent per independent problem domain | "use the parallel agents superpower" | | Git Worktrees | Isolated workspaces with safety verification | "use the git worktrees superpower" |

Core Principles

These seven principles govern all work and are enshrined in the project constitution:

| # | Principle | One-liner | |-----|----------------------------|-------------------------------------------------------------------------| | I | Test-First | No production code without a failing test first | | II | Design Before Code | "Too simple to design" is where most work gets wasted | | III | Evidence Before Claims | Run the command, read the output, then claim the result | | IV | Systematic Root-Cause | No fixes without investigation. 3+ failures → question the architecture | | V | Bite-Sized Tasks | 2-5 minutes each. One action per step. Complete code in every step | | VI | Script Handoff | Amazon Q can't run scripts — present exact commands, wait for output | | VII | Simplicity & YAGNI | Start simple. No features until needed |

Project Structure

.
├── .amazonq/
│   ├── rules/                     # Golden Rules (14 skill files)
│   ├── scripts/                   # Execution scripts (14 directories)
│   ├── prompts/                   # Structured prompts (14 files)
│   └── setup.sh                   # Install/check/clean symlinks
├── GUIDELINE.md                   # Runtime development guidance
└── README.md

Setup Script

bash .amazonq/setup.sh            # Install — symlinks to ~/.aws/amazonq/prompts/
bash .amazonq/setup.sh --check    # Verify installation status
bash .amazonq/setup.sh --clean    # Remove all symlinks

Idempotent — safe to re-run. Existing non-symlink files are never overwritten.

Adding New Skills

Use the writing-skills superpower to scaffold a new skill:

bash .amazonq/scripts/writing-skills/execute.sh "my-new-skill"
bash .amazonq/setup.sh  # Re-deploy prompts

Or manually create the three files:

.amazonq/rules/{skill}.md — Golden Rules
.amazonq/scripts/{skill}/execute.sh — Execution script
.amazonq/prompts/{skill}.md — Structured prompt

Amazonq Customization Hub

Install / Use

README