BEST-PRACTICES-CONSOLIDATED.md

Kiro-to-Claude Converter: Consolidated Best Practices

All rules, checks, and metrics that govern the conversion of Kiro powers into Claude Code plugins. Sourced from 5 reference files: best-practices-checklist.md, content-adaptation-rules.md, verification-checklist.md, quality-comparison-guide.md, and skillmd-generation-guide.md.

---

A. Skill Structure (Rules 1-4)

#	Rule	Rationale
1	SKILL.md is the only required file	Claude Code loads SKILL.md to register the skill. Everything else is optional.
2	references/ must be flat (no subdirectories)	Claude Code resolves references/X.md relative to the skill root. Nested directories break path resolution.
3	Place automation scripts in scripts/	Separates executable logic from instructional content. Scripts offload fragile or repetitive tasks from the LLM.
4	Place templates and sample files in assets/	Keeps concrete output examples separate from guidance. The agent copies from assets/ rather than generating from scratch.

Required directory layout:

{skill-name}/
├── SKILL.md
├── references/
│   ├── {topic-a}.md
│   └── {topic-b}.md
├── scripts/         (optional)
│   └── {script}.sh
└── assets/          (optional)
    └── {template}.txt

---

B. Frontmatter (Rules 5-10)

#	Rule	Rationale
5	name must be 1-64 characters, lowercase letters, digits, and hyphens only	Claude Code uses the name as an identifier. Uppercase, spaces, or special characters cause registration failures.
6	name must match the skill directory name	Claude Code locates {name}/SKILL.md. A mismatch means the skill files are not found.
7	description must include trigger phrases ("Use when...")	Trigger phrases help Claude Code match user requests to skills. Without them, the skill may not activate for relevant queries.
8	description must include anti-triggers ("Don't use for...")	Anti-triggers prevent false activation. They reduce conflicts between skills with overlapping domains.
9	description must be under 1024 characters	Long descriptions are truncated in skill listings. Keep the description scannable.
10	description must be a single-line string — NEVER use YAML block scalars (>, |, >-, |-)	Claude Code's frontmatter parser does not support block scalars. Using description: > causes the skill to fail to load. The entire description must appear on one line after description: .

Correct frontmatter template:

---
name: {skill-name}
description: {1-2 sentence summary}. Use when the user asks to "{trigger 1}", "{trigger 2}", "{trigger 3}", "{trigger 4}", or "{trigger 5}". Don't use for {anti-trigger 1}, {anti-trigger 2}, or {anti-trigger 3}.
---

Deriving name: Extract from POWER.md frontmatter, or derive from directory name in kebab-case (replace spaces/underscores with hyphens, lowercase).

Deriving triggers: Extract verbs from POWER.md description. Include 3-5 common phrasings. Always include the literal skill purpose.

Deriving anti-triggers: Identify adjacent skills. Exclude execution if planning-only (and vice versa). Exclude unsupported platforms.

---

C. Progressive Disclosure (Rules 11-15c)

#	Rule	Rationale
11	SKILL.md must be under 500 lines (hard limit)	Claude Code truncates content beyond 500 lines. Anything past this point is silently ignored.
12	Target 300-400 lines for SKILL.md	Provides comprehensive guidance without hitting the limit. Leaves headroom for future edits.
13	Use Read \references/X.md`` directives for detail	Standard format Claude Code recognizes for loading reference content at runtime.
14	Every reference file must be mentioned in SKILL.md at least once	Unreferenced files are never loaded — dead content.
15	Reference files must be self-contained	The agent may load a reference in isolation. Each file must be readable without SKILL.md context.
15a	One level deep only — no subdirectories in references/	Flat structure ensures predictable path resolution.
15b	No reference file exceeds 400 lines	Large files waste agent context window. Split oversized files per Content Adaptation Rule 1.
15c	Reference files must be adapted, not raw copies	Raw copies waste the opportunity to optimize for Claude Code. Apply voice conversion, boilerplate removal, and deduplication.

SKILL.md line budget:

Section	Allocation	Notes
YAML frontmatter	3-4 lines	name + single-line description
H1 title + overview	15-25 lines	Intro paragraph + bullet list
Prerequisites	10-20 lines	MCP servers, workspace requirements
Workflow diagram	15-30 lines	ASCII art phase flow
Phase sections	~15-25 lines each	One H2 per phase file
Output structure	20-40 lines	Directory tree + behaviors
Reference Files Index	25-50 lines	Table, 1 row per reference
Extras (MCP setup)	10-30 lines	Optional

Scaling: Small powers (1-3 phases): 200-300 lines. Medium (4-6 phases): 300-400. Large (6+ phases): 350-450.

Trimming (if over 450): Shorten overview → compress phases to 3 items → merge overlapping phases → move MCP to reference → truncate diagram.

---

D. Content Adaptation (Rules CA1-CA4)

CA1: Split Oversized Files

Reference files >400 lines must be split at logical section boundaries.

File type	0-400 lines	401-800	801-1200	1200+
Phase files	No split	Split into 2 by workflow boundary	Split into 3 by section	Extract sub-topics
Reference files	No split	Split by category/service	Extract each major section	—
Support files	No split	Extract schema/template portion	—	—

Split procedure:

1. Identify split points at H2 headings or numbered boundaries
2. Create new files with shared prefix (e.g., execute-timeline.md, execute-ops.md)
3. Add brief H1 header + purpose statement to each new file
4. Update all Read directives in SKILL.md
5. Add new files to Reference Files Index
6. Verify each split file is self-contained

CA2: Remove Kiro Navigation Boilerplate

Remove these Kiro-specific patterns (automated by copy-and-transform.sh):

Pattern	Example	Detection
Phase breadcrumbs	**Phase 3 of 5**	**Phase N of M**
Input/Output Location	**Input Location:** .migration/...	Lines starting with **Input Location:** or **Output Location:**
Next/Previous navigation	**Next:** \kiro power steering/design.md``	Lines starting with **Next:** or **Previous:**
Standalone horizontal rules	---	--- lines that are NOT YAML frontmatter
Consecutive blank lines	3+ blank lines	Collapse to 2

Manual (agent): Remove duplicate phase overviews — paragraphs that restate SKILL.md phase summaries.

CA3: Restructure for Self-Containment

Every reference file must be understandable in isolation.

Required header:

# {Descriptive Title}

{1-2 sentence purpose statement explaining what this file covers and when to use it.}

Voice conversion:

Kiro (second-person)	Claude Code (imperative)
"You should scan the workspace for..."	"Scan the workspace for..."
"Your next step is to generate..."	"Generate..."
"You will need to verify that..."	"Verify that..."
"In this phase, you will..."	"This phase covers..."
"You can optionally run..."	"Optionally run..."
"If you find any issues..."	"If issues are found..."

Self-containment checklist:

• Descriptive H1 heading (not just filename)
• Opening paragraph explains purpose without SKILL.md context
• Technical terms defined within the file
• Tools/scripts/commands include enough context
• Does not begin with "Continue from..." or "After completing Phase N..."

CA4: Deduplicate Against SKILL.md

SKILL.md states WHAT and WHEN. References detail HOW. No content in both.

Content Type	SKILL.md	Reference
Phase purpose (1-2 sentences)	Yes	No (or brief restatement)
Action items (numbered list)	Summary (3-5 items)	Full detail
Output file list	Brief mention	Complete specification
Decision criteria	Summary	Full rubric
Code examples	No	Yes
Templates	No	Yes
Edge cases	No	Yes
MCP server names	Prerequisites list	Configuration detail

Procedure:

1. For each SKILL.md phase section, read the corresponding reference
2. Identify paragraphs in the reference that restate the SKILL.md summary
3. Remove or rephrase duplicates to add detail not in SKILL.md
4. Keep the reference self-contained (Rule 15 / CA3)

---

E. Writing Style (Rules 16-20)

#	Rule	Rationale
16	Use third-person imperative voice	"Scan the workspace" is clearer than "You should scan". Reduces line count and ambiguity.
17	Number steps sequentially within each phase	Gives the agent clear execution order.
18	No emojis in headings or file names	Emojis cause rendering issues and add noise.
19	Use consistent domain terminology	Define key terms once and use consistently. Inconsistent terminology confuses the agent.
20	Provide concrete templates in assets/ for complex output	Templates reduce hallucination.

---

F. Scripts (Rules 21-23, 28-30)

#	Rule	Rationale
21	Offload fragile or repetitive tasks to bash scripts	Sed patterns, JSON parsing, file counting are error-prone for LLMs. Scripts are deterministic.
22	Write descriptive error messages to stdout/stderr	The agent reads script output to decide next actions.
23	Scripts must be runnable standalone	Enables manual testing and CI integration without the full skill.
28	Extract deterministic workflows into scripts during conversion	Shell commands, JSON schemas, checklists, state machines, directory templates execute identically as scripts.
29	Keep extracted scripts under 100 lines each	If >100, split into focused subscripts.
30	Replace extracted blocks with script invocation directives	Replace code blocks with one-line directives (e.g., "Run scripts/validate-env.sh"). Keep surrounding prose.

---

G. What NOT to Create (Rules 24-27)

#	Item	Why
24	README.md inside the skill directory	README belongs at plugin root. SKILL.md is the skill's documentation.
25	CHANGELOG.md	Skills versioned at plugin level via marketplace.json.
26	Library code or shared utilities	Skills are self-contained. Cross-skill dependencies create fragile coupling.
27	Redundant logic across SKILL.md and references	State each instruction once. SKILL.md summarizes, reference details.

---

H. Verification Checks (24 automated checks)

Run with: bash scripts/verify-conversion.sh <plugin-root-dir>

Structural Checks (1-7)

#	Check	Pass Criteria	Severity
1	Directory structure	.claude-plugin/ and {skill-name}/ exist	FAIL
2	Valid marketplace.json	Parses without JSON errors	FAIL
3	SKILL.md exists	Found in skill subdirectory	FAIL
4	SKILL.md under 500 lines	Line count < 500	FAIL
5	YAML frontmatter	SKILL.md starts with ---	FAIL
5b	Description single-line	No >, |, >-, |- after description:	FAIL
6	Reference file integrity	Every references/X.md in SKILL.md exists on disk	FAIL
7	File count	references/ has ≥1 file	FAIL

Stale Path Checks (8-11)

#	Check	Pass Criteria	Severity
8	No steering/ references	Zero steering/ in any .md file	FAIL
9	No kiro power commands	Zero kiro power in any .md file	FAIL
10	No resources/ paths	Zero resources/ in SKILL.md	FAIL
11	No inclusion: frontmatter	No reference has inclusion: in YAML frontmatter	FAIL

Metadata Checks (12-15)

#	Check	Pass Criteria	Severity
12	README.md exists	Found at plugin root	FAIL
13	Skill name matches directory	Frontmatter name: = directory basename	FAIL
14	Description has triggers	Contains "Use when"	FAIL
15	Description has anti-triggers	Contains "Don't use"	FAIL

Quality Checks (16-20)

#	Check	Pass Criteria	Severity
16	Third-person imperative voice	No "You should", "I will", "We need" lines	FAIL
17	No nested subdirectories	references/ has no subdirs with files	FAIL
18	Scripts have shebang + executable	Every .sh/.py starts with #! and has +x	FAIL
19	All referenced scripts exist	Every scripts/X.sh in markdown exists on disk	FAIL
20	No orphaned scripts	Every script in scripts/ is referenced in markdown	FAIL

Content Adaptation Checks (21-24) — NEW

#	Check	Pass Criteria	Severity
21	SKILL.md within target range	300-400 lines	WARN
22	No oversized references	No reference file >400 lines	FAIL
23	No Kiro boilerplate	No **Phase N of M**, **Input/Output Location:**, **Next/Previous:** in references	FAIL
24	Scripts referenced in SKILL.md	When scripts/ has files, SKILL.md mentions scripts/	FAIL

---

I. Quality Metrics (10 comparison metrics)

Run with: bash scripts/compare-power-plugin.sh <power-dir> <plugin-dir>

#	Metric	PASS	WARN	FAIL
1	File Coverage	All steering files in references	—	Any missing
2	Heading Coverage	≥80% POWER.md headings in SKILL.md	<80%	—
3	Reference Integrity	All SKILL.md references exist on disk	—	Any orphan
4	Line Ratio	SKILL.md/POWER.md ratio 0.30-0.80	Outside range	—
5	Content Fidelity	≥90% unchanged (path transforms only)	<90%	—
6	Progressive Disclosure	All reference files have Read directives	—	Any uncovered
7	MCP Parity	MCP deps documented or N/A	Mismatch	—
8	Content Adaptation Depth	≥80% files show >10% substantive changes	<80%	—
9	Reference File Size	All ≤400 lines	—	Any >400 lines
10	Description Format	Single-line, no block scalars	—	Block scalar used

---

J. Validation Methodology (4 stages)

Stage 1: Discovery Validation

• Each trigger phrase activates the skill for relevant user requests
• Each anti-trigger phrase does NOT activate the skill
• Skill name is discoverable via natural language queries

Stage 2: Logic Validation

• Every step references files or tools that exist
• No step requires information unavailable at that point in the workflow
• Instructions are unambiguous — the agent should not need to guess

Stage 3: Edge Case Testing

• What happens with empty input, missing files, or malformed data?
• What happens when optional components (MCP servers, assets) are unavailable?
• Do error paths provide actionable guidance?

Stage 4: Architecture Refinement

• SKILL.md line count within 300-400 target
• No reference file exceeds 400 lines
• Every Read directive is in a "Progressive disclosure:" section
• No duplicate content between SKILL.md and reference files

---

Quick Reference: Rule Count by Category

Category	Rules	Source File
Skill Structure	1-4	best-practices-checklist.md
Frontmatter	5-10	best-practices-checklist.md, skillmd-generation-guide.md
Progressive Disclosure	11-15c	best-practices-checklist.md
Content Adaptation	CA1-CA4	content-adaptation-rules.md
Writing Style	16-20	best-practices-checklist.md
Scripts	21-23, 28-30	best-practices-checklist.md
What NOT to Create	24-27	best-practices-checklist.md
Verification Checks	1-24	verification-checklist.md
Quality Metrics	1-10	quality-comparison-guide.md
Validation Stages	1-4	best-practices-checklist.md
Total	32 rules + 24 checks + 10 metrics + 4 stages