Kiro Agent Hooks Guide

What Are Agent Hooks?

Agent Hooks are event-driven AI automations that trigger when you:

• Save files - Run tests, update docs, format code
• Create files - Add boilerplate, generate tests
• Delete files - Clean up references, update imports
• Manual trigger - On-demand code reviews, audits

Unlike simple scripts, hooks have access to Kiro's AI agent and project context, making them intelligent and context-aware.

Essential Production Hooks

# .kiro/hooks/security-scan.md

## Trigger: On File Save
## Pattern: **/*

Review changed files for security issues:

1. Look for API keys, tokens, or credentials in source code
2. Check for hardcoded passwords or secrets
3. Identify potential SQL injection vulnerabilities
4. Scan for XSS vulnerabilities in web code
5. Check for insecure HTTP requests (should be HTTPS)

For each issue found:
1. Highlight the specific security risk
2. Suggest a secure alternative (environment variables, etc.)
3. Provide remediation steps

# .kiro/hooks/test-generator.md

## Trigger: On File Create
## Pattern: src/**/*.{js,ts,jsx,tsx}

When a new source file is created:

1. Analyze the file's exports and functions
2. Create a corresponding test file in the appropriate test directory
3. Generate test cases for:
   - All exported functions
   - Edge cases and error conditions
   - Integration scenarios if applicable
4. Include proper imports and setup/teardown
5. Add TODO comments for complex test scenarios

# .kiro/hooks/doc-sync.md

## Trigger: On File Save
## Pattern: src/**/*.{js,ts}

When source files are modified:

1. Check if function signatures have changed
2. Update JSDoc comments if they exist
3. Update README.md if API changes are detected
4. Update CHANGELOG.md with a brief description
5. Check for broken internal links in documentation
6. Generate API documentation if needed

# .kiro/hooks/import-cleanup.md

## Trigger: On File Delete
## Pattern: **/*.{js,ts,jsx,tsx}

When a file is deleted:

1. Search the entire codebase for imports of the deleted file
2. Remove or comment out the import statements
3. Check for any references to exported items from the deleted file
4. Suggest alternative imports if similar functionality exists
5. Update any documentation that referenced the deleted file

# .kiro/hooks/quality-audit.md

## Trigger: Manual
## Pattern: **/*

Perform comprehensive code quality analysis:

1. Check for code smells and anti-patterns
2. Identify overly complex functions (high cyclomatic complexity)
3. Look for duplicate code that could be refactored
4. Check naming conventions and consistency
5. Analyze performance bottlenecks
6. Review error handling patterns
7. Generate a quality report with recommendations

# .kiro/hooks/i18n-helper.md

## Trigger: On File Save
## Pattern: src/locales/en/*.json

When English locale files are updated:

1. Identify which string keys were added or modified
2. For each other language file, check if those keys exist
3. If a key is missing, add it with "NEEDS_TRANSLATION" placeholder
4. If a key was modified in English, mark it "NEEDS_REVIEW" in others
5. Generate a summary of what translations need updating
6. Create a translation task list

Advanced Hook Patterns

Conditional Hooks

Hooks can include conditions to run only in specific scenarios:

# .kiro/hooks/conditional-test.md

## Trigger: On File Save
## Pattern: src/**/*.js
## Condition: Only run if file contains "TODO" or "FIXME"

When files with TODO/FIXME comments are saved:

1. Extract all TODO and FIXME comments
2. Check if they have associated GitHub issues
3. If not, suggest creating issues for tracking
4. Estimate complexity and priority
5. Add to project backlog if configured

Multi-Step Hooks

Complex hooks can chain multiple actions:

# .kiro/hooks/deployment-prep.md

## Trigger: Manual
## Pattern: **/*

Prepare for deployment:

1. Run full test suite and report results
2. Check for security vulnerabilities
3. Update version numbers in package.json
4. Generate/update CHANGELOG.md
5. Build production assets
6. Run performance benchmarks
7. Create deployment checklist
8. Generate deployment summary report

Hook Configuration

Creating Hooks in Kiro

1. Open the Kiro sidebar and navigate to "Agent Hooks"
2. Click "+" to create a new hook
3. Choose trigger type (Save, Create, Delete, Manual)
4. Set file pattern (e.g., **/*.js for all JS files)
5. Write instructions in natural language
6. Test the hook on a sample file
7. Enable the hook for automatic execution

Hook File Structure

Hooks are stored as markdown files in .kiro/hooks/:

project/
├── .kiro/
│   ├── hooks/
│   │   ├── security-scan.md
│   │   ├── test-generator.md
│   │   ├── doc-sync.md
│   │   └── quality-audit.md
│   └── specs/
└── src/

Best Practices

Hook Design Principles

• Be Specific: Clear, actionable instructions work better than vague requests
• Handle Errors: Include instructions for what to do when things go wrong
• Provide Context: Explain why the hook is running and what it's checking
• Be Incremental: Focus on the changed files, not the entire codebase

Performance Considerations

• Use specific file patterns to avoid unnecessary triggers
• Keep hook instructions concise but complete
• Consider using manual triggers for expensive operations
• Test hooks on small files before enabling project-wide

Team Collaboration

Hooks are particularly powerful for team development:

• Consistent Standards: Everyone gets the same code quality checks
• Knowledge Sharing: Hooks can enforce team conventions automatically
• Onboarding: New team members get guidance through hooks
• Documentation: Hooks keep docs updated as code changes

Example Team Hook: Code Review Assistant

# .kiro/hooks/code-review-assistant.md

## Trigger: Manual
## Pattern: **/*.{js,ts,jsx,tsx}

Prepare code for team review:

1. Check adherence to team coding standards
2. Identify potential performance issues
3. Verify error handling patterns match team conventions
4. Check for proper logging and monitoring
5. Ensure accessibility standards are met
6. Validate security best practices
7. Generate a pre-review checklist
8. Suggest improvements with explanations

Troubleshooting Hooks

Common Issues

• Hook not triggering: Check file pattern matches your files
• Slow execution: Make instructions more specific and focused
• Inconsistent results: Add more context about project structure
• Too many false positives: Refine conditions and patterns

Debugging Hooks

Kiro provides hook execution logs in the Agent Hooks panel. Check these when hooks aren't working as expected.

Next Steps

Ready to implement hooks in your project?

1. Start with the Security Scanner hook - it provides immediate value
2. Add the Documentation Sync hook to keep docs current
3. Create project-specific hooks for your team's workflow
4. Share successful hooks with the community

For more advanced automation, explore combining hooks with spec-driven development and compare Kiro's automation with other AI coding tools.