Customer Support Macros skill for Codex

Good macros let an agent answer a common question correctly in under a minute while still sounding like a person who read the ticket. Good knowledge base articles answer the question before a ticket is filed, are found by the words customers actually type, and are updated when the product changes. Both are judged by data: macro usage and edit rate, article views versus tickets on the same topic.

Workflow

1. Get a ticket export (CSV with subject, first message, tags, resolution, CSAT) for the last 60-90 days, plus the existing macro list and help center articles. Never paste customer personal data into new documents; work with redacted examples.
2. Find the top contact reasons: cluster by tag and by subject keywords; count. The top 15-25 reasons usually cover most volume.
3. For each top reason decide: product fix (send to product), KB article (self-serve), macro (agent answer), or workflow (needs investigation, escalation path).
4. Write or rewrite macros and articles using the templates below.
5. Review with two experienced agents for accuracy and tone; check policy statements (refunds, SLAs, security) with the owner of that policy.
6. Load into the help desk only with the user’s approval; publishing articles is customer-facing.
7. Set the maintenance loop.

Quick reason count from a CSV export (standard library only):

python3 - tickets.csv <<'EOF'
import csv, sys, collections, re
rows = list(csv.DictReader(open(sys.argv[1], encoding="utf-8-sig")))
# Zendesk exports space-separated tags; other tools use commas. Adjust the column name.
tags = collections.Counter(t for r in rows for t in re.split(r"[,\s]+", r.get("tags") or "") if t)
print(len(rows), "tickets")
for tag, n in tags.most_common(25):
    print(f"{n:6d}  {n/len(rows):6.1%}  {tag}")
EOF

Macro library structure

• Naming: Category::Topic::Variant, e.g. Billing::Refund::Approved, Billing::Refund::Outside window. Agents find macros by typing, so put the noun first.
• One macro per situation, not per wording preference. Merge near-duplicates.
• Each macro record has: name, when to use (one line, internal), body, ticket actions, owner, last reviewed date.
• Ticket actions make macros do more than text: set tags (for reporting), status (pending or solved), priority, group or form fields. Keep tags consistent with reporting.

Macro template

Hi {{ticket.requester.first_name}},

[ONE SENTENCE SPECIFIC TO THIS CUSTOMER - REQUIRED, DELETE THIS LINE]

<Answer in the fewest steps. Numbered if more than two actions.>
1. Go to **Settings > Billing**.
2. Select **Download invoice** next to the month you need.

<What happens next / expectation: timing, what they will receive.>
You'll see the refund on your statement within 5-10 business days.

<Optional: link to the KB article for detail.>

If anything still looks wrong, reply here and I'll take another look.

{{current_user.first_name}}

The forced custom first line stops macros from reading as automated replies; agents must edit it before sending. Placeholder syntax differs by tool; the example uses Zendesk placeholders. Check the help desk’s placeholder reference for Intercom, Help Scout or Freshdesk, and always include a fallback for missing first names where the tool supports one.

Voice and content rules

• Lead with the answer; acknowledgement in one short clause at most (“Thanks for flagging this” rather than three sentences of apology).
• Apologise when the company is at fault, specifically: “Sorry, we charged you twice.” Do not apologise for policy.
• No blame language (“you failed to”, “as stated in our terms”).
• Plain words, short sentences, second person. Match the brand voice guide if one exists.
• Policy and money statements must be exact and match the current policy: refund windows, SLA times, prices. Mark any uncertain figure for owner review.
• Never ask customers to send passwords, full card numbers or other secrets; macros that need identity verification point to the secure flow.
• Write macros for “no” answers too, with an alternative where one exists.

Knowledge base articles

Title with the words customers search, phrased as the task or problem: “Download an invoice”, “Why was I charged twice?” not “Billing documentation”.

# <Task or question in customer words>
<One sentence: who this is for and what they will achieve.>

**Before you start:** <plan, role or permission required>

## Steps
1. Go to **Settings > Billing**.
2. ...
Result: <what they should see>

## Troubleshooting
**I don't see the Billing tab.** Only account owners can see it. Ask your owner to ...
**The download is empty.** ...

## Related articles
- <2-4 links>

<!-- internal: keywords customers use: receipt, bill, statement, VAT invoice -->

Rules: one task per article; troubleshooting covers the questions that generate tickets after people read the steps; screenshots only for hard-to-find UI and refreshed when the UI changes; dates or version numbers where behaviour changed.

Measuring and maintaining

Signal	Meaning	Action
Macro unused for 90 days	Topic gone or agents prefer another	Retire or merge
Macro heavily edited before sending	Body does not fit the situations	Split into variants or rewrite
Low CSAT on tickets using a macro	Answer or tone wrong	Rewrite; check policy
Article high views and high tickets on same topic	Article does not solve it	Add troubleshooting; check accuracy
Search terms with no results	Missing article or missing keywords	Write article or add keywords
Product release touches a topic	Content likely stale	Review before release ships

Review the full library each quarter with a named owner per category.

Localisation

Translate from the final reviewed source; keep placeholders untouched; have a native speaker review policy macros. Track translated versions so source updates propagate.

Gotchas

• Macros that promise timelines the team does not meet create a second ticket.
• Copy-pasted links to old article URLs break after help center restructuring; use the tool’s article reference feature if it has one, and check links quarterly.
• Tags applied by macros feed reporting; renaming them silently breaks dashboards.
• A macro for every edge case makes the library unsearchable. Rare cases get an internal note with guidance instead.
• Writing articles for features that are confusing by design hides a product problem; report the top contact reasons to product every month.

Output

1. Contact reason analysis: top reasons, share of volume, recommended handling
2. Macro library: name | when to use | body | actions | owner
3. KB articles (markdown) with internal keywords
4. Policy statements needing owner confirmation
5. Maintenance plan: owners, review dates, metrics to watch