comm

name

comm

description

Communication consultant for messages to a specific person — Slack, email, LinkedIn, PR or Linear comments, meeting prep. Use when drafting, reviewing, calibrating tone, picking register, or managing recipient profiles (look up, refresh stale). Triggers: 'draft a message to', 'reply to', 'help me respond', 'how do I tell/push back on X', 'is my draft for Y OK', 'calibrate', 'profile for', 'prep for 1:1 with', and any task where the recipient is a specific named person.

/comm — Communication Consultant

A communication consultant skill. Invoke before drafting any message to a specific person, or when you need to think through how to communicate with someone.

What it does

Given a recipient and a situation, returns:

1. Strategy — what to aim for, what leverage point to use, what to avoid
2. Tactics — specific moves (e.g. "frame as customer impact", "propose alternative", "offer huddle")
3. Register/structure — medium, length, paragraphs vs bullets, capitalization, tone
4. Excerpt of "Communication tips for [user]" from the recipient's profile

It does NOT draft the message itself — that's a per-call prompt-level choice.

Data root resolution

Profiles live at a configurable data root:

1. If ~/.claude/skills/comm/comm-config.json exists, use its data_root field (tildes expanded).
2. Else, use <skill>/data/.

The data root contains:

• INDEX.md — roster
• <slug>.md — one file per person
• self-profile.md — the user's own profile (optional)

Config fields

comm-config.json accepts:

• data_root (string) — see above.
• pr_review_policy (optional, "binary" | "non-blocking-allowed") — when the calibrate medium is a PR review comment, overrides the self-profile's PR-review register default. "binary" = approve OR request-changes, no non-blocking-only passes. "non-blocking-allowed" = Conventional Comments with both blocking and non-blocking labels allowed. Omit to defer to whatever the self-profile says.

See comm-config.example.json for the canonical template.

Theory references

references/ ships with:

• comm-psych-index.md — situation → topic router
• comm-psych-disc.md, comm-psych-attachment-theory.md, comm-psych-conflict-modes.md, comm-psych-async-communication.md, comm-psych-cross-cultural.md, comm-psych-managing-difficulty.md, comm-psych-motivation.md, comm-psych-situational-leadership.md, comm-psych-upward-management.md
• profile-template.md — canonical profile structure
• profile-template-self.md — canonical self-profile structure
• freshness-policy.md — when to refresh a profile

---

Onboarding

/comm onboard

First-run setup. Takes a new user from a fresh clone to a working skill. Suggest it automatically the first time the skill is used with no self-profile present; it can also be invoked directly.

1. Confirm the data root. Resolve per "Data root resolution". If there's no comm-config.json, explain the default (<skill>/data/) and offer to create the config pointing at a writable, ideally private profiles directory — profiles hold candid notes about colleagues, so keep them out of shared or committed locations.
2. Build the self-profile — the highest-value step, since it's what lets calibration override naive style-mirroring. Walk through references/profile-template-self.md one section at a time:
   • DISC / attachment / conflict-style summary
   • Default posture rules
   • Strengths and watch-outs
   • Register defaults by medium Ground every answer in the user's own evidence. If you have access to a sample of their recent messages, offer to draft a starting version for them to correct — never invent traits. Write <data-root>/self-profile.md with today's last_verified (run date -u '+%Y-%m-%d').
3. Create the first recipient profiles. Run the /comm profile new wizard for 1–2 people the user communicates with most (e.g. their manager and one peer) so they see the value immediately.
4. Profile team cultures (optional). If the user works across cultures, list the nationalities on their team and, per references/comm-psych-cross-cultural.md, build a short culture profile for each one they don't already know well.
5. Set policy and finish. Confirm pr_review_policy if they review PRs. Print next steps: Try /comm calibrate <person> "<situation>".

Keep it conversational and skippable. The self-profile alone makes calibration useful — the user can stop there and add recipient profiles as they go.

---

Profile Management

/comm profile list

Show the roster.

1. Resolve data root (see Data root resolution above).
2. Read <data-root>/INDEX.md.
3. Print the table: name, role, relationship, last_verified, tags.
4. Flag any profile with last_verified older than 45 days as STALE; older than 90 days as BLOCKED.

/comm profile show <person>

Print the full profile for one person.

1. Resolve data root.
2. Find the profile file: try <data-root>/<slug>.md where <slug> is the lowercase, hyphen-separated version of <person>. If not found, grep INDEX.md for <person> and present matches.
3. If multiple matches: ask user to pick one.
4. Print the file content.
5. Flag freshness status against the freshness policy.

/comm profile new <person>

Wizard: create a new profile.

1. Resolve data root. If unwritable, surface error and stop.
2. Ask the user (one question at a time):
   • Display name (full name if different)
   • Slack ID (optional)
   • Email (optional)
   • Role (short description)
   • Relationship (manager | peer | direct-report | report | vendor | external)
   • DISC personality guess (D/I/S/C or combinations, e.g. "CD")
   • Tags (comma-separated)
   • One-sentence "what works when communicating with them" — seeds the Communication tips section
3. Render the new profile using references/profile-template.md. Set last_verified and created to today (run date -u '+%Y-%m-%d' for authoritative timestamp).
4. Write to <data-root>/<slug>.md. Append a row to INDEX.md.
5. Confirm with the user. Offer to populate more sections now or defer.

/comm profile edit <person>

Open a profile for direct edit.

1. Resolve data root + locate the profile file.
2. Open the file for edit (Read + show to the user, then Edit on their input).
3. On save, prompt: "Bump last_verified to today?" Default yes.

/comm profile refresh [person|all]

Check freshness and propose updates.

1. Resolve data root.
2. For each target profile, check last_verified against references/freshness-policy.md:
   • <45 days: skip (fresh)
   • 45-90 days: flag and propose refresh

   • 90 days: block use — require refresh before next calibrate

3. For each stale profile:
   • Scan the last 30 days (or last 20-30 messages, whichever is broader) from/with that person across Slack channels (use slack_search with from:<@id> or in:<dm>).
   • Surface candidate updates (new behavior, contradictions, role changes).
   • Propose specific edits. On approval, apply via Edit and append a Recent Signals entry.
   • Bump last_verified only after edits land.

---

Calibrate Workflow

The core flow. Called via /comm calibrate <person> [situation] or routed from a freeform query.

Steps

1. Identify recipient(s) + situation

   • Recipient(s) from the invocation argument or the user's freeform query.
   • Situation = what's happening (a Slack thread, a 1:1, a PR comment, etc.).
   • Medium = where it lands (Slack DM, Slack channel, email, LinkedIn, in-person).
   • If any of these are ambiguous, ask one targeted question.

2. Identify strategic goal

   • Pick one: inform | persuade | push back | escalate | de-escalate | set boundary | build relationship | give feedback | ask for help.
   • If unstated, ask: "What are you trying to achieve here?" with the options above as a multi-choice.

3. Load recipient profile

   • Resolve data root → locate profile file by slug.
   • If missing: surface "No profile for . Want to create a stub now or proceed without?" Default: create stub with minimal fields, then proceed.
   • Check last_verified against references/freshness-policy.md:
     • <45d: proceed
     • 45-90d: flag inline ("Profile last verified ; using anyway but consider /comm profile refresh")
     • >90d: BLOCK. Force /comm profile refresh <person> before continuing.

4. Load self-profile

   • Read <data-root>/self-profile.md if it exists. Extract: posture rules, escalation patterns, strengths and watch-outs, register defaults.
   • If missing: surface "No self-profile yet — calibration will use the recipient profile only. Run /comm onboard to set one up (it's the highest-value step)." Offer to onboard now or defer.
   • PR review medium override: if the situation's medium is a PR review comment AND comm-config.json has pr_review_policy set, that value overrides any PR-review register default in the self-profile. Surface the override in the Register section of the output (e.g., "PR review policy: binary (from config)").

5. Pick leverage point

   • Goal × recipient × situation → which theory framework applies.
   • Routing table:

     Goal	Recipient	Load
     push back	manager	comm-psych-upward-management.md
     give feedback	direct-report	comm-psych-situational-leadership.md
     de-escalate	any	comm-psych-conflict-modes.md
     accommodate	any (under stress)	comm-psych-managing-difficulty.md
     motivate	direct-report	comm-psych-motivation.md
     sync vs async	any	comm-psych-async-communication.md
     cross-region	any (cultural mismatch)	comm-psych-cross-cultural.md
     any	any (read style signals)	comm-psych-disc.md

   • When in doubt, load comm-psych-index.md and route from there.

6. Synthesize and return

   Output structure:

   ## Strategy
   What to aim for, leverage point, what to avoid.
   
   ## Tactics
   - Move 1: ...
   - Move 2: ...
   - Move 3: ...
   
   ## Register
   - Medium: <Slack DM | Slack channel | email | …>
   - Length: <one-liner | short paragraph | full prose>
   - Structure: <lowercase one-liner | sentence-case paragraphs | bulleted>
   - Tone: <peer-warm | peer-direct | formal-warm | formal-direct>
   - Special: <e.g. "no em-dashes", "don't apologize twice", "open with the ask">
   
   ## From profile
   > [Excerpt from "Communication tips for [user]" section, 3-5 bullets]
   
   ## Sources
   - Profile: <data-root>/<slug>.md (last_verified: <date>)
   - Self-profile: <data-root>/self-profile.md (last_verified: <date>)
   - Theory: references/<framework>.md
   

7. The skill stops here. The caller (the user, or another skill) decides whether to draft the message. The skill does not draft by default.

Freeform routing

When invoked as /comm without a subcommand, or via natural language that matches the description triggers ("help me reply to X", "is my draft to Y OK", "how do I tell Z"):

1. Extract recipient(s) from the query if possible.
2. Infer the strategic goal from verb cues:
   • "reply to", "respond to" → inform or de-escalate (ask which)
   • "push back", "disagree with" → push back
   • "tell", "give feedback to" → give feedback
   • "ask", "request" → persuade
   • "is my draft OK" → calibrate (sanity check mode handled at prompt level)
3. Route into the calibrate workflow with extracted args.
4. If extraction fails, ask: "Who's the recipient, and what are you trying to do?"