agent-toolkit-cli 1.11.0__py3-none-win_amd64.whl

agent_toolkit/data/skills/design/design-improvement/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: design-improvement
+description: WHAT - Browser-grounded iterative design improvement. Consumes design-assessment findings, defines direction, prioritizes safe vs ambiguous changes, implements within existing design system, runs app, captures rendered evidence via browser, reviews and iterates. Reuses evidence model — no new scoring framework.
+origin:
+  type: first-party
+---
+
+# Design Improvement (WHAT)
+
+Close the loop from **assessment → implementation → rendered verification**. Use this skill when the user wants to act on `design-assessment` (or `frontend-design-review`) findings, improve an existing interface, or run a browser-grounded iteration loop.
+
+**Composition, not duplication:** Orchestrates `design-assessment`, `frontend-design`, `frontend-design-review`, `web-design-guidelines`, `playwright-cli` / `chrome-devtools`, `figma` and accessibility — delegates work, does not copy their instructions.
+
+## Default guardrails
+
+1. **Consume assessment findings** — start from a `design-assessment` scorecard / `frontend-design-review` output (Blocking/Major/Minor + evidence links). If no assessment exists, offer to run `design-assessment` first; do not invent findings.
+2. Reuse the single evidence model: `observation / impact / severity / effort / confidence / evidence / screens / recommended fix` plus 1–5 scale, `3 = Defined`, `Not assessed`, confidence `High/Medium/Low`, and `output-handshake` before final artifacts. Do not introduce `72/100` or other synthetic scores.
+3. Do not assume code is good without **rendered evidence** (screenshot/recording via browser). Implement → run → capture → inspect → compare → iterate. Where browser/vision unavailable, use text-only heuristic and mark **Low confidence — browser/vision unavailable**.
+4. Do not auto-push to default branch or create tickets/docs without explicit approval. L2 controlled mutations for code changes; app runs isolated (no prod).
+5. Generic-AI lens is contextual, not a checklist — a pattern is not bad merely because AI often produces it; judge appropriateness for *this* product's subject and tone.
+
+## Safe vs ambiguous changes
+
+Triage before implementation:
+
+| Safe / mechanical — low judgment, implement directly with review | Ambiguous / product-defining — requires human direction, propose then confirm |
+|---|---|
+| Spacing/token inconsistency, broken responsive reflow, contrast violation (WCAG failure), missing focus state, overflow/clipping, misaligned design-system token, dead/incorrect ARIA, duplicate primary action | Brand direction, major visual identity, information architecture / navigation model, product-specific interaction changes, large typography or palette direction, pricing/offer hierarchy |
+
+If a finding is ambiguous, **propose direction + rationale + rendered preview** and pause for human selection; do not blindly redesign an established product.
+
+## Design-system preservation (existing apps)
+
+Before inventing aesthetics, discover and respect:
+
+- Design tokens (Figma variables, Style Dictionary, Tailwind/theme config, CSS variables)
+- Component library (Storybook), existing Figma libraries, typography/spacing/color scales
+- Prior decision: `greenfield` (no system, you own direction via `frontend-design`) vs `improvement within system` (default for existing apps)
+
+Prefer **improve within system** unless explicitly commissioned to redesign. When tightening the system, author tokens/constraints rather than scattering one-off overrides.
+
+Anti-generic-AI objective (contextual): avoid unmotivated gradients, gratuitous glow, everything-in-cards, repetitive 3-col grids, generic SaaS hero, random oversized rounded rectangles, weak hierarchy, purposeless whitespace, arbitrary decorative complexity, identical dashboard compositions, generic purple/blue palettes — unless appropriate for the product.
+
+## Lifecycle
+
+```
+ASSESS (design-assessment) → UNDERSTAND FINDINGS → DEFINE DIRECTION → PRIORITIZE → PLAN CHANGES
+  → IMPLEMENT → RUN APPLICATION → CAPTURE RENDERED EVIDENCE → REVIEW → FIX → RE-REVIEW → HANDSHAKE
+```
+
+### 1. Understand findings
+
+- Ingest assessment scorecard: Blocking/Major/Minor, evidence links, screenshots, Figma nodes.
+- Cluster findings by screen/component and by safe vs ambiguous. Surface missing-evidence items as `Not assessed` with what would enable a decision.
+
+### 2. Define design direction (only where system gaps exist)
+
+If greenfield or system is missing/contradictory:
+
+- Define direction as in `frontend-design`: palette as 4–6 named hex values, typefaces for display/body/utility, layout concept with ASCII wireframe, single signature element. State subject grounding — what in the product's world motivates each choice.
+- For existing branded apps, direction is *tightening* (tokens, constraints, hierarchy rules) rather than replacement.
+
+### 3. Propose variants → select with rationale
+
+- Propose **2–3 variants** only for ambiguous decisions (e.g., two hierarchy treatments). For safe/mechanical fixes, one implementation is enough.
+- Each variant: brief rationale, trade-off, and which finding(s) it resolves.
+- Pause for human selection; record decision + evidence link.
+
+### 4. Prioritize
+
+Rank by `severity × user impact × effort` using assessment severity plus confidence. Suggested buckets: `quick win (S, Blocking)` → `next sprint (M, Major)` → `needs design (L, ambiguous)`. Respect user-approved priority; do not re-order against approval.
+
+### 5. Plan changes
+
+Produce a change plan mapped to evidence:
+
+| Finding | Decision | Change | Files / tokens | Verification (browser capture) |
+|---------|----------|--------|----------------|-------------------------------|
+| [link] | [safe/ambiguous + direction] | [token, component, layout fix] | [path:line] | [screenshot/viewport/theme] |
+
+Include Figma/token references and, where relevant, WCAG SC mapping for a11y fixes.
+
+### 6. Implement
+
+- Implement within the discovered system (tokens/CSS variables, not hardcoded values). Reuse design-system components; document any exception with rationale.
+- Keep changes small and reviewable; one concern per commit where possible.
+
+### 7. Run application
+
+- Run per repo docs (`npm run dev`, `docker compose up`, etc.) in an isolated, non-prod context. Record URL/port and prerequisites as evidence. Do not assume success without seeing it run.
+
+### 8. Capture rendered evidence
+
+- Use `playwright-cli` (primary for deterministic interaction, locators, assertions, screenshots, traces, multi-tab) and/or Chrome DevTools / `chrome-devtools` skill when runtime diagnostics needed (network, console, performance, rendering, trace). See browser provider decision below.
+- Capture at breakpoints (mobile/tablet/desktop), themes (light/dark), and relevant states (empty/loading/error/dense). Record viewport, theme, date and store artifacts alongside the change plan.
+- **Required:** `screenshot` (or recording) for each changed screen/state before considering the change validated. Source code alone is not validation.
+
+### 9. Review → fix → re-review
+
+- Review captured output vs direction and vs findings: hierarchy, spacing vs tokens, typography, color, interaction, responsive reflow, a11y (contrast, focus, keyboard), design-system compliance, distinctiveness for this product.
+- For each captured finding, delegate to the appropriate reviewer:
+  - Visual/hierarchy → `frontend-design-review` (three pillars + output format)
+  - WIG rules (a11y, focus, forms, motion) → `web-design-guidelines`
+  - A11y deeper → `accessibility` capability (when available) + browser a11y tree
+  - Design-system divergence → `figma` Dev Mode compare
+  - Distinctiveness → `frontend-design` creative lens
+- Cite observation with screenshot anchor (`file:line` for code, region for visual). Classify `Blocking/Major/Minor` + confidence, downgraded if browser/vision was degraded.
+- Fix failures and re-capture. Iterate until Blocking cleared and no new Major introduced; for greenfield, iterate until direction is satisfied. Gate on human approval for ambiguous changes.
+
+### 10. Handshake
+
+Apply `output-handshake` before final report: ask where the artifact lives (repo/docs/URL), who reviews/approves, and confirm human review. Do not create follow-up tickets without approval; delegate to ticket skills after approval.
+
+## Browser provider selection (conceptual capabilities)
+
+Request capabilities, not brand names, where practical:
+
+| Capability | Playwright (`playwright-cli` / `e2e-runner`) | Chrome DevTools (`chrome-devtools`) |
+|------------|----------------------------------------------|-------------------------------------|
+| `browser.interact` (click/fill/navigate) | ✅ deterministic locators, fixtures | limited |
+| `browser.capture` (screenshot, trace, pdf) | ✅ screenshots, traces, `snapshot` | ✅ screenshots, rendering diagnostics |
+| `browser.dom` + `browser.accessibility` tree | `snapshot` (accessibility-aware) | ✅ DOM, accessibility tree, computed styles |
+| `browser.network` / `browser.console` / `browser.performance` | limited | ✅ network, console, performance, runtime |
+| `browser.trace` / `browser.visual-compare` | trace via CLI | trace + rendering inspection |
+| E2E validation (`browser.assert`) | ✅ assertions, `e2e-runner` specs | — |
+
+**Rule:** Use `playwright-cli` for deterministic interaction + E2E validation + primary capture; use `chrome-devtools` for runtime debugging, network, performance, and rendering diagnostics. Either alone suffices for degraded mode; together they cover the full `implement → render → capture → inspect → compare → iterate` loop.
+
+If neither provider is available (no browser), fall back to text-only heuristic (code, tokens, ARIA attributes) with **Low confidence** and explicit missing-evidence register.
+
+## Quality dimensions to consider (evidence-backed, not scored in aggregate)
+
+Visual hierarchy, layout, spacing, typography, color, interaction, responsive behavior, accessibility, consistency, design-system compliance, product appropriateness, distinctiveness, information density, navigation clarity, feedback/states, performance where UX-relevant.
+
+## Delegation table
+
+| Need | Skill |
+|------|-------|
+| Assessment findings (input) | `design-assessment` (scorecard + prioritized findings) |
+| Single-screen procedural critique | `frontend-design-review` |
+| WIG rules (a11y, focus, forms, motion) | `web-design-guidelines` |
+| Deterministic interaction + primary capture + E2E | `playwright-cli` (`tooling/playwright-cli`) / `e2e-runner` |
+| Runtime debugging (network/console/perf/rendering) | `chrome-devtools` (`tooling/chrome-devtools`, next issue) |
+| Design-system compare / tokens | `figma` / `figma-implement-design` / `figma-create-design-system-rules` |
+| Distinctive direction | `frontend-design` |
+| Accessibility deeper | `accessibility` (curated, WCAG 2.2 AA) when available |
+| Evidence intake (single framework) | `project-assessment-evidence` |
+| Multi-unit routing | `project-assessment` |
+| Output gate | `output-handshake` |
+| Parallel variant generation / multi-screen review | `swarm` (optional, sequential valid) |
+
+## Security & compatibility
+
+- No mutation without approval; no default-branch push.
+- `playwright-cli` runs a real browser — treat tool arguments as executable-ish; validate URLs/inputs (no SSRF via tool injection).
+- Portable orchestration; browser/vision optional with degraded confidence.
+
+## References
+
+- `references/improvement-plan-template.md` — change-plan + capture + review loop template
+- `design-assessment` + `references/design-scorecard-template.md` — inputs (1–5, confidence, Blocking/Major/Minor, evidence links)
+- `frontend-design-review` + `references/review-output-format.md` — review output format
+- `web-design-guidelines` + `references/web-interface-guidelines.md` — WIG rules
+- `playwright-cli` — deterministic browser automation; `chrome-devtools` — runtime diagnostics (next skill)
+- `project-assessment-evidence` / `technical-unit-assessment` — evidence model and scale
+- `output-handshake` — destination + review gate
+

agent_toolkit/data/skills/design/design-improvement/references/improvement-plan-template.md

@@ -0,0 +1,113 @@
+# Design Improvement Plan Template
+
+**Product:** [name]  **Source assessment:** [link to design-assessment scorecard]  **Period:** [dates]
+**Branch:** [feature branch]  **Running app:** [URL/port + command]  **Assessor:** [name]
+
+> Reuses evidence model from `project-assessment-evidence` (observation/impact/severity/effort/confidence/evidence/screens/fix, 1–5 scale 3=Defined, Not assessed, output-handshake). Do not score without evidence.
+
+## Findings intake (from assessment)
+
+| # | Finding | Severity | Confidence | Evidence | Screen/Component | Recommended fix |
+|---|---------|----------|------------|----------|------------------|-----------------|
+| 1 | [title] | Blocking/Major/Minor | High/Med/Low | [scorecard link, screenshot] | [screen] | [Figma/token/WIG rule] |
+
+### Triage: safe vs ambiguous
+
+| Finding | Safe (mechanical) | Ambiguous (needs direction) | Decision |
+|---------|-------------------|-----------------------------|----------|
+| 1 | [e.g. contrast violation] |  | Implement directly → review |
+| 2 |  | [e.g. hero hierarchy] | Propose variants → human select |
+
+## Design direction (only where system gaps exist)
+
+**Subject grounding:** [what in product's world motivates choices]
+**Palette:** 4–6 named hex values
+**Typography:** display / body / utility faces
+**Layout concept + ASCII wireframe:**
+```
+[wireframe]
+```
+**Signature element:** [single memorable element]
+**For existing apps:** tightening tokens/constraints vs replacement: [decision]
+
+## Variants (only for ambiguous)
+
+| Variant | Rationale | Resolves findings | Trade-off |
+|---------|-----------|-------------------|-----------|
+| A |  |  |  |
+| B |  |  |  |
+
+**Selection:** [A/B] — [why] — approved by [who] on [date] — evidence [link]
+
+## Prioritization
+
+Ranked by `severity × impact × effort` + confidence. Buckets:
+
+| Priority | Finding | Effort | Confidence | Verification capture |
+|----------|---------|--------|------------|----------------------|
+| Quick win |  | S | High | screenshot viewport/theme |
+| Next sprint |  | M |  |  |
+| Needs design |  | L |  |  |
+
+## Change plan
+
+| Finding | Decision | Change (token/component/layout) | Files / tokens | Expected rendering |
+|---------|----------|----------------------------------|----------------|--------------------|
+| 1 | safe/ambiguous + direction | [e.g. spacing token s-400] | path:line | [what screenshot should show] |
+
+## Implementation log
+
+| Commit | Change | Finding | Evidence before | Evidence after |
+|--------|--------|---------|-----------------|----------------|
+| [sha] | [desc] | #1 | [screenshot before] | [screenshot after] |
+
+## Rendered verification (required — code alone is not validation)
+
+Record per captured state:
+
+| Screen | Viewport | Theme | State | Screenshot | Review vs direction | Result |
+|--------|----------|-------|-------|------------|---------------------|--------|
+| home | desktop 1440 | light | default | [link] | [pass/fix] | Blocking cleared / Major remains |
+| home | mobile 390 | light | default | [link] |  |  |
+
+**Browser provider used:** `playwright-cli` (deterministic interaction + capture) / `chrome-devtools` (network/console/perf) / both. If degraded (no browser), mark `Low confidence — browser/vision unavailable` and list missing evidence.
+
+### Review delegation
+
+- Visual/hierarchy → `frontend-design-review` (three pillars)
+- WIG rules → `web-design-guidelines`
+- A11y deeper → `accessibility` + browser a11y tree + WCAG SC mapping
+- Design-system divergence → `figma` Dev Mode compare
+- Distinctiveness → `frontend-design` creative lens
+
+## Re-review loop
+
+Iterate `review → fix → re-capture` until Blocking cleared and no new Major introduced. For greenfield, until direction satisfied. Record:
+
+| Iteration | Reviewer | Finding | Action | Re-capture link | Status |
+|-----------|----------|---------|--------|-----------------|--------|
+| 1 | frontend-design-review | #1 contrast | fix token | [link] | ✅ Blocking cleared |
+
+## Missing evidence register
+
+| Need | What would enable |
+|------|-------------------|
+| [e.g. mobile 390 screenshot] | `playwright-cli screenshot` at viewport |
+
+## Output handshake
+
+- **Destination:** [repo/docs/URL]
+- **Reviewer:** [who approves]
+- **Confirmed:** [date]
+- **Follow-ups:** [tickets only after approval]
+
+## Design-system evidence
+
+Discovered tokens / Figma / Storybook:
+
+| System | Location | Freshness | Strength | Notes |
+|--------|----------|-----------|----------|-------|
+| Tokens | [path/URL] | [date] | Direct |  |
+| Figma | [file] | [date] | Direct |  |
+| Storybook | [URL] | [date] | Indirect |  |
+

agent_toolkit/data/skills/design/figma/LICENSE.txt

@@ -0,0 +1,2 @@
+Use of these Figma skills and related files ("Materials") is governed by the Figma Developer Terms (available at https://www.figma.com/legal/developer-terms/). By accessing, downloading, or using these Materials — including through automated systems or AI agents — you agree to the Figma Developer Terms.
+These Materials are currently offered as a Beta feature. Figma may modify, suspend, or discontinue them at any time without notice.

agent_toolkit/data/skills/design/figma/NOTICE.txt

@@ -0,0 +1,25 @@
+figma (agent-toolkit distribution)
+============================
+
+This skill is derived from the OpenAI "skills" repository, originally licensed
+under the Apache License 2.0:
+
+  https://github.com/openai/skills (skills/.curated/figma)
+
+Modifications by agent-toolkit S.A. for distribution via agent-toolkit:
+
+- Replaced the Codex-only `references/figma-mcp-config.md` (which assumed
+  `~/.codex/config.toml`, `bearer_token_env_var`, and
+  `[features].rmcp_client = true`) with a tool-agnostic guide that points to
+  the chezmoi-managed MCP template at `~/.local/share/agent-toolkit/mcp/figma/` and
+  documents Claude Code, Cursor, OpenCode and Windsurf registration paths.
+- Rewrote the SKILL.md introduction with a routing table to the rest of the
+  Figma family, and flagged `figma-use` and `figma-generate-design` /
+  `figma-generate-library` as opt-in packs (not bundled by default).
+- Documented secret handling via `~/.config/agent-toolkit/env.d/figma.env`
+  (`FIGMA_OAUTH_TOKEN`, `FIGMA_REGION`).
+- Removed the `agents/openai.yaml` manifest in favor of the agent-toolkit
+  `skill.json` schema.
+- Dropped vendor logo assets (`assets/figma*`).
+
+Original LICENSE.txt is preserved in this directory.

agent_toolkit/data/skills/design/figma/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: figma
+description: Use the Figma MCP server to fetch design context, screenshots, variables, and assets, and
+  to translate Figma nodes into production code. Trigger when a task involves Figma URLs, node IDs, design-to-code
+  implementation, or Figma MCP setup and troubleshooting.
+origin:
+  type: first-party
+---
+# Figma MCP
+
+Use the Figma MCP server for Figma-driven implementation. For setup and
+debugging details (env vars, tool registration, verification), see
+[`references/figma-mcp-config.md`](references/figma-mcp-config.md).
+
+This is the **entry-point skill** for the Figma family. Switch to a more
+specialized skill once intent is clear:
+
+| If the user wants to… | Use |
+|---|---|
+| Translate a Figma node into production code | [`figma-implement-design`](../figma-implement-design/SKILL.md) |
+| Generate a full screen in Figma from code/description | `figma-generate-design` (opt-in pack — see `docs/SKILLS.md`) |
+| Author Code Connect mappings | [`figma-code-connect-components`](../figma-code-connect-components/SKILL.md) |
+| Create reusable agent rules (`CLAUDE.md`/`AGENTS.md`) for a design system | [`figma-create-design-system-rules`](../figma-create-design-system-rules/SKILL.md) |
+| Create a brand-new Figma file | [`figma-create-new-file`](../figma-create-new-file/SKILL.md) |
+| Run JS in Figma via the Plugin API | `figma-use` (opt-in pack — see `docs/SKILLS.md`) |
+| Generate/import a full library | `figma-generate-library` (opt-in pack — see `docs/SKILLS.md`) |
+
+## Figma MCP Integration Rules
+
+These rules define how to translate Figma inputs into code for this project and
+must be followed for every Figma-driven change.
+
+### Required flow (do not skip)
+
+1. Run `get_design_context` first to fetch the structured representation for
+   the exact node(s).
+2. If the response is too large or truncated, run `get_metadata` to get the
+   high-level node map and then re-fetch only the required node(s) with
+   `get_design_context`.
+3. Run `get_screenshot` for a visual reference of the node variant being
+   implemented.
+4. Only after you have both `get_design_context` and `get_screenshot`, download
+   any assets needed and start implementation.
+5. Translate the output (usually React + Tailwind) into this project's
+   conventions, styles and framework. Reuse the project's color tokens,
+   components, and typography wherever possible.
+6. Validate against Figma for 1:1 look and behavior before marking complete.
+
+### Implementation rules
+
+- Treat the Figma MCP output (React + Tailwind) as a representation of design
+  and behavior, not as final code style.
+- Replace Tailwind utility classes with the project's preferred utilities /
+  design-system tokens when applicable.
+- Reuse existing components (e.g. buttons, inputs, typography, icon wrappers)
+  instead of duplicating functionality.
+- Use the project's color system, typography scale, and spacing tokens
+  consistently.
+- Respect existing routing, state management, and data-fetch patterns already
+  adopted in the repo.
+- Strive for 1:1 visual parity with the Figma design. When conflicts arise,
+  prefer design-system tokens and adjust spacing or sizes minimally to match
+  visuals.
+- Validate the final UI against the Figma screenshot for both look and
+  behavior.
+
+### Asset handling
+
+- The Figma MCP server provides an assets endpoint that serves image and SVG
+  assets.
+- **Important**: if the Figma MCP server returns a `localhost` source for an
+  image or SVG, use that source directly.
+- **Important**: do NOT import/add new icon packages — all assets should be in
+  the Figma payload.
+- **Important**: do NOT use or create placeholders if a `localhost` source is
+  provided.
+
+### Link-based prompting
+
+- The remote Figma MCP server is link-based: copy the Figma frame/layer link
+  and provide that URL to the AI tool when asking for implementation help.
+- The AI tool cannot browse the URL but extracts the node ID from the link.
+  Always ensure the link points to the exact node/variant you want.
+
+## Boundaries
+
+- This skill **reads** Figma context and **writes code in the user's repo**.
+  It does not write back into Figma — that lives in the opt-in `figma-use` /
+  `figma-generate-design` pack (see `docs/SKILLS.md`).
+- Do not bypass the MCP and call the Figma REST API directly from this skill.
+
+## References
+
+- [`references/figma-mcp-config.md`](references/figma-mcp-config.md) — register
+  the Figma MCP in Claude Code / Cursor / OpenCode / Windsurf. Points at the
+  agent-toolkit template under `~/.local/share/agent-toolkit/mcp/figma/`.
+- [`references/figma-tools-and-prompts.md`](references/figma-tools-and-prompts.md)
+  — tool catalog and prompt patterns.

agent_toolkit/data/skills/design/figma/references/figma-mcp-config.md

@@ -0,0 +1,82 @@
+# Figma MCP — setup and troubleshooting
+
+The Figma MCP is a **streamable HTTP** endpoint with bearer-token auth pulled
+from an environment variable. agent-toolkit ships a tool-agnostic template at
+`~/.local/share/agent-toolkit/mcp/figma/` (deployed by `chezmoi apply`).
+
+## 1) Get a Figma token
+
+1. In Figma → Settings → **Personal access tokens** (or your org's OAuth flow).
+2. Create a token with the scopes you need (read + assets at minimum).
+3. Store it persistently in `~/.config/agent-toolkit/env.d/` (covered by `loadenv`):
+
+   ```bash
+   mkdir -p ~/.config/agent-toolkit/env.d
+   cat >> ~/.config/agent-toolkit/env.d/figma.env <<'EOF'
+   export FIGMA_OAUTH_TOKEN="<paste-token-here>"
+   export FIGMA_REGION="us-east-1"   # change if your org uses a different region
+   EOF
+   chmod 600 ~/.config/agent-toolkit/env.d/figma.env
+   ```
+
+   `doctor` will pick up `figma.env` under "Integrations" without ever
+   printing the token value.
+
+> [!CAUTION]
+> Tokens copied from Figma should not include surrounding quotes. Never commit
+> `figma.env` to a repository.
+
+## 2) Register the MCP in your AI tool
+
+Each AI tool registers MCP servers in a different file. Use the values from
+`~/.local/share/agent-toolkit/mcp/figma/config.template.json` as reference:
+
+| AI tool | Configuration file |
+|---------|--------------------|
+| Claude Code | `~/.claude/mcp.json` (or `claude mcp add figma --transport http --url https://mcp.figma.com/mcp --header "Authorization: Bearer $FIGMA_OAUTH_TOKEN" --header "X-Figma-Region: $FIGMA_REGION"`) |
+| Cursor | `~/.cursor/mcp.json` |
+| OpenCode | `~/.config/opencode/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+
+Required headers:
+
+- `Authorization: Bearer ${FIGMA_OAUTH_TOKEN}`
+- `X-Figma-Region: ${FIGMA_REGION}` (default `us-east-1`; change if your org
+  uses another region)
+
+Make sure `FIGMA_OAUTH_TOKEN` is exported in the shell that launches your AI
+tool. With `loadenv` already wired in `bootstrap`, sourcing your shell
+profile is enough.
+
+## 3) Verify
+
+1. Run `doctor` and confirm `~/.config/agent-toolkit/env.d/figma.env` is listed
+   under Integrations.
+2. Restart your AI tool so it re-reads its MCP config.
+3. Ask the AI to list Figma tools or call `whoami` — it should return your
+   Figma user identity.
+
+## Troubleshooting
+
+- **Token not picked up**: confirm `echo $FIGMA_OAUTH_TOKEN` returns a value in
+  the shell that launches your AI tool. If it doesn't, re-source the profile
+  (`exec $SHELL -l`) or restart the IDE.
+- **OAuth errors**: verify the bearer token is valid and not expired. Tokens
+  copied from the Figma UI should not have surrounding quotes.
+- **Network/region**: if your org runs in a non-default Figma region, update
+  `FIGMA_REGION` in `figma.env` and restart the AI tool.
+- **Generic / vague output**: re-state the project-specific rules from the
+  parent `SKILL.md` and ensure you follow the required flow
+  (`get_design_context` → optional `get_metadata` → `get_screenshot`).
+
+## Link-based prompting
+
+The remote Figma MCP server is link-based: copy the Figma frame/layer link and
+provide that URL to the AI tool. The AI tool will extract the node ID from the
+link (it cannot browse the page itself).
+
+## Optional: per-server timeouts
+
+Most AI tools allow per-server `startup_timeout_sec` (default ~10) and
+`tool_timeout_sec` (default ~60). Adjust them in your AI tool's config if you
+hit timeouts on large nodes.

agent_toolkit/data/skills/design/figma/references/figma-tools-and-prompts.md

@@ -0,0 +1,34 @@
+# Figma MCP tools and prompt patterns
+
+Quick reference for the Figma MCP toolset, when to use each tool, and prompt examples to steer output toward your stack.
+
+## Core tools
+- `get_design_context` (Figma Design, Figma Make): Primary tool. Returns structured design data and default React + Tailwind code. Selection-based prompting works on desktop; the remote server uses a frame/layer link to extract the node ID.
+- `get_variable_defs` (Figma Design): Lists variables/styles (colors, spacing, typography) used in the selection. Useful to align with tokens.
+- `get_metadata` (Figma Design): Sparse XML outline of layer IDs/names/types/positions/sizes. Use before re-calling `get_design_context` on large nodes to avoid truncation.
+- `get_screenshot` (Figma Design, FigJam): Screenshot of the selection for visual fidelity checks.
+- `get_figjam` (FigJam): XML + screenshots for FigJam diagrams (architecture, flows).
+- `create_design_system_rules` (no file context): Generates a rule file with design-to-code guidance for your stack. Save it where the agent can read it.
+- `get_code_connect_map` (Figma Design): Returns mapping of Figma node IDs to code components (`codeConnectSrc`, `codeConnectName`). Use to reuse existing components.
+- `add_code_connect_map` (Figma Design): Adds/updates a mapping between a Figma node and a code component to improve reuse.
+- `get_strategy_for_mapping` (alpha, local only): Figma-prompted tool to decide mapping strategy for connecting a node to a code component.
+- `send_get_strategy_response` (alpha, local only): Sends the response after `get_strategy_for_mapping`.
+- `whoami` (remote only): Returns the authenticated Figma user identity (email, plans, seat types).
+
+## Prompt patterns (design context)
+- Change framework: “generate my Figma selection in Vue” or “in plain HTML + CSS” or “for iOS”.
+- Use my components: “generate my Figma selection using components from `src/components/ui`”.
+- Combine: “generate my Figma selection using components from `src/ui` and style with Tailwind”.
+- Note: On the remote server, selection-based prompting requires a frame/layer link; the server extracts the node ID from the URL.
+
+## Prompt patterns (variables/styles)
+- “get the variables used in my Figma selection”
+- “what color and spacing variables are used in my Figma selection?”
+- “list the variable names and their values used in my Figma selection”
+
+## Prompt patterns (code connect)
+- “show the code connect map for this selection”
+- “map this node to `src/components/ui/Button.tsx` with name `Button`”
+
+## Best-practice flow reminder
+Use `get_design_context` → (optionally `get_metadata` for large nodes) → `get_screenshot`, and keep project rules from `SKILL.md` in mind when applying the generated output.

agent_toolkit/data/skills/design/figma-code-connect-components/LICENSE.txt

@@ -0,0 +1,2 @@
+Use of these Figma skills and related files ("Materials") is governed by the Figma Developer Terms (available at https://www.figma.com/legal/developer-terms/). By accessing, downloading, or using these Materials — including through automated systems or AI agents — you agree to the Figma Developer Terms.
+These Materials are currently offered as a Beta feature. Figma may modify, suspend, or discontinue them at any time without notice.

agent_toolkit/data/skills/design/figma-code-connect-components/NOTICE.txt

@@ -0,0 +1,18 @@
+figma-code-connect-components (agent-toolkit distribution)
+====================================================
+
+This skill is derived from the OpenAI "skills" repository, originally licensed
+under the Apache License 2.0:
+
+  https://github.com/openai/skills (skills/.curated/figma-code-connect-components)
+
+Modifications by agent-toolkit S.A. for distribution via agent-toolkit:
+
+- Removed the `agents/openai.yaml` manifest in favor of the agent-toolkit
+  `skill.json` schema.
+- Updated cross-references to point to the opt-in `figma-use` pack (see
+  `docs/SKILLS.md`) since it is not bundled by default.
+- Dropped vendor logo assets (`assets/figma*`).
+
+`scripts/normalize_node_id.py` and `references/mapping-checklist.md` are
+preserved unmodified. Original LICENSE.txt is preserved in this directory.