communication-guidelines

Use when starting work - guidelines for asking questions and commit policies

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 15, 2025

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.
namecommunication-guidelines
descriptionUse 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 --amend unless user requests it
    • Respect commit history
  • 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:

  1. Is this information necessary to proceed? (If no → proceed with reasonable defaults)
  2. Are there multiple valid approaches with different trade-offs? (If yes → ask)
  3. Could my assumption cause significant rework if wrong? (If yes → ask)
  4. 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