[alidotforrest]

Description

Edits the existing content-guidelines skill in place at domains/ui/skills/content-guidelines/. Shared rules live in skill.md. The mobile overlay is updated. A new extension overlay is at repos/metamask-extension.md.

The skill is the agent-readable implementation of approved MetaMask content guidance, for agents to use day to day. It follows the MetaMask Content Design Style Guide and Design Brain. If those sources disagree with this file, flag it to the content owner. Do not invent a rule.

No app strings were migrated.

Key decisions

• Wallet vs account
• Network fee instead of gas in default flows
• Spending cap
• Button verbs: Continue, Confirm, Approve, with Cancel as the default decline
• Secret Recovery Phrase spelled out. Private Key is title case
• Error pattern: what happened, then what to do
• Voice: no "please" or "successfully". No "sorry" or "unfortunately" in a routine error. Exclamation points only for a really exciting moment, never in an error or an alert
• No "(s)" plurals or \n in strings
• Time: local time, "ET" as the fallback, written times like 6:30 am
• "NFT" only when the thing is an NFT. The Collectibles feature keeps its name
• "Paid by MetaMask" only when MetaMask covers a fee the user would otherwise pay (a sponsored network fee). Never for a $0 or waived MetaMask fee. No chain names in the example

Aligned with the Style Guide

No Style Guide overrides:

• Em dash (—) with no spaces may offset an aside
• Written times use a space and lowercase am / pm (6:30 am)
• A period only when the copy is more than one sentence
• No loading ellipsis. Loading is animation, or a present participle with no ... or …. An ellipsis is only for a shortened address
• Question marks are avoided. Not on buttons. A statement is used when the outcome is known
• Exclamation points, emoji, colons, and bullets follow the guide: exciting moments only, emoji sparingly on lower-impact messages, a colon may offset a list, no comma at the end of a bullet

George's review

Non-blocking callouts are addressed: authority and source links, contractions when they read naturally, "your" only on onboarding titles, consent "I understand…" kept as a skill exception not yet in the Style Guide, directional words limited to pointing on screen, "MetaMask Snaps" on first mention in a page or flow, Rewards vs points vs redeemed, no yield/ROI/securities analogies, loading status announced to assistive tech, "site" in consumer UI and "dapp" for a technical audience, and the safety example no longer says funds are safe. Polymarket and Predictions label casing is in the mobile overlay. Activity-row copy is in the extension overlay. Component README lines tied to #212 and #213 were left unchanged.

Audit fixes

• Removed the false claim that sentence-casing a Polymarket title would break team matching
• "Learn more." cites mobile keys only (app_settings.learn_more, predict.consent_sheet.learn_more)
• Removed the invented "Hold to reveal private key" row
• Directional words narrowed to pointing at something on screen
• Dropped the "apologize when appropriate" line
• "Paid by MetaMask" example is generic
• Design Brain is named, not linked
• Collectibles keeps its name, with no "upcoming" or "gacha cards"

Still proposed or unresolved

• Number ranges: the Style Guide says both a hyphen (1-20) and an en dash for a fixed range. Not migrated
• The Style Guide's WIP glossary still has a struck-through note preferring "transaction fee" over "Network fee", and an unfinished "dapps" entry. The main guide body does not decide those. This skill keeps "Network fee", and "site" in consumer UI
• Curly quotes, the "I understand…" consent exception, and not showing "fiat" to users are not covered by the Style Guide. They stay. The consent line is marked as a skill exception not yet in the Style Guide

Rollout checks not yet done

• Onboarding layout, larger text, and translation checks before dropping "your" on onboarding titles
• Enable/Disable edge-case pass for toggles
• Signature and permission decline wording before replacing Reject with Cancel

How agents get it

yarn skills syncs this into the app repos as mms-content-guidelines. The copy under .claude/skills/mms-content-guidelines is generated. Do not edit it there. AGENTS.md pointers are in draft PRs metamask-mobile #39056 and metamask-extension #47681. The extension gets the skill after this PR merges.

A Consensys/skills overlay may exist. This environment could not read that repo. Reviewers should check it does not override these rules.

Type of Change

• New skill
• Skill improvement/update
• Bug fix
• Documentation update
• Other (please describe):

Skill Details (if adding a new skill)

Provider Name:
Skill Name: content-guidelines (existing)
Brief Description: Agent-readable MetaMask content guidance for mobile and extension.

Checklist

• I have read the CONTRIBUTING.md guidelines
• My skill follows the SKILL_TEMPLATE.md format
• I have tested this skill with an AI agent
• My skill does not contain any secrets, private keys, or sensitive data
• I have added appropriate documentation
• My changes don't break existing skills

Testing

yarn audit:skills on this skill reports no errors. yarn test passed. A local install for metamask-mobile and metamask-extension writes mms-content-guidelines and appends only the matching overlay.

Additional Context

No app-repo string migrations are included.

  

[georgewrmarshall]

Thanks for this — shared rules plus thin Mobile/Extension overlays is the right shape, and the Extension overlay closes the previous Mobile-only gap.

I reviewed this against Design Brain’s Lessons & Rules (Active + Proposed) and the MetaMask Content Design Style Guide / related Notion content docs. You’re the content owner on this, so take these as callouts and questions rather than blockers — a few places looked like they might drift from the current source text, and I wanted to surface them for your eye.

Questions / things to address (non-blocking)

1. Authority vs sources — The skill currently says Notion, the design-system rule, and component READMEs are background and this file always wins. Could we frame it as the agent-readable implementation of approved guidance, link the originals, and flag disagreements for content-owner review instead? That would avoid concealing real conflicts if sources move.

2. Possible Active Design Brain / Style Guide mismatches (worth a quick reconcile or a note that content design has consciously overridden):

   • Sentence-case “Private key” vs Style Guide / Active rule still listing Private Key as a title-case exception
   • “Use contractions. No exceptions.” vs guidance to use them when they read naturally
   • Extending drop-“your” from onboarding titles to new field prompts — Active rule says that doesn’t automatically apply to field labels / inline instructions
   • Consent-checkbox first-person exception vs Active “Never first-person user POV” (Notion doesn’t currently document that exception)
   • Hyphenated numeric ranges (1-20) as settled — Notion still marks hyphen vs en dash unresolved

3. Missing safeguards that look approved in Notion today and might be worth a short cross-ref:

   • No spatial references (above / below / left / right), not only “click here”
   • Full “MetaMask Snaps” on first mention in a page/flow
   • Rewards’ three meanings; points vs redeemed rewards; no yield/ROI/securities analogies for network rewards
   • Async errors/status announced; loading can’t rely on animation alone
   • Technical-audience exceptions for “dapp” (PR currently treats “site” as absolute)

4. Trust / security example — The approved example “Your wallet and funds are safe. This screen didn’t load. Try again.” reads as an unconditional safety assurance. Worth gating on verified product facts, or softening, so agents don’t invent fund-safety claims from a load failure alone.

5. Shape nits — Shared base still carries a few Mobile Polymarket/key internals and Extension Activity specifics; overlays are the better home. Also worth a deliberate merge reconcile with #212/#213 (esp. the component-README / no-MCP lookup path).

Design Brain discrepancies can stay explicit follow-ups — no need to auto-rewrite Notion from this PR. Happy to sync on any of these if useful.

[georgewrmarshall]

Follow-up to the approval — one more non-blocking note:

6. CHANGELOG.md — Please leave this for the skills package release process. Skill content PRs (including this content-guidelines reshape) shouldn’t need to edit it unless we’re cutting a release.

[georgewrmarshall]

Blocking: Please revert / drop the CHANGELOG.md edits from this PR.

CHANGELOG.md is for the skills package release process. Content-guideline skill updates shouldn’t touch it unless we’re cutting a release.

(The earlier approve callouts stay non-blocking; this CHANGELOG change is the only blocker.)

[georgewrmarshall]

Thanks for turning these around. The CHANGELOG.md revert clears the blocker, and the earlier callouts are all addressed: the sources framing, Private Key title case, contractions, "your" limited to onboarding titles, the consent exception note, numeric ranges as Proposed, the five safeguards, the fund-safety example, and the overlay moves. Approving.

Non-blocking (AI-assisted review)

1. Reversed decisions in c899da5e. "Align with Style Guide" reverses several decisions this PR recorded from Corey's review:

   • Loading text: was ... as an exception, now animation with no ellipsis.
   • Em dash: was banned, now allowed for an aside.
   • Times: were a.m. / p.m., now 6:30 am.
   • Periods: every full sentence used to end in one. Now a single sentence has none.
   • Destructive confirmation titles: now statements with no question mark ("Lock your wallet").

   That may be the right call if the Style Guide is the newer source. Could you confirm content leadership is OK overriding Corey's review, so agents don't flip-flop if someone re-applies the older decisions?

2. Period rule not applied everywhere. Under the new rule, some ✅ examples still end a single sentence with a period:

   • "We're investigating the problem."
   • "We're here to help." / "This can't be undone."
   • "Open the Ethereum app on your device."
   • "By continuing, you agree to the Terms of Use."

   Either drop the periods or note why these are exceptions.