ComfyUI MCP Server

# Skill Development Best Practices **Purpose**: Guide for creating well-structured, maintainable skills for Cursor and GitHub Copilot that follow industry best practices. ## Core Principles ### Multi-Editor Compatibility - Use `AGENTS.md` files as universal standard (supported by Cursor, Copilot, and other AI tools) - Keep skills in `.cursor/skills/[name]/SKILL.md` format for Cursor-specific features - Support `.github/copilot-instructions.md` for Copilot users - Maintain hierarchical organization (nearest-wins for AGENTS.md files) ### Content Guidelines **What TO Include:** - ✅ High-level context (repository purpose, tech stack, architecture) - ✅ Build & validation steps (exact commands with preconditions/postconditions) - ✅ Project layout (directory structure, key file locations) - ✅ Coding standards (language-specific conventions, style guides) - ✅ Common pitfalls (documented errors and workarounds) - ✅ Testing patterns (how to run tests, validation steps) - ✅ Tool-specific instructions (scripts that must be run in order) - ✅ Environment setup (required dependencies, versions) **What NOT to Include (Guardrails):** - ❌ Task-specific instructions (keep general, not for one-off tasks) - ❌ Excessive length (max 2 pages for repo-wide instructions) - ❌ Duplicate information (don't repeat what's in code/comments) - ❌ Outdated patterns (keep synchronized with codebase) - ❌ Secrets or credentials (never hardcode sensitive data) - ❌ Overly prescriptive details (allow AI flexibility within guidelines) ## Skill Structure Best Practices ### Standard Skill Template ```markdown # Skill Title ## Purpose Brief description of what this skill covers and when to use it ## Core Principles - Key principle 1 - Key principle 2 - Key principle 3 ## Technical Stack - Language/Framework version - Key dependencies - Tool requirements ## Code Style Standards ### Formatting - Specific formatting rules - Linting configuration ### Naming Conventions - File naming patterns - Variable/function naming - Class/module naming ## Common Patterns ### Pattern 1: [Name] Description and example ### Pattern 2: [Name] Description and example ## Build & Test ### Setup Commands ```bash # Command with explanation command --flags ``` ### Testing Commands ```bash # How to run tests pytest tests/ ``` ### Validation Steps 1. Step 1 2. Step 2 ## Common Mistakes & Solutions ### Mistake 1 **Problem:** Description **Solution:** Fix **Prevention:** How to avoid ### Mistake 2 **Problem:** Description **Solution:** Fix **Prevention:** How to avoid ## Additional Resources - Link to docs - Related skills ``` ## When to Create Skills ### Create Separate Skills When: 1. **Different domains** - Frontend vs backend, data vs compute 2. **Different frameworks/tools** - React vs Vue, FastAPI vs Django 3. **Conflicting conventions** - Different style guides for different parts 4. **Reusable across projects** - Generic patterns applicable elsewhere 5. **Complex multi-step workflows** - Deployment, testing pipelines ### Consolidate Skills When: 1. **Closely related technologies** - React + TypeScript 2. **Same project phase** - Development, testing, deployment 3. **Complementary patterns** - Database + ORM patterns 4. **Risk of context fragmentation** - Too many small skills ## Skill Size Guidelines ### Small Skills (< 200 lines) - Single framework basics - Specific design patterns - Tool-specific configurations - **Example:** Docker Compose patterns, Commit message guidelines ### Medium Skills (200-500 lines) - Full-stack framework rules - Architectural patterns - Complete testing strategies - **Example:** FastAPI development, Discord bot development ### Large Skills (500+ lines) - Consider splitting into sub-skills - Use supporting files for related content - Organize with clear section headers - **Example:** Core PIV loop (split into prime/plan/execute) ## Optimization Strategies ### For Token Efficiency - **Use bullet points** over paragraphs - **Prioritize actionable instructions** over explanatory text - **Reference files by path** instead of including full content - **Use "always/never" language** for critical rules - **Group related concepts** to reduce repetition ### For Accuracy - **Be specific about versions** (e.g., "Python 3.10+", "React 19") - **Include example commands** that have been tested - **Document the "why"** for non-obvious rules - **Provide context** for when rules apply/don't apply ### For Maintainability - **Version control** all instruction files - **Add "Last Updated"** dates or version tags - **Document drift** between instructions and actual code - **Review after major changes** to tech stack or patterns - **Use consistent formatting** across all skills ## Path-Specific Instructions (Copilot) Use frontmatter in `.github/instructions/` files for scoped rules: ```markdown --- applyTo: "**/*.py" excludeAgent: "code-review" # Optional: exclude from code-review or coding-agent --- Python-specific rules here ``` ### Glob Pattern Examples - `*` - All files in current directory - `**` or `**/*` - All files in all directories - `*.py` - All Python files in current directory - `**/*.py` - All Python files recursively - `src/**/*.py` - All Python files in src/ recursively - `**/tests/**/*.py` - All Python files in any tests/ directory ## Quality Checklist Before committing a new skill, verify: - [ ] **Reduces exploration time** - AI doesn't need to search for basic info - [ ] **Commands are tested** - All examples work as written - [ ] **Appropriate length** - Not too long (< 2 pages general rules) - [ ] **Avoids task-specifics** - General patterns, not one-off tasks - [ ] **Accurate paths/versions** - All references are current - [ ] **Documents common errors** - Known issues and fixes - [ ] **Understandable by newcomers** - Clear for those unfamiliar with project - [ ] **No sensitive data** - Free of secrets, credentials, API keys - [ ] **Consistent formatting** - Follows project markdown standards - [ ] **Linked properly** - Referenced in parent AGENTS.md if applicable ## Supporting Files Skills can include additional files for complex topics: ### Common Supporting Files - **testing-patterns.md** - Detailed testing strategies - **troubleshooting.md** - Common issues and solutions - **examples/** - Code examples directory - **templates/** - Template files - **migration-guide.md** - Upgrade/migration instructions ### When to Use Supporting Files - Main SKILL.md exceeds 500 lines - Detailed reference material needed - Multiple related subtopics - Template/example code included ## Universal vs Editor-Specific Features ### Universal (Works in Both Cursor & Copilot) - Natural language instructions - Markdown formatting - File structure documentation - Build commands - Testing guidelines - Code style rules ### Cursor-Specific - Skills with executable scripts - .cursor/rules files - Cursor commands integration - Custom keyboard shortcuts ### Copilot-Specific - Path-specific glob patterns with frontmatter - excludeAgent directives - .github/copilot-instructions.md - Integration with GitHub workflows ## Integration Patterns ### Referencing Other Skills ```markdown See [FastAPI Development](../fastapi-development/SKILL.md) for API patterns. ``` ### Linking to AGENTS.md ```markdown For project-wide rules, see [Root AGENTS.md](../../AGENTS.md). For Lambda-specific rules, see [Lambda AGENTS.md](../../04-lambda/AGENTS.md). ``` ### Cross-Referencing Documentation ```markdown For deployment procedures, see [docs/DEPLOYMENT.md](../../docs/DEPLOYMENT.md). ``` ## Maintenance Workflow ### Regular Review Schedule 1. **After major dependency updates** - Review affected skills 2. **Quarterly reviews** - Check all skills for drift 3. **When patterns change** - Update immediately 4. **On team feedback** - Incorporate improvements ### Update Process 1. Identify outdated content 2. Test new commands/patterns 3. Update skill content 4. Add "Last Updated" note 5. Notify team of changes 6. Update related skills if needed ### Deprecation Process 1. Mark skill as deprecated in header 2. Document replacement skill 3. Keep for 1-2 sprints 4. Archive (don't delete immediately) 5. Update references in other skills ## Example: Creating a New Skill ### 1. Create Directory ```bash mkdir -p .cursor/skills/new-skill-name ``` ### 2. Create SKILL.md Use the standard template above, filling in: - Clear purpose statement - Core principles (3-5 key rules) - Technical requirements - Common patterns - Validation steps ### 3. Add Supporting Files (Optional) ```bash touch .cursor/skills/new-skill-name/testing-patterns.md touch .cursor/skills/new-skill-name/troubleshooting.md ``` ### 4. Test the Skill - Use in actual development - Have teammate review - Verify AI understands instructions - Check for ambiguity ### 5. Integrate - Link from related skills - Reference in AGENTS.md if needed - Add to skill index/README ## Anti-Patterns to Avoid ### ❌ Over-Specification Don't dictate every implementation detail. Allow AI to use judgment. **Bad:** ```markdown Always use exactly 3 newlines between functions. Variables must be exactly 15 characters long. ``` **Good:** ```markdown Follow Black formatting for Python. Use descriptive variable names. ``` ### ❌ Outdated Information Don't leave deprecated patterns in skills. **Bad:** ```markdown Use Python 2.7 for all scripts. ``` **Good:** ```markdown Use Python 3.10+ features (match statements, type hints). ``` ### ❌ Conflicting Instructions Don't have contradictory rules across skills. **Bad:** ```markdown # In skill A: Always use camelCase # In skill B: Always use snake_case ``` **Good:** ```markdown # In skill A: Use camelCase for JavaScript # In skill B: Use snake_case for Python ``` ### ❌ Excessive Detail Don't document what's already in code or obvious from context. **Bad:** ```markdown The FastAPI decorator @router.get() is used to define GET endpoints. It takes a path as the first argument... ``` **Good:** ```markdown Use dependency injection for database sessions. See services/auth/dependencies.py for patterns. ``` ## Related Skills - [Generate AGENTS.md](../generate-agents-md/SKILL.md) - Automated AGENTS.md generation - [Code Review](../validation/code-review/SKILL.md) - Review patterns for skills - [Init Project](../init-project/SKILL.md) - Setting up new projects with skills ## References - [Cursor Documentation](https://docs.cursor.com/) - [GitHub Copilot Custom Instructions](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) - [AGENTS.md Open Standard](https://github.com/openai/agents.md) - [Awesome Cursor Rules](https://github.com/PatrickJS/awesome-cursorrules) --- **Last Updated**: January 22, 2026 **Maintainer**: Development Team **Version**: 1.0.0