Agent Skills: Kiro Context Management

Kiro Context Management

Scope: Kiro-specific context management, terminal limitations, tool preferences Load if: Using Kiro IDE (ALWAYS load first in Kiro sessions) Prerequisites: None (this file loads before other rules)

CRITICAL: Terminal Limitations

Terminal commands that cause Kiro to freeze — avoid these:

• Use single quotes or write to a file instead of echo with double quotes (causes hang)
• Avoid heredoc syntax (<<EOF) — it fails in the Kiro terminal
• Use simple shell configurations — complex zsh themes (powerlevel10k, oh-my-zsh) cause timeouts
• Use non-interactive commands in automation — avoid interactive editors (vim, nano)
• Avoid interactive pagers (less, more) in automated commands
• Keep scripts simple — avoid chaining commands with && or || in complex scripts
• Treat a second command in the same terminal session as unreliable (known zsh bug) — run one command per invocation

Terminal best practices for Kiro:

• Use Python scripts instead of complex shell commands
• Write output to files, then read files (not echo)
• Use -m flag with git commit (avoid editor)
• Use --no-pager with git commands
• Use simple bash syntax over zsh features
• Run one command per terminal invocation when possible
• Add timeouts to long-running commands

CRITICAL: Serena MCP is Mandatory

When Serena MCP is available, you MUST use Serena tools for all file operations.

Kiro native tools have known reliability issues:

• strReplace fails on duplicate content
• readFile silently truncates large files
• File writes can create duplicate sections
• Mid-operation aborts during file reads/edits

Tool Preference Order (mandatory):

1. Reading code: find_symbol, get_symbols_overview > readFile
2. Editing code: replace_content (regex mode) > strReplace
3. Navigation: find_referencing_symbols > grepSearch
4. Context: write_memory, read_memory for persistent state

Use Serena replace_content over Kiro strReplace when Serena is available. Use Serena tools over Kiro readFile for large files when Serena tools are available. Always check for and use Serena MCP availability rather than ignoring it.

Serena Activation Workflow

At session start:

1. Check if Serena MCP is available
2. Run activate_project to initialize
3. Run check_onboarding_performed to verify setup
4. Run list_memories to discover available context
5. Run read_memory for relevant project context

During work:

• Use write_memory for important discoveries
• Use semantic tools (find_symbol, replace_content) over text-based

Before compaction (70% context):

• Save session state with write_memory

AGENTS.md Integration

Kiro automatically loads AGENTS.md from workspace root (Kiro v0.5.0+). No separate .kiro/steering/ files needed.

How it works:

• Place AGENTS.md at workspace root
• Kiro reads it automatically at session start
• Include instructions for loading domain-specific files
• Critical rules (terminal limitations) embedded directly with XML tags

Related

• @smith-ctx/SKILL.md - Universal context strategies
• @smith-serena/SKILL.md - Serena MCP tools (mandatory for Kiro)

Before You Finish

Proactive context management:

1. Prompt for context status periodically
2. At 70%: Warn that 80% auto-summarize is approaching
3. Save important context to Serena memory before 80%

Platform auto-summarizes at 80% - agent prepares user by saving state first.

In Kiro sessions:

1. Avoid echo with double quotes
2. Use Python scripts for file generation
3. Use Serena MCP tools (mandatory, not optional)