Discussion: how should this skill work with aws-cdk's AGENTS.md?

[mazyu36]

Context

aws/aws-cdk#37565 added AGENTS.md at the root of the aws-cdk repo. It is loaded automatically by AI agents working in the aws-cdk checkout and acts as the canonical contributor guide.

It seems worth thinking about how this skill should account for AGENTS.md going forward, so that the two remain complementary rather than diverge.

One idea (not a proposal)

One direction would be to have each SOP whose subagent runs inside the aws-cdk checkout include a short instruction to read and follow aws-cdk's AGENTS.md before doing its work — since the substantive rules already live there.

But it's not clear this is the right shape. For example, the SOPs carry entry-level templates and JSII gotchas that don't fully overlap with AGENTS.md, so a blanket "defer to AGENTS.md" may lose useful content. There are probably other options (partial linking, side-by-side, etc.).

Opening this as a discussion rather than a concrete proposal — would love input on the right direction before anyone picks up a PR.

[pahud]

@mazyu36 mazyu36 Thanks for raising this — it's an important architectural question.

I agree we should treat AGENTS.md as the canonical repo-level guide and keep the skill SOPs focused on workflow execution. Here's a clean layered approach that avoids both duplication and loss of skill-specific value:

Proposed Integration Strategy: Layered Complementary Approach

Goal: Keep AGENTS.md (repo-level canonical guide) and the contribution skill's SOPs (workflow-specific) complementary without duplication or divergence.

Architecture (ASCII diagram)

aws-cdk checkout
│
├── AGENTS.md                  ← Repo-level rules (loaded by all agents)
│   • Contribution workflow overview
│   • JSII / build / testing conventions
│   • PR & review expectations
│
└── .kiro/contribution-skill/
    ├── SKILL.md
    └── references/
        ├── issue-analyst-sop.md
        ├── solution-architect-sop.md
        ├── ...
        └── review-report-generator-sop.md
            └── Each SOP contains:
                1. MANDATORY: "Read and follow AGENTS.md first"
                2. Skill-specific templates & checklists
                3. Deliverable format requirements

How it works in practice

1. Every SOP starts with an explicit prerequisite step:

   **MANDATORY PRE-READ**
   Read `AGENTS.md` at the root of the aws-cdk checkout.
   Follow its rules for contribution process, style, and testing.
   

2. SOPs retain their unique value:

   • Detailed phase-by-phase instructions
   • Exact deliverable filenames and structure
   • Skill-specific gotchas and templates

3. Result: No conflict, maximum coverage, easy maintenance.

This keeps both AGENTS.md (repo-level canonical rules) and the skill SOPs (phase-specific workflows & templates) focused on their respective layers while ensuring contributors always receive the complete picture without duplication or gaps.

[pahud]

requesting inputs from @gudipati as well.

[gudipati]

From what I understand, Kiro / other agents already pick up the AGENTS.md file and use it with the skill right now.
We need to look at whether to remove duplication between the skill SOPs and AGENTS.md so they work well together.
This also needs to be thoroughly tested so we don't degrade the AGENTS.md (for any agent task) or the contribution skill.