| name | zammad-mcp-quality |
| description | Quality assurance and CodeRabbit learning system for Zammad MCP development. Use when creating PRs, implementing MCP tools, adding pagination, handling errors, or addressing CodeRabbit feedback. Provides checklists, pattern guides, and accumulated project learnings to prevent recurring issues. |
Zammad MCP Quality Guardian
Purpose
Ensure consistent, high-quality contributions to the Zammad MCP project by:
- Preventing recurring issues flagged by CodeRabbit
- Providing actionable checklists for self-review
- Capturing project learnings in accessible references
- Systematic improvement through feedback loop integration
When to Use This Skill
Trigger this skill when:
- Before creating a PR - Self-review with checklist
- Implementing MCP tools - Follow established patterns
- Adding pagination - Use correct metadata structure
- Handling errors - Create actionable messages
- Addressing CodeRabbit feedback - Learn patterns, not just fix issues
- Onboarding to project - Understand quality standards
- Monthly review - Update learnings from recent PRs
Workflow
1. Pre-Development (Optional)
When starting a new feature, review relevant references:
For pagination features:
→ Read pagination-patterns.md
For error handling:
→ Read error-handling-guide.md
For type-heavy code:
→ Read type-annotation-standards.md
2. During Development
Keep patterns in mind while coding:
- Use Python 3.10+ type syntax
- Provide actionable error messages
- Structure pagination metadata correctly
- Follow naming conventions (no shadowing)
3. Pre-PR Self-Review (CRITICAL)
ALWAYS run through the checklist before creating a PR:
→ Open pre-pr-checklist.md
This takes 5-10 minutes but reduces review iterations by 60-70%.
Quick quality check:
./scripts/quality-check.sh && uv run pytest --cov=mcp_zammad
4. After CodeRabbit Review
When CodeRabbit comments on your PR:
- Fix the immediate issue in your code
- Understand the pattern - don't just copy-paste
- Check if pattern is documented in this skill
- If yes: Review reference to avoid future occurrences
- If no: Consider if pattern should be added
- Search codebase for similar instances
- Update learnings if pattern recurs (see Update Process below)
5. Monthly Review (Maintainers)
Process for keeping skill current:
- Review last 10 merged PRs
- Note recurring CodeRabbit feedback
- Update coderabbit-learnings.md
- Update pre-pr-checklist.md if needed
- Refine reference guides based on new patterns
Estimated time: 30 minutes/month
Reference Documents
📊 Start Here
pre-pr-checklist.md
Quick self-review checklist. Use before every PR.
coderabbit-learnings.md
Consolidated feedback from PR reviews. Living knowledge base.
📚 Deep Dive Guides
pagination-patterns.md
Complete guide to pagination in MCP servers:
- Required metadata fields
- Common mistakes & fixes
- JSON truncation that preserves validity
- Examples from codebase
error-handling-guide.md
Actionable error message patterns:
- Error message template
- HTTP status code mapping
- ID vs number confusion (Issue #99)
- Configuration errors
- Anti-patterns to avoid
type-annotation-standards.md
Python 3.10+ type annotation guide:
- Modern vs legacy syntax
- Parameter shadowing fixes
- Pydantic model types
- Type narrowing with
cast()
- MyPy configuration
Scripts
extract_feedback.py (Future)
Stub for automating CodeRabbit feedback extraction:
python scripts/extract_feedback.py --prs 10 --output references/coderabbit-learnings.md
Status: Planned for Phase 3 automation
See: scripts/extract_feedback.py for stub
Usage Examples
Example 1: Before Creating a PR
User: "I'm ready to create a PR for the new search filter feature"
Codex: Let me help you with pre-PR review using the Zammad MCP Quality skill.
*Reviews pre-pr-checklist.md*
I'll check your code against the quality checklist:
1. Type Annotations ✓
- All functions have return types
- Using modern list[str] syntax
- No parameter shadowing
2. Pagination ⚠️
- Found: response["total"] = len(items)
- Should be: total from API or None
- See pagination-patterns.md line 45
3. Error Handling ✓
- Messages are actionable
- Using proper exception chaining
Let me fix the pagination issue before you create the PR...
Example 2: Implementing New Tool
User: "Add a new tool for managing ticket watchers"
Codex: I'll implement following Zammad MCP patterns from the quality skill.
*Checks coderabbit-learnings.md for relevant patterns*
Key patterns to follow:
1. Use Pydantic model for input (TicketSearchParams pattern)
2. Support ResponseFormat.JSON and .MARKDOWN
3. Clear docstring explaining ID vs number (from Issue #99 learnings)
4. Proper error handling with actionable messages
*Reviews error-handling-guide.md for message templates*
Implementing tool with these quality standards...
Example 3: Addressing CodeRabbit Feedback
CodeRabbit: "The 'total' field is set to page count, not true total across all pages."
Codex: Let me check the pagination-patterns.md guide...
*Reviews pagination-patterns.md section on "Common Mistakes"*
I see - this is a known pattern. The guide shows:
❌ Wrong: response["total"] = len(tickets)
✅ Correct: response["total"] = total_from_api # or None if unknown
Let me fix this and also check for similar instances in the codebase...
*Searches for pattern in other pagination functions*
Found 3 other locations with same issue. Fixing all...
*Updates coderabbit-learnings.md with occurrence count*
Quality Metrics
Track these over time to measure skill effectiveness:
Leading Indicators
- CodeRabbit comments per PR (Target: < 5)
- Checklist completion rate (Target: 100%)
- Pre-commit check pass rate (Target: > 95%)
Lagging Indicators
- Issue recurrence rate (same pattern 2+ PRs)
- Time to first approval (Target: < 1 hour)
- Test coverage (Target: > 90%)
Skill Maintenance
Update Triggers
Update this skill when:
- CodeRabbit pattern appears 2+ times
- Major PR with significant feedback
- New MCP best practice discovered
- Project architecture changes
- Monthly review cycle
Update Process
- Identify pattern from CodeRabbit feedback
- Categorize (pagination, errors, types, etc.)
- Document in appropriate reference guide
- Add to checklist if high-frequency
- Test pattern with codebase examples
- Validate in next PR
Contributors
When updating references:
- Use imperative form (not second person)
- Include code examples (both good and bad)
- Link to source PRs/issues
- Add to relevant checklist items
- Keep
coderabbit-learnings.md as index
Integration with Other Documentation
This skill complements existing docs:
CLAUDE.md - Repository agent guidance
→ Focuses on architecture, development rules
→ Quality skill adds CodeRabbit-specific patterns
.github/copilot-instructions.md - GitHub Copilot guidance
→ Focuses on code generation patterns
→ Quality skill adds review/validation patterns
.coderabbit.yaml - CodeRabbit configuration
→ Focuses on tool settings and path instructions
→ Quality skill captures learnings from reviews
mcp-builder skill - Generic MCP development
→ Focuses on MCP protocol and general patterns
→ Quality skill adds Zammad-specific learnings
Success Stories
Expected outcomes after skill adoption:
Week 1:
- 60-70% reduction in common CodeRabbit comments
- Faster PR reviews (fewer iterations)
- Developers report increased confidence
Month 1:
- Comprehensive reference guides for all major patterns
- Self-documenting knowledge base
- Measurable reduction in repeated feedback
Month 3+:
- Self-improving system with periodic updates
- New contributor onboarding resource
- Foundation for automation (Phase 3)
Troubleshooting
Q: Checklist is too long, takes too much time
A: Focus on sections relevant to your changes. Not every item applies to every PR.
Q: Found a pattern not documented here
A: Great! Document it in coderabbit-learnings.md or open an issue to add it.
Q: CodeRabbit still commenting despite following checklist
A: Skill evolves with project. Update references based on new feedback.
Q: How do I know which reference to read?
A: Start with pre-pr-checklist.md - it links to detailed guides as needed.
Future Enhancements (Phase 3)
Planned automation:
extract_feedback.py - Parse CodeRabbit comments from PRs- Semi-automated skill updates from PR feedback
- CI/CD integration for pre-commit validation
- Metrics dashboard tracking improvement
- Auto-generate monthly learning summaries
Status: Designed in Phase 2, implementation pending
Related Skills
- mcp-builder - Generic MCP server development guidance
- skill-creator - Creating and maintaining skills
Feedback
Skill working well? Great! Keep using the checklist.
Found issues or improvements? Update the skill! It's designed to evolve.
Have questions? Check existing references or ask in PR discussions.
Monthly reviews ensure skill stays current and useful.
This skill is part of a systematic quality improvement system. By using it consistently, you're helping the project learn and improve over time.
