restructure kiro power as power or skill

[yaythomas]

Following on from PR discussion here, #5

Under discussion is:

1. Migrate Power to Skill
2. how much to trim from the current kiro agent, if anything. there is currently a lot of replicated content and already a problem with drift and inaccurate machine generated content in the power. The counterpoint is that local is more reliable in case GenAI decides not to fetch link.

1. skill vs power

Proposal:

1. SKILL.md — the portable, agent-consumable format. Works in Kiro CLI agents,
   and the SKILL.md format is also recognized by Claude Code. This is where the
   rules, patterns, and bundled references live.
2. POWER.md — a thin Kiro IDE wrapper that provides keyword activation,
   optional MCP config, and points to steering files. The steering files can
   contain the same content as the skill's reference files.

Point is to author the content once as a skill structure (SKILL.md + references/), then create a thin POWER.md that maps to the same steering content for Kiro IDE distribution. The content is shared, the packaging differs.

2 Lean Local vs All Local

Recommended Tiered Approach for the Durable Functions Skill

Tier 1: Bundled in SKILL.md (~3KB)

Content the agent will hallucinate without and that rarely changes:

• The 4 replay rules (non-deterministic code in steps, no nesting, closure
  mutations lost, side effects repeat)
• Step semantics (AtLeastOnce vs AtMostOnce) with correct defaults
• Package names + install commands for TS, Python, Java
• API shape comparison table — one row per operation (step, wait, callback,
  etc.), one column per language, just method signatures
• Qualified ARN invocation requirement
• IAM managed policy name
• Testing class/runner names per language
• context.logger for replay-safe logging
• Routing table: "when the user asks about X → load references/Y.md"

Tier 2: Bundled in references/ (~2-3KB)

Curated skeletons loaded on demand. Enough to anchor the API shape, not full tutorials:

Handler and test skeletons.

   examples/
     handler.ts
     handler.py
     Handler.java
     handler.test.ts
     handler_test.py
     HandlerTest.java

Deployment-gotchas.md — the non-obvious stuff (qualified ARN, IAM policy attachment, IaC snippets for the durable-specific config only)

Tier 3: Links to living docs (in SKILL.md footer)

Everything else — the agent fetches when it needs detail beyond the
skeletons:

• https://docs.aws.amazon.com/durable-execution/
  (https://docs.aws.amazon.com/durable-execution/) — full SDK reference,
  operations, error handling, patterns
• SDK GitHub repos (examples directories)
• Lambda service docs (quotas, monitoring, security)

What Gets Cut

The current 11 steering files (~106KB) collapse into 3 small reference files (~2-3KB). The content that was in those files either:

• Moves to Tier 1 as a concise rule or table row
• Gets replaced by a link to the docs site where it's already maintained
• Gets dropped because it was duplicated across multiple steering files (@yaythomas main review feedback from docs(power): clarify replay safety and step semantics #5)

[yaythomas]

The alternative, proposed by @bfreiberg here #5 (comment), is to prefer content and references fully bundled locally.

[bfreiberg]

We could test both approaches using evals to better understand the resulting behavior.