agent-toolkit-cli 1.0.3__py3-none-any.whl

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/skills/delivery/workflow-client-bootstrap/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: workflow-client-bootstrap
+description: >-
+  WHAT — Interactive interview to capture client delivery context and store it inside the user's
+  ~/.ai-workspace (or similar) as packs + knowledge (no client skills). Use when onboarding a
+  new client project or updating an existing workspace context.
+---
+
+# Workflow Client Bootstrap
+
+Use this skill to **create or update** a client-specific delivery context for any project.
+It runs a structured interview and stores the result inside the user’s **workspace**
+(`~/.ai-workspace`, `~/.ai-workspace`, or a workspace-like directory) as **packs + knowledge**
+(not new skills).
+
+**All generated files, PR text, and Jira/ClickUp comments must be in English.**
+
+## When to use
+
+- Onboarding a new client project that needs its own delivery workflow (beyond `workflow-generic-project`)
+- Updating an existing workflow with new lifecycle states, repos, or guardrails
+- Documenting a client's ticket lifecycle so future agent sessions can use correct status transitions
+
+## Do not use when
+
+- The project already has an up-to-date workflow skill and only a ticket or code change is needed
+- The work fits entirely within `workflow-generic-project` without client-specific gates
+
+## Interview process
+
+Read `questions.yaml` (co-located with this skill) before starting. It defines multiple question groups.
+
+| Group | Topics |
+| --- | --- |
+| **Identity** | Client name, slug, ticket system, docs platform, repo host |
+| **Workflow** | Custom ticket statuses, done criteria, base branch, staging/QA gates |
+| **Stack** | Repository list with roles, AGENTS.md presence, validation tools |
+| **Conventions** | Branch naming, PR style, guardrails, Slack channel |
+
+### Workspace root selection (mandatory)
+
+Before asking client questions, resolve the workspace root directory:
+
+1. Look for workspace-like directories (in order):
+   - `~/.ai-workspace`
+   - `~/.ai-workspace`
+   - the current working directory if it looks like a workspace (has `packs/` and `knowledge/`)
+   - other close matches (e.g. `~/*workspace*`) that contain both `packs/` and `knowledge/`
+2. If exactly one plausible workspace is found, select it and print: `Using workspace: <path>`.
+3. If multiple are found, present a numbered list and ask which one to use.
+4. If none are found, explain the expected structure and ask the user for the path to use.
+
+After selecting the path, clearly explain where answers will be stored (see **Storage explanation** below).
+
+### Interview rules
+
+1. Work through the groups **in order**: Identity → Workflow → Stack → Conventions.
+2. Ask **all required questions**. Skip optional ones only if context already answers them.
+3. Apply **conditional questions**: only ask `jira_project_key` if `ticket_system == jira`, etc.
+4. After each group, briefly summarise what you collected and ask for corrections before moving on.
+5. If the user shares a screenshot or diagram of the ticket workflow, extract statuses and transitions from it.
+6. **Never generate files until the full interview is complete and the user has approved the summary.**
+
+## Pre-generation summary (gate)
+
+After the interview, present a structured summary:
+
+```
+Client:          <name>
+Slug:            <slug>
+Ticket system:   <system> (<key prefix if Jira>)
+Docs platform:   <platform>
+Repo host:       <host> / org: <org>
+Base branch:     <branch>
+Done status:     <status>
+Has staging QA:  <yes/no>
+Repos:           <list>
+Validation:      <tools>
+Branch naming:   <convention>
+PR style:        <draft/direct>
+Guardrails:      <list>
+
+Files to generate:
+  packs/clients/<slug>/pack.yaml
+  knowledge/clients/<slug>/reference.md
+  knowledge/clients/<slug>/workflow.md
+  (optional) personas/clients/<slug>.md
+
+Storage location: <workspace-root>/(paths above)
+```
+
+**Stop here and ask: "Does everything look correct? Shall I generate the files?"**
+Do not proceed until the user explicitly confirms.
+
+## File generation (workspace)
+
+Generate files that follow the patterns below. Do **not** hardcode CLI commands inside the generated
+SKILL.md — delegate those to the appropriate tool skills.
+
+### Workspace outputs
+
+Generate these files under the selected workspace root:
+
+- `packs/clients/<slug>/pack.yaml`
+- `knowledge/clients/<slug>/reference.md`
+- `knowledge/clients/<slug>/workflow.md`
+- (optional) `personas/clients/<slug>.md`
+
+### Storage explanation (mandatory)
+
+After selecting the workspace root, clearly explain:
+
+- the chosen workspace directory path
+- which exact files will be written (full paths)
+- that this data is local to the workstation and only becomes shared if the workspace is committed/pushed
+- how to load it later (e.g. via the workspace context loader, or by opening the pack/knowledge files)
+
+## Post-generation steps
+
+1. Write the files under the chosen workspace root.
+2. If the workspace is a git repo and the user wants to share changes, create a commit there (English message) and open a PR as appropriate for that repo.
+3. Otherwise, keep it local and provide the exact paths so the user can back it up or share it later.
+
+## Updating an existing workflow
+
+If the client already has a workflow skill:
+1. Load the existing `SKILL.md` and `reference.md`.
+2. Run only the interview groups relevant to what changed (ask the user which groups to revisit).
+3. Show a diff summary before applying changes.
+4. Follow the same commit/PR flow above.
+
+## Delegation
+
+| Need | Delegate to |
+| --- | --- |
+| Push branch and create draft PR | **github-cli-workflow** or **gitlab-cli-workflow** |
+| Jira ticket operations | External **jira-*** skills |
+| ClickUp ticket operations | **clickup-cli** |
+| Repo discovery | **assistant** |
+
+## Checklist
+
+- [ ] All required interview questions answered
+- [ ] Summary approved by user before file generation
+- [ ] Generated files follow established patterns (use existing bundled skills as structure reference)
+- [ ] `skill-catalog.yaml` updated with both new entries
+- [ ] Agent wrappers created for Claude Code and opencode
+- [ ] Commit and draft PR created; URL shared with user

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/skills/delivery/workflow-client-bootstrap/questions.yaml

@@ -0,0 +1,165 @@
+# workflow-client-bootstrap — interview question bank
+# Each block is an interview group. The agent MUST ask all required questions
+# and may skip optional ones if context already answers them.
+
+version: 2
+
+groups:
+  - id: workspace
+    label: "Workspace Root (where data will be stored)"
+    description: "Select the workspace directory (e.g. ~/.ai-workspace) and explain storage paths."
+    questions:
+      - id: workspace_root_override
+        required: false
+        prompt: >-
+          (Optional) If you want to explicitly set the workspace root path, paste it now.
+          Otherwise leave blank and I will auto-detect candidates (e.g. ~/.ai-workspace, ~/.ai-workspace, current dir).
+
+  - id: identity
+    label: "Project Identity"
+    description: "Establish client name, slug, and tooling stack."
+    questions:
+      - id: client_name
+        required: true
+        prompt: "What is the client or project name? (e.g. Acme Payments, Example Corp)"
+
+      - id: client_slug
+        required: true
+        prompt: "What short slug should be used for naming? Use lowercase-kebab-case (e.g. `acme-payments`). This becomes the directory name under packs/clients/ and knowledge/clients/."
+
+      - id: ticket_system
+        required: true
+        prompt: "Which ticket system does this project use?"
+        options: [jira, clickup, linear, github-issues, none, other]
+
+      - id: jira_project_key
+        required: false
+        condition: "ticket_system == jira"
+        prompt: "What is the Jira project key prefix? (e.g. PROJ, ABC)"
+
+      - id: docs_platform
+        required: true
+        prompt: "Which documentation platform does this project use?"
+        options: [confluence, notion, github-wiki, none, other]
+
+      - id: repo_host
+        required: true
+        prompt: "Where are the code repositories hosted?"
+        options: [github, gitlab, bitbucket, other]
+
+      - id: repo_org
+        required: true
+        prompt: "What is the GitHub / GitLab organization or group name? (e.g. my-client-org)"
+
+      - id: account_name
+        required: false
+        prompt: "Optional: Is there an account/engagement name you want to group this client under? (e.g. Internal, Acme)."
+
+  - id: workflow
+    label: "Ticket Lifecycle & Delivery Workflow"
+    description: "Understand the client's Jira/ClickUp workflow and delivery gates."
+    questions:
+      - id: has_custom_workflow
+        required: true
+        prompt: "Does the ticket system have a custom status workflow (beyond the default To Do / In Progress / Done)? Answer yes or no."
+        options: [yes, no]
+
+      - id: custom_statuses
+        required: false
+        condition: "has_custom_workflow == yes"
+        prompt: "List all ticket statuses in order, from creation to done. Include any blocked or failed states. (You can paste a list or describe them.)"
+
+      - id: done_status
+        required: true
+        prompt: "What status means a ticket is fully done and accepted? (e.g. Accepted, Done, Closed)"
+
+      - id: base_branch
+        required: true
+        prompt: "What is the base branch for all feature work? (e.g. main, develop, master)"
+
+      - id: branching_model
+        required: true
+        prompt: "What branching model does this client use?"
+        options: [single-branch-main, gitflow-develop, staging-and-prod-branches, release-branches, other]
+
+      - id: has_staging
+        required: true
+        prompt: "Does the project have a staging environment with a QA gate before production? Answer yes or no."
+        options: [yes, no]
+
+      - id: has_preprod_pr
+        required: false
+        condition: "has_staging == yes"
+        prompt: "Is there a separate pre-prod PR review step before the production release? Answer yes or no."
+        options: [yes, no]
+
+      - id: deploy_method
+        required: true
+        prompt: "How are changes deployed to production? (e.g. CI/CD auto-deploy on merge, manual trigger, scheduled pipeline)"
+
+      - id: environments
+        required: false
+        prompt: "List known environments and their purpose (e.g. dev, staging, prod; or ANALYTICS_STAGING vs ANALYTICS). Answer none if not applicable."
+
+  - id: stack
+    label: "Repositories & Technical Stack"
+    description: "Capture repos and any validation tools specific to this client."
+    questions:
+      - id: repos
+        required: true
+        prompt: "List the main repositories for this project, one per line. Format: `<repo-name> — <role>` (e.g. `dbt-project-main — primary dbt project`, `api-service — backend REST API`)."
+
+      - id: has_agents_md
+        required: true
+        prompt: "Do the repositories use an AGENTS.md (or CLAUDE.md) as the agent contract? Answer yes, no, or varies."
+        options: [yes, no, varies]
+
+      - id: validation_tools
+        required: true
+        prompt: "Which technical validation tools does this project require before merging? (e.g. dbt parse/test, Snowflake queries, pytest, Cypress, eslint, none)"
+
+      - id: secrets_and_credentials
+        required: false
+        prompt: "Where do credentials live (vault, 1Password, env vars)? Any strict rules to follow?"
+
+      - id: ci_system
+        required: false
+        prompt: "What CI system runs validation (GitHub Actions, GitLab CI, CircleCI, none, other)?"
+
+      - id: data_artifacts_policy
+        required: false
+        prompt: "Are there any data artifacts (CSVs, exports) that must NEVER be committed? Describe the policy or answer none."
+
+  - id: conventions
+    label: "Conventions & Guardrails"
+    description: "Branch naming, PR style, and any client-specific restrictions."
+    questions:
+      - id: branch_naming
+        required: true
+        prompt: "What is the branch naming convention? Leave blank to use the agent-toolkit default: `<username>/<ticket-id>-<short-slug>`."
+
+      - id: pr_style
+        required: true
+        prompt: "Should PRs start as drafts or go directly to review?"
+        options: [draft, direct]
+
+      - id: pr_template
+        required: false
+        prompt: "Does the repo have a PR template at `.github/PULL_REQUEST_TEMPLATE.md` or similar? Answer yes, no, or unknown."
+
+      - id: slack_channel
+        required: false
+        prompt: "Is there a primary Slack channel for communication with this client or team? (e.g. #acme-engineering)"
+
+      - id: guardrails
+        required: false
+        prompt: "Are there any special guardrails or restrictions for this client? (e.g. never commit credentials, no force-push, secrets in specific vault). Answer none if not applicable."
+
+      - id: storage_visibility
+        required: true
+        prompt: "Should the generated workspace files be local-only, or committed to the workspace repo for sharing?"
+        options: [local-only, commit-to-workspace]
+
+      - id: extra_notes
+        required: false
+        prompt: "Any additional context the workflow should capture? (e.g. time zone constraints, review SLAs, specific tooling notes)"

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/skills/delivery/workflow-generic-project/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: workflow-generic-project
+description: >-
+  WHAT — Generic client delivery: Jira or ClickUp, full repo context, human gates, English traceability
+  on tickets, draft PR via delegated forge skills. Use workspace packs for client/account overlays.
+---
+
+# Workflow — Generic Project (WHAT)
+
+**All skill instructions, ticket comments, and PR text must be in English.**
+
+This workflow supports client delivery phases and gates. Apply any client/account constraints by loading the appropriate workspace pack first.
+
+## Mode selection (mandatory)
+
+- Use **this skill** for client delivery phases and gates.
+- If the task is in a specific client/account context, load the corresponding workspace pack overlay first.
+- If unclear → **ask** which engagement context to use before proceeding.
+
+## Delegation (HOW lives in tool skills)
+
+| Need | Delegate to |
+| --- | --- |
+| ClickUp tasks, comments, status | **clickup-cli** |
+| Jira issue ops, comments, dev links | External **jira-*** skills (e.g. via **jira-assistant** router; CLI: `jira-as`) per repo docs |
+| Confluence pages, search | External **confluence-*** skills (e.g. via **confluence-assistant** router; CLI: `confluence-as`) per repo docs |
+| Planning and estimation | **planning** |
+| Default development workflow / validation fallback | **development-workflow** |
+| Work item structure and templates | **work-item**, **epic**, **user-story**, **task**, **bug**, **incident** |
+| Meetings, decisions, agreements, spikes | **meeting-minutes**, **decision-log**, **agreement**, **spike** |
+| Project assessments, evidence maps, technical/management unit scorecards | **project-assessment**, **project-assessment-evidence**, **technical-unit-assessment**, **management-unit-assessment** |
+| PRD / TRD / ADR structure (templates) | **prd**, **trd**, **adr** (WHAT; see local template references inside each skill) |
+| Where to save a deliverable + human review | **output-handshake** (WHAT; always before final deliverables and PR/MR text) |
+| Default PR body when the repo has no template | **pr-fallback** (WHAT) then **github-cli-workflow** (HOW) |
+| Draft PR on GitHub after push | **github-cli-workflow** |
+| Draft MR on GitLab after push | **gitlab-cli-workflow** |
+| Repository discovery and conflicts | **assistant** |
+
+Do **not** paste forge or ticket CLI sequences here; open the tool skill and follow it.
+
+## Principles
+
+1. **Context:** Pull Jira, ClickUp, Confluence, and linked docs the task references; treat them as source of truth with the codebase (**assistant** inspection order).
+2. **Repo standards:** Follow `AGENTS.md`, CONTRIBUTING, PR templates, and documented Docker or devcontainer flows.
+3. **Human in the loop:** Confirm understanding and plan **before** substantial implementation; get explicit approval **before** finalizing PR text; escalate when context is missing.
+4. **Validation first:** Align on acceptance criteria and approach before deep implementation.
+5. **Traceability:** Add concise English comments on the **original** ticket for plan approval, meaningful milestones, and PR link—no duplicate full PR bodies in tickets.
+
+## Phases (gates)
+
+1. **Intake:** Identify ticket IDs and engagement context; retrieve linked docs via appropriate skills.
+2. **Discovery:** Analyze repo per **assistant**; note CI, templates, dev environments.
+3. **Plan:** Written plan → **stop for user approval.** No implementation until approved.
+4. **Plan traceability:** After plan approval, post a short ticket comment (delegate comment mechanism to **clickup-cli**, **jira-*** or **confluence-*** as applicable).
+5. **Implement:** Work in logical commits per repo conventions; self-review.
+6. **Push and draft PR/MR:** Push branch, then invoke **github-cli-workflow** or **gitlab-cli-workflow** for a **draft**; confirm title/body with the user.
+7. **Close loop:** Post final short ticket comment with PR link (via same ticket skills as above).
+
+## Branch naming (intent)
+
+Prefer **`<short-username>/<WORK_ITEM_ID>-<short-slug>`** (lowercase). Resolve username per repo or user preference; base branch per repo default (**main**, **develop**, etc.).
+
+## Session override
+
+If the user requests **local-only** work: skip push/PR automation; note limitations in ticket updates if still posting.
+
+## Safety
+
+- Never commit secrets; no force-push to shared defaults unless the user explicitly requests recovery steps.
+
+## Checklist
+
+- [ ] Engagement context (if any) confirmed
+- [ ] Work item + doc context retrieved
+- [ ] Plan approved before code; ticket comment after plan approval
+- [ ] Repo standards (template, devcontainer) respected
+- [ ] Draft PR/MR via **github-cli-workflow** or **gitlab-cli-workflow** (or documented fallback)
+- [ ] Final traceability comment with PR link when applicable

agent_toolkit_cli-1.0.3.data/data/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_cli-1.0.3.data/data/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_cli-1.0.3.data/data/agent_toolkit/data/skills/design/figma/SKILL.md

@@ -0,0 +1,95 @@
+---
+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.
+---
+
+# 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_cli-1.0.3.data/data/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_cli-1.0.3.data/data/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_cli-1.0.3.data/data/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_cli-1.0.3.data/data/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.