Contributing to Promptz

Welcome to the Promptz community! This library makes it easy to share your AI development resources with the community. Simply drop your raw Kiro files and create a pull request.

TL;DR

Quick Start:

Fork promptz.lib repository
Copy files from your ~/.kiro/ or <project>/.kiro/ folders
Place in appropriate directories: steering/, prompts/, agents/, hooks/, powers/
Remove sensitive data, use kebab-case naming
Create PR with clear description

Key Requirements:

Hooks: Use .kiro.hook extension (not .hook)
Agents: System prompts optional (inline or file://./agent-name.md)
Powers: Only POWER.md required (with YAML frontmatter), mcp.json optional
Everything else: No frontmatter needed, simple markdown files

Compatibility:

IDECLI
Universal (CLI + IDE): Steering, Prompts
CLI
CLI Only: Custom Agents
IDE
IDE Only: Agent Hooks, Kiro Powers

What is Promptz?
Content Types by Compatibility
What You Can Contribute
File Structure Reference
Content Guidelines
How to Contribute
Quality Standards
Getting Help
Review Process
Recognition

What is Promptz?

Promptz is a community-driven platform that accepts raw Kiro files from your .kiro folders. These are the same files you use locally with Kiro IDE and Kiro CLI. The content is stored in the promptz.lib repository and displayed on promptz.dev for the community to discover and use.

Content Types by Compatibility

Understanding which content works where helps you contribute the right resources:

Universal Content (CLI + IDE)

IDECLI

Works in both Kiro CLI and Kiro IDE environments:

Steering Documents - Development standards and coding guidelines
Prompts - Reusable AI instructions for development tasks

CLI-Only Content

CLI

Specialized for command-line workflows:

Custom Agents - AI assistants configured for terminal-based development

IDE-Only Content

IDE

Designed for the integrated development environment:

Agent Hooks - Event-driven automation that responds to file changes
Kiro Powers - Complete tool packages with specialized knowledge

What You Can Contribute

From Your Global Kiro Folder (`~/.kiro/`)

User-wide configurations that work across all projects:

Steering Documents (~/.kiro/steering/*.md) - Personal coding standards and development guidelines
Custom Agents (~/.kiro/agents/) - Your custom agent configurations for CLI workflows
Prompts - Reusable AI instructions you've developed

From Your Workspace Kiro Folders (`<project>/.kiro/`)

Project-specific configurations that could benefit other projects:

Project-specific steering (<project>/.kiro/steering/*.md) - Standards for particular frameworks or domains
Custom Agents (<project>/.kiro/agents/) - Domain-specific AI assistants for CLI
Agent Hooks (<project>/.kiro/hooks/) - Project automation for IDE users
Prompts - Task-specific AI guidance for common development activities

Kiro Powers

If you've created Kiro powers, you can contribute them to the promptz.lib repository! Powers are complete tool packages that provide specialized knowledge and capabilities. While there's also an official kiro-powers repository from AWS, we welcome community powers in promptz.lib to make them easily discoverable alongside other community resources.

File Structure Reference

🟣 Universal Content (CLI + IDE)

Prompts

Simple markdown files with no frontmatter required:

prompts/
├── automated-code-review.md        # Code review instructions
├── git-commit-message.md           # Commit message generation
├── unit-test-generation.md         # Test generation prompts
└── security-review.md              # Security analysis prompts

Steering Documents

Markdown files with no frontmatter required:

steering/
├── git.md                          # Git conventions and workflows
├── cdk-python.md                   # CDK Python development guidelines
├── typescript-conventions.md       # TypeScript coding standards
└── testing-guidelines.md           # Testing standards

🔵 CLI-Only Content

Custom Agents

JSON configuration with optional system prompt:

agents/
├── atlassian-kanban-agent.json     # Required: Agent configuration
├── atlassian-kanban-agent.md       # Optional: System prompt (naming convention)
├── aws-operations-agent.json       # Agent config only (inline prompt)
└── web-frontend-agent.json         # Another config-only example

Agent Configuration Options:

Option 1 - Inline system prompt:

{
  "name": "my-agent",
  "description": "Agent description",
  "prompt": "Inline system prompt here...",
  "mcpServers": {},
  "tools": ["@builtin", "@server/tool"]
}

Option 2 - File reference system prompt:

{
  "name": "my-agent",
  "description": "Agent description",
  "prompt": "file://./my-agent.md",
  "mcpServers": {},
  "tools": ["@builtin", "@server/tool"]
}

🟢 IDE-Only Content

Agent Hooks

JSON files with .kiro.hook extension:

hooks/
├── session-init-workflow.kiro.hook # Session initialization automation
├── auto-format-on-save.kiro.hook   # Formatting automation
└── run-tests-on-commit.kiro.hook   # Pre-commit testing

Hook Structure:

{
  "enabled": true,
  "name": "Hook Name",
  "description": "What this hook does",
  "when": { "type": "userTriggered" },
  "then": { "type": "askAgent", "prompt": "Instructions..." }
}

Kiro Powers

Powers can be contributed to the promptz.lib repository alongside other community content:

powers/
├── stripe/
│   ├── POWER.md                    # Required: Main power file with YAML frontmatter
│   ├── mcp.json                    # Optional: MCP server configuration
│   └── steering/                   # Optional: Additional guidance files
│       ├── getting-started.md
│       └── best-practices.md
└── aws-infrastructure-as-code/
    └── POWER.md                    # Minimal power: just POWER.md required

Power Frontmatter (Required):

---
name: "power-name"
displayName: "Human Readable Name"
description: "Brief explanation of what this power does"
keywords: ["keyword1", "keyword2", "keyword3"]
author: "Your Name"
---

Your power content here...

How to Contribute

Step 1: Find Your Kiro Files

Global Kiro Folder (~/.kiro/):

Contains user-wide configurations that apply to all your projects
Look for: steering/, agents/, and any prompt files you've created

Workspace Kiro Folders (<project>/.kiro/):

Contains project-specific configurations
Look for: steering/, agents/, hooks/, and project-specific prompts

Start with high-impact content:

Steering documents that define useful coding standards
Prompts that solve common development challenges
Agents that provide specialized assistance for CLI workflows
Hooks that automate frequent IDE tasks

Consider broad applicability:

Will other developers find this useful?
Does it solve a common problem?
Is it generic enough to work in different projects?

Step 3: Prepare Your Files

Remove sensitive information - Strip out API keys, personal data, absolute paths
Test your configurations - Ensure they work in a clean Kiro environment
Use proper naming - Follow kebab-case convention for all files
Verify file extensions - Use .kiro.hook for hooks, not .hook

Step 4: Fork and Contribute

Fork the repository:
- Fork the promptz.lib repository for all community content including prompts, steering documents, agents, hooks, and powers
Add your files to the appropriate directories:
- steering/ for steering documents
- prompts/ for AI prompts
- hooks/ for agent hooks (.kiro.hook files)
- agents/ for custom agents
- powers/ for Kiro powers (separate repository)
Create a pull request with:
- Clear title describing your contribution
- Description explaining how others can use your content
- Context about when and why to use your resources

Step 5: Review Process

Automated validation - Files are checked for format and safety
Community feedback - Other contributors may provide suggestions
Maintainer review - Final approval for quality and appropriateness
Automatic publication - Approved content appears on promptz.dev

Content Guidelines

File Requirements

No sensitive data - Remove API keys, passwords, personal information
Use kebab-case naming - All files should use kebab-case (my-agent-name.json)
Generic paths - Use relative paths or placeholders instead of absolute paths
Clear descriptions - Use descriptive file names that explain the purpose

Content-Specific Requirements

Prompts and Steering Documents

No frontmatter required - Simple markdown files work perfectly
Clear, actionable instructions - Write instructions that AI assistants can follow
Standard markdown formatting - Use proper headers, lists, and code blocks
Test with AI assistants - Verify your prompts work before contributing

Custom Agents (CLI)

Valid JSON syntax - Ensure your configuration files are properly formatted
System prompts are optional - Choose inline or file reference based on complexity
File naming convention - If using separate .md file, name it same as .json file
Test in clean environment - Verify agent works without your local dependencies

Agent Hooks (IDE)

Use .kiro.hook extension - This is the correct file extension for IDE hooks
Valid JSON structure - Include required fields: enabled, name, description, when, then
Clear trigger conditions - Specify when the hook should activate
Test hook behavior - Ensure hooks work as expected before contributing

Kiro Powers (IDE)

YAML frontmatter required - Only content type that needs frontmatter
POWER.md is required - The main documentation file is mandatory
mcp.json is optional - Only include if your power needs MCP server integration
Clear keywords - Help users discover your power with relevant keywords

Quality Standards

Before Contributing

Test thoroughly - Ensure your files work in a clean Kiro environment
Remove personal data - Strip out sensitive information, API keys, absolute paths
Verify compatibility - Check that files work with current Kiro versions
Document clearly - Include clear descriptions of purpose and usage

File Validation Checklist

All Content Types

No sensitive data (API keys, passwords, personal information)
Uses kebab-case naming convention
Clear, descriptive file names
Tested in clean environment

Prompts & Steering Documents

Standard markdown formatting
No frontmatter (not required)
Clear, actionable instructions
Tested with AI assistants

Custom Agents

Valid JSON syntax in configuration file
System prompt is optional (inline or file reference)
If using separate .md file, named same as .json file
All referenced tools are commonly available

Agent Hooks

Uses correct .kiro.hook file extension
Valid JSON structure with required fields
Clear trigger conditions in when property
Appropriate actions in then property

Kiro Powers

POWER.md file with required YAML frontmatter
Optional mcp.json only if MCP integration needed
Clear keywords for discoverability
Comprehensive documentation

What We Look For

Broad applicability - Resources that help many developers
Clear documentation - Well-explained purpose and usage instructions
Working examples - Tested and functional configurations
Community value - Solutions to real development challenges
Proper structure - Follows established file format conventions

Getting Help

Questions? Open a GitHub issue with the "question" label
Problems? Report bugs with the "bug" label
Ideas? Share feature requests with the "enhancement" label

Review Process

Automated checks - Files are validated for format and safety
Community review - Other contributors may provide feedback
Maintainer approval - Final review for quality and appropriateness
Merge and publish - Approved contributions appear on promptz.dev automatically

Recognition

Contributors are automatically credited through git history and displayed on promptz.dev with:

Author attribution on all contributed content
Contributor profiles showing your contributions
Community recognition for valuable resources

Thank you for sharing your Kiro configurations with the Promptz community! Your contributions help make AI-assisted development more accessible and effective for everyone. 🚀

Contributing to Promptz

TL;DR

Table of Contents

What is Promptz?

Content Types by Compatibility

Universal Content (CLI + IDE)

CLI-Only Content

IDE-Only Content

What You Can Contribute

From Your Global Kiro Folder (~/.kiro/)

From Your Workspace Kiro Folders (<project>/.kiro/)

Kiro Powers

File Structure Reference

🟣 Universal Content (CLI + IDE)

Prompts

Steering Documents

🔵 CLI-Only Content

Custom Agents

🟢 IDE-Only Content

Agent Hooks

Kiro Powers

How to Contribute

Step 1: Find Your Kiro Files

Step 2: Choose What to Share

Step 3: Prepare Your Files

Step 4: Fork and Contribute

Step 5: Review Process

Content Guidelines

File Requirements

Content-Specific Requirements

Prompts and Steering Documents

Custom Agents (CLI)

Agent Hooks (IDE)

Kiro Powers (IDE)

Quality Standards

Before Contributing

File Validation Checklist

All Content Types

Prompts & Steering Documents

Custom Agents

Agent Hooks

Kiro Powers

What We Look For

Getting Help

Review Process

Recognition

From Your Global Kiro Folder (`~/.kiro/`)

From Your Workspace Kiro Folders (`<project>/.kiro/`)