zhongwei/gh-l-sypniewski-claude-code-toolkit-plugins-documentation-templates
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:36:37 +08:00
commit 7d67ed06c8
5 changed files with 645 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,11 @@
{
"name": "documentation-templates",
"description": "Templates and examples for creating comprehensive project documentation including AGENTS.md and Claude Code delegation rules with best practices",
"version": "1.1.0",
"author": {
"name": "Claude Code Toolkit"
},
"skills": [
"./skills"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# documentation-templates
Templates and examples for creating comprehensive project documentation including AGENTS.md and Claude Code delegation rules with best practices

49
plugin.lock.json Normal file
View File

@@ -0,0 +1,49 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:L-Sypniewski/claude-code-toolkit:plugins/documentation-templates",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "8f851543b7f79d45a9e59d44a2e61db6bfc18f2d",
"treeHash": "e9429b745a12fb5903c49a86519c7017beff14bb5ff46aab570fee7886b9c7be",
"generatedAt": "2025-11-28T10:12:00.032961Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "documentation-templates",
"description": "Templates and examples for creating comprehensive project documentation including AGENTS.md and Claude Code delegation rules with best practices",
"version": "1.1.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "e6fabad190068987d94e2bf046d82282a6431e264a2493deca56bccb43f21c18"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "06f962f59a902b3b2d37be53543bdeabf52083319ad3ca2c7234a00471712443"
},
{
"path": "skills/agent-documentation/SKILL.md",
"sha256": "c0bb1a79d2d6d14877af94858624b4fc51fb903af04661cee06c30c9eedf034e"
},
{
"path": "skills/claude-delegation-rules/SKILL.md",
"sha256": "ba194723c509a7c646b7b810921065f2e3af1b255f3bfbec1e1717c4116974d0"
}
],
"dirSha256": "e9429b745a12fb5903c49a86519c7017beff14bb5ff46aab570fee7886b9c7be"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

210
skills/agent-documentation/SKILL.md Normal file
View File

@@ -0,0 +1,210 @@
---
name: agent-documentation
description: Standards for creating AGENTS.md files that guide AI coding agents working with your codebase. Use when creating instructions for AI agents to follow project conventions, setup, and workflows.
---
# AGENTS.md Documentation
This skill provides standards for creating AGENTS.md files - dedicated instructions for AI coding agents working with your codebase.
## What is AGENTS.md?
AGENTS.md is the "README for AI agents" - a machine-readable guide that provides explicit instructions for AI coding tools (like Claude, Copilot, Cursor) working with your project. Unlike README.md (for humans), AGENTS.md gives AI agents unambiguous, step-by-step guidance.
## Purpose
- **Centralized Instructions**: Single source of truth for all AI agents
- **Explicit Guidance**: Clear setup commands, coding standards, testing workflows
- **Project Context**: Architecture decisions, conventions, constraints
- **Consistency**: Ensures AI-generated code matches project standards
## AGENTS.md Structure
Based on real-world examples, a well-structured AGENTS.md follows this pattern:
```markdown
# ProjectName - Development Guide
**Stack**: [Tech stack components]
**Principles**: [Core development principles, e.g., SOLID, KISS, YAGNI]
## Project Overview
[Brief description of architecture and approach]
## Repository Structure
- `path/to/main/`: [Description]
- `path/to/tests/`: [Description]
- `path/to/config/`: [Description]
## Key Commands
```bash
# Core commands
[build command]
[test command]
[format command]
# Additional tools
[migration/deployment commands]
[additional commands]
```
## Quality Gates (Required)
Define the quality standards that must be met:
### Code Quality
- [ ] Build succeeds without errors
- [ ] All tests pass
- [ ] Code formatting/linting passes
- [ ] No compiler warnings
### Testing Requirements
- [ ] Integration tests for key workflows (favor sociable tests over isolated unit tests)
- [ ] Avoid excessive mocking - test real collaborations
- [ ] All edge cases and error paths covered
### Code Review Standards
- [ ] Follows project conventions
- [ ] No code smells or anti-patterns
- [ ] Proper error handling
- [ ] Security considerations addressed
## Coding Conventions (Optional)
[Project-specific coding standards]
## Testing Guidelines (Optional)
[Testing expectations]
```
## Key Sections Explained
### 1. Title and Metadata (Required)
**Format**: `# ProjectName - Development Guide`
Include **Stack** and **Principles** at the top for quick reference.
### 2. Project Overview (Required)
Brief architectural summary - what type of project, key technologies, approach.
### 3. Repository Structure (Required)
Map of directories with brief descriptions. Helps agents understand where code lives.
### 4. Key Commands (Required)
Copy-paste commands for:
- Building the project
- Running tests
- Formatting code
- Database migrations or other critical operations
### 5. Quality Gates (Required)
Define quality standards that code must meet:
- **Code Quality**: Build, test, lint requirements
- **Testing Requirements**: Coverage thresholds, test types needed
- **Code Review Standards**: Conventions, patterns, security checks
### 6. Optional Sections
Add as needed:
- **Coding Conventions**: Project-specific rules
- **Testing Guidelines**: Reference separate tests/AGENTS.md for detailed testing guidelines
## Best Practices
### Start with Essentials
Include at minimum: Stack, Principles, Project Overview, Repository Structure, and Key Commands.
### Be Explicit and Specific
❌ "Set up the environment"
✅ "npm install && cp .env.example .env"
❌ "Write good tests"
✅ "Write integration tests for all API endpoints, test real collaborations"
### Use Exact Commands
Provide copy-paste ready commands. AI agents will execute them literally.
### Keep It Updated
Review and update AGENTS.md when project structure or conventions change.
## Integration with Claude Code
AGENTS.md works alongside Claude Code agents:
- Claude Code agents can reference AGENTS.md for project context
- Use AGENTS.md for project-specific conventions
- Use agent specifications (.md files) for agent-specific behavior
## Complete Example
```markdown
# StockToolset - Development Guide
**Stack**: .NET 10, ASP.NET Core Minimal APIs, .NET Aspire 13, PostgreSQL, PGMQ.
**Principles**: SOLID, KISS, YAGNI. Consistency over innovation.
## Project Overview
Cloud-native .NET 10 modular monolith using Vertical Slice Architecture,
Aspire 13, PostgreSQL, and PGMQ.
## Repository Structure
- `StockStorage/src/`: Main app (Features/, Database/, Infrastructure/)
- `StockStorage/tests/`: Unified test project (Unit, Integration, System). **See `StockStorage/tests/AGENTS.md`**.
- `StockStorage.AppHost/`: .NET Aspire orchestration
- `StockStorage.ServiceDefaults/`: Shared Aspire defaults
## Key Commands
```bash
# Core
dotnet build
dotnet test # Requires Docker
dotnet format
# EF Core
dotnet ef migrations add <MigrationName>
dotnet ef database update
```
## Testing
**Refer to `StockStorage/tests/AGENTS.md` for all testing guidelines.**
- Stack: TUnit, AwesomeAssertions, Testcontainers.
- Categories: Unit, Integration, System.
## Quality Gates
### Code Quality
- [ ] `dotnet build` succeeds with zero warnings
- [ ] `dotnet format` shows no formatting issues
- [ ] All tests pass (`dotnet test`)
### Testing Requirements
- [ ] Integration tests for key workflows (favor sociable tests)
- [ ] Avoid excessive mocking - test real collaborations
- [ ] All edge cases and error paths tested
### Code Review Standards
- [ ] Follows Vertical Slice Architecture
- [ ] SOLID, KISS, YAGNI principles applied
- [ ] No code duplication
- [ ] Proper error handling and logging
## Coding Conventions
- Follow SOLID, KISS, YAGNI principles
- Consistency over innovation
- Use Vertical Slice Architecture per feature
```
## Further Reading
- [AGENTS.md Specification](https://agents.md/)
- [GitHub's AGENTS.md Guide](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)
- [OpenAI AGENTS.md Repo](https://github.com/openai/agents.md)

372
skills/claude-delegation-rules/SKILL.md Normal file
View File

@@ -0,0 +1,372 @@
---
name: claude-delegation-rules
description: Rules and patterns for Claude Code agent delegation, including when to delegate, how to hand off context, and how to coordinate between agents. Use when designing agent systems or delegation workflows.
---
# Claude Delegation Rules
This skill provides patterns and rules for effective agent delegation in Claude Code.
## Core Delegation Principles
### 1. Single Responsibility
Each agent should have a clear, focused purpose:
```yaml
# ✅ Good - Clear, focused responsibility
name: code-reviewer
description: Expert code review with comprehensive quality analysis
# ❌ Bad - Too broad
name: developer
description: Does development tasks
```
### 2. Explicit Activation
Agents should know exactly when they should activate:
```yaml
# ✅ Good - Clear activation triggers
description: Senior engineer for implementation tasks. Use PROACTIVELY
for fix, implement, build, create, add, refactor, optimize keywords.
# ❌ Bad - Vague activation
description: Helps with coding
```
### 3. Clear Boundaries
Define what an agent does and doesn't do:
```markdown
## When to Use
- Implementing new features
- Fixing bugs
- Refactoring code
## When NOT to Use
- High-level architecture decisions (use technical-architecture-advisor)
- UI/UX design (use designer agent)
- Database schema design (use data-architect)
```
## Delegation Patterns
### One-Way Handoff
Agent completes work and hands off to next agent:
```markdown
Senior Engineer
1. Completes implementation
2. Documents approach
3. Hands off to Code Reviewer
↓
Code Reviewer
1. Receives implementation
2. Performs review
3. Provides feedback
```
**When to use**: Sequential workflow, clear completion criteria
**Example**:
```markdown
## Delegation Protocol in senior-engineer.md
After implementation:
1. Document changes made
2. Run tests and verify success
3. Create summary for code-reviewer
4. Delegate to code-reviewer with context
5. DO NOT return to implementation unless requested
```
### Consultation Pattern
Agent delegates for advice, then continues work:
```markdown
Senior Engineer
1. Encounters architectural decision
2. Delegates to technical-architecture-advisor
3. Receives architectural guidance
4. Continues implementation with guidance
```
**When to use**: Specialized knowledge needed, agent continues after consultation
**Example**:
```markdown
## Delegation Protocol in senior-engineer.md
When architectural guidance needed:
1. Identify architectural question
2. Prepare context and specific questions
3. Delegate to technical-architecture-advisor
4. Receive recommendations
5. Incorporate into implementation plan
6. Continue implementation
```
### Parallel Execution
Multiple agents work simultaneously:
```markdown
Orchestrator
├─→ Backend Developer (API implementation)
├─→ Frontend Developer (UI implementation)
└─→ Documentation Writer (docs update)
↓
Integration Phase
```
**When to use**: Independent tasks, can run concurrently
**Example**:
```markdown
## Orchestrator Delegation
For feature development:
1. Break down into independent components
2. Delegate backend to senior-engineer-backend
3. Delegate frontend to senior-engineer-frontend
4. Delegate docs to documentation-writer
5. Monitor progress from all agents
6. Coordinate integration when complete
```
### Iterative Refinement
Agent delegates, receives feedback, iterates:
```markdown
Developer
↓
Code Reviewer → Feedback
↓
Developer (iteration)
↓
Code Reviewer → Approval
```
**When to use**: Quality refinement, iterative improvement
## Context Handoff
### What to Pass
**Always include**:
- Purpose of delegation
- Current state/progress
- Specific questions or tasks
- Success criteria
- Relevant files or code
- Constraints or requirements
**Example handoff message**:
```markdown
@technical-architecture-advisor
I need architectural guidance for implementing a caching layer.
**Context**:
- Current system: REST API with PostgreSQL
- Performance issue: N+1 queries on user dashboard
- Load: 10k requests/hour, growing 20% monthly
**Specific Questions**:
1. Should we use Redis or in-memory caching?
2. What caching strategy (write-through, write-back)?
3. How to handle cache invalidation?
**Constraints**:
- Must support horizontal scaling
- Budget: Can add $200/month infrastructure
- Timeline: 2 weeks
**Files**:
- src/api/users.js (current implementation)
- src/database/queries.js (problematic queries)
**Success Criteria**:
- Dashboard load time < 500ms
- Cache hit rate > 80%
- Zero data inconsistencies
```
### What NOT to Pass
- Unnecessary history
- Unrelated code
- Implementation details (unless relevant)
- Personal opinions without context
- Ambiguous requirements
## Agent Coordination
### Shared Context Files
Use shared files for multi-agent workflows:
```markdown
# .plans/feature-implementation.md
## Status: In Progress
## Architecture Review
**Owner**: technical-architecture-advisor
**Status**: ✅ Complete
**Outcome**: Use microservices pattern, see details below
## Implementation
**Owner**: senior-engineer
**Status**: 🔄 In Progress (60%)
**Next Steps**: Complete API endpoints
## Testing
**Owner**: QA agent
**Status**: ⏸️ Waiting for implementation
```
### Communication Protocol
**Starting Delegation**:
```markdown
@agent-name
**Task**: [Clear, specific task]
**Context**: [Essential background]
**Deliverables**: [What you need back]
**Timeline**: [If applicable]
```
**Completing Delegation**:
```markdown
@delegating-agent
**Status**: Complete
**Summary**: [What was done]
**Deliverables**: [Links to files, decisions]
**Next Steps**: [What should happen next]
**Blockers**: [Any issues encountered]
```
## Delegation Anti-Patterns
### ❌ Circular Delegation
```
Agent A → Agent B → Agent C → Agent A (infinite loop)
```
**Fix**: Clear ownership and final decision maker
### ❌ Over-Delegation
```
Agent delegates every tiny decision
```
**Fix**: Delegate only when specialized expertise needed
### ❌ Under-Context
```
@agent: "Please help" (no context provided)
```
**Fix**: Provide comprehensive context with every delegation
### ❌ Ambiguous Boundaries
```
Both Agent A and Agent B think they're responsible for task X
```
**Fix**: Document clear responsibility boundaries
## Delegation Decision Tree
```
Does task require specialized expertise?
├─ No → Handle it yourself
└─ Yes → Is the expertise in your domain?
├─ Yes → Handle it yourself
└─ No → Should you learn first or delegate?
├─ Learn → Research then handle
└─ Delegate → Identify appropriate agent
↓
Is agent clearly defined?
├─ Yes → Delegate with full context
└─ No → Create spec for new agent
```
## Agent Configuration Examples
### Proactive Agent
```yaml
---
name: senior-engineer
description: Senior engineer for all development and implementation tasks.
Use PROACTIVELY for fix, implement, build, create, add, refactor, optimize
keywords. Delegates to technical-architecture-advisor for architectural concerns.
---
```
### Reactive Agent
```yaml
---
name: technical-architecture-advisor
description: Architecture evaluation and design guidance. Use when requested
for architectural decisions, system design, or when senior-engineer identifies
architectural concerns requiring expert analysis.
---
```
### Coordinator Agent
```yaml
---
name: workflow-orchestrator
description: Coordinates complex multi-step workflows involving multiple agents.
Use when tasks require coordination between specialized agents, parallel work
streams, or complex dependencies.
---
```
## Testing Delegation
Verify delegation works correctly:
1. **Clear Activation**: Agent activates for intended scenarios
2. **Proper Context**: Receives necessary information
3. **Appropriate Delegation**: Delegates to correct agents
4. **No Loops**: No circular delegation patterns
5. **Clean Handoffs**: Clear completion and transitions
## Best Practices Summary
- [ ] Each agent has single, clear responsibility
- [ ] Activation criteria are explicit and testable
- [ ] Delegation triggers are well-defined
- [ ] Context handoff is comprehensive
- [ ] Boundaries between agents are clear
- [ ] Shared state is managed through files
- [ ] Error handling includes delegation paths
- [ ] No circular delegation patterns
- [ ] Performance impact is considered
## Integration Points
This skill informs:
- Agent specification creation
- AGENTS.md documentation
- Workflow design
- Plugin architecture
- Team collaboration patterns