Comment Writer: Warm Collaboration Comments
Write warm, direct, and useful collaboration comments for PR feedback, issue replies, and team messages.
The skill is static text guidance plus a read-only PR inspection command, no network access or external side effects; it handles no sensitive data, but lacks user confirmation and explicit data-flow disclosure. Deductions for missing confirmation, limited transparency, and unverified authorship.
Instructions are self-consistent and examples are clear, but no tests or executable verification exist; the command relies on GH CLI and no error handling or failure feedback is provided. Deductions for lack of reproduction and thin error handling.
Use cases are clear (PR comments, issue replies, etc.), trigger description is specific, but capability boundaries and non-fit scenarios are not declared; no overseas service dependency noted. Deductions for incomplete boundaries and trigger conditions.
Documentation is structured, with version and metadata, but missing install/dependency notes, FAQ, known limitations, and changelog; license conflicts with repository (Apache-2.0 vs MIT), and provenance is only an author name. Deductions for incomplete governance and license discrepancy.
Value proposition is clear and examples are directly usable, but no comparative evidence or representative output verification; command may not apply to all PR scenarios. Deductions for unverified effectiveness and limited completeness evidence.
No tests, CI, or third-party evidence for the skill itself; the command uses a common tool but has no recorded execution. Deductions for lack of internal tests and independent corroboration.
- The skill is static guidance with no tests or execution verification; actual effectiveness is unverified.
- The PR inspection command depends on GitHub CLI, which may not be available everywhere; no clear error handling or failure feedback.
- Capability boundaries are not declared, risking misuse in unsuitable scenarios.
- License declaration conflicts with the repository: SKILL.md says Apache-2.0, repo is MIT; confirm ownership.
- Author is unverified, and maintenance responsibility and update path are unclear.
What does this skill do, and when should you use it?
This skill guides an AI agent in writing clear, warm, and direct messages for comments that will be read by other humans, such as GitHub PR comments, issue replies, review feedback, Slack messages, and async project updates. It emphasizes being useful fast, keeping comments short, and explaining the reasons behind requested changes. The skill provides a set of voice rules, a three-part comment formula (direct observation, why it matters, and concrete next action), and examples for different scenarios like requesting a change, approving with a note, and asking for a split.
The skill reads the target context's language to determine the writing language (e.g., Spanish issue → Spanish comment, English issue → English comment). It applies a set of voice rules: be useful fast, be warm and direct, keep it short, explain why, avoid pile-ons, and match the target context language. It provides a comment formula consisting of a direct observation or request, an optional explanation of why it matters, and a concrete next action. It includes examples for requesting changes, approving with a note, and asking for a split. It also suggests a command (gh pr view) to inspect a PR before providing feedback, but this is optional. The skill does not execute any automation; it only provides writing guidelines.
- A developer providing review feedback on a GitHub PR who wants to be helpful and direct without writing a lengthy summary.
- A maintainer replying to an issue who needs a concise, warm response with actionable next steps.
- A team member writing an async project update on Slack or Discord who wants to be clear and direct.
- A reviewer requesting changes who needs to explain the technical reason without being verbose.
- A developer who wants to split a large PR and needs to suggest a logical order for splitting.
What are this skill's strengths and limitations?
- Provides clear, actionable guidelines for writing effective collaboration comments
- Emphasizes directness and warmth, avoiding overly technical jargon
- Supports language matching (e.g., write in Spanish if the context is Spanish)
- Applies to multiple communication platforms
- Includes practical examples for requesting changes, approvals, and PR splits
- Only provides writing guidance, does not automatically generate or post comments
- Does not include a test suite or automated validation
- Implementation of warmth and directness rules may vary by model
- Does not cover platform-specific formatting (e.g., Markdown tables or Slack blocks)
How do you install this skill?
This skill is bundled in the Gentle-AI repository at internal/assets/skills/comment-writer/SKILL.md. To install the whole collection, follow the Gentle-AI installation instructions in the README (e.g., for macOS/Linux, run curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash). After installation, the skill should be available automatically if your agent supports skill registration.
How do you use this skill?
Load the skill whenever you need to write a comment by invoking a prompt that mentions it, such as "Write a friendly review feedback for this PR" or "Draft a comment to respond to this issue". Follow the voice rules and comment formula provided: start with a direct observation or request, add the reason if needed, and end with a concrete next action. If the context is in Spanish, write in neutral/professional Spanish by default unless otherwise requested.