Pack Development
Learn how to create, publish, and maintain AI agent packs for the ayaiay ecosystem.
What is a Pack?
A pack is a versioned collection of AI resources stored in a Git repository. Packs can contain:
- Agents: AI agent profiles with specific capabilities
- Instructions: Detailed guidelines for AI behavior
- Prompts: Reusable prompt templates with variables
- MCP Servers: Model Context Protocol server configurations
Pack Structure
Every pack follows a standard directory structure:
my-agent-pack/
├── ayaiay.yaml # Pack manifest (required)
├── README.md # Pack documentation
├── agents/ # Agent definitions
│ ├── code-reviewer.md
│ └── task-automator.md
├── instructions/ # Instruction files
│ ├── review-guidelines.md
│ └── automation-best-practices.md
├── prompts/ # Prompt templates
│ ├── review-prompt.md
│ └── automation-prompt.md
├── skills/ # Agent skill definitions (optional)
│ ├── style-check.md
│ └── security-scan.md
└── mcp-servers/ # MCP server configs (optional)
└── my-server.yaml
The Manifest: ayaiay.yaml
The ayaiay.yaml file is the heart of your pack. It defines metadata and references all resources.
Basic Example
apiVersion: v1
kind: Pack
metadata:
name: my-agent-pack
version: 1.0.0
display_name: My Agent Pack
description: A collection of helpful AI agents
repository: https://github.com/username/my-agent-pack
license: MIT
author:
name: Your Name
email: your.email@example.com
url: https://yoursite.com
spec:
agents:
- name: code-reviewer
display_name: Code Reviewer
description: Expert code reviewer
instructions_path: agents/code-reviewer.md
model_provider: anthropic
model_name: claude-3-5-sonnet-20241022
instructions:
- name: review-guidelines
display_name: Code Review Guidelines
description: Guidelines for effective code reviews
path: instructions/review-guidelines.md
prompts:
- name: review-prompt
display_name: Review Prompt Template
description: Template for code review requests
path: prompts/review-prompt.md
variables:
- name: language
type: string
required: true
description: Programming language
- name: context
type: string
required: false
description: Additional context
Quick Start Guide
1. Create Your Pack Directory
mkdir my-agent-pack
cd my-agent-pack
2. Create the Manifest
Create ayaiay.yaml with your pack's metadata:
apiVersion: v1
kind: Pack
metadata:
name: my-agent-pack
version: 1.0.0
display_name: My First Pack
description: My first ayaiay pack
repository: https://github.com/yourusername/my-agent-pack
license: MIT
spec:
agents: []
instructions: []
prompts: []
3. Add Your First Agent
Create agents/helper.md:
---
name: helper
display_name: Helpful Assistant
description: A friendly and helpful AI assistant
---
# Helpful Assistant
You are a friendly and helpful AI assistant. Your goal is to:
1. Understand user needs clearly
2. Provide accurate and helpful responses
3. Ask clarifying questions when needed
4. Maintain a positive and encouraging tone
## Capabilities
- Answer questions across various topics
- Help with problem-solving
- Provide explanations and examples
- Assist with planning and organization
## Guidelines
- Always be respectful and professional
- Admit when you don't know something
- Provide sources when making factual claims
- Break down complex topics into simple explanations
4. Update the Manifest
Add the agent to ayaiay.yaml:
spec:
agents:
- name: helper
display_name: Helpful Assistant
description: A friendly and helpful AI assistant
instructions_path: agents/helper.md
model_provider: anthropic
model_name: claude-3-5-sonnet-20241022
5. Validate Your Pack
ayaiay validate ayaiay.yaml
6. Initialize Git Repository
git init
git add .
git commit -m "Initial commit: Add helpful assistant"
git tag v1.0.0
7. Publish to GitHub
# Create repository on GitHub first
git remote add origin https://github.com/yourusername/my-agent-pack.git
git push -u origin main
git push --tags
8. Import to ayaiay Catalog
- Go to ayaiay.org/dashboard
- Create a publisher if you haven't already
- Click "Import Pack from GitHub"
- Enter your repository URL
- Select the version (tag) to import
- Publish!
Pack Types
Agent Packs
Focus on AI agent profiles with specific personalities and capabilities.
Example use cases:
- Code review agents
- Writing assistants
- Technical experts
- Customer service bots
Instruction Packs
Collections of detailed guidelines and best practices.
Example use cases:
- Coding standards
- Documentation guidelines
- Quality assurance checklists
- Project workflows
Prompt Packs
Libraries of reusable prompt templates.
Example use cases:
- Content generation templates
- Analysis frameworks
- Question templates
- Report structures
MCP Server Packs
Bundles of MCP server configurations and tools.
Example use cases:
- Development tools
- API integrations
- Data processors
- Automation utilities
Mixed Packs
Combine multiple resource types for comprehensive solutions.
Example use cases:
- Complete development workflows
- Project starter kits
- Domain-specific toolkits
- Educational packages
Best Practices
Naming Conventions
- Pack names: lowercase with hyphens (e.g.,
code-review-pack) - Display names: Title Case (e.g.,
Code Review Pack) - File names: lowercase with hyphens (e.g.,
senior-reviewer.md) - Agent names: lowercase with hyphens (e.g.,
senior-reviewer)
Versioning
Follow Semantic Versioning:
1.0.0- Initial release1.0.1- Patch: Bug fixes and minor changes1.1.0- Minor: New features, backward compatible2.0.0- Major: Breaking changes
Documentation
Every pack should have:
- README.md: Overview and usage instructions
- Clear descriptions: Help users understand each resource
- Examples: Show how to use agents, instructions, and prompts
- Changelog: Document changes between versions
Organization
- Group related resources: Keep similar resources together
- Use subdirectories: Organize large packs with subdirectories
- Consistent formatting: Use consistent markdown formatting
- Include metadata: Add frontmatter to markdown files
Quality
- Test thoroughly: Validate your pack before publishing
- Proofread content: Check for typos and clarity
- Follow conventions: Adhere to community standards
- Get feedback: Share drafts for review
Manifest Reference
Required Fields
metadata.name
Pack identifier (lowercase, hyphens only)
metadata:
name: my-pack
metadata.version
Semantic version string
metadata:
version: 1.0.0
metadata.repository
Git repository URL
metadata:
repository: https://github.com/user/repo
Optional Fields
metadata.display_name
Human-readable name
metadata:
display_name: My Awesome Pack
metadata.description
Brief description of the pack
metadata:
description: A collection of helpful AI agents
metadata.license
License identifier (e.g., MIT, Apache-2.0)
metadata:
license: MIT
metadata.author
Author information
metadata:
author:
name: Your Name
email: email@example.com
url: https://example.com
metadata.keywords
Searchable keywords
metadata:
keywords:
- code-review
- automation
- ai-agents
Agent Specification
spec:
agents:
- name: agent-id # Required: unique identifier
display_name: Agent Name # Optional: human-readable name
description: Brief description # Optional
instructions_path: path.md # Required: path to instructions
model_provider: anthropic # Optional: ai provider
model_name: model-id # Optional: model identifier
model_parameters: # Optional: model settings
temperature: 0.7
max_tokens: 4096
avatar_url: https://... # Optional: agent avatar
Instruction Specification
spec:
instructions:
- name: instruction-id # Required: unique identifier
display_name: Instruction Name # Optional: human-readable name
description: Brief description # Optional
path: instructions/file.md # Required: path to content
tags: # Optional: categorization
- coding
- best-practices
Prompt Specification
spec:
prompts:
- name: prompt-id # Required: unique identifier
display_name: Prompt Name # Optional: human-readable name
description: Brief description # Optional
path: prompts/template.md # Required: path to template
variables: # Optional: template variables
- name: var_name
type: string
required: true
description: Variable purpose
default: default_value # Optional
MCP Server Specification
spec:
mcp_servers:
- name: server-id # Required: unique identifier
display_name: Server Name # Optional
description: Brief description # Optional
transport_type: stdio # Required: stdio, http, ws
command: dotnet # Required for stdio
args: # Required for stdio
- run
- --project
- ./server
env: # Optional: environment variables
API_KEY: ${API_KEY}
Skill Categories Specification
Skill categories let you group related skills into logical sections. When categories are defined, the pack detail page renders a category sidebar (desktop) or accordion (mobile) with per-category filtering and search — making large skill sets easy to navigate.
spec:
skillCategories:
- slug: code-quality # Required: lowercase alphanumeric + hyphens
label: Code Quality # Required: full display label
shortLabel: Quality # Optional: shorter label for sidebar
description: >- # Optional: shown below the category heading
Skills for improving and maintaining code quality standards.
- slug: automation
label: Task Automation
description: Skills for automating repetitive development tasks.
Rules:
slugmust match^[a-z0-9-]+$(lowercase, numbers, hyphens only)- Slugs must be unique within the pack
- A skill's
categoryfield must reference a defined slug — skills with an unknown or missing category are shown in an "Other Skills" section
Skill Specification
Skills represent atomic capabilities exposed by a pack. Each skill can optionally be linked to a category defined in skillCategories.
spec:
skills:
- name: style-check # Required: unique identifier
display_name: Style Check # Optional: human-readable name
description: >- # Optional
Checks code style and formatting against project standards.
category: code-quality # Optional: must match a skillCategories slug
path: ./skills/style-check.md # Required: path to the skill definition
tags: # Optional: searchable keywords
- linting
- formatting
- name: security-scan
display_name: Security Scanner
description: Scans code for common security vulnerabilities.
category: code-quality
path: ./skills/security-scan.md
tags:
- security
- owasp
Full example with categories:
apiVersion: v1
kind: Pack
metadata:
name: dev-toolkit
version: 1.0.0
description: Developer productivity skills with category navigation
spec:
skillCategories:
- slug: code-quality
label: Code Quality
shortLabel: Quality
description: Skills for maintaining high code quality.
- slug: automation
label: Task Automation
description: Skills for automating development workflows.
skills:
- name: style-check
display_name: Style Check
description: Enforce consistent code style.
category: code-quality
path: ./skills/style-check.md
tags: [linting, formatting]
- name: security-scan
display_name: Security Scanner
description: Detect security vulnerabilities.
category: code-quality
path: ./skills/security-scan.md
tags: [security]
- name: ci-generator
display_name: CI Pipeline Generator
description: Generate CI/CD pipeline configs.
category: automation
path: ./skills/ci-generator.md
tags: [ci, devops]
Next Steps
- Creating Your First Pack - Step-by-step tutorial
- Publishing Packs - Share your work
- Manifest Reference - Complete specification
- Best Practices - Advanced tips and patterns
- Examples - Sample packs