communication-guidelines
Use when starting work - guidelines for asking questions and commit policies
When & Why to Use This Skill
This Claude skill establishes a robust communication and operational framework for AI agents, specifically designed to streamline the software development lifecycle. By defining clear triggers for clarifying questions and enforcing strict git commit and pull request policies, it ensures that the agent operates with the right balance of autonomy and user oversight. This skill is essential for maintaining code integrity, reducing development friction, and ensuring that AI-driven workflows align with professional engineering standards.
Use Cases
- Project Onboarding: Use this skill when starting a new task to align the AI agent with specific team communication preferences and technical decision-making frameworks.
- Requirement Clarification: Automatically identify ambiguous requests (e.g., 'optimize this') and prompt the agent to ask for specific targets like speed, memory, or readability before starting work.
- Version Control Governance: Enforce strict 'permission-only' policies for git commits and pull requests, preventing unauthorized changes to the repository history.
- Architectural Decision Making: Guide the agent to seek explicit confirmation for significant design choices, such as selecting state management libraries or authentication methods, to avoid costly rework.
- Workflow Optimization: Minimize 'noise' by training the agent to proceed independently on trivial tasks like code formatting or running tests while remaining vigilant on complex feature implementations.
| name | communication-guidelines |
|---|---|
| description | Use when starting work - guidelines for asking questions and commit policies |
Communication Guidelines
Use this skill at the start of work to determine when to ask questions and follow commit policies.
Checklist
When to Ask Clarifying Questions
Ask questions for:
- Ambiguous requests - Multiple valid interpretations exist
- Example: "optimize this" → Ask: speed, memory, or readability?
- Example: "improve performance" → Ask: runtime, bundle size, or render speed?
- Complex features - Significant design decisions required
- Example: "add authentication" → Ask: JWT, OAuth, session-based?
- Example: "add state management" → Ask: Zustand store, React Query, local state?
- Missing context - Information needed to implement correctly
- Example: "fix the bug" → Ask: which bug? What's the expected behavior?
When to Skip Questions
Proceed directly for:
- Trivial commands - Clear, single-step operations
- Examples: "run tests", "format code", "type check"
- Well-defined tasks - All necessary information provided
- Examples: "add logging to generateImage()", "fix type error in service.ts:42"
- Standard operations - Following established patterns
- Examples: "create a test for this component", "add error handling here"
Commit and PR Policies
- Never create commits without explicit permission
- Wait for user to say "commit this" or "create a commit"
- Don't assume completion means commit
- Never amend commits without explicit permission
- Don't use
git commit --amendunless user requests it - Respect commit history
- Don't use
- Ask before creating pull requests
- Don't automatically create PRs after completing work
- Wait for user to request PR creation
Decision-Making Framework
Before asking a question, check:
- Is this information necessary to proceed? (If no → proceed with reasonable defaults)
- Are there multiple valid approaches with different trade-offs? (If yes → ask)
- Could my assumption cause significant rework if wrong? (If yes → ask)
- Is this a trivial/standard operation? (If yes → proceed)
Examples:
❌ Don't ask: "Should I use single or double quotes?" (Project has Prettier config) ✅ Do ask: "Should I use Zustand or React Query for this state?" (Architectural decision)
❌ Don't ask: "Should I run the tests?" (Standard verification step) ✅ Do ask: "Should I mock Socket.io or use real connections for this test?" (Testing strategy)
Communication Style
- Be concise and direct
- Focus on technical clarity over politeness
- Provide options when asking questions (use AskUserQuestion tool)
- Explain trade-offs when recommending approaches