Update to CommScore

{
  "description": "Write, edit or rewrite customer communications (emails, letters, text messages, push notifications, in-app messages, notices, replies to complaints, help-centre answers, web or app copy, headlines, social posts, policy wording) in a brand's voice using its brand guide in CommScore, and check the result with CommScore before handing it over. Use whenever the user asks you to draft, reply to, edit, rewrite or \"make this sound like\" a brand or organisation for its customers, members or the public, including any brand set up in their CommScore workspace, even if they don't mention CommScore.",
  "included_files": [],
  "name": "write-on-brand",
  "skill_md_contents": "---\nname: write-on-brand\ndescription: Write, edit or rewrite customer communications (emails, letters, text messages, push notifications, in-app messages, notices, replies to complaints, help-centre answers, web or app copy, headlines, social posts, policy wording) in a brand's voice using its brand guide in CommScore, and check the result with CommScore before handing it over. Use whenever the user asks you to draft, reply to, edit, rewrite or \"make this sound like\" a brand or organisation for its customers, members or the public, including any brand set up in their CommScore workspace, even if they don't mention CommScore.\n---\n\n# Write on brand\n\nCommScore holds the organisation's brand voice and language guide (tone, style, audiences,\nterms to use and avoid) and can score a draft against it. Read the guide before you write\nand check the draft afterwards. The user then gets text that already sounds like their\norganisation and has been checked, instead of a generic draft they have to fix.\n\n## 1. Find the brand\n\n- If this conversation already has a brand_id, use it.\n- Otherwise call `list_brands`.\n  - One brand: use it.\n  - Several brands: pick from context, such as the organisation, product or website the\n    user mentioned. If it's still unclear, ask one short question listing the brand names.\n  - Brands with the same name: tell them apart by website. Don't guess.\n  - No brands: tell the user a CommScore admin needs to add one first. You can still\n    write the draft, but say it hasn't been checked against a brand guide.\n\n## 2. Read the brand guide\n\nCall `get_brand_profile`. Most of what matters for writing is in these fields:\n\n- `preferred_tone`, `core_idea`, values and `customer_charter`: how the organisation wants\n  to sound and what it promises customers.\n- `style_do` / `style_dont` / `style_checklist`: concrete house-style rules. Follow them\n  over your own default style.\n- `audiences`: who the brand writes for. Match the reader of this communication.\n- `approved_terms`: the brand's own words. Use them. For a general audience, add the\n  `plain_explanation` the first time a term appears.\n- `avoid_terms`: words the brand doesn't use. Use the alternative given.\n\n## 3. Get the brief straight\n\nBefore drafting, be clear on:\n\n- who is reading;\n- what they need to know;\n- what, if anything, they need to do, and how and by when.\n\nKeep every fact the user gives exactly as given: amounts, dates (in the user's format),\nnames, reference numbers and any wording they say must stay. If a fact the reader needs is\nmissing (a date, an amount, a phone number), ask, or leave a clearly marked placeholder\nsuch as `[due date]`. Never invent one. A confident draft with a made-up date is worse than\none with a visible gap.\n\nThe same goes for **promises and instructions**. Don't add a commitment the user didn't\nmake, such as \"we'll update you by Friday\", \"you'll be refunded\" or \"we'll restore it\".\nDon't add instructions or warnings to the reader, such as \"don't reset your account\". A\nwarmer tone is your job; new obligations are the user's call. If one would help the reader,\nsuggest it to the user after the draft rather than putting it in.\n\n## 4. Draft\n\nWrite the communication in the brand's voice, for the reader in step 3. Put what matters\nmost to the reader first. If the reader must act, say what to do, how and by when.\n\n## 5. Check before handing over\n\n1. Call `check_terminology` on the draft. It is instant and free. Swap any avoided terms\n   it finds.\n2. Call `score_text`. Set `communication_type` (email, letter, newsletter, invitation,\n   text_message or document). Set `audience_rank` (1 = general public, 5 = specialists)\n   and `action_expected` when you know them, because they change what good looks like.\n   Scoring takes up to a minute and uses the workspace's AI credits.\n   - Score anything that will go to customers.\n   - For a quick throwaway line, the terminology check is usually enough.\n3. If `top_fixes` point to real problems, fix them. Either:\n   - edit the draft yourself, which often works well because you know the intent and the\n     facts; or\n   - call `rewrite_text` with `focus` set to `suggested_focus`, then check that the\n     rewrite kept every fact from step 3.\n\n   Then score once more, passing the first result's `draft.draft_id` as `draft_id`, so\n   CommScore links the rounds and the result's `draft.change` shows what moved. Give the\n   first score a short `title` (e.g. \"Holiday closure email\") so the user can find it in\n   their history later.\n\n**The score you report must belong to the text you hand over.** If you change the text\nafter the last score, even a small edit, score it again. If you can't (credits, errors),\nsay plainly that the score is for the earlier draft.\n\nOne improvement round is usually enough; two at most. Scores on longer texts can move by\nabout a point between runs, so don't spend the user's credits chasing a decimal. Stop when\nthe remaining fixes are minor or depend on something only the user knows.\n\n## 6. Hand over\n\nLead with the finished communication, ready to copy. The user asked for the email, not a\nreport. After it, add a short CommScore note:\n\n```\n**CommScore:** 4.3 / 5 overall (first draft 3.6), brand: <brand name>\nClarity 4.5 · Certainty 4.0 · Structure, style & grammar 4.5 · Brand alignment 4.0 · Customer experience 4.5\nStill open: <anything you couldn't fix, e.g. \"add the actual due date\">\n```\n\nSkip the \"first draft\" figure if you only scored once, and drop \"Still open\" if nothing is\nopen. If you scored more than once, show the trail from `draft.history`, e.g. `3.6 → 4.3`.\n\n## When something goes wrong\n\n- **Access, licence or credit messages** from a tool: pass the message on as written,\n  because it says what the user or their admin can do. Then give the draft written from\n  the brand guide, marked as not yet scored.\n- **Text too long:** score it in sections and report each section.\n- **Several drafts or variants requested** (e.g. an email and an SMS version): read the\n  profile once, then write, check and score each variant.\n"
}