# Adapto Microcopy

> Manage UI micro copy (nav, buttons, labels, errors) as Adapto key/value/language entries. Two modes — init seeds a curated, on-brand starter set; extract scans your frontend for hardcoded strings and creates entries + a replacement guide (no source rewrite). Plan-then-apply.

- **Type:** Skill
- **Install:** `agentstack add skill-adaptocms-adapto-cms-agent-skills-adapto-microcopy`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [adaptocms](https://agentstack.voostack.com/s/adaptocms)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [adaptocms](https://github.com/adaptocms)
- **Source:** https://github.com/adaptocms/adapto-cms-agent-skills/tree/main/plugin/skills/adapto-microcopy
- **Website:** https://adaptocms.com/

## Install

```sh
agentstack add skill-adaptocms-adapto-cms-agent-skills-adapto-microcopy
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# adapto:microcopy

Manages a project's **micro copy** — the short UI strings (nav, buttons, labels, validation, empty/loading
states, footer) stored in Adapto as `key`/`value`/`language` entries. Two modes:
- **`init`** — seed a curated, project-aware **starter set** of UI strings with on-brand values (greenfield).
- **`extract`** — scan an existing frontend for **hardcoded** UI strings, create entries, and emit a
  `file:line → key` **replacement guide** (it never rewrites your source).

> ⚠️ Micro copy has **no draft state** — entries go **live on create**. So the plan-approval below is the
> **only** safety gate (there's no draft-review net like the content skills have). Review the plan carefully.

## When to use
- `init`: "seed UI strings", "starter microcopy", "set up my UI text".
- `extract`: "extract microcopy", "pull the hardcoded strings from my site into Adapto".

## When not to use
- Translating microcopy into another language → `adapto:translate`.
- Content (articles / pages / collection items) → `adapto:content-seed`.
- Just checking the environment → `adapto:doctor`.

## Inputs
- **Mode** — `init` or `extract`. Infer from the request; if ambiguous, ask which.
- **Project context** for voice (`.adapto/project.md` cache or `adapto collections get-by-slug
  _adapto_project_config --json`); absent → neutral defaults.
- **Tenant language** (`adapto auth orgs --json`).
- **For `extract`:** a scaffolded frontend in the current directory.
- **Key convention:** **dot-namespaced** (`nav.home`, `button.submit`, `form.email.label`) — both modes use it.

## Outputs
- Created micro copy entries (`key`/`value`/`language`); a report of created + skipped.
- **`extract` only:** a replacement guide at `.adapto/microcopy-extract-.md` mapping `file:line → key`,
  so you can wire the read-client lookups yourself. **Source is never modified.**
- **Next step:** suggest `adapto:translate` to localize the micro copy into another enabled language; for
  `extract`, also wiring the read-client lookups from the guide; for `init`, `extract` mode to catch any
  hardcoded strings already in the frontend.

## Preconditions
- **Preflight** with the `adapto:doctor` checks (CLAUDE.md §3.14).
- **Hard-block** on an authenticated CLI (`adapto auth me`) **and** a selected tenant — this skill writes.
  Confirm the **working tenant** first (§3.5); never assume the active one.
- `adapto` CLI `>= 0.0.7`. `extract` additionally needs a scaffolded frontend in the cwd.

### How each mode gathers its candidates
- **`init`** — read project context → **auto-propose** a curated, dot-namespaced starter set (nav,
  buttons/CTAs, form labels, validation/errors, empty/loading, footer; tailored to the project type — e.g.
  e-commerce → cart/checkout, a blog → read-more/subscribe) with **on-brand values** → take **one edit pass**.
  Values follow the applicable [prose-standards.md](../../shared/prose-standards.md) rules (plain language,
  no filler/jargon — §6; rhythm/paragraph rules don't fit UI strings).
- **`extract`** — detect the framework (Next/Astro/SvelteKit, as `adapto:doctor` does) → scan
  `.astro`/`.tsx`/`.jsx`/`.svelte` for **user-facing** strings (template/JSX text + `placeholder`,
  `aria-label`, `title`, `alt`; skip code, imports, `className`) → propose a dot-namespaced key + value per
  string. LLM = Sonnet-class (§7).

## Plan phase
Print a machine-parseable plan and wait for an explicit `approve`:
- The keys + values to create, the target language, and which keys **already exist** (skip via `get-by-key`).
- `extract` also shows the source location (`file:line`) for each proposed key.
- ⚠️ **No draft** — entries go live on create, so this plan **is** the review. No cost/token figures (§3.10).
- Nothing to create → say so and stop.

## Apply phase
Loop (no batch); `--json` on each; dedup via `get-by-key`:
```bash
adapto microcopy get-by-key  --json        # skip if it already exists
adapto microcopy create --key  --value "" --language  [--tags ""] --json
```
- **`extract` only, after the creates:** write the replacement guide `.adapto/microcopy-extract-.md`
  (`file:line → key`). Never rewrite source.
- Report created + skipped (with keys). Partial failure (no batch) → report what was created, stop; re-run is safe.
  Loop cleanly — judge success from each call's `--json`, end the loop exit 0 on success, so a created batch
  never surfaces as a red `Error: Exit code 1` (§8).
- **Then restart the dev server (stop→start) and keep it running** so the user sees the new micro copy —
  **never kill it** (starters sync content at startup — §14).

## Errors and recovery
- **`extract` with no frontend in cwd** → stop; it scans a scaffolded project — run it from the project root.
- **Key already exists** → skip (idempotent); report it, don't overwrite (use `microcopy update` manually if intended).
- **Partial failure mid-loop** (no batch) → report what was created, then stop; re-run is safe.
- **`extract` finds nothing** (or only false positives) → report; nothing to create.
- **Not authenticated / no tenant** → stop; route to `adapto auth login` + tenant selection.
- **Language discovery fails** → ask the user for a language code the tenant has enabled; don't guess.

## Forbidden actions
- Never write without an **approved plan** (§3.8) — and since micro copy has no draft, the plan is the **only** gate.
- Never **overwrite** an existing key (dedup via `get-by-key`); skip and report instead.
- Never **rewrite source** in `extract` — emit the replacement guide only (§3.11 — don't touch the frontend/read-client).
- Never assume the working tenant — confirm it before any write (§3.5).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [adaptocms](https://github.com/adaptocms)
- **Source:** [adaptocms/adapto-cms-agent-skills](https://github.com/adaptocms/adapto-cms-agent-skills)
- **License:** MIT
- **Homepage:** https://adaptocms.com/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-adaptocms-adapto-cms-agent-skills-adapto-microcopy
- Seller: https://agentstack.voostack.com/s/adaptocms
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.