Individual AI interaction practices do not scale to teams. Repository conventions transform personal productivity into team capability.
The Team Scaling Problem
When one person uses AI tools, conventions emerge organically through personal practice. When teams use AI tools, conventions must be explicit and shared. Without explicit conventions, teams duplicate effort, produce inconsistent artifacts, and cannot leverage each other's work.
Team conventions should be organized hierarchically from most to least constraining. Principles are overarching guidelines that inform decisions across situations. Policies are specific rules that must be followed without exception. Practices are recommended approaches that can be adapted to specific contexts. Patterns are proven solutions to recurring problems that teams can apply directly.
Directory Structure Conventions
Establish a consistent directory structure for AI interaction artifacts. This makes it easy to find and reuse work across the team.
Recommended Structure
.ai/
skills/ # Reusable skill definitions
templates/ # Prompt templates
rules/ # Behavioral rules
memory/ # Cross-session context
docs/ # AI interaction documentation
prompts/ # One-off prompts (reference)
experiments/ # Exploration and testing
CONTEXT.md # Project-level context
RULES.md # Project-level rules
SKILLS.md # Index of available skills
QuickShip established the .ai/ directory structure for their exception handler project:
.ai/
skills/
email-classifier/
SKILL.md
examples/
response-generator/
SKILL.md
templates/
classification-template.md
response-template.md
rules/
security-rules.md
performance-rules.md
memory/
classification-history.md
CONTEXT.md
RULES.md
SKILLS.md
Any team member could navigate the AI artifacts, find relevant skills, and understand the project context.
Skill Documentation Conventions
Skills should be documented consistently so team members can find, understand, and use them. Define a standard skill template.
Skill Template
# Skill: [Name]
## Purpose
[One sentence describing what this skill does]
## Inputs
- [Input name]: [Description], [Format/type], [Required/Optional]
## Outputs
- [Output name]: [Description], [Format/type]
## Behavior Rules
- [Rule 1]
- [Rule 2]
## Context Requirements
- [Context element 1]
- [Context element 2]
## Usage Examples
### Example 1: [Description]
[Prompt or invocation]
[Expected output]
### Example 2: [Description]
[Prompt or invocation]
[Expected output]
## Related Skills
- [Other skill name]: [Relationship]
Naming Conventions
Consistent naming makes artifacts findable and understandable. Establish naming conventions for skill files and directories, template files, rule files, and prompt references. Use descriptive, hyphenated names such as email-classifier-skill.md, classification-prompt-template.md, and security-rules.md. Avoid cryptic abbreviations or single words, favoring clarity over brevity.
Context Document Conventions
Context documents should follow a consistent structure. This enables team members to quickly understand project state and AI interaction patterns.
Context Document Template
# [Project Name] - Context
## Last Updated
[Date] by [Author]
## Project Overview
[What this project does, who it serves]
## Tech Stack
- [Technology 1]
- [Technology 2]
## Architecture
[High-level architecture description]
## AI Interaction Patterns
[How AI is used in this project]
## Key Conventions
[Important patterns team should follow]
## Current State
[What is working, what is being worked on]
## Team Contact
[Who to ask questions about this project]
Rule Conventions
Rules should be categorized and documented consistently, separated by type. Security rules cover data handling, access control, and privacy requirements. Quality rules define output standards and validation requirements. Performance rules specify latency, throughput, and resource limits. Compliance rules address regulatory requirements and audit needs.
Onboarding Integration
AI conventions should be part of team onboarding. New team members should understand where AI artifacts are located, how to use existing skills and templates, how to contribute new skills, and what rules apply and why they exist.
QuickShip includes AI tooling in their engineering onboarding:
- Read PROJECT_CONTEXT.md and .ai/CONTEXT.md
- Review SKILLS.md index of available skills
- Complete tutorial: classify an email using email-classifier skill
- Review RULES.md and understand security rules
- Pair with existing team member on an AI task
Maintenance and Evolution
Conventions are not static; they evolve as the project and team mature. Establish processes for adding new skills including who creates them, who reviews them, and how to share them across the team. Define when to update context and who bears responsibility for keeping it current. Create a process for deprecating skills that are no longer used, removing them cleanly without losing institutional knowledge. Establish how to resolve convention disagreements when team members have conflicting views on practices.
Key Takeaways
Individual AI practices do not scale to teams; explicit conventions transform personal productivity into team capability. The convention hierarchy moves from principles through policies and practices to patterns, each with different levels of constraint. Establish a .ai/ directory structure for organizing AI interaction artifacts so team members can find what they need. Standardize skill documentation with a template to ensure consistency and completeness. Use consistent naming conventions for findability, preferring descriptive hyphenated names over cryptic abbreviations. Integrate AI conventions into team onboarding so new members become productive quickly. Establish maintenance processes for convention evolution to keep artifacts current as the project matures.
Evaluate your team's AI convention readiness by asking several diagnostic questions. First, consider where AI artifacts are currently stored and whether they are organized in a findable structure. Second, assess whether you have skill documentation and if it follows consistent standards. Third, examine what naming conventions exist and whether they are consistently followed. Fourth, determine how new team members learn AI practices and whether onboarding addresses AI tooling. Fifth, define what a minimal viable convention set would look like for your team, focusing on the essential elements that would provide immediate value.
What's Next
In Chapter 13, we examine Multi-Agent and Tool-Based Build Flows, exploring when multi-agent architectures are justified and how to design them.