{
  "$schema": "https://humangarden.ai/.well-known/skill-spec.schema.json",
  "canonical_url": "https://humangarden.ai/skills/internal-comms/spec.json",
  "slug": "internal-comms",
  "last_tested": "2026-06-05",
  "tested_by": "humangarden",
  "verdict_one_line": "four well-crafted style guides wrapped in a 33-line dispatcher — zero install, format-correct on 3P updates, but silently falls through to \"general principles\" on incident reports and three other types SKILL.md advertises",
  "fires_when": [
    "user wants to write a 3P (Progress / Plans / Problems) team update",
    "user wants to draft a company-wide newsletter that summarises a week or month",
    "user wants to compile a company FAQ from recent questions",
    "user wants any internal memo, announcement, or org-wide comm",
    "user wants a status / leadership / project / incident update (falls through to general-comms)"
  ],
  "skip_when": [
    "user wants external comms (customer email, press release, marketing copy) — this skill is internal only",
    "user wants the skill to pull from Slack/Drive/Email/Calendar without those tools attached — guidelines reference these sources but the skill itself does not integrate them",
    "user wants a strict, branded incident-report template — SKILL.md lists incident reports but ships no template",
    "user wants Markdown-pure output — the formats embed Slack-style emoji shortcodes (`:megaphone:`, `:dart:`) that render literally outside Slack"
  ],
  "inputs": [
    {
      "type": "prompt",
      "format": "natural-language",
      "constraint": "the more facts you supply (names, dates, metrics, owner) the closer the output will be to publish-ready"
    },
    {
      "type": "structured-data",
      "format": "bullet-dump",
      "constraint": "for 3P updates, providing pre-bucketed Progress / Plans / Problems facts is what makes the output ship-ready"
    }
  ],
  "outputs": [
    {
      "type": "text",
      "format": "markdown",
      "quality_note": "3P format is strict and the skill nails it; newsletter format follows the section template; general-comms output is well-organised prose without a fixed template"
    },
    {
      "type": "text",
      "format": "slack-flavored-markdown",
      "quality_note": "newsletter format uses Slack emoji shortcodes (`:megaphone:`) which render as text outside Slack"
    }
  ],
  "installation": {
    "pip": [],
    "npm": [],
    "system": {},
    "notes": "Pure prompt skill. No requirements.txt, no package.json, no scripts, no tests. The skill is 1 SKILL.md (33 lines) + 4 markdown guideline files in examples/. 'Install' = clone the folder and let the loader read SKILL.md. Works offline. No credentials. No runtime."
  },
  "artifacts": [
    {
      "kind": "text",
      "inline": "USER PROMPT (fed to Claude with internal-comms skill loaded):\n\n\"Write an internal comm announcing that we're freezing merges\nThursday for the mobile release cut. Audience is the whole\nengineering org (~120 people). Cut happens 10am PT Thursday,\nfreeze lifts Friday after smoke tests pass. Mobile release\nmanager is Priya Sundaram. Hot-fix exception process: ping\n#release-eng with reasoning, requires Priya's approval. The\nrelease is v4.7.0 and it's the big rewrite of the onboarding\nflow we've been working on for 3 months.\"\n",
      "caption": "Input — a realistic merge-freeze announcement prompt. Audience + facts + named owner + exception process all provided.",
      "role": "input",
      "hero": true
    },
    {
      "kind": "text",
      "inline": "# Merge freeze Thursday 10am PT — v4.7.0 mobile release cut\n\n**Audience:** All Engineering (~120)\n**From:** Release Engineering\n**Posted:** #eng-announce, mirrored to email\n\n---\n\nHeads up: we're cutting **v4.7.0** — the new onboarding rewrite\n— on **Thursday at 10am PT**. To get a clean cut, all merges to\n`main` are **frozen from 10am PT Thursday until Friday after\nsmoke tests pass**.\n\n**What this means for you**\n- Land everything you want in v4.7.0 by **EOD Wednesday**.\n  Anything merged after Wednesday is going in v4.7.1.\n- During the freeze, your PRs can stay open and reviewed —\n  they just can't merge.\n- The freeze lifts as soon as smoke tests pass on Friday.\n  Watch #release-eng for the all-clear.\n\n**Hot-fix exceptions**\nIf you genuinely need to merge during the freeze (production-down,\nsecurity, blocking another team):\n1. Post in **#release-eng** with the PR link and a one-line\n   \"why this can't wait\".\n2. Get explicit approval from **Priya Sundaram** (release\n   manager for v4.7.0).\n3. Merge, then ping the thread so Priya can re-run the cut.\n\nNo exceptions without Priya's approval. Even mine.\n\n**Why this one matters**\nv4.7.0 is the onboarding rewrite we've been working on for\nthree months. Clean cut = clean release = no late-Friday\nrollbacks. Thanks for holding the line for ~24 hours.\n\nQuestions → #release-eng or DM Priya.\n",
      "caption": "Output — general-comms.md applied. Lead with action + date, scannable bullets, named owner, exception path, closing CTA. Sounds like a real merge-freeze post.",
      "role": "output",
      "hero": true
    },
    {
      "kind": "text",
      "file": "https://humangarden.ai/spec-artifacts/internal-comms/output-3p.md",
      "caption": "3P-format edge case (Platform team). Strict format hit exactly. Note one fabricated metric (\"now at 9\") not supplied by the user.",
      "role": "output",
      "hero": false
    },
    {
      "kind": "text",
      "file": "https://humangarden.ai/spec-artifacts/internal-comms/output-incident.md",
      "caption": "Incident report — silent fall-through. SKILL.md lists \"incident reports\" as supported but no template ships; output is freeform from general-comms principles.",
      "role": "output",
      "hero": false
    },
    {
      "kind": "text",
      "file": "https://humangarden.ai/spec-artifacts/internal-comms/transcript.txt",
      "caption": "Full run transcript — install, execution traces, observations.",
      "role": "reference",
      "hero": false
    }
  ],
  "caveats": [
    "SKILL.md advertises 7 supported types (3P, newsletter, FAQ, status, leadership, project, incident) but only 4 guideline files ship. status / leadership / project / incident reports all silently fall through to general-comms.md without the skill telling the user.",
    "general-comms.md instructs Claude to ask about audience / purpose / tone / format up front — in a one-shot agent run those questions may be skipped, producing generic prose.",
    "company-newsletter.md and 3p-updates.md presume access to Slack / Google Drive / Email / Calendar to gather source material. Without those integrations, output quality degrades to \"polish what the user pastes in\" — and the skill does not warn about this.",
    "newsletter format embeds Slack emoji shortcodes (`:megaphone:`, `:dart:`, `:pillar:`, `:thread:`) — these render literally outside Slack/email-with-Slack-rendering, and `:pillar:` is not even a real Slack default emoji.",
    "On 3P updates the model will quietly invent metrics the user did not supply (e.g. team size \"now at 9\" after onboarding two) — data-driven format invites hallucinated data when facts are missing.",
    "3p-updates.md says \"make sure you know the team name… and time period\" but does not make Claude block on missing inputs — date ranges get inferred silently.",
    "No tests, no validators, no fixtures. SKILL.md ships with 4 prose guidelines; quality of output is entirely a function of the underlying model on a given day."
  ],
  "needs_credentials": [],
  "source_repo": "https://github.com/anthropics/skills/tree/main/skills/internal-comms",
  "human_review_url": "https://humangarden.ai/skills/internal-comms/"
}