communication-craft
Skill0 starsChanged 9 days agoMITView on GitHub
Communication patterns for feedback, cross-audience content, and eliciting needs. SBI feedback model (Situation → Behavior → Impact), stakes-calibrated review voice, So-What/What/Now-What audience lead for PRs and status reports, and the three-layer Need/Solution/Feature elicitation ladder. Use when giving feedback in a review, writing for a mixed audience (decision-makers + peers + newcomers + skeptics), clarifying an ambiguous ask before committing to a solution, or coaching someone else's communication.
In this repository66 other files it gives its agents.
- AGENTS.mdAGENTS.md
- skills/bootstrap-project/resources/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- skills/bootstrap-project/resources/CLAUDE.mdCLAUDE.md
- act-tenetsSkill
- adversarial-reviewSkill
- annotate-screenshotSkill
- anti-hallucinationSkill
- ascii-chartSkill
- assess-brainSkill
- big-ideaSkill
- bootstrap-coreSkill
- bootstrap-projectSkill
- browser-toolsSkill
- chart-big-ideaSkill
- chart-interpretationSkill
- chart-vocabularySkill
- code-reviewSkill
- compile-brainSkill
- convertSkill
- corpus-qa-sweepSkill
- critical-thinkingSkill
- deep-reviewSkill
- doc-hygieneSkill
- docs-shellSkill
- docx-to-mdSkill
- ethical-reasoningSkill
- evaluate-before-adoptingSkill
- figure-generatorSkill
- flint-chartSkill
- flint-interactionsSkill
- flint-themeSkill
- git-workflowSkill
- html-to-mdSkill
- humanizerSkill
- install-visual-companionsSkill
- lint-clean-markdownSkill
- markdown-mermaidSkill
- markdown-sanitization-chainSkill
- md-to-emlSkill
- md-to-htmlSkill
- md-to-txtSkill
- md-to-wordSkill
- meditationSkill
- mutation-testingSkill
- planSkill
- platform-awarenessSkill
- print-svg-style-guideSkill
- proactive-awarenessSkill
- problem-framing-auditSkill
- project-capability-authoringSkill
- project-statusSkill
- render-chartSkill
- render-verifySkill
- rich-emailSkill
- risk-analysisSkill
- security-and-hardeningSkill
- setup-dependenciesSkill
- setup-enterprise-stackSkill
- spikeSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 40
Rule of Three: If giving 3+ critical pieces of feedback on one artifact, stop and ask whether the _level_ of review is right — don't pile …
- Distinctive: line 56
When the user says "build me X," distinguish three layers:
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Communication Craft
Patterns for feedback, audience, and elicitation. Inherited LLM behaviors (clear prose, jargon-defining, signposting) are assumed and not re-stated. Fires on description-match when the request is about how to communicate — for the always-on tone/attunement rules that fire on every user message, see emotional-intelligence.instructions.md.
1. Giving Feedback
SBI Model — Situation, Behavior, Impact
| Component | Include | Example |
| Situation | Specific context | "In parseInput() line 42..." |
| Behavior | Observable action, not interpretation | "...the function mutates the input array..." |
| Impact | Effect on caller / system / reader | "...which breaks the contract for any caller passing a frozen array." |
Anti-pattern: "This is wrong." → Replace with "This could cause X. Suggest: [specific change]."
Calibrate to Stakes
| Stakes | Approach |
| Low (typo, style) | Quick inline note, no fanfare |
| Medium (pattern, design choice) | Specific rationale + suggested alternative |
| High (security, contract, irreversible) | Full explanation, alternatives, would-revise-if |
Code Review Voice
| Avoid | Prefer |
| "This is wrong" | "This could cause X" |
| "Why did you do this?" | "What led to this approach?" |
| "Obviously should be..." | "Consider X because..." |
| "Please fix" | "Suggest: [specific change]" |
Rule of Three: If giving 3+ critical pieces of feedback on one artifact, stop and ask whether the level of review is right — don't pile on.
2. Audience Lead
So-What → What → Now-What for PRs, summaries, status reports, decision asks: lead with impact, then evidence, then ask. Anti-pattern: data dump first, ask buried at the end.
| Audience | Lead with | Avoid |
| Decision-maker | Impact + ask | Implementation detail |
| Peer engineer | Approach + trade-offs | Marketing language |
| Domain expert | Specifics + edge cases | Over-explanation |
| Newcomer | Context + prerequisites | Jargon without definition |
| Skeptic | Concerns + mitigation | Aggressive certainty |
3. Eliciting Needs
When the user says "build me X," distinguish three layers:
| Layer | Question | Example |
| Need (why) | What outcome do you want? | "Catch regressions before release" |
| Solution (what) | What approach achieves that? | "Pre-merge integration test" |
| Feature (how) | What specific thing to build? | "GitHub Action running tests on PR" |
Validate the need before committing to a solution. One sharp question beats five generic ones. Ask "why" up to five times when the root need is unclear.
Related
- emotional-intelligence.instructions.md — the always-on tone/attunement rules that read every user message; this skill fires when the user's request is about how to communicate (feedback, audience, elicitation)
- big-idea skill — the compression discipline that distills the "So-What" that this skill's audience-lead pattern requires
- status-reporting skill — a specific application of the audience-lead pattern for status updates
Would Revise If
Revise if SBI feedback fails to identify a specific behavior and its impact, the audience-lead table produces a tone mismatch in a concrete case, or the elicitation pattern misses a user need that later surfaces as a scope change.
Runtime contract references
Load only the reference selected by the triggering instruction; do not replay all runtime contracts for unrelated work. These references add no authority and do not call the instruction again.
- identity: alex-finch-personality
- emotional-attunement: emotional-intelligence
- reliance: reliance-nudges
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.