Initial public release of Warp.
Repo-Sync-Origin: warpdotdev/warp-internal@12af1d983b
This commit is contained in:
David Stern
@@ -0,0 +1,216 @@
|
||||
---
|
||||
name: edit-figma-design
|
||||
description: Create or update Figma designs directly from a written product or UI description using the Figma MCP authoring tools. Use when the user wants a mockup, wireframe, screen, component, flow, or concept designed in Figma from text, or wants to iterate on an existing Figma file from textual feedback. Despite the name, this skill can start from a new blank file or edit an existing one. Do not use for capture-based workflows that turn a running page into Figma; use `figma-generate-design` for those, and use `implement-design` for code implementation requests. Requires Figma MCP server connection.
|
||||
metadata:
|
||||
mcp-server: figma
|
||||
---
|
||||
|
||||
# Edit Figma Design
|
||||
|
||||
## Overview
|
||||
|
||||
This skill creates or updates Figma designs directly from a natural-language description. It combines Figma library search with direct file authoring, and uses Warp's broader agent capabilities only when they are needed to make the design more product-aware or codebase-aware.
|
||||
|
||||
## When to use this skill
|
||||
|
||||
Use this skill when the user wants you to:
|
||||
|
||||
- design a new screen, flow, component, or mockup in Figma from a written description
|
||||
- refine or extend an existing Figma file from text feedback
|
||||
- create a first-pass wireframe or higher-fidelity design directly in Figma
|
||||
- align a Figma design to an existing design system or product vocabulary
|
||||
|
||||
Do not use this skill when:
|
||||
|
||||
- the user wants production code from a design — use `implement-design`
|
||||
- the user wants to capture a running page or app into Figma — use `figma-generate-design`
|
||||
- the user only wants to inspect or pull existing Figma context — use `pull-figma-content`
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Figma MCP server must be connected and accessible.
|
||||
- Verify that `search_design_system`, `create_new_file`, and `use_figma` are available.
|
||||
- Gather the minimum information needed to proceed:
|
||||
- what should be designed
|
||||
- whether to use an existing Figma file or create a new one
|
||||
- whether the result should align to an existing design system or codebase
|
||||
- Ask clarifying questions only when the user has not already given enough detail to start. Keep them short and batch them into one message when possible.
|
||||
|
||||
## Required Workflow
|
||||
|
||||
**Follow these steps in order. Do not skip steps.**
|
||||
|
||||
### Step 1: Confirm this is a Figma-authoring request
|
||||
|
||||
If the user is actually asking for implementation, stop and consult `implement-design`.
|
||||
|
||||
If the user wants a screenshot-to-Figma or webpage capture flow, stop and consult `figma-generate-design`. That skill is for capture-based workflows; this skill is for text-to-design authoring.
|
||||
|
||||
### Step 2: Resolve the destination file first
|
||||
|
||||
Both `search_design_system` and `use_figma` need a `fileKey`, so determine the destination before searching or editing.
|
||||
|
||||
**If the user provided an existing Figma URL or file key:**
|
||||
|
||||
- Extract and use that `fileKey`.
|
||||
- Reuse the provided URL when you respond.
|
||||
|
||||
**If the user wants a new file:**
|
||||
|
||||
1. Decide on a clear file name from the request.
|
||||
2. If the user already provided a `planKey`, use it.
|
||||
3. Otherwise call the Figma MCP `whoami` tool to inspect the authenticated Figma user and available plans. This is not the shell `whoami` command.
|
||||
4. If there is exactly one plan, use its `key`.
|
||||
5. If there are multiple plans, ask the user which team or organization to use.
|
||||
6. Call `create_new_file(editorType="design", fileName=..., planKey=...)`.
|
||||
7. Save the returned `fileKey` and URL. Share the URL once the first usable draft is ready.
|
||||
|
||||
### Step 3: Gather the right context, but only when it is needed
|
||||
|
||||
Decide how much non-Figma context is actually necessary.
|
||||
|
||||
**Stay inside Figma MCP only** when the user wants an exploratory concept, wireframe, or mockup and does not ask for codebase alignment.
|
||||
|
||||
**Use Warp agent context selectively** when the user wants the design to match an existing product or design system:
|
||||
|
||||
- read project rules from `AGENTS.md` and/or `WARP.md` if they exist
|
||||
- use semantic codebase search, grep, and file reads to find relevant components, product vocabulary, layout patterns, and design-token sources
|
||||
- use other MCP sources or web search only when the prompt directly depends on them, such as product requirements in another system or explicit inspiration requests
|
||||
- do not edit code, run REPL commands, or use computer use as part of this skill's normal workflow
|
||||
|
||||
### Step 4: Search the design system before authoring
|
||||
|
||||
Call `search_design_system` with the resolved `fileKey` before creating new components or styles.
|
||||
|
||||
Search for the most reusable assets first:
|
||||
|
||||
- components and component sets
|
||||
- variables and token-like values
|
||||
- styles for color, typography, spacing, or effects
|
||||
|
||||
Start with the user's domain terms and any names discovered from project rules or codebase search.
|
||||
|
||||
If needed, narrow follow-up searches with returned library keys rather than immediately broadening the search.
|
||||
|
||||
Prefer reusing and importing matches over recreating them from scratch.
|
||||
|
||||
### Step 5: Prepare `use_figma` safely
|
||||
|
||||
Before the first `use_figma` call, plan the edit sequence and follow the tool's required Plugin API constraints.
|
||||
|
||||
Keep the authoring plan incremental:
|
||||
|
||||
1. create page and frame structure
|
||||
2. establish layout and major sections
|
||||
3. reuse or import design-system assets
|
||||
4. apply variables, styles, and typography
|
||||
5. add content and polish
|
||||
6. make targeted revisions based on what the file now contains
|
||||
|
||||
### Step 6: Edit the design in small `use_figma` steps
|
||||
|
||||
Use multiple small `use_figma` calls instead of one giant script.
|
||||
|
||||
Good step boundaries:
|
||||
|
||||
- create a page and top-level frames
|
||||
- lay out a header, sidebar, hero, or content region
|
||||
- import or place one family of reusable components
|
||||
- bind colors, text styles, or spacing variables
|
||||
- update copy, states, or alignment for a specific section
|
||||
|
||||
After each step, inspect the result and only continue once the previous step succeeded.
|
||||
|
||||
When creating anything component-like, prefer imported library assets discovered in Step 4.
|
||||
|
||||
### Step 7: Hand back the design and next options
|
||||
|
||||
When the first usable draft is ready:
|
||||
|
||||
- return the Figma URL if you have it
|
||||
- summarize what you created or updated at a high level
|
||||
- ask whether the user wants revisions in Figma
|
||||
|
||||
If the user asks to implement the approved design in code, stop using this skill and consult `implement-design`.
|
||||
|
||||
## Warp-agent guidance
|
||||
|
||||
Use Warp's broader capabilities to reduce manual prompting, not to add unnecessary work.
|
||||
|
||||
**Good uses of Warp agent capabilities in this skill:**
|
||||
|
||||
- finding existing component names or design tokens in the repo
|
||||
- reading project rules that constrain layout, naming, or branding
|
||||
- pulling product requirements from other connected systems when the user explicitly relies on them
|
||||
|
||||
**Usually unnecessary for this skill:**
|
||||
|
||||
- shell commands or REPL access
|
||||
- code edits
|
||||
- computer-use validation
|
||||
- broad web research without a specific user request
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: New file from a product description
|
||||
|
||||
User says: "Design a billing overview screen in Figma for our desktop app. Use our existing design system and create a new file."
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Confirm this is Figma authoring, not code implementation.
|
||||
2. Resolve the destination by calling `whoami` if needed, then `create_new_file`.
|
||||
3. Read `AGENTS.md` or `WARP.md`, or search the codebase only if needed to understand billing terminology and existing components.
|
||||
4. Call `search_design_system` with billing-related queries.
|
||||
5. Build the screen in small `use_figma` steps.
|
||||
6. Return the new Figma file URL and offer to revise.
|
||||
|
||||
### Example 2: Update an existing Figma file
|
||||
|
||||
User says: "Add an onboarding checklist to this Figma file: https://figma.com/design/FILEKEY/Product?node-id=1-2"
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Extract the `fileKey` from the existing URL.
|
||||
2. Search the design system for checklist, card, badge, and progress assets before creating anything new.
|
||||
3. Use incremental `use_figma` calls to add the new section.
|
||||
4. Return the same Figma URL and summarize the change.
|
||||
|
||||
### Example 3: Pure exploratory concept
|
||||
|
||||
User says: "Create a first-pass mobile workout planner mockup in Figma. It doesn't need to match my codebase yet."
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Create a new file if needed.
|
||||
2. Skip codebase search and project-rule inspection.
|
||||
3. Use `search_design_system` only to reuse any relevant Figma library assets.
|
||||
4. Build the concept directly in Figma with small `use_figma` steps.
|
||||
5. Share the file link and ask what to refine next.
|
||||
|
||||
## Common issues and responses
|
||||
|
||||
### Issue: The user hasn't said whether to use an existing file or a new one
|
||||
|
||||
Ask one direct question that resolves the destination. Do not start `search_design_system` or `use_figma` until you have a `fileKey`.
|
||||
|
||||
### Issue: Multiple Figma plans are available for `create_new_file`
|
||||
|
||||
Ask the user which team or organization to use. Do not guess.
|
||||
|
||||
### Issue: The user wants the design to match existing product conventions, but the request is vague
|
||||
|
||||
Read the project's rules first. Then use targeted codebase search to gather only the components and conventions relevant to the requested surface.
|
||||
|
||||
### Issue: The user asks for both a Figma design and implementation
|
||||
|
||||
Create or update the Figma design first only if the user's request is primarily about authoring in Figma. If the request is primarily about implementation, consult `implement-design` instead. After the design is approved, implementation can follow in a separate step.
|
||||
|
||||
### Issue: `use_figma` fails or the script is getting large
|
||||
|
||||
Break the task into smaller `use_figma` calls. Prefer structure first, then styling, then targeted revisions.
|
||||
|
||||
## Additional resources
|
||||
|
||||
- [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server/)
|
||||
- [Figma MCP Server Tools and Prompts](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/)
|
||||
@@ -0,0 +1,350 @@
|
||||
---
|
||||
name: figma-code-connect-components
|
||||
description: Connects Figma design components to code components using Code Connect mapping tools. Use when user says "code connect", "connect this component to code", "map this component", "link component to code", "create code connect mapping", or wants to establish mappings between Figma designs and code implementations. For canvas writes via `use_figma`, use `figma-use`.
|
||||
disable-model-invocation: false
|
||||
---
|
||||
|
||||
# Code Connect Components
|
||||
|
||||
## Overview
|
||||
|
||||
This skill helps you connect Figma design components to their corresponding code implementations using Figma's Code Connect feature. It analyzes the Figma design structure, searches your codebase for matching components, and establishes mappings that maintain design-code consistency.
|
||||
|
||||
## Skill Boundaries
|
||||
|
||||
- Use this skill for `get_code_connect_suggestions` + `send_code_connect_mappings` workflows.
|
||||
- If the task requires writing to the Figma canvas with Plugin API scripts, switch to [figma-use](../figma-use/SKILL.md).
|
||||
- If the task is building or updating a full-page screen in Figma from code or a description, switch to [figma-generate-design](../figma-generate-design/SKILL.md).
|
||||
- If the task is implementing product code from Figma, switch to [figma-implement-design](../figma-implement-design/SKILL.md).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Figma MCP server must be connected and accessible
|
||||
- User must provide a Figma URL with node ID: `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
|
||||
- **IMPORTANT:** The Figma URL must include the `node-id` parameter. Code Connect mapping will fail without it.
|
||||
- **OR** when using `figma-desktop` MCP: User can select a node directly in the Figma desktop app (no URL required)
|
||||
- **IMPORTANT:** The Figma component must be published to a team library. Code Connect only works with published components or component sets.
|
||||
- **IMPORTANT:** Code Connect is only available on Organization and Enterprise plans.
|
||||
- Access to the project codebase for component scanning
|
||||
|
||||
## Required Workflow
|
||||
|
||||
**Follow these steps in order. Do not skip steps.**
|
||||
|
||||
### Step 1: Get Code Connect Suggestions
|
||||
|
||||
Call `get_code_connect_suggestions` to identify all unmapped components in a single operation. This tool automatically:
|
||||
|
||||
- Fetches component info from the Figma scenegraph
|
||||
- Identifies published components in the selection
|
||||
- Checks existing Code Connect mappings and filters out already-connected components
|
||||
- Returns component names, properties, and thumbnail images for each unmapped component
|
||||
|
||||
#### Option A: Using `figma-desktop` MCP (no URL provided)
|
||||
|
||||
If the `figma-desktop` MCP server is connected and the user has NOT provided a Figma URL, immediately call `get_code_connect_suggestions`. No URL parsing is needed — the desktop MCP server automatically uses the currently selected node from the open Figma file.
|
||||
|
||||
**Note:** The user must have the Figma desktop app open with a node selected. `fileKey` is not passed as a parameter — the server uses the currently open file.
|
||||
|
||||
#### Option B: When a Figma URL is provided
|
||||
|
||||
Parse the URL to extract `fileKey` and `nodeId`, then call `get_code_connect_suggestions`.
|
||||
|
||||
**IMPORTANT:** When extracting the node ID from a Figma URL, convert the format:
|
||||
|
||||
- URL format uses hyphens: `node-id=1-2`
|
||||
- Tool expects colons: `nodeId=1:2`
|
||||
|
||||
**Parse the Figma URL:**
|
||||
|
||||
- URL format: `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
|
||||
- Extract file key: `:fileKey` (segment after `/design/`)
|
||||
- Extract node ID: `1-2` from URL, then convert to `1:2` for the tool
|
||||
|
||||
```
|
||||
get_code_connect_suggestions(fileKey=":fileKey", nodeId="1:2")
|
||||
```
|
||||
|
||||
**Handle the response:**
|
||||
|
||||
- If the tool returns **"No published components found in this selection"** → inform the user and stop. The components may need to be published to a team library first.
|
||||
- If the tool returns **"All component instances in this selection are already connected to code via Code Connect"** → inform the user that everything is already mapped.
|
||||
- Otherwise, the response contains a list of unmapped components, each with:
|
||||
- Component name
|
||||
- Node ID
|
||||
- Component properties (JSON with prop names and values)
|
||||
- A thumbnail image of the component (for visual inspection)
|
||||
|
||||
### Step 2: Scan Codebase for Matching Components
|
||||
|
||||
For each unmapped component returned by `get_code_connect_suggestions`, search the codebase for a matching code component.
|
||||
|
||||
**What to look for:**
|
||||
|
||||
- Component names that match or are similar to the Figma component name
|
||||
- Component structure that aligns with the Figma hierarchy
|
||||
- Props that correspond to Figma properties (variants, text, styles)
|
||||
- Files in typical component directories (`src/components/`, `components/`, `ui/`, etc.)
|
||||
|
||||
**Search strategy:**
|
||||
|
||||
1. Search for component files with matching names
|
||||
2. Read candidate files to check structure and props
|
||||
3. Compare the code component's props with the Figma component properties returned in Step 1
|
||||
4. Detect the programming language (TypeScript, JavaScript) and framework (React, Vue, etc.)
|
||||
5. Identify the best match based on structural similarity, weighing:
|
||||
- Prop names and their correspondence to Figma properties
|
||||
- Default values that match Figma defaults
|
||||
- CSS classes or style objects
|
||||
- Descriptive comments that clarify intent
|
||||
6. If multiple candidates are equally good, pick the one with the closest prop-interface match and document your reasoning in a 1-2 sentence comment before your tool call
|
||||
|
||||
**Example search patterns:**
|
||||
|
||||
- If Figma component is "PrimaryButton", search for `Button.tsx`, `PrimaryButton.tsx`, `Button.jsx`
|
||||
- Check common component paths: `src/components/`, `app/components/`, `lib/ui/`
|
||||
- Look for variant props like `variant`, `size`, `color` that match Figma variants
|
||||
|
||||
### Step 3: Present Matches to User
|
||||
|
||||
Present your findings and let the user choose which mappings to create. The user can accept all, some, or none of the suggested mappings.
|
||||
|
||||
**Present matches in this format:**
|
||||
|
||||
```
|
||||
The following components match the design:
|
||||
- [ComponentName](path/to/component): DesignComponentName at nodeId [nodeId](figmaUrl?node-id=X-Y)
|
||||
- [AnotherComponent](path/to/another): AnotherDesign at nodeId [nodeId2](figmaUrl?node-id=X-Y)
|
||||
|
||||
Would you like to connect these components? You can accept all, select specific ones, or skip.
|
||||
```
|
||||
|
||||
**If no exact match is found for a component:**
|
||||
|
||||
- Show the 2 closest candidates
|
||||
- Explain the differences
|
||||
- Ask the user to confirm which component to use or provide the correct path
|
||||
|
||||
**If the user declines all mappings**, inform them and stop. No further tool calls are needed.
|
||||
|
||||
### Step 4: Create Code Connect Mappings
|
||||
|
||||
Once the user confirms their selections, call `send_code_connect_mappings` with only the accepted mappings. This tool handles batch creation of all mappings in a single call.
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
send_code_connect_mappings(
|
||||
fileKey=":fileKey",
|
||||
nodeId="1:2",
|
||||
mappings=[
|
||||
{ nodeId: "1:2", componentName: "Button", source: "src/components/Button.tsx", label: "React" },
|
||||
{ nodeId: "1:5", componentName: "Card", source: "src/components/Card.tsx", label: "React" }
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
**Key parameters for each mapping:**
|
||||
|
||||
- `nodeId`: The Figma node ID (with colon format: `1:2`)
|
||||
- `componentName`: Name of the component to connect (e.g., "Button", "Card")
|
||||
- `source`: Path to the code component file (relative to project root)
|
||||
- `label`: The framework or language label for this Code Connect mapping. Valid values include:
|
||||
- Web: 'React', 'Web Components', 'Vue', 'Svelte', 'Storybook', 'Javascript'
|
||||
- iOS: 'Swift UIKit', 'Objective-C UIKit', 'SwiftUI'
|
||||
- Android: 'Compose', 'Java', 'Kotlin', 'Android XML Layout'
|
||||
- Cross-platform: 'Flutter'
|
||||
- Docs: 'Markdown'
|
||||
|
||||
**After the call:**
|
||||
|
||||
- On success: the tool confirms the mappings were created
|
||||
- On error: the tool reports which specific mappings failed and why (e.g., "Component is already mapped to code", "Published component not found", "Insufficient permissions")
|
||||
|
||||
**Provide a summary** after processing:
|
||||
|
||||
```
|
||||
Code Connect Summary:
|
||||
- Successfully connected: 3
|
||||
- Button (1:2) → src/components/Button.tsx
|
||||
- Card (1:5) → src/components/Card.tsx
|
||||
- Input (1:8) → src/components/Input.tsx
|
||||
- Could not connect: 1
|
||||
- CustomWidget (1:10) - No matching component found in codebase
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Connecting a Button Component
|
||||
|
||||
User says: "Connect this Figma button to my code: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15"
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Parse URL: fileKey=`kL9xQn2VwM8pYrTb4ZcHjF`, nodeId=`42-15` → convert to `42:15`
|
||||
2. Run `get_code_connect_suggestions(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42:15")`
|
||||
3. Response shows: Button component (unmapped) with `variant` (primary/secondary) and `size` (sm/md/lg) properties, plus a thumbnail image
|
||||
4. Search codebase for Button components: Find `src/components/Button.tsx`
|
||||
5. Read `Button.tsx` and confirm it has `variant` and `size` props
|
||||
6. Present to user:
|
||||
```
|
||||
I found a match:
|
||||
- [Button](src/components/Button.tsx): Button at nodeId [42:15](https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15)
|
||||
|
||||
Would you like to connect this component?
|
||||
```
|
||||
|
||||
7. User confirms: "Yes"
|
||||
8. Detect that it's a TypeScript React component
|
||||
9. Run `send_code_connect_mappings(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42:15", mappings=[{ nodeId: "42:15", componentName: "Button", source: "src/components/Button.tsx", label: "React" }])`
|
||||
|
||||
**Result:** Figma button component is now connected to the code Button component.
|
||||
|
||||
### Example 2: Multiple Components with Partial Selection
|
||||
|
||||
User says: "Connect components in this frame: https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-50"
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Parse URL: fileKey=`pR8mNv5KqXzGwY2JtCfL4D`, nodeId=`10-50` → convert to `10:50`
|
||||
2. Run `get_code_connect_suggestions(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10:50")`
|
||||
3. Response shows 3 unmapped components: ProductCard, Badge, and CustomWidget
|
||||
4. Search codebase:
|
||||
- ProductCard: Found `src/components/ProductCard.tsx` (props match)
|
||||
- Badge: Found `src/components/Badge.tsx` (props match)
|
||||
- CustomWidget: No matching component found
|
||||
5. Present to user:
|
||||
```
|
||||
The following components match the design:
|
||||
- [ProductCard](src/components/ProductCard.tsx): ProductCard at nodeId [10:51](https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-51)
|
||||
- [Badge](src/components/Badge.tsx): Badge at nodeId [10:52](https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-52)
|
||||
|
||||
I couldn't find a match for CustomWidget (10:53).
|
||||
|
||||
Would you like to connect these components? You can accept all, select specific ones, or skip.
|
||||
```
|
||||
|
||||
6. User: "Just connect ProductCard, skip Badge for now"
|
||||
7. Run `send_code_connect_mappings(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10:50", mappings=[{ nodeId: "10:51", componentName: "ProductCard", source: "src/components/ProductCard.tsx", label: "React" }])`
|
||||
|
||||
**Result:** Only ProductCard is connected, per the user's selection.
|
||||
|
||||
### Example 3: Component Needs Creation
|
||||
|
||||
User says: "Connect this icon: https://figma.com/design/8yJDMeWDyBz71EnMOSuUiw/Icons?node-id=5-20"
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Parse URL: fileKey=`8yJDMeWDyBz71EnMOSuUiw`, nodeId=`5-20` → convert to `5:20`
|
||||
2. Run `get_code_connect_suggestions(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20")`
|
||||
3. Response shows: CheckIcon component (unmapped) with color and size properties
|
||||
4. Search codebase for CheckIcon: No matches found
|
||||
5. Search for generic Icon components: Find `src/icons/` directory with other icons
|
||||
6. Report to user: "I couldn't find a CheckIcon component, but I found an icons directory at src/icons/. Would you like to:
|
||||
- Create a new CheckIcon.tsx component first, then connect it
|
||||
- Connect to a different existing icon
|
||||
- Provide the path to the CheckIcon if it exists elsewhere"
|
||||
7. User provides path: "src/icons/CheckIcon.tsx"
|
||||
8. Detect language and framework from the file
|
||||
9. Run `send_code_connect_mappings(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20", mappings=[{ nodeId: "5:20", componentName: "CheckIcon", source: "src/icons/CheckIcon.tsx", label: "React" }])`
|
||||
|
||||
**Result:** CheckIcon component is successfully connected to the Figma design.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Proactive Component Discovery
|
||||
|
||||
Don't just ask the user for the file path — actively search their codebase to find matching components. This provides a better experience and catches potential mapping opportunities.
|
||||
|
||||
### Accurate Structure Matching
|
||||
|
||||
When comparing Figma components to code components, look beyond just names. Check that:
|
||||
|
||||
- Props align (variant types, size options, etc.)
|
||||
- Component hierarchy matches (nested elements)
|
||||
- The component serves the same purpose
|
||||
|
||||
### Clear Communication
|
||||
|
||||
When offering to create a mapping, clearly explain:
|
||||
|
||||
- What you found
|
||||
- Why it's a good match
|
||||
- What the mapping will do
|
||||
- How props will be connected
|
||||
|
||||
### Handle Ambiguity
|
||||
|
||||
If multiple components could match, present options rather than guessing. Let the user make the final decision about which component to connect.
|
||||
|
||||
### Graceful Degradation
|
||||
|
||||
If you can't find an exact match, provide helpful next steps:
|
||||
|
||||
- Show close candidates
|
||||
- Suggest component creation
|
||||
- Ask for user guidance
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Issue: "No published components found in this selection"
|
||||
|
||||
**Cause:** The Figma component is not published to a team library. Code Connect only works with published components.
|
||||
**Solution:** The user needs to publish the component to a team library in Figma:
|
||||
|
||||
1. In Figma, select the component or component set
|
||||
2. Right-click and choose "Publish to library" or use the Team Library publish modal
|
||||
3. Publish the component
|
||||
4. Once published, retry the Code Connect mapping with the same node ID
|
||||
|
||||
### Issue: "Code Connect is only available on Organization and Enterprise plans"
|
||||
|
||||
**Cause:** The user's Figma plan does not include Code Connect access.
|
||||
**Solution:** The user needs to upgrade to an Organization or Enterprise plan, or contact their administrator.
|
||||
|
||||
### Issue: No matching component found in codebase
|
||||
|
||||
**Cause:** The codebase search did not find a component with a matching name or structure.
|
||||
**Solution:** Ask the user if the component exists under a different name or in a different location. They may need to create the component first, or it might be located in an unexpected directory.
|
||||
|
||||
### Issue: "Published component not found" (CODE_CONNECT_ASSET_NOT_FOUND)
|
||||
|
||||
**Cause:** The source file path is incorrect, the component doesn't exist at that location, or the componentName doesn't match the actual export.
|
||||
**Solution:** Verify the source path is correct and relative to the project root. Check that the component is properly exported from the file with the exact componentName specified.
|
||||
|
||||
### Issue: "Component is already mapped to code" (CODE_CONNECT_MAPPING_ALREADY_EXISTS)
|
||||
|
||||
**Cause:** A Code Connect mapping already exists for this component.
|
||||
**Solution:** The component is already connected. If the user wants to update the mapping, they may need to remove the existing one first in Figma.
|
||||
|
||||
### Issue: "Insufficient permissions to create mapping" (CODE_CONNECT_INSUFFICIENT_PERMISSIONS)
|
||||
|
||||
**Cause:** The user does not have edit permissions on the Figma file or library.
|
||||
**Solution:** The user needs edit access to the file containing the component. Contact the file owner or team admin.
|
||||
|
||||
### Issue: Code Connect mapping fails with URL errors
|
||||
|
||||
**Cause:** The Figma URL format is incorrect or missing the `node-id` parameter.
|
||||
**Solution:** Verify the URL follows the required format: `https://figma.com/design/:fileKey/:fileName?node-id=1-2`. The `node-id` parameter is required. Also ensure you convert `1-2` to `1:2` when calling tools.
|
||||
|
||||
### Issue: Multiple similar components found
|
||||
|
||||
**Cause:** The codebase contains multiple components that could match the Figma component.
|
||||
**Solution:** Present all candidates to the user with their file paths and let them choose which one to connect. Different components might be used in different contexts (e.g., `Button.tsx` vs `LinkButton.tsx`).
|
||||
|
||||
## Understanding Code Connect
|
||||
|
||||
Code Connect establishes a bidirectional link between design and code:
|
||||
|
||||
**For designers:** See which code component implements a Figma component
|
||||
**For developers:** Navigate from Figma designs directly to the code that implements them
|
||||
**For teams:** Maintain a single source of truth for component mappings
|
||||
|
||||
The mapping you create helps keep design and code in sync by making these connections explicit and discoverable.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
For more information about Code Connect:
|
||||
|
||||
- [Code Connect Documentation](https://help.figma.com/hc/en-us/articles/23920389749655-Code-Connect)
|
||||
- [Figma MCP Server Tools and Prompts](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/)
|
||||
@@ -0,0 +1,538 @@
|
||||
---
|
||||
name: figma-create-design-system-rules
|
||||
description: Generates custom design system rules for the user's codebase. Use when user says "create design system rules", "generate rules for my project", "set up design rules", "customize design system guidelines", or wants to establish project-specific conventions for Figma-to-code workflows. Requires Figma MCP server connection.
|
||||
disable-model-invocation: false
|
||||
---
|
||||
|
||||
# Create Design System Rules
|
||||
|
||||
## Overview
|
||||
|
||||
This skill helps you generate custom design system rules tailored to your project's specific needs. These rules guide AI coding agents to produce consistent, high-quality code when implementing Figma designs, ensuring that your team's conventions, component patterns, and architectural decisions are followed automatically.
|
||||
|
||||
### Supported Rule Files
|
||||
|
||||
| Agent | Rule File |
|
||||
|-------|-----------|
|
||||
| Claude Code | `CLAUDE.md` |
|
||||
| Codex CLI | `AGENTS.md` |
|
||||
| Cursor | `.cursor/rules/figma-design-system.mdc` |
|
||||
|
||||
## What Are Design System Rules?
|
||||
|
||||
Design system rules are project-level instructions that encode the "unwritten knowledge" of your codebase - the kind of expertise that experienced developers know and would pass on to new team members:
|
||||
|
||||
- Which layout primitives and components to use
|
||||
- Where component files should be located
|
||||
- How components should be named and structured
|
||||
- What should never be hardcoded
|
||||
- How to handle design tokens and styling
|
||||
- Project-specific architectural patterns
|
||||
|
||||
Once defined, these rules dramatically reduce repetitive prompting and ensure consistent output across all Figma implementation tasks.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Figma MCP server must be connected and accessible
|
||||
- Access to the project codebase for analysis
|
||||
- Understanding of your team's component conventions (or willingness to establish them)
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
|
||||
- Starting a new project that will use Figma designs
|
||||
- Onboarding an AI coding agent to an existing project with established patterns
|
||||
- Standardizing Figma-to-code workflows across your team
|
||||
- Updating or refining existing design system conventions
|
||||
- Users explicitly request: "create design system rules", "set up Figma guidelines", "customize rules for my project"
|
||||
|
||||
## Required Workflow
|
||||
|
||||
**Follow these steps in order. Do not skip steps.**
|
||||
|
||||
### Step 1: Run the Create Design System Rules Tool
|
||||
|
||||
Call the Figma MCP server's `create_design_system_rules` tool to get the foundational prompt and template.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
- `clientLanguages`: Comma-separated list of languages used in the project (e.g., "typescript,javascript", "python", "javascript")
|
||||
- `clientFrameworks`: Framework being used (e.g., "react", "vue", "svelte", "angular", "unknown")
|
||||
|
||||
This tool returns guidance and a template for creating design system rules.
|
||||
|
||||
Structure your design system rules following the template format provided in the tool's response.
|
||||
|
||||
### Step 2: Analyze the Codebase
|
||||
|
||||
Before finalizing rules, analyze the project to understand existing patterns:
|
||||
|
||||
**Component Organization:**
|
||||
|
||||
- Where are UI components located? (e.g., `src/components/`, `app/ui/`, `lib/components/`)
|
||||
- Is there a dedicated design system directory?
|
||||
- How are components organized? (by feature, by type, flat structure)
|
||||
|
||||
**Styling Approach:**
|
||||
|
||||
- What CSS framework or approach is used? (Tailwind, CSS Modules, styled-components, etc.)
|
||||
- Where are design tokens defined? (CSS variables, theme files, config files)
|
||||
- Are there existing color, typography, or spacing tokens?
|
||||
|
||||
**Component Patterns:**
|
||||
|
||||
- What naming conventions are used? (PascalCase, kebab-case, prefixes)
|
||||
- How are component props typically structured?
|
||||
- Are there common composition patterns?
|
||||
|
||||
**Architecture Decisions:**
|
||||
|
||||
- How is state management handled?
|
||||
- What routing system is used?
|
||||
- Are there specific import patterns or path aliases?
|
||||
|
||||
### Step 3: Generate Project-Specific Rules
|
||||
|
||||
Based on your codebase analysis, create a comprehensive set of rules. Include:
|
||||
|
||||
#### General Component Rules
|
||||
|
||||
```markdown
|
||||
- IMPORTANT: Always use components from `[YOUR_PATH]` when possible
|
||||
- Place new UI components in `[COMPONENT_DIRECTORY]`
|
||||
- Follow `[NAMING_CONVENTION]` for component names
|
||||
- Components must export as `[EXPORT_PATTERN]`
|
||||
```
|
||||
|
||||
#### Styling Rules
|
||||
|
||||
```markdown
|
||||
- Use `[CSS_FRAMEWORK/APPROACH]` for styling
|
||||
- Design tokens are defined in `[TOKEN_LOCATION]`
|
||||
- IMPORTANT: Never hardcode colors - always use tokens from `[TOKEN_FILE]`
|
||||
- Spacing values must use the `[SPACING_SYSTEM]` scale
|
||||
- Typography follows the scale defined in `[TYPOGRAPHY_LOCATION]`
|
||||
```
|
||||
|
||||
#### Figma MCP Integration Rules
|
||||
|
||||
```markdown
|
||||
## 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, 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
|
||||
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 `[YOUR_STYLING_APPROACH]` when applicable
|
||||
- Reuse existing components from `[COMPONENT_PATH]` 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
|
||||
- Strive for 1:1 visual parity with the Figma design
|
||||
- Validate the final UI against the Figma screenshot for both look and behavior
|
||||
```
|
||||
|
||||
#### Asset Handling Rules
|
||||
|
||||
```markdown
|
||||
## Asset Handling
|
||||
|
||||
- The Figma MCP server provides an assets endpoint which can serve 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
|
||||
- Store downloaded assets in `[ASSET_DIRECTORY]`
|
||||
```
|
||||
|
||||
#### Project-Specific Conventions
|
||||
|
||||
```markdown
|
||||
## Project-Specific Conventions
|
||||
|
||||
- [Add any unique architectural patterns]
|
||||
- [Add any special import requirements]
|
||||
- [Add any testing requirements]
|
||||
- [Add any accessibility standards]
|
||||
- [Add any performance considerations]
|
||||
```
|
||||
|
||||
### Step 4: Save Rules to the Appropriate Rule File
|
||||
|
||||
Detect which AI coding agent the user is working with and save the generated rules to the corresponding file:
|
||||
|
||||
| Agent | Rule File | Notes |
|
||||
|-------|-----------|-------|
|
||||
| Claude Code | `CLAUDE.md` in project root | Markdown format. Can also use `.claude/rules/figma-design-system.md` for modular organization. |
|
||||
| Codex CLI | `AGENTS.md` in project root | Markdown format. Append as a new section if file already exists. 32 KiB combined size limit. |
|
||||
| Cursor | `.cursor/rules/figma-design-system.mdc` | Markdown with YAML frontmatter (`description`, `globs`, `alwaysApply`). |
|
||||
|
||||
If unsure which agent the user is working with, check for existing rule files in the project or ask the user.
|
||||
|
||||
For Cursor, wrap the rules with YAML frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Rules for implementing Figma designs using the Figma MCP server. Covers component organization, styling conventions, design tokens, asset handling, and the required Figma-to-code workflow.
|
||||
globs: "src/components/**"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
[Generated rules here]
|
||||
```
|
||||
|
||||
Customize the `globs` pattern to match the directories where Figma-derived code will live in the project (e.g., `"src/**/*.tsx"` or `["src/components/**", "src/pages/**"]`).
|
||||
|
||||
After saving, the rules will be automatically loaded by the agent and applied to all Figma implementation tasks.
|
||||
|
||||
### Step 5: Validate and Iterate
|
||||
|
||||
After creating rules:
|
||||
|
||||
1. Test with a simple Figma component implementation
|
||||
2. Verify the agent follows the rules correctly
|
||||
3. Refine any rules that aren't working as expected
|
||||
4. Share with team members for feedback
|
||||
5. Update rules as the project evolves
|
||||
|
||||
## Rule Categories and Examples
|
||||
|
||||
### Essential Rules (Always Include)
|
||||
|
||||
**Component Discovery:**
|
||||
|
||||
```markdown
|
||||
- UI components are located in `src/components/ui/`
|
||||
- Feature components are in `src/components/features/`
|
||||
- Layout primitives are in `src/components/layout/`
|
||||
```
|
||||
|
||||
**Design Token Usage:**
|
||||
|
||||
```markdown
|
||||
- Colors are defined as CSS variables in `src/styles/tokens.css`
|
||||
- Never hardcode hex colors - use `var(--color-*)` tokens
|
||||
- Spacing uses the 4px base scale: `--space-1` (4px), `--space-2` (8px), etc.
|
||||
```
|
||||
|
||||
**Styling Approach:**
|
||||
|
||||
```markdown
|
||||
- Use Tailwind utility classes for styling
|
||||
- Custom styles go in component-level CSS modules
|
||||
- Theme customization is in `tailwind.config.js`
|
||||
```
|
||||
|
||||
### Recommended Rules (Highly Valuable)
|
||||
|
||||
**Component Patterns:**
|
||||
|
||||
```markdown
|
||||
- All components must accept a `className` prop for composition
|
||||
- Variant props should use union types: `variant: 'primary' | 'secondary'`
|
||||
- Icon components should accept `size` and `color` props
|
||||
```
|
||||
|
||||
**Import Conventions:**
|
||||
|
||||
```markdown
|
||||
- Use path aliases: `@/components`, `@/styles`, `@/utils`
|
||||
- Group imports: React, third-party, internal, types
|
||||
- No relative imports beyond parent directory
|
||||
```
|
||||
|
||||
**Code Quality:**
|
||||
|
||||
```markdown
|
||||
- Add JSDoc comments for exported components
|
||||
- Include PropTypes or TypeScript types for all props
|
||||
- Extract magic numbers to named constants
|
||||
```
|
||||
|
||||
### Optional Rules (Project-Specific)
|
||||
|
||||
**Accessibility:**
|
||||
|
||||
```markdown
|
||||
- All interactive elements must have aria-labels
|
||||
- Color contrast must meet WCAG AA standards
|
||||
- Keyboard navigation required for all interactions
|
||||
```
|
||||
|
||||
**Performance:**
|
||||
|
||||
```markdown
|
||||
- Lazy load images with the `Image` component from `@/components/Image`
|
||||
- Use React.memo for components that receive complex props
|
||||
- Icons should be SVG components, not icon fonts
|
||||
```
|
||||
|
||||
**Testing:**
|
||||
|
||||
```markdown
|
||||
- Include unit tests for new components in `__tests__/` directory
|
||||
- Use Testing Library queries (getByRole, getByLabelText)
|
||||
- Test all interactive states and variants
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: React + Tailwind Project
|
||||
|
||||
User says: "Create design system rules for my React project"
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Run `create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="react")`
|
||||
2. Analyze codebase structure
|
||||
3. Generate rules:
|
||||
|
||||
```markdown
|
||||
# Figma MCP Integration Rules
|
||||
|
||||
## Component Organization
|
||||
|
||||
- UI components are in `src/components/ui/`
|
||||
- Page components are in `src/app/`
|
||||
- Use Tailwind for styling
|
||||
|
||||
## Figma Implementation Flow
|
||||
|
||||
1. Run get_design_context for the node
|
||||
2. Run get_screenshot for visual reference
|
||||
3. Map Figma colors to Tailwind colors defined in `tailwind.config.js`
|
||||
4. Reuse components from `src/components/ui/` when possible
|
||||
5. Validate against screenshot before completing
|
||||
|
||||
## Styling Rules
|
||||
|
||||
- IMPORTANT: Use Tailwind utility classes, not inline styles
|
||||
- Colors are defined in `tailwind.config.js` theme.colors
|
||||
- Spacing uses Tailwind's default scale
|
||||
- Custom components go in `src/components/ui/`
|
||||
|
||||
## Asset Rules
|
||||
|
||||
- IMPORTANT: Use localhost sources from Figma MCP server directly
|
||||
- Store static assets in `public/assets/`
|
||||
- DO NOT install new icon libraries
|
||||
```
|
||||
|
||||
4. Save to the appropriate rule file for the user's agent
|
||||
5. Test with a simple button implementation
|
||||
|
||||
**Result:** The agent now consistently follows the project's conventions when implementing Figma designs.
|
||||
|
||||
### Example 2: Vue + Custom CSS Project
|
||||
|
||||
User says: "Set up Figma rules for my Vue app"
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Run `create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="vue")`
|
||||
2. Discover that project uses CSS modules and a custom design token system
|
||||
3. Generate rules:
|
||||
|
||||
```markdown
|
||||
# Figma MCP Integration Rules
|
||||
|
||||
## Component Organization
|
||||
|
||||
- Components are in `src/components/`
|
||||
- Composables are in `src/composables/`
|
||||
- Vue SFC structure: <script setup>, <template>, <style scoped>
|
||||
|
||||
## Design Tokens
|
||||
|
||||
- IMPORTANT: All colors defined in `src/styles/tokens.css` as CSS variables
|
||||
- Use `var(--color-primary)`, `var(--color-secondary)`, etc.
|
||||
- Spacing: `var(--space-xs)` through `var(--space-xl)`
|
||||
- Typography: `var(--text-sm)` through `var(--text-2xl)`
|
||||
|
||||
## Figma Implementation Flow
|
||||
|
||||
1. Run get_design_context and get_screenshot
|
||||
2. Translate React output to Vue 3 Composition API
|
||||
3. Map Figma colors to CSS variables in `src/styles/tokens.css`
|
||||
4. Use CSS Modules for component styles
|
||||
5. Check for existing components in `src/components/` before creating new ones
|
||||
|
||||
## Styling Rules
|
||||
|
||||
- Use CSS Modules (`.module.css` files)
|
||||
- IMPORTANT: Reference design tokens, never hardcode values
|
||||
- Scoped styles with CSS modules
|
||||
```
|
||||
|
||||
4. Save to the appropriate rule file for the user's agent
|
||||
5. Validate with a card component
|
||||
|
||||
**Result:** The agent now correctly translates Figma designs to Vue components using the project's design token system.
|
||||
|
||||
### Example 3: Design System Team
|
||||
|
||||
User says: "Generate rules for our design system library"
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Run `create_design_system_rules(clientLanguages="typescript", clientFrameworks="react")`
|
||||
2. Analyze the monorepo structure with design system package
|
||||
3. Generate comprehensive rules:
|
||||
|
||||
```markdown
|
||||
# Design System Rules
|
||||
|
||||
## Repository Structure
|
||||
|
||||
- Design system components: `packages/design-system/src/components/`
|
||||
- Documentation: `packages/docs/`
|
||||
- Design tokens: `packages/tokens/src/`
|
||||
|
||||
## Component Development
|
||||
|
||||
- IMPORTANT: All components must be in `packages/design-system/src/components/`
|
||||
- Component file structure: `ComponentName/index.tsx`, `ComponentName.stories.tsx`, `ComponentName.test.tsx`
|
||||
- Export all components from `packages/design-system/src/index.ts`
|
||||
|
||||
## Design Tokens
|
||||
|
||||
- Colors: `packages/tokens/src/colors.ts`
|
||||
- Typography: `packages/tokens/src/typography.ts`
|
||||
- Spacing: `packages/tokens/src/spacing.ts`
|
||||
- IMPORTANT: Never hardcode values - import from tokens package
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
- Add Storybook story for every component
|
||||
- Include JSDoc with @example
|
||||
- Document all props with descriptions
|
||||
- Add accessibility notes
|
||||
|
||||
## Figma Integration
|
||||
|
||||
1. Get design context and screenshot from Figma
|
||||
2. Map Figma tokens to design system tokens
|
||||
3. Create or extend component in design system package
|
||||
4. Add Storybook stories showing all variants
|
||||
5. Validate against Figma screenshot
|
||||
6. Update documentation
|
||||
```
|
||||
|
||||
4. Save to the appropriate rule file and share with team
|
||||
5. Add to team documentation
|
||||
|
||||
**Result:** Entire team follows consistent patterns when adding components from Figma to the design system.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Start Simple, Iterate
|
||||
|
||||
Don't try to capture every rule upfront. Start with the most important conventions and add rules as you encounter inconsistencies.
|
||||
|
||||
### Be Specific
|
||||
|
||||
Instead of: "Use the design system"
|
||||
Write: "Always use Button components from `src/components/ui/Button.tsx` with variant prop ('primary' | 'secondary' | 'ghost')"
|
||||
|
||||
### Make Rules Actionable
|
||||
|
||||
Each rule should tell the agent exactly what to do, not just what to avoid.
|
||||
|
||||
Good: "Colors are defined in `src/theme/colors.ts` - import and use these constants"
|
||||
Bad: "Don't hardcode colors"
|
||||
|
||||
### Use IMPORTANT for Critical Rules
|
||||
|
||||
Prefix rules that must never be violated with "IMPORTANT:" to ensure the agent prioritizes them.
|
||||
|
||||
```markdown
|
||||
- IMPORTANT: Never expose API keys in client-side code
|
||||
- IMPORTANT: Always sanitize user input before rendering
|
||||
```
|
||||
|
||||
### Document the Why
|
||||
|
||||
When rules seem arbitrary, explain the reasoning:
|
||||
|
||||
```markdown
|
||||
- Place all data-fetching in server components (reduces client bundle size and improves performance)
|
||||
- Use absolute imports with `@/` alias (makes refactoring easier and prevents broken relative paths)
|
||||
```
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Issue: The agent isn't following the rules
|
||||
|
||||
**Cause:** Rules may be too vague or not properly loaded by the agent.
|
||||
**Solution:**
|
||||
|
||||
- Make rules more specific and actionable
|
||||
- Verify rules are saved in the correct configuration file
|
||||
- Restart your agent or IDE to reload rules
|
||||
- Add "IMPORTANT:" prefix to critical rules
|
||||
|
||||
### Issue: Rules conflict with each other
|
||||
|
||||
**Cause:** Contradictory or overlapping rules.
|
||||
**Solution:**
|
||||
|
||||
- Review all rules for conflicts
|
||||
- Establish a clear priority hierarchy
|
||||
- Remove redundant rules
|
||||
- Consolidate related rules into single, clear statements
|
||||
|
||||
### Issue: Too many rules increase latency
|
||||
|
||||
**Cause:** Excessive rules increase context size and processing time.
|
||||
**Solution:**
|
||||
|
||||
- Focus on the 20% of rules that solve 80% of consistency issues
|
||||
- Remove overly specific rules that rarely apply
|
||||
- Combine related rules
|
||||
- Use progressive disclosure (basic rules first, advanced rules in linked files)
|
||||
|
||||
### Issue: Rules become outdated as project evolves
|
||||
|
||||
**Cause:** Codebase changes but rules don't.
|
||||
**Solution:**
|
||||
|
||||
- Schedule periodic rule reviews (monthly or quarterly)
|
||||
- Update rules when architectural decisions change
|
||||
- Version control your rule files
|
||||
- Document rule changes in commit messages
|
||||
|
||||
## Understanding Design System Rules
|
||||
|
||||
Design system rules transform how AI coding agents work with your Figma designs:
|
||||
|
||||
**Before rules:**
|
||||
|
||||
- The agent makes assumptions about component structure
|
||||
- Inconsistent styling approaches across implementations
|
||||
- Hardcoded values that don't match design tokens
|
||||
- Components created in random locations
|
||||
- Repetitive explanations of project conventions
|
||||
|
||||
**After rules:**
|
||||
|
||||
- The agent automatically follows your conventions
|
||||
- Consistent component structure and styling
|
||||
- Proper use of design tokens from the start
|
||||
- Components organized correctly
|
||||
- Zero repetitive prompting
|
||||
|
||||
The time invested in creating good rules pays off exponentially across every Figma implementation task.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server/)
|
||||
- [Figma Variables and Design Tokens](https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma)
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
name: figma-create-new-file
|
||||
description: Create a new blank Figma file. Use when the user wants to create a new Figma design or FigJam file, or when you need a new file before calling use_figma. Handles plan resolution via whoami if needed. Usage — /figma-create-new-file [editorType] [fileName] (e.g. /figma-create-new-file figjam My Whiteboard)
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# create_new_file — Create a New Figma File
|
||||
|
||||
Use the `create_new_file` MCP tool to create a new blank Figma file in the user's drafts folder. This is typically used before `use_figma` when you need a fresh file to work with.
|
||||
|
||||
## Skill Arguments
|
||||
|
||||
This skill accepts optional arguments: `/figma-create-new-file [editorType] [fileName]`
|
||||
|
||||
- **editorType**: `design` (default) or `figjam`
|
||||
- **fileName**: Name for the new file (defaults to "Untitled")
|
||||
|
||||
Examples:
|
||||
- `/figma-create-new-file` — creates a design file named "Untitled"
|
||||
- `/figma-create-new-file figjam My Whiteboard` — creates a FigJam file named "My Whiteboard"
|
||||
- `/figma-create-new-file design My New Design` — creates a design file named "My New Design"
|
||||
|
||||
Parse the arguments from the skill invocation. If editorType is not provided, default to `"design"`. If fileName is not provided, default to `"Untitled"`.
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Resolve the planKey
|
||||
|
||||
The `create_new_file` tool requires a `planKey` parameter. Follow this decision tree:
|
||||
|
||||
1. **User already provided a planKey** (e.g. from a previous `whoami` call or in their prompt) → use it directly, skip to Step 2.
|
||||
|
||||
2. **No planKey available** → call the `whoami` tool. The response contains a `plans` array. Each plan has a `key`, `name`, `seat`, and `tier`.
|
||||
|
||||
- **Single plan**: use its `key` field automatically.
|
||||
- **Multiple plans**: ask the user which team or organization they want to create the file in, then use the corresponding plan's `key`.
|
||||
|
||||
### Step 2: Call create_new_file
|
||||
|
||||
Call the `create_new_file` tool with:
|
||||
|
||||
| Parameter | Required | Description |
|
||||
|-------------|----------|-------------|
|
||||
| `planKey` | Yes | The plan key from Step 1 |
|
||||
| `fileName` | Yes | Name for the new file |
|
||||
| `editorType`| Yes | `"design"` or `"figjam"` |
|
||||
|
||||
Example:
|
||||
```json
|
||||
{
|
||||
"planKey": "team:123456",
|
||||
"fileName": "My New Design",
|
||||
"editorType": "design"
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Use the result
|
||||
|
||||
The tool returns:
|
||||
- `file_key` — the key of the newly created file
|
||||
- `file_url` — a direct URL to open the file in Figma
|
||||
|
||||
Use the `file_key` for subsequent tool calls like `use_figma`.
|
||||
|
||||
## Important Notes
|
||||
|
||||
- The file is created in the user's **drafts folder** for the selected plan.
|
||||
- Only `"design"` and `"figjam"` editor types are supported.
|
||||
- If `use_figma` is your next step, load the `figma-use` skill before calling it.
|
||||
@@ -0,0 +1,341 @@
|
||||
---
|
||||
name: figma-generate-design
|
||||
description: "Use this skill alongside figma-use when the task involves translating an application page, view, or multi-section layout into Figma. Triggers: 'write to Figma', 'create in Figma from code', 'push page to Figma', 'take this app/page and build it in Figma', 'create a screen', 'build a landing page in Figma', 'update the Figma screen to match code'. This is the preferred workflow skill whenever the user wants to build or update a full page, screen, or view in Figma from code or a description. Discovers design system components, variables, and styles via search_design_system, imports them, and assembles screens incrementally section-by-section using design system tokens instead of hardcoded values."
|
||||
---
|
||||
|
||||
# Build / Update Screens from Design System
|
||||
|
||||
Use this skill to create or update full-page screens in Figma by **reusing the published design system** — components, variables, and styles — rather than drawing primitives with hardcoded values. The key insight: the Figma file likely has a published design system with components, color/spacing variables, and text/effect styles that correspond to the codebase's UI components and tokens. Find and use those instead of drawing boxes with hex colors.
|
||||
|
||||
**MANDATORY**: You MUST also load [figma-use](../figma-use/SKILL.md) before any `use_figma` call. That skill contains critical rules (color ranges, font loading, etc.) that apply to every script you write.
|
||||
|
||||
**Always pass `skillNames: "figma-generate-design"` when calling `use_figma` as part of this skill.** This is a logging parameter — it does not affect execution.
|
||||
|
||||
## Skill Boundaries
|
||||
|
||||
- Use this skill when the deliverable is a **Figma screen** (new or updated) composed of design system component instances.
|
||||
- If the user wants to generate **code from a Figma design**, switch to [figma-implement-design](../figma-implement-design/SKILL.md).
|
||||
- If the user wants to create **new reusable components or variants**, use [figma-use](../figma-use/SKILL.md) directly.
|
||||
- If the user wants to write **Code Connect mappings**, switch to [figma-code-connect-components](../figma-code-connect-components/SKILL.md).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Figma MCP server must be connected
|
||||
- The target Figma file must have a published design system with components (or access to a team library)
|
||||
- User should provide either:
|
||||
- A Figma file URL / file key to work in
|
||||
- Or context about which file to target (the agent can discover pages)
|
||||
- Source code or description of the screen to build/update
|
||||
|
||||
## Parallel Workflow with generate_figma_design (Web Apps Only)
|
||||
|
||||
When building a screen from a **web app** that can be rendered in a browser, the best results come from running both approaches in parallel:
|
||||
|
||||
1. **In parallel:**
|
||||
- Start building the screen using this skill's workflow (use_figma + design system components)
|
||||
- Run `generate_figma_design` to capture a pixel-perfect screenshot of the running web app
|
||||
2. **Once both complete:** Update the use_figma output to match the pixel-perfect layout from the `generate_figma_design` capture. The capture provides the exact spacing, sizing, and visual treatment to aim for, while your use_figma output has proper component instances linked to the design system.
|
||||
3. **Once confirmed looking good:** Delete the `generate_figma_design` output — it was only used as a visual reference.
|
||||
|
||||
This combines the best of both: `generate_figma_design` gives pixel-perfect layout accuracy, while use_figma gives proper design system component instances that stay linked and updatable.
|
||||
|
||||
**This workflow only applies to web apps** where `generate_figma_design` can capture the running page. For non-web apps (iOS, Android, etc.) or when updating existing screens, use the standard workflow below.
|
||||
|
||||
## Required Workflow
|
||||
|
||||
**Follow these steps in order. Do not skip steps.**
|
||||
|
||||
### Step 1: Understand the Screen
|
||||
|
||||
Before touching Figma, understand what you're building:
|
||||
|
||||
1. If building from code, read the relevant source files to understand the page structure, sections, and which components are used.
|
||||
2. Identify the major sections of the screen (e.g., Header, Hero, Content Panels, Pricing Grid, FAQ Accordion, Footer).
|
||||
3. For each section, list the UI components involved (buttons, inputs, cards, navigation pills, accordions, etc.).
|
||||
|
||||
### Step 2: Discover Design System — Components, Variables, and Styles
|
||||
|
||||
You need three things from the design system: **components** (buttons, cards, etc.), **variables** (colors, spacing, radii), and **styles** (text styles, effect styles like shadows). Don't hardcode hex colors or pixel values when design system tokens exist.
|
||||
|
||||
#### 2a: Discover components
|
||||
|
||||
**Preferred: inspect existing screens first.** If the target file already contains screens using the same design system, skip `search_design_system` and inspect existing instances directly. A single `use_figma` call that walks an existing frame's instances gives you an exact, authoritative component map:
|
||||
|
||||
```js
|
||||
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
|
||||
const uniqueSets = new Map();
|
||||
frame.findAll(n => n.type === "INSTANCE").forEach(inst => {
|
||||
const mc = inst.mainComponent;
|
||||
const cs = mc?.parent?.type === "COMPONENT_SET" ? mc.parent : null;
|
||||
const key = cs ? cs.key : mc?.key;
|
||||
const name = cs ? cs.name : mc?.name;
|
||||
if (key && !uniqueSets.has(key)) {
|
||||
uniqueSets.set(key, { name, key, isSet: !!cs, sampleVariant: mc.name });
|
||||
}
|
||||
});
|
||||
return [...uniqueSets.values()];
|
||||
```
|
||||
|
||||
Only fall back to `search_design_system` when the file has no existing screens to reference. When using it, **search broadly** — try multiple terms and synonyms (e.g., "button", "input", "nav", "card", "accordion", "header", "footer", "tag", "avatar", "toggle", "icon", etc.). Use `includeComponents: true` to focus on components.
|
||||
|
||||
**Include component properties** in your map — you need to know which TEXT properties each component exposes for text overrides. Create a temporary instance, read its `componentProperties` (and those of nested instances), then remove the temp instance.
|
||||
|
||||
Example component map with property info:
|
||||
|
||||
```
|
||||
Component Map:
|
||||
- Button → key: "abc123", type: COMPONENT_SET
|
||||
Properties: { "Label#2:0": TEXT, "Has Icon#4:64": BOOLEAN }
|
||||
- PricingCard → key: "ghi789", type: COMPONENT_SET
|
||||
Properties: { "Device": VARIANT, "Variant": VARIANT }
|
||||
Nested "Text Heading" has: { "Text#2104:5": TEXT }
|
||||
Nested "Button" has: { "Label#2:0": TEXT }
|
||||
```
|
||||
|
||||
#### 2b: Discover variables (colors, spacing, radii)
|
||||
|
||||
**Inspect existing screens first** (same as components). Or use `search_design_system` with `includeVariables: true`.
|
||||
|
||||
> **WARNING: Two different variable discovery methods — do not confuse them.**
|
||||
>
|
||||
> - `use_figma` with `figma.variables.getLocalVariableCollectionsAsync()` — returns **only local variables defined in the current file**. If this returns empty, it does **not** mean no variables exist. Remote/published library variables are invisible to this API.
|
||||
> - `search_design_system` with `includeVariables: true` — searches across **all linked libraries**, including remote and published ones. This is the correct tool for discovering design system variables.
|
||||
>
|
||||
> **Never conclude "no variables exist" based solely on `getLocalVariableCollectionsAsync()` returning empty.** Always also run `search_design_system` with `includeVariables: true` to check for library variables before deciding to create your own.
|
||||
|
||||
**Query strategy:** `search_design_system` matches against **variable names** (e.g., "Gray/gray-9", "core/gray/100", "space/400"), not categories. Run multiple short, simple queries in parallel rather than one compound query:
|
||||
|
||||
- **Primitive colors:** "gray", "red", "blue", "green", "white", "brand"
|
||||
- **Semantic colors:** "background", "foreground", "border", "surface", "text"
|
||||
- **Spacing/sizing:** "space", "radius", "gap", "padding"
|
||||
|
||||
If initial searches return empty, try shorter fragments or different naming conventions — libraries vary widely ("grey" vs "gray", "spacing" vs "space", "color/bg" vs "background").
|
||||
|
||||
Inspect an existing screen's bound variables for the most authoritative results:
|
||||
|
||||
```js
|
||||
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
|
||||
const varMap = new Map();
|
||||
frame.findAll(() => true).forEach(node => {
|
||||
const bv = node.boundVariables;
|
||||
if (!bv) return;
|
||||
for (const [prop, binding] of Object.entries(bv)) {
|
||||
const bindings = Array.isArray(binding) ? binding : [binding];
|
||||
for (const b of bindings) {
|
||||
if (b?.id && !varMap.has(b.id)) {
|
||||
const v = await figma.variables.getVariableByIdAsync(b.id);
|
||||
if (v) varMap.set(b.id, { name: v.name, id: v.id, key: v.key, type: v.resolvedType, remote: v.remote });
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
return [...varMap.values()];
|
||||
```
|
||||
|
||||
For library variables (remote = true), import them by key with `figma.variables.importVariableByKeyAsync(key)`. For local variables, use `figma.variables.getVariableByIdAsync(id)` directly.
|
||||
|
||||
See [variable-patterns.md](../figma-use/references/variable-patterns.md) for binding patterns.
|
||||
|
||||
#### 2c: Discover styles (text styles, effect styles)
|
||||
|
||||
Search for styles using `search_design_system` with `includeStyles: true` and terms like "heading", "body", "shadow", "elevation". Or inspect what an existing screen uses:
|
||||
|
||||
```js
|
||||
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
|
||||
const styles = { text: new Map(), effect: new Map() };
|
||||
frame.findAll(() => true).forEach(node => {
|
||||
if ('textStyleId' in node && node.textStyleId) {
|
||||
const s = figma.getStyleById(node.textStyleId);
|
||||
if (s) styles.text.set(s.id, { name: s.name, id: s.id, key: s.key });
|
||||
}
|
||||
if ('effectStyleId' in node && node.effectStyleId) {
|
||||
const s = figma.getStyleById(node.effectStyleId);
|
||||
if (s) styles.effect.set(s.id, { name: s.name, id: s.id, key: s.key });
|
||||
}
|
||||
});
|
||||
return {
|
||||
textStyles: [...styles.text.values()],
|
||||
effectStyles: [...styles.effect.values()]
|
||||
};
|
||||
```
|
||||
|
||||
Import library styles with `figma.importStyleByKeyAsync(key)`, then apply with `node.textStyleId = style.id` or `node.effectStyleId = style.id`.
|
||||
|
||||
See [text-style-patterns.md](../figma-use/references/text-style-patterns.md) and [effect-style-patterns.md](../figma-use/references/effect-style-patterns.md) for details.
|
||||
|
||||
### Step 3: Create the Page Wrapper Frame First
|
||||
|
||||
**Do NOT build sections as top-level page children and reparent them later** — moving nodes across `use_figma` calls with `appendChild()` silently fails and produces orphaned frames. Instead, create the wrapper first, then build each section directly inside it.
|
||||
|
||||
Create the page wrapper in its own `use_figma` call. Position it away from existing content and return its ID:
|
||||
|
||||
```js
|
||||
// Find clear space
|
||||
let maxX = 0;
|
||||
for (const child of figma.currentPage.children) {
|
||||
maxX = Math.max(maxX, child.x + child.width);
|
||||
}
|
||||
|
||||
const wrapper = figma.createFrame();
|
||||
wrapper.name = "Homepage";
|
||||
wrapper.layoutMode = "VERTICAL";
|
||||
wrapper.primaryAxisAlignItems = "CENTER";
|
||||
wrapper.counterAxisAlignItems = "CENTER";
|
||||
wrapper.resize(1440, 100);
|
||||
wrapper.layoutSizingHorizontal = "FIXED";
|
||||
wrapper.layoutSizingVertical = "HUG";
|
||||
wrapper.x = maxX + 200;
|
||||
wrapper.y = 0;
|
||||
|
||||
return { success: true, wrapperId: wrapper.id };
|
||||
```
|
||||
|
||||
### Step 4: Build Each Section Inside the Wrapper
|
||||
|
||||
**This is the most important step.** Build one section at a time, each in its own `use_figma` call. At the start of each script, fetch the wrapper by ID and append new content directly to it.
|
||||
|
||||
```js
|
||||
const createdNodeIds = [];
|
||||
const wrapper = await figma.getNodeByIdAsync("WRAPPER_ID_FROM_STEP_3");
|
||||
|
||||
// Import design system components by key
|
||||
const buttonSet = await figma.importComponentSetByKeyAsync("BUTTON_SET_KEY");
|
||||
const primaryButton = buttonSet.children.find(c =>
|
||||
c.type === "COMPONENT" && c.name.includes("variant=primary")
|
||||
) || buttonSet.defaultVariant;
|
||||
|
||||
// Import design system variables for colors and spacing
|
||||
const bgColorVar = await figma.variables.importVariableByKeyAsync("BG_COLOR_VAR_KEY");
|
||||
const spacingVar = await figma.variables.importVariableByKeyAsync("SPACING_VAR_KEY");
|
||||
|
||||
// Build section frame with variable bindings (not hardcoded values)
|
||||
const section = figma.createFrame();
|
||||
section.name = "Header";
|
||||
section.layoutMode = "HORIZONTAL";
|
||||
section.setBoundVariable("paddingLeft", spacingVar);
|
||||
section.setBoundVariable("paddingRight", spacingVar);
|
||||
const bgPaint = figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', bgColorVar
|
||||
);
|
||||
section.fills = [bgPaint];
|
||||
|
||||
// Import and apply text/effect styles
|
||||
const shadowStyle = await figma.importStyleByKeyAsync("SHADOW_STYLE_KEY");
|
||||
section.effectStyleId = shadowStyle.id;
|
||||
|
||||
// Create component instances inside the section
|
||||
const btnInstance = primaryButton.createInstance();
|
||||
section.appendChild(btnInstance);
|
||||
createdNodeIds.push(btnInstance.id);
|
||||
|
||||
// Append section to wrapper
|
||||
wrapper.appendChild(section);
|
||||
section.layoutSizingHorizontal = "FILL"; // AFTER appending
|
||||
|
||||
createdNodeIds.push(section.id);
|
||||
return { success: true, createdNodeIds };
|
||||
```
|
||||
|
||||
After each section, validate with `get_screenshot` before moving on. Look closely for cropped/clipped text (line heights cutting off content) and overlapping elements — these are the most common issues and easy to miss at a glance.
|
||||
|
||||
#### Override instance text with setProperties()
|
||||
|
||||
Component instances ship with placeholder text ("Title", "Heading", "Button"). Use the component property keys you discovered in Step 2 to override them with `setProperties()` — this is more reliable than direct `node.characters` manipulation. See [component-patterns.md](../figma-use/references/component-patterns.md#overriding-text-in-a-component-instance) for the full pattern.
|
||||
|
||||
For nested instances that expose their own TEXT properties, call `setProperties()` on the nested instance:
|
||||
|
||||
```js
|
||||
const nestedHeading = cardInstance.findOne(n => n.type === "INSTANCE" && n.name === "Text Heading");
|
||||
if (nestedHeading) {
|
||||
nestedHeading.setProperties({ "Text#2104:5": "Actual heading from source code" });
|
||||
}
|
||||
```
|
||||
|
||||
Only fall back to direct `node.characters` for text that is NOT managed by any component property.
|
||||
|
||||
#### Read source code defaults carefully
|
||||
|
||||
When translating code components to Figma instances, check the component's default prop values in the source code, not just what's explicitly passed. For example, `<Button size="small">Register</Button>` with no variant prop — check the component definition to find `variant = "primary"` as the default. Selecting the wrong variant (e.g., Neutral instead of Primary) produces a visually incorrect result that's easy to miss.
|
||||
|
||||
#### What to build manually vs. import from design system
|
||||
|
||||
| Build manually | Import from design system |
|
||||
|----------------|--------------------------|
|
||||
| Page wrapper frame | **Components**: buttons, cards, inputs, nav, etc. |
|
||||
| Section container frames | **Variables**: colors (fills, strokes), spacing (padding, gap), radii |
|
||||
| Layout grids (rows, columns) | **Text styles**: heading, body, caption, etc. |
|
||||
| | **Effect styles**: shadows, blurs, etc. |
|
||||
|
||||
**Never hardcode hex colors or pixel spacing** when a design system variable exists. Use `setBoundVariable` for spacing/radii and `setBoundVariableForPaint` for colors. Apply text styles with `node.textStyleId` and effect styles with `node.effectStyleId`.
|
||||
|
||||
### Step 5: Validate the Full Screen
|
||||
|
||||
After composing all sections, call `get_screenshot` on the full page frame and compare against the source. Fix any issues with targeted `use_figma` calls — don't rebuild the entire screen.
|
||||
|
||||
**Screenshot individual sections, not just the full page.** A full-page screenshot at reduced resolution hides text truncation, wrong colors, and placeholder text that hasn't been overridden. Take a screenshot of each section by node ID to catch:
|
||||
- **Cropped/clipped text** — line heights or frame sizing cutting off descenders, ascenders, or entire lines
|
||||
- **Overlapping content** — elements stacking on top of each other due to incorrect sizing or missing auto-layout
|
||||
- Placeholder text still showing ("Title", "Heading", "Button")
|
||||
- Truncated content from layout sizing bugs
|
||||
- Wrong component variants (e.g., Neutral vs Primary button)
|
||||
|
||||
### Step 6: Updating an Existing Screen
|
||||
|
||||
When updating rather than creating from scratch:
|
||||
|
||||
1. Use `get_metadata` to inspect the existing screen structure.
|
||||
2. Identify which sections need updating and which can stay.
|
||||
3. For each section that needs changes:
|
||||
- Locate the existing nodes by ID or name
|
||||
- Swap component instances if the design system component changed
|
||||
- Update text content, variant properties, or layout as needed
|
||||
- Remove deprecated sections
|
||||
- Add new sections
|
||||
4. Validate with `get_screenshot` after each modification.
|
||||
|
||||
```js
|
||||
// Example: Swap a button variant in an existing screen
|
||||
const existingButton = await figma.getNodeByIdAsync("EXISTING_BUTTON_INSTANCE_ID");
|
||||
if (existingButton && existingButton.type === "INSTANCE") {
|
||||
// Import the updated component
|
||||
const buttonSet = await figma.importComponentSetByKeyAsync("BUTTON_SET_KEY");
|
||||
const newVariant = buttonSet.children.find(c =>
|
||||
c.name.includes("variant=primary") && c.name.includes("size=lg")
|
||||
) || buttonSet.defaultVariant;
|
||||
existingButton.swapComponent(newVariant);
|
||||
}
|
||||
return { success: true, mutatedNodeIds: [existingButton.id] };
|
||||
```
|
||||
|
||||
## Reference Docs
|
||||
|
||||
For detailed API patterns and gotchas, load these from the [figma-use](../figma-use/SKILL.md) references as needed:
|
||||
|
||||
- [component-patterns.md](../figma-use/references/component-patterns.md) — importing by key, finding variants, setProperties, text overrides, working with instances
|
||||
- [variable-patterns.md](../figma-use/references/variable-patterns.md) — creating/binding variables, importing library variables, scopes, aliasing, discovering existing variables
|
||||
- [text-style-patterns.md](../figma-use/references/text-style-patterns.md) — creating/applying text styles, importing library text styles, type ramps
|
||||
- [effect-style-patterns.md](../figma-use/references/effect-style-patterns.md) — creating/applying effect styles (shadows), importing library effect styles
|
||||
- [gotchas.md](../figma-use/references/gotchas.md) — layout pitfalls (HUG/FILL interactions, counterAxisAlignItems, sizing order), paint/color issues, page context resets
|
||||
|
||||
## Error Recovery
|
||||
|
||||
Follow the error recovery process from [figma-use](../figma-use/SKILL.md#6-error-recovery--self-correction):
|
||||
|
||||
1. **STOP** on error — do not retry immediately.
|
||||
2. **Read the error message carefully** to understand what went wrong.
|
||||
3. If the error is unclear, call `get_metadata` or `get_screenshot` to inspect the current file state.
|
||||
4. **Fix the script** based on the error message.
|
||||
5. **Retry** the corrected script — this is safe because failed scripts are atomic (nothing is created if a script errors).
|
||||
|
||||
Because this skill works incrementally (one section per call), errors are naturally scoped to a single section. Previous sections from successful calls remain intact.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Always search before building.** The design system likely has the component, variable, or style you need. Manual construction and hardcoded values should be the exception, not the rule.
|
||||
- **Search broadly.** Try synonyms and partial terms. A "NavigationPill" might be found under "pill", "nav", "tab", or "chip". For variables, search "color", "spacing", "radius", etc.
|
||||
- **Prefer design system tokens over hardcoded values.** Use variable bindings for colors, spacing, and radii. Use text styles for typography. Use effect styles for shadows. This keeps the screen linked to the design system.
|
||||
- **Prefer component instances over manual builds.** Instances stay linked to the source component and update automatically when the design system evolves.
|
||||
- **Work section by section.** Never build more than one major section per `use_figma` call.
|
||||
- **Return node IDs from every call.** You'll need them to compose sections and for error recovery.
|
||||
- **Validate visually after each section.** Use `get_screenshot` to catch issues early.
|
||||
- **Match existing conventions.** If the file already has screens, match their naming, sizing, and layout patterns.
|
||||
@@ -0,0 +1,315 @@
|
||||
---
|
||||
name: figma-generate-library
|
||||
description: "Build or update a professional-grade design system in Figma from a codebase. Use when the user wants to create variables/tokens, build component libraries, set up theming (light/dark modes), document foundations, or reconcile gaps between code and Figma. This skill teaches WHAT to build and in WHAT ORDER — it complements the `figma-use` skill which teaches HOW to call the Plugin API. Both skills should be loaded together."
|
||||
disable-model-invocation: false
|
||||
---
|
||||
|
||||
# Design System Builder — Figma MCP Skill
|
||||
|
||||
Build professional-grade design systems in Figma that match code. This skill orchestrates multi-phase workflows across 20–100+ `use_figma` calls, enforcing quality patterns from real-world design systems (Material 3, Polaris, Figma UI3, Simple DS).
|
||||
|
||||
**Prerequisites**: The `figma-use` skill MUST also be loaded for every `use_figma` call. It provides Plugin API syntax rules (return pattern, page reset, ID return, font loading, color range). This skill provides design system domain knowledge and workflow orchestration.
|
||||
|
||||
**Always pass `skillNames: "figma-generate-library"` when calling `use_figma` as part of this skill.** This is a logging parameter — it does not affect execution.
|
||||
|
||||
---
|
||||
|
||||
## 1. The One Rule That Matters Most
|
||||
|
||||
**This is NEVER a one-shot task.** Building a design system requires 20–100+ `use_figma` calls across multiple phases, with mandatory user checkpoints between them. Any attempt to create everything in one call WILL produce broken, incomplete, or unrecoverable results. Break every operation to the smallest useful unit, validate, get feedback, proceed.
|
||||
|
||||
---
|
||||
|
||||
## 2. Mandatory Workflow
|
||||
|
||||
Every design system build follows this phase order. Skipping or reordering phases causes structural failures that are expensive to undo.
|
||||
|
||||
```
|
||||
Phase 0: DISCOVERY (always first — no use_figma writes yet)
|
||||
0a. Analyze codebase → extract tokens, components, naming conventions
|
||||
0b. Inspect Figma file → pages, variables, components, styles, existing conventions
|
||||
0c. Search subscribed libraries → use search_design_system for reusable assets
|
||||
0d. Lock v1 scope → agree on exact token set + component list before any creation
|
||||
0e. Map code → Figma → resolve conflicts (code and Figma disagree = ask user)
|
||||
✋ USER CHECKPOINT: present full plan, await explicit approval
|
||||
|
||||
Phase 1: FOUNDATIONS (tokens first — always before components)
|
||||
1a. Create variable collections and modes
|
||||
1b. Create primitive variables (raw values, 1 mode)
|
||||
1c. Create semantic variables (aliased to primitives, mode-aware)
|
||||
1d. Set scopes on ALL variables
|
||||
1e. Set code syntax on ALL variables
|
||||
1f. Create effect styles (shadows) and text styles (typography)
|
||||
→ Exit criteria: every token from the agreed plan exists, all scopes set, all code syntax set
|
||||
✋ USER CHECKPOINT: show variable summary, await approval
|
||||
|
||||
Phase 2: FILE STRUCTURE (before components)
|
||||
2a. Create page skeleton: Cover → Getting Started → Foundations → --- → Components → --- → Utilities
|
||||
2b. Create foundations documentation pages (color swatches, type specimens, spacing bars)
|
||||
→ Exit criteria: all planned pages exist, foundations docs are navigable
|
||||
✋ USER CHECKPOINT: show page list + screenshot, await approval
|
||||
|
||||
Phase 3: COMPONENTS (one at a time — never batch)
|
||||
For EACH component (in dependency order: atoms before molecules):
|
||||
3a. Create dedicated page
|
||||
3b. Build base component with auto-layout + full variable bindings
|
||||
3c. Create all variant combinations (combineAsVariants + grid layout)
|
||||
3d. Add component properties (TEXT, BOOLEAN, INSTANCE_SWAP)
|
||||
3e. Link properties to child nodes
|
||||
3f. Add page documentation (title, description, usage notes)
|
||||
3g. Validate: get_metadata (structure) + get_screenshot (visual)
|
||||
3h. Optional: lightweight Code Connect mapping while context is fresh
|
||||
→ Exit criteria: variant count correct, all bindings verified, screenshot looks right
|
||||
✋ USER CHECKPOINT per component: show screenshot, await approval before next component
|
||||
|
||||
Phase 4: INTEGRATION + QA (final pass)
|
||||
4a. Finalize all Code Connect mappings
|
||||
4b. Accessibility audit (contrast, min touch targets, focus visibility)
|
||||
4c. Naming audit (no duplicates, no unnamed nodes, consistent casing)
|
||||
4d. Unresolved bindings audit (no hardcoded fills/strokes remaining)
|
||||
4e. Final review screenshots of every page
|
||||
✋ USER CHECKPOINT: complete sign-off
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Critical Rules
|
||||
|
||||
**Plugin API basics** (from use_figma skill — enforced here too):
|
||||
- Use `return` to send data back (auto-serialized). Do NOT wrap in IIFE or call closePlugin.
|
||||
- Return ALL created/mutated node IDs in every return value
|
||||
- Page context resets each call — always `await figma.setCurrentPageAsync(page)` at start
|
||||
- `figma.notify()` throws — never use it
|
||||
- Colors are 0–1 range, not 0–255
|
||||
- Font MUST be loaded before any text write: `await figma.loadFontAsync({family, style})`
|
||||
|
||||
**Design system rules**:
|
||||
1. **Variables BEFORE components** — components bind to variables. No token = no component.
|
||||
2. **Inspect before creating** — run read-only `use_figma` to discover existing conventions. Match them.
|
||||
3. **One page per component** *(default)* — exception: tightly related families (e.g., Input + helpers) may share a page with clear section separation.
|
||||
4. **Bind visual properties to variables** *(default)* — fills, strokes, padding, radius, gap. Exceptions: intentionally fixed geometry (icon pixel-grid sizes, static dividers).
|
||||
5. **Scopes on every variable** — NEVER leave as `ALL_SCOPES`. Background: `FRAME_FILL, SHAPE_FILL`. Text: `TEXT_FILL`. Border: `STROKE_COLOR`. Spacing: `GAP`. Radii: `CORNER_RADIUS`. Primitives: `[]` (hidden).
|
||||
6. **Code syntax on every variable** — WEB syntax MUST use the `var()` wrapper: `var(--color-bg-primary)`, not `--color-bg-primary`. Use the actual CSS variable name from the codebase. ANDROID/iOS do NOT use a wrapper.
|
||||
7. **Alias semantics to primitives** — `{ type: 'VARIABLE_ALIAS', id: primitiveVar.id }`. Never duplicate raw values in semantic layer.
|
||||
8. **Position variants after combineAsVariants** — they stack at (0,0). Manually grid-layout + resize.
|
||||
9. **INSTANCE_SWAP for icons** — never create a variant per icon. Cap variant matrices: if Size × Style × State > 30 combinations, split into sub-component.
|
||||
10. **Deterministic naming** — use consistent, unique node names for idempotent cleanup and resumability. Track created node IDs via return values and the state ledger.
|
||||
11. **No destructive cleanup** — cleanup scripts identify nodes by name convention or returned IDs, not by guessing.
|
||||
12. **Validate before proceeding** — never build on unvalidated work. `get_metadata` after every create, `get_screenshot` after each component.
|
||||
13. **NEVER parallelize `use_figma` calls** — Figma state mutations must be strictly sequential. Even if your tool supports parallel calls, never run two use_figma calls simultaneously.
|
||||
14. **Never hallucinate Node IDs** — always read IDs from the state ledger returned by previous calls. Never reconstruct or guess an ID from memory.
|
||||
15. **Use the helper scripts** — embed scripts from `scripts/` into your use_figma calls. Don't write 200-line inline scripts from scratch.
|
||||
16. **Explicit phase approval** — at each checkpoint, name the next phase explicitly. "looks good" is not approval to proceed to Phase 3 if you asked about Phase 1.
|
||||
|
||||
---
|
||||
|
||||
## 4. State Management (Required for Long Workflows)
|
||||
|
||||
> **`getPluginData()` / `setPluginData()` are NOT supported in `use_figma`.** Use `getSharedPluginData()` / `setSharedPluginData()` instead (these ARE supported), or use name-based lookups and the state ledger (returned IDs).
|
||||
|
||||
| Entity type | Idempotency key | How to check existence |
|
||||
|-------------|----------------|----------------------|
|
||||
| Scene nodes (pages, frames, components) | `setSharedPluginData('dsb', 'key', value)` or unique name | `node.getSharedPluginData('dsb', 'key')` or `page.findOne(n => n.name === 'Button')` |
|
||||
| Variables | Name within collection | `(await figma.variables.getLocalVariablesAsync()).find(v => v.name === name && v.variableCollectionId === collId)` |
|
||||
| Styles | Name | `getLocalTextStyles().find(s => s.name === name)` |
|
||||
|
||||
Tag every created **scene node** immediately after creation:
|
||||
```javascript
|
||||
node.setSharedPluginData('dsb', 'run_id', RUN_ID); // identifies this build run
|
||||
node.setSharedPluginData('dsb', 'phase', 'phase3'); // which phase created it
|
||||
node.setSharedPluginData('dsb', 'key', 'component/button');// unique logical key
|
||||
```
|
||||
|
||||
**State persistence**: Do NOT rely solely on conversation context for the state ledger. Write it to disk:
|
||||
```
|
||||
/tmp/dsb-state-{RUN_ID}.json
|
||||
```
|
||||
Re-read this file at the start of every turn. In long workflows, conversation context will be truncated — the file is the source of truth.
|
||||
|
||||
Maintain a state ledger tracking:
|
||||
```json
|
||||
{
|
||||
"runId": "ds-build-2024-001",
|
||||
"phase": "phase3",
|
||||
"step": "component-button",
|
||||
"entities": {
|
||||
"collections": { "primitives": "id:...", "color": "id:..." },
|
||||
"variables": { "color/bg/primary": "id:...", "spacing/sm": "id:..." },
|
||||
"pages": { "Cover": "id:...", "Button": "id:..." },
|
||||
"components": { "Button": "id:..." }
|
||||
},
|
||||
"pendingValidations": ["Button:screenshot"],
|
||||
"completedSteps": ["phase0", "phase1", "phase2", "component-avatar"]
|
||||
}
|
||||
```
|
||||
|
||||
**Idempotency check** before every create: query by name + state ledger ID. If exists, skip or update — never duplicate.
|
||||
|
||||
**Resume protocol**: at session start or after context truncation, run a read-only `use_figma` to scan all pages, components, variables, and styles by name to reconstruct the `{key → id}` map. Then re-read the state file from disk if available.
|
||||
|
||||
**Continuation prompt** (give this to the user when resuming in a new chat):
|
||||
> "I'm continuing a design system build. Run ID: {RUN_ID}. Load the figma-generate-library skill and resume from the last completed step."
|
||||
|
||||
---
|
||||
|
||||
## 5. search_design_system — Reuse Decision Matrix
|
||||
|
||||
Search FIRST in Phase 0, then again immediately before each component creation.
|
||||
|
||||
```
|
||||
search_design_system({ query, fileKey, includeComponents: true, includeVariables: true, includeStyles: true })
|
||||
```
|
||||
|
||||
**Reuse if** all of these are true:
|
||||
- Component property API matches your needs (same variant axes, compatible types)
|
||||
- Token binding model is compatible (uses same or aliasable variables)
|
||||
- Naming conventions match the target file
|
||||
- Component is editable (not locked in a remote library you don't own)
|
||||
|
||||
**Rebuild if** any of these:
|
||||
- API incompatibility (different property names, wrong variant model)
|
||||
- Token model incompatible (hardcoded values, different variable schema)
|
||||
- Ownership issue (can't modify the library)
|
||||
|
||||
**Wrap if** visual match but API incompatible:
|
||||
- Import the library component as a nested instance inside a new wrapper component
|
||||
- Expose a clean API on the wrapper
|
||||
|
||||
**Three-way priority**: local existing → subscribed library import → create new.
|
||||
|
||||
---
|
||||
|
||||
## 6. User Checkpoints
|
||||
|
||||
Mandatory. Design decisions require human judgment.
|
||||
|
||||
| After | Required artifacts | Ask |
|
||||
|-------|-------------------|-----|
|
||||
| Discovery + scope lock | Token list, component list, gap analysis | "Here's my plan. Approve before I create anything?" |
|
||||
| Foundations | Variable summary (N collections, M vars, K modes), style list | "All tokens created. Review before file structure?" |
|
||||
| File structure | Page list + screenshot | "Pages set up. Review before components?" |
|
||||
| Each component | get_screenshot of component page | "Here's [Component] with N variants. Correct?" |
|
||||
| Each conflict (code ≠ Figma) | Show both versions | "Code says X, Figma has Y. Which wins?" |
|
||||
| Final QA | Per-page screenshots + audit report | "Complete. Sign off?" |
|
||||
|
||||
**If user rejects**: fix before moving on. Never build on rejected work.
|
||||
|
||||
---
|
||||
|
||||
## 7. Naming Conventions
|
||||
|
||||
Match existing file conventions. If starting fresh:
|
||||
|
||||
**Variables** (slash-separated):
|
||||
```
|
||||
color/bg/primary color/text/secondary color/border/default
|
||||
spacing/xs spacing/sm spacing/md spacing/lg spacing/xl spacing/2xl
|
||||
radius/none radius/sm radius/md radius/lg radius/full
|
||||
typography/body/font-size typography/heading/line-height
|
||||
```
|
||||
|
||||
**Primitives**: `blue/50` → `blue/900`, `gray/50` → `gray/900`
|
||||
|
||||
**Component names**: `Button`, `Input`, `Card`, `Avatar`, `Badge`, `Checkbox`, `Toggle`
|
||||
|
||||
**Variant names**: `Property=Value, Property=Value` — e.g., `Size=Medium, Style=Primary, State=Default`
|
||||
|
||||
**Page separators**: `---` (most common) or `——— COMPONENTS ———`
|
||||
|
||||
> Full naming reference: [naming-conventions.md](references/naming-conventions.md)
|
||||
|
||||
---
|
||||
|
||||
## 8. Token Architecture
|
||||
|
||||
| Complexity | Pattern |
|
||||
|-----------|---------|
|
||||
| < 50 tokens | Single collection, 2 modes (Light/Dark) |
|
||||
| 50–200 tokens | **Standard**: Primitives (1 mode) + Color semantic (Light/Dark) + Spacing (1 mode) + Typography (1 mode) |
|
||||
| 200+ tokens | **Advanced**: Multiple semantic collections, 4–8 modes (Light/Dark × Contrast × Brand). See M3 pattern in [token-creation.md](references/token-creation.md) |
|
||||
|
||||
Standard pattern (recommended starting point):
|
||||
```
|
||||
Collection: "Primitives" modes: ["Value"]
|
||||
blue/500 = #3B82F6, gray/900 = #111827, ...
|
||||
|
||||
Collection: "Color" modes: ["Light", "Dark"]
|
||||
color/bg/primary → Light: alias Primitives/white, Dark: alias Primitives/gray-900
|
||||
color/text/primary → Light: alias Primitives/gray-900, Dark: alias Primitives/white
|
||||
|
||||
Collection: "Spacing" modes: ["Value"]
|
||||
spacing/xs = 4, spacing/sm = 8, spacing/md = 16, ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Per-Phase Anti-Patterns
|
||||
|
||||
**Phase 0 anti-patterns:**
|
||||
- ❌ Starting to create anything before scope is locked with user
|
||||
- ❌ Ignoring existing file conventions and imposing new ones
|
||||
- ❌ Skipping `search_design_system` before planning component creation
|
||||
|
||||
**Phase 1 anti-patterns:**
|
||||
- ❌ Using `ALL_SCOPES` on any variable
|
||||
- ❌ Duplicating raw values in semantic layer instead of aliasing
|
||||
- ❌ Not setting code syntax (breaks Dev Mode and round-tripping)
|
||||
- ❌ Creating component tokens before agreeing on token taxonomy
|
||||
|
||||
**Phase 2 anti-patterns:**
|
||||
- ❌ Skipping the cover page or foundations docs
|
||||
- ❌ Putting multiple unrelated components on one page
|
||||
|
||||
**Phase 3 anti-patterns:**
|
||||
- ❌ Creating components before foundations exist
|
||||
- ❌ Hardcoding any fill/stroke/spacing/radius value in a component
|
||||
- ❌ Creating a variant per icon (use INSTANCE_SWAP instead)
|
||||
- ❌ Not positioning variants after combineAsVariants (they all stack at 0,0)
|
||||
- ❌ Building variant matrix > 30 without splitting (variant explosion)
|
||||
- ❌ Importing remote components then immediately detaching them
|
||||
|
||||
**General anti-patterns:**
|
||||
- ❌ Retrying a failed script without understanding the error first
|
||||
- ❌ Using name-prefix matching for cleanup (deletes user-owned nodes)
|
||||
- ❌ Building on unvalidated work from the previous step
|
||||
- ❌ Skipping user checkpoints to "save time"
|
||||
- ❌ Parallelizing use_figma calls (always sequential)
|
||||
- ❌ Guessing/hallucinating node IDs from memory (always read from state ledger)
|
||||
- ❌ Writing massive inline scripts instead of using the provided helper scripts
|
||||
- ❌ Starting Phase 3 because the user said "build the button" without completing Phases 0-2
|
||||
|
||||
---
|
||||
|
||||
## 10. Reference Docs
|
||||
|
||||
Load on demand — each reference is authoritative for its phase:
|
||||
|
||||
Use your file reading tool to read these docs when needed. Do not assume their contents from the filename.
|
||||
|
||||
| Doc | Phase | Required / Optional | Load when |
|
||||
|-----|-------|---------------------|-----------|
|
||||
| [discovery-phase.md](references/discovery-phase.md) | 0 | **Required** | Starting any build — codebase analysis + Figma inspection |
|
||||
| [token-creation.md](references/token-creation.md) | 1 | **Required** | Creating variables, collections, modes, styles |
|
||||
| [documentation-creation.md](references/documentation-creation.md) | 2 | Required | Creating cover page, foundations docs, swatches |
|
||||
| [component-creation.md](references/component-creation.md) | 3 | **Required** | Creating any component or variant |
|
||||
| [code-connect-setup.md](references/code-connect-setup.md) | 3–4 | Required | Setting up Code Connect or variable code syntax |
|
||||
| [naming-conventions.md](references/naming-conventions.md) | Any | Optional | Naming anything — variables, pages, variants, styles |
|
||||
| [error-recovery.md](references/error-recovery.md) | Any | **Required on error** | Script fails, multi-step workflow recovery, cleanup of abandoned workflow state |
|
||||
|
||||
---
|
||||
|
||||
## 11. Scripts
|
||||
|
||||
Reusable Plugin API helper functions. Embed in `use_figma` calls:
|
||||
|
||||
| Script | Purpose |
|
||||
|--------|---------|
|
||||
| [inspectFileStructure.js](scripts/inspectFileStructure.js) | Discover all pages, components, variables, styles; returns full inventory |
|
||||
| [createVariableCollection.js](scripts/createVariableCollection.js) | Create a named collection with modes; returns `{collectionId, modeIds}` |
|
||||
| [createSemanticTokens.js](scripts/createSemanticTokens.js) | Create aliased semantic variables from a token map |
|
||||
| [createComponentWithVariants.js](scripts/createComponentWithVariants.js) | Build a component set from a variant matrix; handles grid layout |
|
||||
| [bindVariablesToComponent.js](scripts/bindVariablesToComponent.js) | Bind design tokens to all component visual properties |
|
||||
| [createDocumentationPage.js](scripts/createDocumentationPage.js) | Create a page with title + description + section structure |
|
||||
| [validateCreation.js](scripts/validateCreation.js) | Verify created nodes match expected counts, names, structure |
|
||||
| [cleanupOrphans.js](scripts/cleanupOrphans.js) | Remove orphaned nodes by name convention or state ledger IDs |
|
||||
| [rehydrateState.js](scripts/rehydrateState.js) | Scan file for all pages, components, variables by name; returns full `{key → nodeId}` map for state reconstruction |
|
||||
+260
@@ -0,0 +1,260 @@
|
||||
> Part of the [figma-generate-library skill](../SKILL.md).
|
||||
|
||||
# Code Connect Setup Reference
|
||||
|
||||
This reference covers all Code Connect tooling available to the figma-generate-library agent: the `add_code_connect_map` tool, `get_code_connect_map` for verification, `send_code_connect_mappings` for bulk application, variable code syntax, framework labels, and the decision of when to map per-component vs. in a final pass.
|
||||
|
||||
---
|
||||
|
||||
## 1. What Code Connect Does
|
||||
|
||||
Code Connect links a Figma component node to its code implementation so that:
|
||||
|
||||
- **Dev Mode** shows a real code snippet (from your codebase) instead of an auto-generated approximation when a developer inspects a component.
|
||||
- **MCP `get_design_context`** returns `componentName`, `source`, and a rendered snippet alongside design tokens, enabling accurate AI-assisted code generation.
|
||||
- **`search_design_system`** can return code references alongside Figma component metadata.
|
||||
|
||||
---
|
||||
|
||||
## 2. The Three MCP Tools
|
||||
|
||||
### 2a. add_code_connect_map — single mapping
|
||||
|
||||
Maps one Figma node to one code component.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Notes |
|
||||
|-----------|------|----------|-------|
|
||||
| `nodeId` | string | Yes (remote) / Optional (desktop) | Format `123:456`. Must be a published component or component set. |
|
||||
| `fileKey` | string | Yes (remote) | The Figma file key. |
|
||||
| `source` | string | Yes | Path in the codebase (e.g. `src/components/Button.tsx`) or a URL. |
|
||||
| `componentName` | string | Yes | The code component name (e.g. `Button`). |
|
||||
| `label` | enum | Yes | Framework label — see Section 4 for valid values. |
|
||||
| `template` | string | Optional | Executable JS template code. Providing this creates a **figmadoc** (template) mapping instead of a simple **component_browser** mapping. Requires the `pixie_mcp_enable_writing_code_connect_templates` feature flag. |
|
||||
| `templateDataJson` | string | Optional | JSON string with optional fields: `isParserless`, `imports`, `nestable`, `props`. |
|
||||
|
||||
**Two mapping tiers:**
|
||||
|
||||
1. **Simple mapping (component_browser):** Only `source`, `componentName`, and `label` provided. Associates the Figma component with a code path + name. Dev Mode generates a basic JSX snippet from Figma prop names. This is the default — use it first.
|
||||
|
||||
2. **Template mapping (figmadoc):** `template` is also provided. The template is executed in a sandboxed QuickJS environment and dynamically renders the snippet based on the actual instance's property values. Use this when precise prop-level Code Connect is required by the user.
|
||||
|
||||
**Common error codes:**
|
||||
|
||||
| Error | Meaning | Fix |
|
||||
|-------|---------|-----|
|
||||
| `CODE_CONNECT_MAPPING_ALREADY_EXISTS` | Component is already mapped | Disconnect existing mapping in Figma UI first |
|
||||
| `CODE_CONNECT_ASSET_NOT_FOUND` | Published component not found | Ensure the component is published to the library |
|
||||
| `CODE_CONNECT_INSUFFICIENT_PERMISSIONS` | No edit access | Request edit permission on the file |
|
||||
| `CODE_CONNECT_NO_LIBRARY_FOUND` | File is not published as a library | Publish the file as a Figma library first |
|
||||
|
||||
**Usage example:**
|
||||
|
||||
```
|
||||
Tool: add_code_connect_map
|
||||
Args: {
|
||||
nodeId: "123:456",
|
||||
fileKey: "abc123",
|
||||
source: "src/components/Button.tsx",
|
||||
componentName: "Button",
|
||||
label: "React"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2b. get_code_connect_map — verification
|
||||
|
||||
Retrieves the current Code Connect mapping for a node. Use this immediately after `add_code_connect_map` to confirm the mapping was saved, and before `send_code_connect_mappings` to audit existing state.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Notes |
|
||||
|-----------|------|----------|-------|
|
||||
| `nodeId` | string | Optional | The node to check. Omit to get all mappings in the file. |
|
||||
| `fileKey` | string | Yes (remote) | The Figma file key. |
|
||||
| `codeConnectLabel` | string | Optional | Filter results to a specific framework label. |
|
||||
|
||||
**Returns:** A map of `nodeId -> { componentName, source, label, snippet, snippetImports }`.
|
||||
|
||||
**How to verify:**
|
||||
|
||||
```
|
||||
1. Call add_code_connect_map with the node.
|
||||
2. Immediately call get_code_connect_map(nodeId, fileKey).
|
||||
3. Confirm the returned object has the expected componentName and source.
|
||||
4. If the mapping is missing, check for error codes from step 1.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2c. send_code_connect_mappings — bulk application
|
||||
|
||||
Applies multiple Code Connect mappings in one call. Use after `get_code_connect_suggestions` returns a batch of unmapped components, or when doing a final-pass bulk mapping at the end of Phase 4.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Notes |
|
||||
|-----------|------|----------|-------|
|
||||
| `nodeId` | string | Optional | Context node for design fallback if mappings array is empty. |
|
||||
| `fileKey` | string | Yes (remote) | The Figma file key. |
|
||||
| `mappings` | array | Yes | Array of mapping objects. |
|
||||
|
||||
**Each mapping object:**
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
|-------|------|----------|-------|
|
||||
| `nodeId` | string | Yes | The Figma node identifier. |
|
||||
| `componentName` | string | Yes | Code component name. |
|
||||
| `source` | string | Yes | Path in the codebase. |
|
||||
| `label` | enum | Yes | Framework label. |
|
||||
| `template` | string | Optional | JS template code for figmadoc mapping. |
|
||||
| `templateDataJson` | string | Optional | JSON template metadata. |
|
||||
|
||||
**Behavior:**
|
||||
|
||||
- All mappings are processed in parallel via POSTs to the backend.
|
||||
- If any mapping fails, errors are reported per mapping — the rest succeed.
|
||||
- On full success, `get_design_context` is called for the nodes and fresh design context is returned.
|
||||
|
||||
**Bulk workflow:**
|
||||
|
||||
```
|
||||
1. Collect all {nodeId, componentName, source, label} pairs.
|
||||
2. Call send_code_connect_mappings({ fileKey, mappings: [...all pairs...] }).
|
||||
3. Review reported errors and call add_code_connect_map individually for any failures.
|
||||
4. Call get_code_connect_map on a sample of nodes to spot-check.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Variable Code Syntax (Token Round-Tripping)
|
||||
|
||||
Setting code syntax on variables creates the bidirectional link between Figma tokens and the codebase token system. This is what enables Dev Mode to show `var(--color-bg-primary)` next to a design value instead of a raw hex.
|
||||
|
||||
**The three platforms:**
|
||||
|
||||
```javascript
|
||||
// In use_figma:
|
||||
variable.setVariableCodeSyntax('WEB', 'var(--color-bg-primary)');
|
||||
variable.setVariableCodeSyntax('ANDROID', 'Theme.colorBgPrimary');
|
||||
variable.setVariableCodeSyntax('iOS', 'Color.bgPrimary');
|
||||
```
|
||||
|
||||
- `WEB` — used for CSS custom properties, design token JSON, and any web framework.
|
||||
- `ANDROID` — used for Jetpack Compose theme references and Android resource names.
|
||||
- `iOS` — used for SwiftUI Color extensions and UIKit color methods.
|
||||
|
||||
**Derivation rules (in priority order):**
|
||||
|
||||
1. **Best:** Use the exact token name from the codebase. Search the codebase for CSS custom properties (`--`), Swift color extensions, or Kotlin theme references and use those exact strings.
|
||||
2. **Good:** Derive from the Figma variable name with a consistent transformation: replace `/` and spaces with `-`, prefix with `var(--` and suffix with `)`.
|
||||
- Example: `color/bg/primary` → `var(--color-bg-primary)`
|
||||
3. **Avoid:** Guessing or inventing names that don't exist in the codebase.
|
||||
|
||||
**Consistency rule:** The transformation must be uniform. If you use `var(--color-bg-primary)` for one variable, use the same `var(--{path-with-hyphens})` pattern for all variables in that collection.
|
||||
|
||||
**WEB syntax bulk example:**
|
||||
|
||||
```javascript
|
||||
// In use_figma — set WEB code syntax on all variables in a collection
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
for (const coll of collections) {
|
||||
if (coll.name !== 'Color') continue;
|
||||
for (const varId of coll.variableIds) {
|
||||
const v = await figma.variables.getVariableByIdAsync(varId);
|
||||
if (!v) continue;
|
||||
// Derive: "color/bg/primary" → "var(--color-bg-primary)"
|
||||
const cssName = 'var(--' + v.name.toLowerCase().replace(/\//g, '-').replace(/\s+/g, '-') + ')';
|
||||
v.setVariableCodeSyntax('WEB', cssName);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Framework Labels
|
||||
|
||||
The following labels are valid for all Code Connect MCP operations. Use the label that matches your codebase framework.
|
||||
|
||||
| Label | Use for |
|
||||
|-------|---------|
|
||||
| `React` | React / JSX / TSX components |
|
||||
| `Web Components` | Native Web Components, Lit, FAST |
|
||||
| `Vue` | Vue 2 and Vue 3 SFCs |
|
||||
| `Svelte` | Svelte components |
|
||||
| `Storybook` | Storybook stories with Code Connect integration |
|
||||
| `Javascript` | Plain JavaScript, framework-agnostic |
|
||||
| `Swift` | Swift / UIKit |
|
||||
| `Swift UIKit` | UIKit specifically |
|
||||
| `Objective-C UIKit` | Objective-C with UIKit |
|
||||
| `SwiftUI` | SwiftUI view components |
|
||||
| `Compose` | Jetpack Compose (Android) |
|
||||
| `Java` | Java Android components |
|
||||
| `Kotlin` | Kotlin Android (non-Compose) |
|
||||
| `Android XML Layout` | Android XML layout files |
|
||||
| `Flutter` | Flutter / Dart widgets |
|
||||
| `Markdown` | Documentation or MDX components |
|
||||
|
||||
**HTML note:** The label `HTML` is used by the Code Connect CLI's HTML parser (for Angular, Vue, and Web Components without a framework-specific parser), but the MCP tools use `Web Components` or `Vue` directly. Check the codebase framework before selecting.
|
||||
|
||||
---
|
||||
|
||||
## 5. Per-Component vs. Final-Pass Strategy
|
||||
|
||||
### Per-component (preferred for new builds)
|
||||
|
||||
Map Code Connect immediately after creating a component, while the context is fresh (Phase 3, step 3h in the SKILL.md workflow):
|
||||
|
||||
**Advantages:**
|
||||
- The node ID is already in hand from the creation script.
|
||||
- You know exactly which code component this Figma component corresponds to (you just designed it to match).
|
||||
- Errors surface early, before building dependent components.
|
||||
|
||||
**When to use:** Any time you create a Figma component that has a clear 1:1 match with an existing code component.
|
||||
|
||||
### Final pass (for bulk mapping at Phase 4)
|
||||
|
||||
Collect all unmapped components and map them in one `send_code_connect_mappings` call:
|
||||
|
||||
**Advantages:**
|
||||
- One bulk call instead of N individual calls.
|
||||
- Can use `get_code_connect_suggestions` to discover unmapped components automatically.
|
||||
- Better for importing existing Figma files where you didn't control creation.
|
||||
|
||||
**When to use:** Retrofitting Code Connect onto an existing file, or when the codebase mapping requires research that is better done after all components are created.
|
||||
|
||||
### Hybrid (recommended for large systems)
|
||||
|
||||
- Map atoms (Button, Input, Badge, Avatar) **per-component** during Phase 3.
|
||||
- Map molecules and organisms in a **final pass** during Phase 4 after all atoms are mapped, since molecule snippets reference atom Code Connect IDs.
|
||||
|
||||
---
|
||||
|
||||
## 6. Verification in Dev Mode
|
||||
|
||||
After mapping:
|
||||
|
||||
1. Open the Figma file in the browser or desktop app.
|
||||
2. Switch to Dev Mode (the `</>` icon in the toolbar).
|
||||
3. Select a component instance (not the main component — an instance placed on a page).
|
||||
4. In the Inspect panel, the code snippet should show the Code Connect output instead of auto-generated code.
|
||||
5. If the snippet is missing or shows `[auto-generated]`, run `get_code_connect_map` via MCP to confirm the mapping exists, then check that the component is published.
|
||||
|
||||
**Via MCP (faster during agent workflows):**
|
||||
|
||||
```
|
||||
get_code_connect_map(nodeId: "<the component set node ID>", fileKey: "<file key>")
|
||||
```
|
||||
|
||||
The response should include `componentName`, `source`, `label`, and a non-empty `snippet`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Important Constraints
|
||||
|
||||
- **Published components only:** `add_code_connect_map` requires the component to be published to a library. If the file is not yet published, the mapping will fail with `CODE_CONNECT_NO_LIBRARY_FOUND`.
|
||||
- **One mapping per label per node:** A node can have multiple mappings (one per framework label), but only one per label. Attempting to add a second React mapping to the same node returns `CODE_CONNECT_MAPPING_ALREADY_EXISTS`.
|
||||
- **Template mappings are gated:** The `template` parameter requires the `pixie_mcp_enable_writing_code_connect_templates` feature flag. Use simple mappings unless the user explicitly requests template-level Code Connect.
|
||||
- **Start simple, escalate:** Always begin with simple mappings (`source` + `componentName` + `label`). Add `template` only if the user needs precise prop-level snippet rendering.
|
||||
+972
@@ -0,0 +1,972 @@
|
||||
> Part of the [figma-generate-library skill](../SKILL.md).
|
||||
|
||||
# Component Creation Reference
|
||||
|
||||
Complete guide for Phase 3: building components with variant matrices, variable bindings, component properties, and documentation.
|
||||
|
||||
---
|
||||
|
||||
## 1. Component Architecture
|
||||
|
||||
### Dependency Ordering: Atoms Before Molecules
|
||||
|
||||
Always build in dependency order. A molecule that contains an atom instance cannot exist until the atom is published. Suggested ordering:
|
||||
|
||||
```
|
||||
Tier 0 (atoms): Icon, Avatar, Badge, Spinner
|
||||
Tier 1 (molecules): Button, Checkbox, Toggle, Input, Select
|
||||
Tier 2 (organisms): Card, Dialog, Menu, Navigation, Form
|
||||
```
|
||||
|
||||
If a component embeds an instance of another component, the embedded component must be created first. Build your dependency graph during Phase 0 and encode the creation order in the plan.
|
||||
|
||||
### Building Blocks Sub-Components (M3 Pattern)
|
||||
|
||||
For complex components with independent sub-element state machines, extract the sub-element into its own component set prefixed with `Building Blocks/` (public) or `.Building Blocks/` (hidden from assets panel). The dot-prefix is a Figma convention for suppressing a component from the public assets panel.
|
||||
|
||||
**When to use Building Blocks:**
|
||||
- The sub-element has its own variant axes (state, selection) that would cause combinatorial explosion in the parent
|
||||
- The sub-element repeats (nav items, table cells, calendar cells, segmented button segments)
|
||||
- The sub-element has different variant axes than the parent
|
||||
|
||||
**Example (M3 Segmented Button):**
|
||||
```
|
||||
Building Blocks/Segmented button/Button segment (start) [27 variants: Config × State × Selected]
|
||||
Building Blocks/Segmented button/Button segment (middle) [27 variants]
|
||||
Building Blocks/Segmented button/Button segment (end) [27 variants]
|
||||
|
||||
Segmented button [16 variants: Segments=2-5 × Density=0/-1/-2/-3]
|
||||
Each variant contains instances of the appropriate Building Block segment components.
|
||||
```
|
||||
|
||||
The parent manages composition and configuration; the Building Block manages its own interaction states.
|
||||
|
||||
### Private Components (`__` Prefix)
|
||||
|
||||
Use the `__` prefix for internal helper components that should not appear in the team library (Shop Minis pattern). Use `_` for documentation-only components (UI3 pattern).
|
||||
|
||||
```
|
||||
__asset // private icon/asset holder
|
||||
_Label/Direction // documentation annotation helper
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Creating the Component Page
|
||||
|
||||
Each component lives on its own dedicated page (one page per component is the default). The page contains: a documentation frame at top-left and the component set positioned to its right or below.
|
||||
|
||||
```javascript
|
||||
// Create or find the component page
|
||||
let page = figma.root.children.find(p => p.name === 'Button');
|
||||
if (!page) {
|
||||
page = figma.createPage();
|
||||
page.name = 'Button';
|
||||
}
|
||||
await figma.setCurrentPageAsync(page);
|
||||
|
||||
// Documentation frame — positioned at (40, 40)
|
||||
const docFrame = figma.createFrame();
|
||||
docFrame.name = 'Button / Documentation';
|
||||
docFrame.x = 40;
|
||||
docFrame.y = 40;
|
||||
docFrame.resize(600, 400);
|
||||
docFrame.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
|
||||
docFrame.layoutMode = 'VERTICAL';
|
||||
docFrame.primaryAxisSizingMode = 'AUTO';
|
||||
docFrame.counterAxisSizingMode = 'FIXED';
|
||||
docFrame.paddingTop = 40;
|
||||
docFrame.paddingBottom = 40;
|
||||
docFrame.paddingLeft = 40;
|
||||
docFrame.paddingRight = 40;
|
||||
docFrame.itemSpacing = 16;
|
||||
|
||||
// Title text node
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
|
||||
const title = figma.createText();
|
||||
title.fontName = { family: 'Inter', style: 'Bold' };
|
||||
title.fontSize = 32;
|
||||
title.characters = 'Button';
|
||||
docFrame.appendChild(title);
|
||||
|
||||
// Description text node
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
|
||||
const desc = figma.createText();
|
||||
desc.fontName = { family: 'Inter', style: 'Regular' };
|
||||
desc.fontSize = 14;
|
||||
desc.characters = 'Buttons allow users to take actions and make choices with a single tap.';
|
||||
docFrame.appendChild(desc);
|
||||
|
||||
// Tag docFrame with sharedPluginData for idempotency
|
||||
docFrame.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
docFrame.setSharedPluginData('dsb', 'key', 'doc/button');
|
||||
|
||||
return { docFrameId: docFrame.id, pageId: page.id };
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Base Component: Auto-Layout, Child Nodes, Variable Bindings
|
||||
|
||||
The base component is the template from which all variants are cloned. It must have:
|
||||
1. Auto-layout (not manual positioning)
|
||||
2. All child nodes present
|
||||
3. ALL visual properties bound to variables (no hardcoded values)
|
||||
|
||||
### Complete Button Base Component Example
|
||||
|
||||
```javascript
|
||||
const RUN_ID = 'ds-build-2024-001'; // replace with your actual run ID
|
||||
await figma.setCurrentPageAsync(
|
||||
figma.root.children.find(p => p.name === 'Button')
|
||||
);
|
||||
|
||||
// Rehydrate variables from IDs stored in state ledger
|
||||
const bgVar = await figma.variables.getVariableByIdAsync('VAR_ID_color_bg_primary');
|
||||
const textVar = await figma.variables.getVariableByIdAsync('VAR_ID_color_text_on_primary');
|
||||
const paddingVar = await figma.variables.getVariableByIdAsync('VAR_ID_spacing_md');
|
||||
const radiusVar = await figma.variables.getVariableByIdAsync('VAR_ID_radius_md');
|
||||
const gapVar = await figma.variables.getVariableByIdAsync('VAR_ID_spacing_sm');
|
||||
|
||||
// --- Base component frame ---
|
||||
const comp = figma.createComponent();
|
||||
comp.name = 'Size=Medium, Style=Primary, State=Default';
|
||||
comp.layoutMode = 'HORIZONTAL';
|
||||
comp.primaryAxisSizingMode = 'AUTO';
|
||||
comp.counterAxisSizingMode = 'AUTO';
|
||||
comp.counterAxisAlignItems = 'CENTER';
|
||||
comp.primaryAxisAlignItems = 'CENTER';
|
||||
|
||||
// Padding — bound to spacing variables
|
||||
comp.setBoundVariable('paddingTop', paddingVar);
|
||||
comp.setBoundVariable('paddingBottom', paddingVar);
|
||||
comp.setBoundVariable('paddingLeft', paddingVar);
|
||||
comp.setBoundVariable('paddingRight', paddingVar);
|
||||
comp.setBoundVariable('itemSpacing', gapVar);
|
||||
|
||||
// Corner radius — bound to radius variable
|
||||
comp.setBoundVariable('topLeftRadius', radiusVar);
|
||||
comp.setBoundVariable('topRightRadius', radiusVar);
|
||||
comp.setBoundVariable('bottomLeftRadius', radiusVar);
|
||||
comp.setBoundVariable('bottomRightRadius', radiusVar);
|
||||
|
||||
// Background fill — bound to color variable
|
||||
const bgPaint = figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } },
|
||||
'color',
|
||||
bgVar
|
||||
);
|
||||
comp.fills = [bgPaint];
|
||||
|
||||
// --- Label text node ---
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
|
||||
const label = figma.createText();
|
||||
label.name = 'label';
|
||||
label.fontName = { family: 'Inter', style: 'Medium' };
|
||||
label.fontSize = 14;
|
||||
label.characters = 'Button';
|
||||
label.layoutSizingHorizontal = 'HUG';
|
||||
label.layoutSizingVertical = 'HUG';
|
||||
|
||||
// Text fill — bound to color variable
|
||||
const textPaint = figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } },
|
||||
'color',
|
||||
textVar
|
||||
);
|
||||
label.fills = [textPaint];
|
||||
comp.appendChild(label);
|
||||
|
||||
// --- Icon placeholder (Rectangle for now — will be INSTANCE_SWAP) ---
|
||||
const iconBox = figma.createFrame();
|
||||
iconBox.name = 'icon';
|
||||
iconBox.resize(16, 16);
|
||||
iconBox.fills = [];
|
||||
iconBox.layoutSizingHorizontal = 'FIXED';
|
||||
iconBox.layoutSizingVertical = 'FIXED';
|
||||
comp.appendChild(iconBox);
|
||||
|
||||
// Tag for idempotency
|
||||
comp.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
comp.setSharedPluginData('dsb', 'phase', 'phase3');
|
||||
comp.setSharedPluginData('dsb', 'key', 'component/button/base');
|
||||
|
||||
return { baseCompId: comp.id };
|
||||
```
|
||||
|
||||
**ALL of these must be variable-bound (never hardcoded):**
|
||||
|
||||
| Property | Variable type | API method |
|
||||
|---|---|---|
|
||||
| Fill color | COLOR | `setBoundVariableForPaint(..., 'color', var)` |
|
||||
| Stroke color | COLOR | `setBoundVariableForPaint(..., 'color', var)` |
|
||||
| Text fill | COLOR | `setBoundVariableForPaint(..., 'color', var)` |
|
||||
| Padding (all 4 sides) | FLOAT | `comp.setBoundVariable('paddingTop', var)` |
|
||||
| Gap / itemSpacing | FLOAT | `comp.setBoundVariable('itemSpacing', var)` |
|
||||
| Corner radius (all 4) | FLOAT | `comp.setBoundVariable('topLeftRadius', var)` etc. |
|
||||
| Stroke weight | FLOAT | `comp.setBoundVariable('strokeWeight', var)` |
|
||||
|
||||
---
|
||||
|
||||
## 4. Variant Matrix
|
||||
|
||||
### Defining Axes
|
||||
|
||||
For each component, identify its variant axes before writing any code. Standard axes:
|
||||
|
||||
```
|
||||
Button:
|
||||
Size → [Small, Medium, Large]
|
||||
Style → [Primary, Secondary, Outline, Ghost]
|
||||
State → [Default, Hover, Focused, Pressed, Disabled]
|
||||
Total = 3 × 4 × 5 = 60 combinations — exceeds 30 limit → split by Style
|
||||
```
|
||||
|
||||
### The 30-Combination Cap and Split Strategy
|
||||
|
||||
When the product of all variant axes exceeds 30 combinations, split the matrix. Options:
|
||||
|
||||
1. **Split by a primary axis**: Create separate component sets, one per Style (Primary Button, Secondary Button, etc.)
|
||||
2. **Use INSTANCE_SWAP**: Remove a visual axis (like Icon) from the variant matrix entirely and expose it as an INSTANCE_SWAP property instead
|
||||
3. **Use Building Blocks**: Extract sub-elements with their own state axes into Building Block component sets
|
||||
|
||||
For Button with Size × State = 15 combinations, add Style as a variant axis only if Style ≤ 2 options (15 × 2 = 30). For more Styles, split.
|
||||
|
||||
### Creating All Variants with use_figma
|
||||
|
||||
Build each variant by cloning the base component and adjusting the variable bindings that differ per variant. Pass in the base component ID from the previous call's state.
|
||||
|
||||
```javascript
|
||||
const RUN_ID = 'ds-build-2024-001';
|
||||
const BASE_COMP_ID = 'BASE_ID_FROM_STATE'; // from state ledger
|
||||
|
||||
await figma.setCurrentPageAsync(
|
||||
figma.root.children.find(p => p.name === 'Button')
|
||||
);
|
||||
|
||||
const base = await figma.getNodeByIdAsync(BASE_COMP_ID);
|
||||
|
||||
// Variable IDs from state ledger
|
||||
const vars = {
|
||||
// Primary style
|
||||
bg_primary: await figma.variables.getVariableByIdAsync('VAR_ID_color_bg_primary'),
|
||||
text_primary: await figma.variables.getVariableByIdAsync('VAR_ID_color_text_on_primary'),
|
||||
// Secondary style
|
||||
bg_secondary: await figma.variables.getVariableByIdAsync('VAR_ID_color_bg_secondary'),
|
||||
text_secondary: await figma.variables.getVariableByIdAsync('VAR_ID_color_text_secondary'),
|
||||
// Disabled
|
||||
bg_disabled: await figma.variables.getVariableByIdAsync('VAR_ID_color_bg_disabled'),
|
||||
text_disabled: await figma.variables.getVariableByIdAsync('VAR_ID_color_text_disabled'),
|
||||
// Sizes
|
||||
padding_sm: await figma.variables.getVariableByIdAsync('VAR_ID_spacing_sm'),
|
||||
padding_md: await figma.variables.getVariableByIdAsync('VAR_ID_spacing_md'),
|
||||
padding_lg: await figma.variables.getVariableByIdAsync('VAR_ID_spacing_lg'),
|
||||
};
|
||||
|
||||
const axes = {
|
||||
Size: ['Small', 'Medium', 'Large'],
|
||||
Style: ['Primary', 'Secondary'],
|
||||
State: ['Default', 'Hover', 'Disabled'],
|
||||
};
|
||||
|
||||
const paddingBySize = { Small: vars.padding_sm, Medium: vars.padding_md, Large: vars.padding_lg };
|
||||
|
||||
const components = [];
|
||||
|
||||
for (const size of axes.Size) {
|
||||
for (const style of axes.Style) {
|
||||
for (const state of axes.State) {
|
||||
const clone = base.clone();
|
||||
clone.name = `Size=${size}, Style=${style}, State=${state}`;
|
||||
|
||||
// Bind padding by size
|
||||
clone.setBoundVariable('paddingTop', paddingBySize[size]);
|
||||
clone.setBoundVariable('paddingBottom', paddingBySize[size]);
|
||||
clone.setBoundVariable('paddingLeft', paddingBySize[size]);
|
||||
clone.setBoundVariable('paddingRight', paddingBySize[size]);
|
||||
|
||||
// Bind fill by style + state
|
||||
const isDisabled = state === 'Disabled';
|
||||
const bgVar = isDisabled ? vars.bg_disabled : (style === 'Primary' ? vars.bg_primary : vars.bg_secondary);
|
||||
const txtVar = isDisabled ? vars.text_disabled : (style === 'Primary' ? vars.text_primary : vars.text_secondary);
|
||||
|
||||
const bgPaint = figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', bgVar
|
||||
);
|
||||
clone.fills = [bgPaint];
|
||||
|
||||
const labelNode = clone.findOne(n => n.name === 'label');
|
||||
const textPaint = figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }, 'color', txtVar
|
||||
);
|
||||
labelNode.fills = [textPaint];
|
||||
|
||||
clone.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
clone.setSharedPluginData('dsb', 'key', `component/button/variant/${size}/${style}/${state}`);
|
||||
|
||||
components.push(clone);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return { variantIds: components.map(c => c.id) };
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. `combineAsVariants` + Grid Layout
|
||||
|
||||
After all variant components exist, combine them into a ComponentSet and position them in a grid. This MUST be a separate `use_figma` call — you must pass in all variant IDs from the previous call's return value.
|
||||
|
||||
### Grid Design Conventions
|
||||
|
||||
Professional design systems lay out variants in a readable grid where:
|
||||
- **Columns** = the property users interact with most (typically **State**: Default, Hover, Focused, Pressed, Disabled)
|
||||
- **Rows** = structural axes grouped together (typically **Size × Style**, where Size varies fastest)
|
||||
- **Gap** = 16–40px between variants (20px is a safe default; match existing file if one exists)
|
||||
- **Padding** = 40px around the grid inside the ComponentSet frame
|
||||
|
||||
```
|
||||
Visual structure:
|
||||
Default Hover Focused Pressed Disabled
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ Small/Primary [comp] [comp] [comp] [comp] [comp] │
|
||||
│ Small/Secondary [comp] [comp] [comp] [comp] [comp] │
|
||||
│ Medium/Primary [comp] [comp] [comp] [comp] [comp] │
|
||||
│ Medium/Secondary[comp] [comp] [comp] [comp] [comp] │
|
||||
│ Large/Primary [comp] [comp] [comp] [comp] [comp] │
|
||||
│ Large/Secondary [comp] [comp] [comp] [comp] [comp] │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Why State on columns?** State is the axis designers scan horizontally to verify interaction consistency. Size/Style define the "identity" of each row. This matches how professional design systems (M3, Polaris, Simple DS) organize their grids.
|
||||
|
||||
### Adding Row/Column Header Labels
|
||||
|
||||
After laying out the grid, add text labels OUTSIDE the ComponentSet to help navigation. These are siblings of the ComponentSet on the page — not children of it:
|
||||
|
||||
```javascript
|
||||
// Add column headers above the component set
|
||||
const colLabels = ['Default', 'Hover', 'Focused', 'Pressed', 'Disabled'];
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
|
||||
for (let i = 0; i < colLabels.length; i++) {
|
||||
const label = figma.createText();
|
||||
label.fontName = { family: 'Inter', style: 'Medium' };
|
||||
label.characters = colLabels[i];
|
||||
label.fontSize = 11;
|
||||
label.fills = [{ type: 'SOLID', color: { r: 0.5, g: 0.5, b: 0.5 } }];
|
||||
label.x = cs.x + padding + i * (childWidth + gap);
|
||||
label.y = cs.y - 20;
|
||||
}
|
||||
|
||||
// Add row headers to the left of the component set
|
||||
const rowLabels = ['Small / Primary', 'Small / Secondary', 'Med / Primary', ...];
|
||||
for (let i = 0; i < rowLabels.length; i++) {
|
||||
const label = figma.createText();
|
||||
label.fontName = { family: 'Inter', style: 'Medium' };
|
||||
label.characters = rowLabels[i];
|
||||
label.fontSize = 11;
|
||||
label.fills = [{ type: 'SOLID', color: { r: 0.5, g: 0.5, b: 0.5 } }];
|
||||
label.x = cs.x - 120;
|
||||
label.y = cs.y + padding + i * (childHeight + gap) + childHeight / 2 - 6;
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** These labels are documentation aids, not part of the component itself. They help designers navigate the variant grid.
|
||||
|
||||
### Grid layout code
|
||||
|
||||
```javascript
|
||||
const VARIANT_IDS = ['ID1', 'ID2', '...']; // from state ledger
|
||||
const PAGE_ID = 'PAGE_ID'; // from state ledger
|
||||
|
||||
await figma.setCurrentPageAsync(await figma.getNodeByIdAsync(PAGE_ID));
|
||||
|
||||
// Collect component nodes
|
||||
const components = await Promise.all(
|
||||
VARIANT_IDS.map(id => figma.getNodeByIdAsync(id))
|
||||
);
|
||||
|
||||
// Combine as variants
|
||||
const cs = figma.combineAsVariants(components, figma.currentPage);
|
||||
cs.name = 'Button';
|
||||
|
||||
// Grid layout: position each variant based on its property values
|
||||
// Determine column axis (State) and row axes (Size × Style)
|
||||
const axes = {
|
||||
Size: ['Small', 'Medium', 'Large'],
|
||||
Style: ['Primary', 'Secondary'],
|
||||
State: ['Default', 'Hover', 'Disabled'],
|
||||
};
|
||||
const COL_AXIS = 'State'; // columns
|
||||
const ROW_AXES = ['Size', 'Style']; // rows (Size changes fastest)
|
||||
|
||||
const gap = 16;
|
||||
const padding = 40;
|
||||
|
||||
// Measure child dimensions (all should be same height within Size tier)
|
||||
// Use the first child as reference for column width
|
||||
const childWidth = 120; // approximate; refine after first screenshot
|
||||
const childHeight = 40;
|
||||
|
||||
cs.children.forEach(child => {
|
||||
const props = {};
|
||||
child.name.split(', ').forEach(part => {
|
||||
const [k, v] = part.split('=');
|
||||
props[k] = v;
|
||||
});
|
||||
|
||||
const colIdx = axes[COL_AXIS].indexOf(props[COL_AXIS]);
|
||||
// Row = Size index * number of styles + Style index
|
||||
const rowIdx = axes.Size.indexOf(props.Size) * axes.Style.length
|
||||
+ axes.Style.indexOf(props.Style);
|
||||
|
||||
child.x = padding + colIdx * (childWidth + gap);
|
||||
child.y = padding + rowIdx * (childHeight + gap);
|
||||
});
|
||||
|
||||
// Resize component set to fit all children + padding
|
||||
let maxX = 0, maxY = 0;
|
||||
for (const child of cs.children) {
|
||||
maxX = Math.max(maxX, child.x + child.width);
|
||||
maxY = Math.max(maxY, child.y + child.height);
|
||||
}
|
||||
cs.resizeWithoutConstraints(maxX + padding, maxY + padding);
|
||||
|
||||
// Style the component set frame
|
||||
cs.fills = [{ type: 'SOLID', color: { r: 0.95, g: 0.95, b: 0.98 } }];
|
||||
cs.cornerRadius = 8;
|
||||
|
||||
// Position component set on page (to the right of doc frame)
|
||||
cs.x = 680;
|
||||
cs.y = 40;
|
||||
|
||||
cs.setSharedPluginData('dsb', 'run_id', 'ds-build-2024-001');
|
||||
cs.setSharedPluginData('dsb', 'key', 'componentset/button');
|
||||
|
||||
return { componentSetId: cs.id };
|
||||
```
|
||||
|
||||
**Critical rules for combineAsVariants:**
|
||||
- `components` must be a non-empty array containing ONLY `ComponentNode` objects (not frames, not groups)
|
||||
- After combining, children are placed at (0,0) and overlap — you MUST manually position them
|
||||
- `resizeWithoutConstraints` is required after positioning to make the component set frame fit its contents
|
||||
- There is no `figma.createComponentSet()` — you cannot create an empty component set
|
||||
|
||||
---
|
||||
|
||||
## 6. Component Properties
|
||||
|
||||
Add TEXT, BOOLEAN, and INSTANCE_SWAP properties to the ComponentSet (not to individual variants). The return value of `addComponentProperty` is the actual property key (it gets a `#id:id` suffix appended) — save this key and use it immediately when setting `componentPropertyReferences`.
|
||||
|
||||
### TEXT Properties
|
||||
|
||||
Expose editable text in instances:
|
||||
|
||||
```javascript
|
||||
// On the ComponentSetNode (cs):
|
||||
const labelKey = cs.addComponentProperty('Label', 'TEXT', 'Button');
|
||||
// labelKey is now something like "Label#0:1"
|
||||
|
||||
// Wire to the label child in each variant:
|
||||
for (const child of cs.children) {
|
||||
const labelNode = child.findOne(n => n.name === 'label');
|
||||
if (labelNode) {
|
||||
labelNode.componentPropertyReferences = { characters: labelKey };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### BOOLEAN Properties
|
||||
|
||||
Toggle child node visibility:
|
||||
|
||||
```javascript
|
||||
const showIconKey = cs.addComponentProperty('Show Icon', 'BOOLEAN', true);
|
||||
|
||||
for (const child of cs.children) {
|
||||
const iconNode = child.findOne(n => n.name === 'icon');
|
||||
if (iconNode) {
|
||||
iconNode.componentPropertyReferences = { visible: showIconKey };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### INSTANCE_SWAP Properties
|
||||
|
||||
Allow swapping a nested component instance (e.g., swap the icon):
|
||||
|
||||
```javascript
|
||||
// defaultIconCompId is the ID of the default icon component (from state ledger)
|
||||
const iconKey = cs.addComponentProperty('Icon', 'INSTANCE_SWAP', DEFAULT_ICON_COMP_ID);
|
||||
|
||||
for (const child of cs.children) {
|
||||
const iconSlot = child.findOne(n => n.name === 'icon');
|
||||
if (iconSlot && iconSlot.type === 'INSTANCE') {
|
||||
iconSlot.componentPropertyReferences = { mainComponent: iconKey };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Use INSTANCE_SWAP instead of creating a variant per icon.** Never add "Icon=ChevronRight, Icon=ChevronLeft, ..." as VARIANT axes — that causes combinatorial explosion. One INSTANCE_SWAP property covers all icons.
|
||||
|
||||
### Creating Icon Components for INSTANCE_SWAP
|
||||
|
||||
INSTANCE_SWAP needs a real Component ID as its default value. Before wiring INSTANCE_SWAP, you need at least one icon component. Here's how to create icons from SVG:
|
||||
|
||||
```javascript
|
||||
// Create a simple icon component from SVG
|
||||
const svgNode = figma.createNodeFromSvg(
|
||||
'<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">' +
|
||||
'<path d="M9 18l6-6-6-6" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>' +
|
||||
'</svg>'
|
||||
);
|
||||
|
||||
// Wrap in a component
|
||||
const iconComp = figma.createComponent();
|
||||
iconComp.name = 'Icon/ChevronRight';
|
||||
iconComp.resize(24, 24);
|
||||
iconComp.clipsContent = true;
|
||||
|
||||
// Move SVG children into the component
|
||||
for (const child of [...svgNode.children]) {
|
||||
iconComp.appendChild(child);
|
||||
}
|
||||
svgNode.remove();
|
||||
|
||||
// Bind the icon fill to a color variable (so it respects themes)
|
||||
// Find vector children and bind their fills
|
||||
iconComp.findAll(n => n.type === 'VECTOR').forEach(vec => {
|
||||
// For stroke-based icons:
|
||||
if (vec.strokes.length > 0) {
|
||||
const strokePaint = figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', iconColorVar
|
||||
);
|
||||
vec.strokes = [strokePaint];
|
||||
}
|
||||
});
|
||||
|
||||
iconComp.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
iconComp.setSharedPluginData('dsb', 'key', 'icon/chevron-right');
|
||||
|
||||
return { iconCompId: iconComp.id };
|
||||
```
|
||||
|
||||
**Then use the returned `iconCompId` as the default value for INSTANCE_SWAP:**
|
||||
```javascript
|
||||
const iconKey = cs.addComponentProperty('Icon', 'INSTANCE_SWAP', ICON_COMP_ID);
|
||||
```
|
||||
|
||||
**Constraining swap options with `preferredValues`:**
|
||||
After adding the INSTANCE_SWAP property, you can optionally limit which components appear in the swap picker:
|
||||
```javascript
|
||||
// Get the property definitions to find the exact key
|
||||
const props = cs.componentPropertyDefinitions;
|
||||
const iconPropKey = Object.keys(props).find(k => k.startsWith('Icon'));
|
||||
|
||||
// Set preferred values (array of component keys or instance IDs)
|
||||
cs.editComponentProperty(iconPropKey, {
|
||||
preferredValues: [
|
||||
{ type: 'COMPONENT', key: chevronRightComp.key },
|
||||
{ type: 'COMPONENT', key: chevronLeftComp.key },
|
||||
{ type: 'COMPONENT', key: closeComp.key },
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
**Icon library tip:** Create all icon components on a dedicated `Icons` page before building any UI components. Then reference their IDs when wiring INSTANCE_SWAP properties.
|
||||
|
||||
### `componentPropertyReferences` mapping
|
||||
|
||||
The `componentPropertyReferences` object maps a node's own property to a component property key:
|
||||
|
||||
| Node property | Component property type | Used for |
|
||||
|---|---|---|
|
||||
| `characters` | TEXT | Editable text content |
|
||||
| `visible` | BOOLEAN | Show/hide toggle |
|
||||
| `mainComponent` | INSTANCE_SWAP | Swap nested instances |
|
||||
|
||||
---
|
||||
|
||||
## 7. `sharedPluginData` Tagging for Idempotency
|
||||
|
||||
Tag EVERY created node immediately after creation. This enables safe cleanup, resumability, and idempotency checks.
|
||||
|
||||
```javascript
|
||||
// After creating any node:
|
||||
node.setSharedPluginData('dsb', 'run_id', RUN_ID); // identifies the build run
|
||||
node.setSharedPluginData('dsb', 'phase', 'phase3'); // which phase created it
|
||||
node.setSharedPluginData('dsb', 'key', KEY); // unique logical key for this entity
|
||||
|
||||
// Reading back:
|
||||
const runId = node.getSharedPluginData('dsb', 'run_id'); // '' if not set
|
||||
const key = node.getSharedPluginData('dsb', 'key');
|
||||
```
|
||||
|
||||
**Key naming convention:** use `/`-separated logical paths that mirror the entity hierarchy:
|
||||
```
|
||||
'component/button/base'
|
||||
'component/button/variant/Medium/Primary/Default'
|
||||
'componentset/button'
|
||||
'doc/button'
|
||||
'page/button'
|
||||
```
|
||||
|
||||
**Idempotency check before creating:** before creating a node, scan the current page for an existing node with the same `key`:
|
||||
|
||||
```javascript
|
||||
const existing = figma.currentPage.findAll(n =>
|
||||
n.getSharedPluginData('dsb', 'key') === 'componentset/button'
|
||||
);
|
||||
if (existing.length > 0) {
|
||||
// Skip creation — already done. Return existing node's ID.
|
||||
return { componentSetId: existing[0].id };
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Documentation
|
||||
|
||||
### Page title + description frame
|
||||
|
||||
The documentation frame (see Section 2) should contain:
|
||||
1. Component name as a large title (32px+ Bold)
|
||||
2. 1–3 sentence description of what the component is and when to use it
|
||||
3. Spec notes (sizes, spacing values, accessibility notes)
|
||||
|
||||
### Component `description` property
|
||||
|
||||
Set the description on the ComponentSet — it appears in the Figma properties panel and is exported as documentation:
|
||||
|
||||
```javascript
|
||||
cs.description = 'Buttons allow users to take actions and make choices. Use Primary for the highest-emphasis action on a page.';
|
||||
```
|
||||
|
||||
### `documentationLinks`
|
||||
|
||||
Link to external documentation (Storybook, design spec, tokens reference):
|
||||
|
||||
```javascript
|
||||
cs.documentationLinks = [
|
||||
{ uri: 'https://your-storybook.com/button' }
|
||||
];
|
||||
```
|
||||
|
||||
### Node names and organization
|
||||
|
||||
- ComponentSet: plain component name — `'Button'`
|
||||
- Individual variants: `'Property=Value, Property=Value'` format (match the file's existing casing)
|
||||
- Child nodes: semantic names — `'label'`, `'icon'`, `'container'`, `'state-layer'`
|
||||
- Documentation frames: `'ComponentName / Documentation'`
|
||||
|
||||
---
|
||||
|
||||
## 9. Validation
|
||||
|
||||
Always validate after creating or modifying a component before proceeding to the next one.
|
||||
|
||||
### `get_metadata` structural checks
|
||||
|
||||
After creating the component set, call `get_metadata` on the ComponentSet node and verify:
|
||||
- `variantGroupProperties` lists the expected axes with the correct value arrays
|
||||
- `componentPropertyDefinitions` contains the expected TEXT/BOOLEAN/INSTANCE_SWAP properties
|
||||
- `children.length` equals the expected variant count (e.g., 18 for 3×2×3)
|
||||
- No children are named `'Component 1'` (unnamed components are a sign of a bug)
|
||||
|
||||
### `get_screenshot` — Visual Validation (Critical)
|
||||
|
||||
`get_screenshot` returns an **image** of the specified node. Call it on the **component page node** (not the component set) to see the full page including documentation and grid labels.
|
||||
|
||||
```
|
||||
Tool: get_screenshot
|
||||
Args: { nodeId: "PAGE_NODE_ID", fileKey: "FILE_KEY" }
|
||||
```
|
||||
|
||||
**How to use the screenshot:**
|
||||
|
||||
1. **Display it to the user** — this is the primary purpose. Show the screenshot as part of the user checkpoint: "Here's the Button component. Does it look right?"
|
||||
2. **Analyze it yourself** — if you have vision capabilities, check the visual checklist below. If you don't (text-only agent), fall back to structural validation only via `get_metadata` and describe what you created textually.
|
||||
|
||||
**Visual validation checklist** (check each item when viewing the screenshot):
|
||||
|
||||
| # | Check | What "good" looks like | What "broken" looks like |
|
||||
|---|-------|----------------------|------------------------|
|
||||
| 1 | **Grid layout** | Variants in neat rows and columns with consistent spacing | All variants piled at top-left (0,0 stacking bug) |
|
||||
| 2 | **Color fills** | Components show distinct, correct colors per style variant | All components are black or same color (variable binding failed) |
|
||||
| 3 | **Size differentiation** | Small variants are visibly smaller than Large variants | All variants are the same size (height/padding not bound to variables) |
|
||||
| 4 | **Text readability** | Labels are visible with correct font and color | Text is invisible (white on white), missing, or shows "undefined" |
|
||||
| 5 | **Spacing/padding** | Interior padding visible, components aren't "shrink-wrapped" | Components look cramped or have no visible internal space |
|
||||
| 6 | **State differentiation** | Hover/Pressed variants have visible color differences from Default | All states look identical (state-specific fills not applied) |
|
||||
| 7 | **Disabled state** | Lower opacity or muted colors compared to active states | Disabled looks identical to Default |
|
||||
| 8 | **Documentation frame** | Title + description text visible above or beside the component grid | No documentation, or it overlaps the component set |
|
||||
| 9 | **Grid labels** | Row/column headers visible around the component set (if added) | Labels overlap the grid or are missing |
|
||||
| 10 | **Component set boundary** | Gray background frame wraps all variants with even padding | Frame is too small (variants clipped) or way too large |
|
||||
|
||||
**Screenshot → diagnosis → fix mapping:**
|
||||
|
||||
| Screenshot shows | Diagnosis | Fix script |
|
||||
|-----------------|-----------|------------|
|
||||
| All variants stacked top-left | Grid layout wasn't applied after `combineAsVariants` | Re-run the grid layout script (§5) |
|
||||
| Everything black/same color | Variable bindings failed or variables don't have values for the active mode | Re-run variable binding, check mode values |
|
||||
| No text visible | Font wasn't loaded, or text fill is same color as background | Check `loadFontAsync` was called; bind text fill to `color/text/*` variable |
|
||||
| Variants all same size | Padding/height not bound to size variables | Re-run `bindVariablesToComponent` with size-specific tokens |
|
||||
| Component set frame tiny | `resizeWithoutConstraints` wasn't called or used wrong dimensions | Re-calculate bounds from children and resize |
|
||||
| Doc frame overlaps components | Component set positioned at same x,y as doc frame | Move component set: `cs.x = docFrame.x + docFrame.width + 60` |
|
||||
|
||||
**When visual analysis isn't available:**
|
||||
If your model can't process images (text-only mode), validate structurally instead:
|
||||
1. Call `get_metadata` on the component set — verify child count, property definitions, variant names
|
||||
2. Run an `use_figma` that samples key properties:
|
||||
```javascript
|
||||
const cs = await figma.getNodeByIdAsync(CS_ID);
|
||||
const sample = cs.children.slice(0, 3).map(c => ({
|
||||
name: c.name,
|
||||
width: c.width, height: c.height,
|
||||
x: c.x, y: c.y,
|
||||
fills: c.fills?.map(f => f.type === 'SOLID' ?
|
||||
{ r: f.color.r.toFixed(2), g: f.color.g.toFixed(2), b: f.color.b.toFixed(2), boundVar: f.boundVariables?.color?.id } : f.type
|
||||
),
|
||||
}));
|
||||
return { sampleVariants: sample, totalChildren: cs.children.length };
|
||||
```
|
||||
This gives you positions (grid working?), dimensions (size differentiation?), and fill info (bindings working?) without needing vision.
|
||||
|
||||
**When to take a screenshot:**
|
||||
- After EVERY completed component (mandatory — part of the user checkpoint)
|
||||
- After creating the foundations documentation page
|
||||
- After final QA (screenshot every page)
|
||||
- Do NOT screenshot after every intermediate step (wastes tool calls)
|
||||
|
||||
### Common issues
|
||||
|
||||
| Symptom | Likely cause | Fix |
|
||||
|---|---|---|
|
||||
| All variants stacked at (0,0) | `combineAsVariants` was called but children were never repositioned | Re-run grid layout script |
|
||||
| Variants show wrong colors | Variable bindings applied after `combineAsVariants` instead of before | Rebind on component set children |
|
||||
| Variant count wrong | Clone loop indexing error | Print `components.map(c => c.name)` before combining |
|
||||
| BOOLEAN property has no effect | `componentPropertyReferences` was set on the component set frame, not on the child node | Find the actual child node and set references there |
|
||||
| INSTANCE_SWAP shows no swap option | Default value was not a valid component ID | Pass a real existing component ID as `defaultValue` |
|
||||
| `combineAsVariants` throws | At least one node in the array is not a `ComponentNode` | Filter array: `nodes.filter(n => n.type === 'COMPONENT')` |
|
||||
| `addComponentProperty` returns unexpected key | Expected — the key gets a `#id:id` suffix | Save the returned value immediately: `const key = cs.addComponentProperty(...)` |
|
||||
|
||||
---
|
||||
|
||||
## 10. Complete Worked Example: Button Component
|
||||
|
||||
This shows the full sequence of `use_figma` calls for a Button component, including state passing between calls. Replace `RUN_ID` and variable IDs with your actual values from the state ledger.
|
||||
|
||||
### Call 1: Create the component page
|
||||
|
||||
**Goal:** Create (or find) the Button page.
|
||||
**State input:** None
|
||||
**State output:** `{ pageId }`
|
||||
|
||||
```javascript
|
||||
let page = figma.root.children.find(p => p.name === 'Button');
|
||||
if (!page) { page = figma.createPage(); page.name = 'Button'; }
|
||||
page.setSharedPluginData('dsb', 'run_id', 'ds-build-2024-001');
|
||||
page.setSharedPluginData('dsb', 'key', 'page/button');
|
||||
return { pageId: page.id };
|
||||
```
|
||||
|
||||
### Call 2: Create documentation frame
|
||||
|
||||
**Goal:** Add title + description frame.
|
||||
**State input:** `{ pageId }`
|
||||
**State output:** `{ docFrameId }`
|
||||
|
||||
```javascript
|
||||
const PAGE_ID = 'PAGE_ID_FROM_STATE';
|
||||
const page = await figma.getNodeByIdAsync(PAGE_ID);
|
||||
await figma.setCurrentPageAsync(page);
|
||||
|
||||
// Idempotency check
|
||||
const existing = page.findAll(n => n.getSharedPluginData('dsb', 'key') === 'doc/button');
|
||||
if (existing.length > 0) {
|
||||
return { docFrameId: existing[0].id };
|
||||
}
|
||||
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
|
||||
|
||||
const docFrame = figma.createFrame();
|
||||
docFrame.name = 'Button / Documentation';
|
||||
docFrame.x = 40; docFrame.y = 40;
|
||||
docFrame.layoutMode = 'VERTICAL';
|
||||
docFrame.primaryAxisSizingMode = 'AUTO';
|
||||
docFrame.counterAxisSizingMode = 'FIXED';
|
||||
docFrame.resize(560, 100);
|
||||
docFrame.paddingTop = 40; docFrame.paddingBottom = 40;
|
||||
docFrame.paddingLeft = 40; docFrame.paddingRight = 40;
|
||||
docFrame.itemSpacing = 16;
|
||||
docFrame.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
|
||||
|
||||
const title = figma.createText();
|
||||
title.fontName = { family: 'Inter', style: 'Bold' };
|
||||
title.fontSize = 32;
|
||||
title.characters = 'Button';
|
||||
docFrame.appendChild(title);
|
||||
|
||||
const desc = figma.createText();
|
||||
desc.fontName = { family: 'Inter', style: 'Regular' };
|
||||
desc.fontSize = 14;
|
||||
desc.characters = 'Buttons allow users to take actions with a single tap. Use Primary for the highest-emphasis action on a page, Secondary for supporting actions.';
|
||||
desc.layoutSizingHorizontal = 'FILL';
|
||||
docFrame.appendChild(desc);
|
||||
|
||||
docFrame.setSharedPluginData('dsb', 'run_id', 'ds-build-2024-001');
|
||||
docFrame.setSharedPluginData('dsb', 'key', 'doc/button');
|
||||
|
||||
return { docFrameId: docFrame.id };
|
||||
```
|
||||
|
||||
### Call 3: Create base component
|
||||
|
||||
**Goal:** Create the base component with auto-layout and all variable bindings.
|
||||
**State input:** `{ pageId }` + variable IDs from Phase 1
|
||||
**State output:** `{ baseCompId }`
|
||||
|
||||
*(See Section 3 for full code — substituting the actual variable IDs from the state ledger.)*
|
||||
|
||||
### Call 4: Create all variants
|
||||
|
||||
**Goal:** Clone base and produce all 18 variants (3 Size × 2 Style × 3 State).
|
||||
**State input:** `{ pageId, baseCompId }` + variable IDs
|
||||
**State output:** `{ variantIds: ['id1', 'id2', ..., 'id18'] }`
|
||||
|
||||
```javascript
|
||||
const RUN_ID = 'ds-build-2024-001';
|
||||
const BASE_ID = 'BASE_COMP_ID_FROM_STATE';
|
||||
const PAGE_ID = 'PAGE_ID_FROM_STATE';
|
||||
// Variable IDs from state ledger:
|
||||
const VAR = {
|
||||
bg_primary: 'VAR_ID_1',
|
||||
text_primary: 'VAR_ID_2',
|
||||
bg_secondary: 'VAR_ID_3',
|
||||
text_secondary: 'VAR_ID_4',
|
||||
bg_disabled: 'VAR_ID_5',
|
||||
text_disabled: 'VAR_ID_6',
|
||||
padding_sm: 'VAR_ID_7',
|
||||
padding_md: 'VAR_ID_8',
|
||||
padding_lg: 'VAR_ID_9',
|
||||
};
|
||||
|
||||
const page = await figma.getNodeByIdAsync(PAGE_ID);
|
||||
await figma.setCurrentPageAsync(page);
|
||||
|
||||
const base = await figma.getNodeByIdAsync(BASE_ID);
|
||||
|
||||
// Load all variables
|
||||
const vars = {};
|
||||
for (const [k, v] of Object.entries(VAR)) {
|
||||
vars[k] = await figma.variables.getVariableByIdAsync(v);
|
||||
}
|
||||
|
||||
const axes = {
|
||||
Size: ['Small', 'Medium', 'Large'],
|
||||
Style: ['Primary', 'Secondary'],
|
||||
State: ['Default', 'Hover', 'Disabled'],
|
||||
};
|
||||
const paddingMap = { Small: vars.padding_sm, Medium: vars.padding_md, Large: vars.padding_lg };
|
||||
|
||||
const components = [];
|
||||
for (const size of axes.Size) {
|
||||
for (const style of axes.Style) {
|
||||
for (const state of axes.State) {
|
||||
const clone = base.clone();
|
||||
clone.name = `Size=${size}, Style=${style}, State=${state}`;
|
||||
|
||||
clone.setBoundVariable('paddingTop', paddingMap[size]);
|
||||
clone.setBoundVariable('paddingBottom', paddingMap[size]);
|
||||
clone.setBoundVariable('paddingLeft', paddingMap[size]);
|
||||
clone.setBoundVariable('paddingRight', paddingMap[size]);
|
||||
|
||||
const isDisabled = state === 'Disabled';
|
||||
const bgV = isDisabled ? vars.bg_disabled : (style === 'Primary' ? vars.bg_primary : vars.bg_secondary);
|
||||
const txV = isDisabled ? vars.text_disabled : (style === 'Primary' ? vars.text_primary : vars.text_secondary);
|
||||
|
||||
clone.fills = [figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', bgV
|
||||
)];
|
||||
|
||||
const labelNode = clone.findOne(n => n.name === 'label');
|
||||
labelNode.fills = [figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }, 'color', txV
|
||||
)];
|
||||
|
||||
clone.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
clone.setSharedPluginData('dsb', 'key', `component/button/variant/${size}/${style}/${state}`);
|
||||
components.push(clone);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return { variantIds: components.map(c => c.id) };
|
||||
```
|
||||
|
||||
### Call 5: combineAsVariants + grid layout
|
||||
|
||||
**Goal:** Combine all 18 variants into a ComponentSet and lay them out in a grid.
|
||||
**State input:** `{ pageId, variantIds }` (18 IDs)
|
||||
**State output:** `{ componentSetId }`
|
||||
|
||||
*(See Section 5 for full code.)*
|
||||
|
||||
### Call 6: Add component properties
|
||||
|
||||
**Goal:** Add TEXT, BOOLEAN, INSTANCE_SWAP properties and wire them to child nodes.
|
||||
**State input:** `{ pageId, componentSetId }`
|
||||
**State output:** `{ componentSetId, properties: { labelKey, showIconKey, iconKey } }`
|
||||
|
||||
```javascript
|
||||
const CS_ID = 'CS_ID_FROM_STATE';
|
||||
const DEFAULT_ICON_ID = 'ICON_COMP_ID_FROM_STATE';
|
||||
const page = figma.root.children.find(p => p.name === 'Button');
|
||||
await figma.setCurrentPageAsync(page);
|
||||
|
||||
const cs = await figma.getNodeByIdAsync(CS_ID);
|
||||
cs.description = 'Buttons allow users to take actions and make choices with a single tap.';
|
||||
cs.documentationLinks = [{ uri: 'https://your-storybook.com/button' }];
|
||||
|
||||
// Add properties — save returned keys
|
||||
const labelKey = cs.addComponentProperty('Label', 'TEXT', 'Button');
|
||||
const showIconKey = cs.addComponentProperty('Show Icon', 'BOOLEAN', true);
|
||||
const iconKey = cs.addComponentProperty('Icon', 'INSTANCE_SWAP', DEFAULT_ICON_ID);
|
||||
|
||||
// Wire to children
|
||||
for (const child of cs.children) {
|
||||
const labelNode = child.findOne(n => n.name === 'label');
|
||||
if (labelNode) labelNode.componentPropertyReferences = { characters: labelKey };
|
||||
|
||||
const iconNode = child.findOne(n => n.name === 'icon');
|
||||
if (iconNode) {
|
||||
iconNode.componentPropertyReferences = {
|
||||
visible: showIconKey,
|
||||
...(iconNode.type === 'INSTANCE' ? { mainComponent: iconKey } : {}),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
componentSetId: cs.id,
|
||||
properties: { labelKey, showIconKey, iconKey },
|
||||
};
|
||||
```
|
||||
|
||||
### Call 7: Validate with get_metadata
|
||||
|
||||
**Goal:** Structural check — variant count, properties, axes.
|
||||
**Action:** Call `get_metadata` on the ComponentSet node ID (from state). Verify in the result:
|
||||
- `children.length === 18`
|
||||
- `variantGroupProperties` has `Size`, `Style`, `State` keys with correct value arrays
|
||||
- `componentPropertyDefinitions` has `Label`, `Show Icon`, `Icon` entries
|
||||
|
||||
### Call 8: Validate with get_screenshot
|
||||
|
||||
**Goal:** Visual check — layout, colors, text.
|
||||
**Action:** Call `get_screenshot` on the Button page. Inspect the screenshot. If variants are stacked, re-run Call 5. If colors look wrong, inspect variable bindings.
|
||||
|
||||
### Checkpoint
|
||||
|
||||
After Call 8: show the screenshot to the user. Ask: "Here's the Button component with 18 variants. Does this look correct?" Do not proceed to the next component until the user approves.
|
||||
+494
@@ -0,0 +1,494 @@
|
||||
> Part of the [figma-generate-library skill](../SKILL.md).
|
||||
|
||||
# Discovery Phase Reference
|
||||
|
||||
This document covers everything needed for Phase 0 of a design system build: analyzing the codebase for tokens, inspecting the Figma file for existing conventions, searching subscribed libraries, building the plan, and resolving conflicts before any write operations begin.
|
||||
|
||||
---
|
||||
|
||||
## 1. Codebase Analysis — Finding Token Sources
|
||||
|
||||
### Search Priority Order
|
||||
|
||||
Look for token sources in this order. Stop as soon as you find a definitive source; multiple formats can coexist:
|
||||
|
||||
1. Design token files: `*.tokens.json`, `tokens/*.json`, `src/tokens/**`
|
||||
2. CSS variable files: `variables.css`, `tokens.css`, `theme.css`, `global.css`
|
||||
3. Tailwind config: `tailwind.config.js`, `tailwind.config.ts`
|
||||
4. CSS-in-JS theme objects: `theme.ts`, `createTheme`, `ThemeProvider`
|
||||
5. Platform-specific: iOS Asset catalogs (`.xcassets`), Android `themes.xml`, `colors.xml`
|
||||
|
||||
### CSS Custom Properties (Most Common for Web)
|
||||
|
||||
**What to search for:**
|
||||
|
||||
```
|
||||
:root { ... }
|
||||
@theme { ... } ← Tailwind v4
|
||||
--color-*, --spacing-*, --radius-*, --shadow-*, --font-*
|
||||
```
|
||||
|
||||
**Pattern:** `/--[\w-]+:\s*[^;]+/g`
|
||||
|
||||
**Common file locations:** `src/styles/tokens.css`, `src/styles/variables.css`, `src/theme/*.css`
|
||||
|
||||
**Extraction and naming translation:**
|
||||
|
||||
| CSS Property | Figma Variable Name | Figma Type | WEB Code Syntax |
|
||||
|---|---|---|---|
|
||||
| `--color-bg-primary: #fff` | `color/bg/primary` | COLOR | `var(--color-bg-primary)` |
|
||||
| `--color-text-secondary: #757575` | `color/text/secondary` | COLOR | `var(--color-text-secondary)` |
|
||||
| `--spacing-sm: 8px` | `spacing/sm` | FLOAT | `var(--spacing-sm)` |
|
||||
| `--radius-md: 8px` | `radius/md` | FLOAT | `var(--radius-md)` |
|
||||
| `--font-body: "Inter"` | `typography/body/font-family` | STRING | `var(--font-body)` |
|
||||
|
||||
**Naming rule:** Replace hyphens with slashes at category boundaries. Keep hyphens within the final path segment: `--color-bg-primary` → `color/bg/primary`, but `--color-bg-primary-hover` → `color/bg/primary-hover`.
|
||||
|
||||
**Always store the original CSS variable name** as the code syntax value — never derive it from the Figma variable name. If the codebase uses `--sds-color-background-brand-default`, use exactly that string in `setVariableCodeSyntax('WEB', '--sds-color-background-brand-default')`.
|
||||
|
||||
### Tailwind Configuration
|
||||
|
||||
**What to look for in `tailwind.config.js` or `tailwind.config.ts`:**
|
||||
|
||||
```javascript
|
||||
// theme.extend.colors → Figma color variables
|
||||
{ primary: { DEFAULT: '#3366FF', light: '#6699FF', dark: '#0033CC' } }
|
||||
// → color/primary/default, color/primary/light, color/primary/dark
|
||||
|
||||
// theme.extend.spacing → Figma FLOAT variables
|
||||
{ 'xs': '4px', 'sm': '8px', 'md': '16px' }
|
||||
// → spacing/xs = 4, spacing/sm = 8, spacing/md = 16
|
||||
|
||||
// theme.extend.borderRadius → Figma FLOAT variables
|
||||
{ 'sm': '4px', 'md': '8px', 'lg': '16px' }
|
||||
// → radius/sm = 4, radius/md = 8, radius/lg = 16
|
||||
```
|
||||
|
||||
Tailwind utility class names (`bg-blue-500`, `p-4`) are not tokens — extract values from the config object, not the class names.
|
||||
|
||||
### Design Token Community Group (DTCG) Format
|
||||
|
||||
**Pattern:** `*.tokens.json` or `tokens/*.json`. Find source files, not generated outputs from Style Dictionary or Tokens Studio.
|
||||
|
||||
```json
|
||||
{
|
||||
"color": {
|
||||
"bg": {
|
||||
"primary": { "$type": "color", "$value": "#ffffff" },
|
||||
"secondary": { "$type": "color", "$value": "#f5f5f5" }
|
||||
}
|
||||
},
|
||||
"spacing": {
|
||||
"sm": { "$type": "dimension", "$value": "8px" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Nested keys map to slash-separated Figma names: `color.bg.primary` → `color/bg/primary`.
|
||||
|
||||
### CSS-in-JS / Theme Objects
|
||||
|
||||
**What to search for:** `createTheme`, `ThemeProvider`, `theme = {}`, styled-components, Emotion, Stitches, vanilla-extract
|
||||
|
||||
```typescript
|
||||
// theme.colors.bg.primary → Figma variable: color/bg/primary
|
||||
// theme.spacing.sm → Figma variable: spacing/sm
|
||||
// Multiple theme objects (lightTheme, darkTheme) → modes in the same collection
|
||||
```
|
||||
|
||||
### iOS Token Sources
|
||||
|
||||
```swift
|
||||
// Asset catalog colors in .xcassets/Colors.xcassets
|
||||
// extension Color { static let bgPrimary = Color("bg-primary") }
|
||||
// Look for traitCollection.userInterfaceStyle for dark mode detection
|
||||
```
|
||||
|
||||
### Android Token Sources
|
||||
|
||||
```kotlin
|
||||
// res/values/colors.xml <color name="primary">#3366FF</color>
|
||||
// res/values-night/colors.xml (dark mode overrides)
|
||||
// MaterialTheme.colorScheme.primary in Compose
|
||||
// val Primary = Color(0xFF3366FF)
|
||||
```
|
||||
|
||||
### Detecting Dark Mode
|
||||
|
||||
| Platform | Signal |
|
||||
|---|---|
|
||||
| Web (CSS) | `@media (prefers-color-scheme: dark)`, `.dark { }`, `[data-theme="dark"]` |
|
||||
| Web (Tailwind) | `darkMode: 'class'` or `darkMode: 'media'` in config |
|
||||
| Web (JS) | Separate `darkTheme` object alongside `lightTheme` |
|
||||
| iOS | `Color(uiColor:)` with `traitCollection.userInterfaceStyle`, dual-appearance asset catalog |
|
||||
| Android | `themes.xml` with `Theme.*.Night`, `isSystemInDarkTheme()` in Compose, `values-night/` folder |
|
||||
|
||||
**Figma mapping:** If dark mode exists → minimum 2 modes (Light/Dark) in the semantic color collection. Primitive collections stay single-mode.
|
||||
|
||||
### Shadow/Elevation Extraction
|
||||
|
||||
Shadows cannot be Figma variables — they become **Effect Styles**.
|
||||
|
||||
```css
|
||||
/* Look for: box-shadow, --shadow-* */
|
||||
--shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
|
||||
--shadow-md: 0 4px 6px -1px rgba(0,0,0,0.10);
|
||||
--shadow-lg: 0 10px 15px -3px rgba(0,0,0,0.10);
|
||||
```
|
||||
|
||||
CSS `0 4px 6px -1px rgba(0,0,0,0.1)` → Figma:
|
||||
```
|
||||
{ type: "DROP_SHADOW", offset: {x:0, y:4}, radius: 6, spread: -1, color: {r:0, g:0, b:0, a:0.1} }
|
||||
```
|
||||
|
||||
### Typography Extraction
|
||||
|
||||
| Code token | Maps to |
|
||||
|---|---|
|
||||
| `font-size: 16px` | FLOAT variable (scope `FONT_SIZE`) or Text Style `fontSize` |
|
||||
| `line-height: 1.5` | Text Style `lineHeight: {value: 24, unit: "PIXELS"}` |
|
||||
| `font-weight: 600` | Text Style `fontName: {family: "Inter", style: "Semi Bold"}` |
|
||||
| `letter-spacing: -0.02em` | Text Style `letterSpacing: {value: -2, unit: "PERCENT"}` |
|
||||
| `font-family: "Inter"` | STRING variable (scope `FONT_FAMILY`) or Text Style `fontName.family` |
|
||||
|
||||
Composite text styles (all properties bundled) → Figma Text Styles. Individual properties → Figma variables with appropriate scopes.
|
||||
|
||||
### Component Extraction
|
||||
|
||||
For each component, extract:
|
||||
|
||||
1. **Name** → Figma component set name
|
||||
2. **Union-type props** → VARIANT properties
|
||||
3. **String content props** → TEXT properties
|
||||
4. **Boolean props** → BOOLEAN properties (and VARIANT State when combined with interaction states)
|
||||
5. **Child/slot props** → INSTANCE_SWAP properties
|
||||
|
||||
```typescript
|
||||
// React example:
|
||||
interface ButtonProps {
|
||||
size: 'sm' | 'md' | 'lg'; // → VARIANT: Size = sm|md|lg
|
||||
variant: 'primary' | 'secondary'; // → VARIANT: Style = primary|secondary
|
||||
disabled?: boolean; // → VARIANT: State (combine: default|hover|pressed|disabled)
|
||||
label: string; // → TEXT: Label
|
||||
icon?: ReactNode; // → INSTANCE_SWAP: Icon + BOOLEAN: Show Icon
|
||||
}
|
||||
// → Component Set "Button", variant count: 3 sizes × 2 styles × 4 states = 24
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Figma File Inspection
|
||||
|
||||
Run these `use_figma` snippets at the start of every build. All are read-only and safe to run before any user checkpoint.
|
||||
|
||||
### List All Pages
|
||||
|
||||
```javascript
|
||||
const pages = figma.root.children.map((p, i) => ({
|
||||
index: i,
|
||||
name: p.name,
|
||||
id: p.id,
|
||||
childCount: p.children.length
|
||||
}));
|
||||
return { pages };
|
||||
```
|
||||
|
||||
Interpret: note page names for naming convention (are they PascalCase? sentence case?), count separator pages (`---`), identify existing component pages vs foundations pages.
|
||||
|
||||
### List Variable Collections With Modes
|
||||
|
||||
```javascript
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
const result = collections.map(c => ({
|
||||
id: c.id,
|
||||
name: c.name,
|
||||
modes: c.modes, // [{modeId, name}, ...]
|
||||
variableCount: c.variableIds.length,
|
||||
defaultModeId: c.defaultModeId
|
||||
}));
|
||||
return { collections: result };
|
||||
```
|
||||
|
||||
Interpret: identify existing primitive/semantic split, note mode names (do they use "Light/Dark" or "SDS Light/SDS Dark"?), count variables to understand scope.
|
||||
|
||||
### List Variables in a Collection (with names, types, scopes, and sample values)
|
||||
|
||||
```javascript
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
const targetName = "Color"; // change to the collection you want to inspect
|
||||
const coll = collections.find(c => c.name === targetName);
|
||||
if (!coll) { return { error: `Collection "${targetName}" not found` }; }
|
||||
|
||||
const allVars = await figma.variables.getLocalVariablesAsync();
|
||||
const vars = allVars.filter(v => v.variableCollectionId === coll.id);
|
||||
|
||||
const result = vars.map(v => ({
|
||||
id: v.id,
|
||||
name: v.name,
|
||||
resolvedType: v.resolvedType,
|
||||
scopes: v.scopes,
|
||||
codeSyntax: v.codeSyntax,
|
||||
// First mode value only, for a sample
|
||||
sampleValue: v.valuesByMode[coll.defaultModeId]
|
||||
}));
|
||||
|
||||
return { collection: coll.name, variableCount: result.length, variables: result };
|
||||
```
|
||||
|
||||
Interpret: check if variables use `ALL_SCOPES` (bad), check naming convention (slash-separated hierarchy?), check if code syntax is set, identify alias chains.
|
||||
|
||||
### List Component Sets with Properties
|
||||
|
||||
```javascript
|
||||
await figma.setCurrentPageAsync(figma.currentPage); // ensures page context
|
||||
const componentSets = figma.currentPage.findAll(n => n.type === 'COMPONENT_SET');
|
||||
const result = componentSets.map(cs => ({
|
||||
id: cs.id,
|
||||
name: cs.name,
|
||||
variantCount: cs.children.length,
|
||||
properties: Object.entries(cs.componentPropertyDefinitions).map(([key, def]) => ({
|
||||
name: key,
|
||||
type: def.type,
|
||||
variantOptions: def.variantOptions || null,
|
||||
defaultValue: def.defaultValue
|
||||
}))
|
||||
}));
|
||||
return { componentSets: result, count: result.length };
|
||||
```
|
||||
|
||||
Note: to search ALL pages, iterate `figma.root.children` and `setCurrentPageAsync` for each.
|
||||
|
||||
### List All Styles
|
||||
|
||||
```javascript
|
||||
const [textStyles, effectStyles, paintStyles] = await Promise.all([
|
||||
figma.getLocalTextStylesAsync(),
|
||||
figma.getLocalEffectStylesAsync(),
|
||||
figma.getLocalPaintStylesAsync()
|
||||
]);
|
||||
|
||||
return {
|
||||
textStyles: textStyles.map(s => ({ id: s.id, name: s.name, fontSize: s.fontSize, fontName: s.fontName })),
|
||||
effectStyles: effectStyles.map(s => ({ id: s.id, name: s.name, effectCount: s.effects.length })),
|
||||
paintStyles: paintStyles.map(s => ({ id: s.id, name: s.name })),
|
||||
counts: { text: textStyles.length, effect: effectStyles.length, paint: paintStyles.length }
|
||||
};
|
||||
```
|
||||
|
||||
### Check Naming Conventions on an Existing Component
|
||||
|
||||
```javascript
|
||||
// Replace with the node ID of an existing component to analyze
|
||||
const node = await figma.getNodeByIdAsync("YOUR_NODE_ID");
|
||||
if (!node) { return { error: "Node not found" }; }
|
||||
|
||||
// Check fills for variable bindings
|
||||
const fillInfo = [];
|
||||
if ('fills' in node && Array.isArray(node.fills)) {
|
||||
for (const fill of node.fills) {
|
||||
if (fill.type === 'SOLID' && fill.boundVariables?.color) {
|
||||
fillInfo.push({ type: 'variable_alias', id: fill.boundVariables.color.id });
|
||||
} else if (fill.type === 'SOLID') {
|
||||
fillInfo.push({ type: 'hardcoded', r: fill.color.r, g: fill.color.g, b: fill.color.b });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
name: node.name,
|
||||
type: node.type,
|
||||
fills: fillInfo,
|
||||
sharedPluginData: node.getSharedPluginData('dsb', 'key') || null
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Using search_design_system
|
||||
|
||||
### What It Searches
|
||||
|
||||
`search_design_system` runs three parallel searches against **subscribed design libraries** for the given file:
|
||||
|
||||
1. **Components** — published library components, searched by name/description via a recommendation engine (relevance-ranked, not exact match)
|
||||
2. **Variables** — design tokens (colors, spacing, etc.) across subscribed libraries
|
||||
3. **Styles** — paint styles, text styles, and effect styles
|
||||
|
||||
Only libraries the file has subscribed to are searched. If results are empty, the file may not be subscribed to any design system libraries.
|
||||
|
||||
### Input
|
||||
|
||||
```
|
||||
search_design_system({
|
||||
query: "button", // required — text query
|
||||
fileKey: "abc123", // required — your file key
|
||||
includeComponents: true, // default true
|
||||
includeVariables: true, // default true
|
||||
includeStyles: true // default true
|
||||
})
|
||||
```
|
||||
|
||||
### What It Returns
|
||||
|
||||
```json
|
||||
{
|
||||
"components": [
|
||||
{
|
||||
"name": "Button",
|
||||
"libraryName": "Design System",
|
||||
"assetType": "component_set",
|
||||
"componentKey": "abc123def",
|
||||
"description": "Primary action button"
|
||||
}
|
||||
],
|
||||
"variables": [
|
||||
{
|
||||
"name": "colors/primary/500",
|
||||
"variableType": "COLOR",
|
||||
"variableSetKey": "set1key",
|
||||
"key": "var1key",
|
||||
"scopes": ["FRAME_FILL", "SHAPE_FILL"],
|
||||
"variableCollectionName": "Colors"
|
||||
}
|
||||
],
|
||||
"styles": [
|
||||
{
|
||||
"name": "Heading/H1",
|
||||
"styleType": "TEXT",
|
||||
"key": "style1key"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### How to Interpret Results
|
||||
|
||||
**Components:** The `componentKey` can be used in `use_figma` to import the component:
|
||||
```javascript
|
||||
const component = await figma.importComponentByKeyAsync("abc123def");
|
||||
// or for component sets:
|
||||
const componentSet = await figma.importComponentSetByKeyAsync("abc123def");
|
||||
```
|
||||
|
||||
**Variables:** The `variableSetKey` is the collection key. The `key` is the variable key. Use these to understand what naming conventions are in use, and what tokens are available to alias from.
|
||||
|
||||
**Styles:** The `key` is usable with `figma.importStyleByKeyAsync(key)` to import into the current file.
|
||||
|
||||
### When to Search
|
||||
|
||||
- **Phase 0, step 0c**: Search broadly (`query: "button"`, `query: "color"`, `query: "spacing"`) before planning anything. This establishes the reuse baseline.
|
||||
- **Immediately before each component creation**: Search for the specific component name before writing any `use_figma` creation code.
|
||||
|
||||
**Reuse decision:**
|
||||
|
||||
| Condition | Decision |
|
||||
|---|---|
|
||||
| Found component with matching variant API, same token model | Import and reuse |
|
||||
| Found component but wrong variant properties or hardcoded values | Rebuild |
|
||||
| Found component that matches visually but API is incompatible | Wrap: nest as instance inside a new wrapper component |
|
||||
|
||||
---
|
||||
|
||||
## 4. Building the Plan
|
||||
|
||||
After codebase analysis and Figma inspection, produce a mapping table and present it to the user.
|
||||
|
||||
### Token → Variable Mapping Table
|
||||
|
||||
For each token found in code, record:
|
||||
|
||||
| Code Token | CSS Name | Raw Value | Figma Collection | Figma Variable Name | Figma Type | Mode(s) |
|
||||
|---|---|---|---|---|---|---|
|
||||
| `theme.colors.blue[500]` | `--color-blue-500` | `#3B82F6` | Primitives | `blue/500` | COLOR | Value |
|
||||
| `theme.colors.bg.primary` | `--color-bg-primary` | (light: blue/50, dark: gray/900) | Color | `color/bg/primary` | COLOR | Light, Dark |
|
||||
| `theme.spacing.sm` | `--spacing-sm` | `8px` | Spacing | `spacing/sm` | FLOAT | Value |
|
||||
| `theme.radii.md` | `--radius-md` | `8px` | Spacing | `radius/md` | FLOAT | Value |
|
||||
| `theme.shadows.md` | `--shadow-md` | `0 4px 6px rgba(0,0,0,0.1)` | — | — | Effect Style | — |
|
||||
|
||||
### Component → Component Set Mapping Table
|
||||
|
||||
| Code Component | Props → Variant Axes | Variant Count | Figma Page | Reuse? |
|
||||
|---|---|---|---|---|
|
||||
| `Button` | size (sm/md/lg) × variant (primary/secondary) × state (default/hover/disabled) | 18 | Buttons | Search first |
|
||||
| `Avatar` | size (sm/md/lg) × type (image/initials/icon) | 9 | Avatars | Search first |
|
||||
|
||||
### Gap Identification
|
||||
|
||||
Compare what was found in code vs what already exists in Figma:
|
||||
|
||||
- **New:** tokens or components that exist in code but not in Figma → create
|
||||
- **Existing:** tokens or components already in Figma with matching names → verify scope/code-syntax, skip or update
|
||||
- **Conflict:** same name, different value → escalate to user (see section 5)
|
||||
- **Figma-only:** exists in Figma but not in code → flag for user, likely skip
|
||||
|
||||
### User-Facing Checkpoint Message Template
|
||||
|
||||
Present this message before proceeding. Never begin Phase 1 without explicit user approval.
|
||||
|
||||
```
|
||||
Here's what I found and what I plan to build:
|
||||
|
||||
CODEBASE ANALYSIS
|
||||
Colors: {N} primitives ({families}), {M} semantic tokens ({light/dark if applicable})
|
||||
Spacing: {N} tokens ({range})
|
||||
Typography: {N} text styles, {M} individual scale tokens
|
||||
Shadows: {N} levels → will become Effect Styles
|
||||
Components: {list of component names}
|
||||
|
||||
EXISTING FIGMA FILE
|
||||
Collections: {N} existing collections
|
||||
Variables: {M} existing variables
|
||||
Styles: {K} text, {L} effect, {J} paint styles
|
||||
Components: {list}
|
||||
|
||||
PLAN
|
||||
New collections: {list with mode counts}
|
||||
New variables: ~{N} ({breakdown by collection})
|
||||
New styles: {N} text, {M} effect
|
||||
New components: {list}
|
||||
Libraries to search before each component: {list}
|
||||
|
||||
GAPS / CONFLICTS NEEDING DECISIONS
|
||||
⚠ {conflict description} — Code says X, Figma already has Y. Which wins?
|
||||
|
||||
WHAT I WON'T BUILD (and why)
|
||||
- {item}: already exists in Figma with matching conventions
|
||||
- {item}: not supported as a Figma variable (e.g. z-index, animation timing)
|
||||
|
||||
Shall I proceed?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Conflict Resolution — When Code and Figma Disagree
|
||||
|
||||
When the same token/component exists in both code and Figma but with different values, names, or structures, **always ask the user**. Never silently pick one.
|
||||
|
||||
### Decision Framework
|
||||
|
||||
| Scenario | Ask the user |
|
||||
|---|---|
|
||||
| Same CSS name, different hex value (e.g., `--color-accent` is `#3366FF` in code but `#5B7FFF` in Figma) | "Code says `#3366FF`, Figma currently has `#5B7FFF` for `color/accent/default`. Which is correct?" |
|
||||
| Same component name, different variant axes (code has `size: sm/md/lg`, Figma has `Size: Small/Large`) | "Code uses 3 sizes (sm/md/lg) but Figma has 2 (Small/Large). Should I add Medium, or rename to match code?" |
|
||||
| Code has a semantic token with no primitive layer; Figma already has a fully-layered system | "The codebase uses a flat single-layer token model. The Figma file uses a primitive/semantic split. Should I match the Figma architecture or the code architecture?" |
|
||||
| Figma variable exists but has `ALL_SCOPES` (incorrect per best practice) | "I found `color/bg/primary` already exists but it uses ALL_SCOPES. I recommend changing it to `FRAME_FILL, SHAPE_FILL`. May I update the scope?" |
|
||||
| Code uses camelCase (`backgroundColor`), Figma uses slash-separated (`color/bg/default`) | "The codebase uses camelCase naming. The Figma file uses slash-separated hierarchy. For new variables, should I use slash-separated (Figma standard) and map via code syntax?" |
|
||||
|
||||
### Code Wins
|
||||
|
||||
Default to code as the source of truth for:
|
||||
- Hex values (code is the live production value)
|
||||
- Token naming (the CSS variable names become code syntax)
|
||||
- Mode values (light/dark split comes from code)
|
||||
|
||||
### Figma Wins
|
||||
|
||||
Default to Figma as the source of truth for:
|
||||
- Collection architecture (if a well-structured system already exists, extend it rather than replace it)
|
||||
- Variable naming hierarchy (if designers are already using the system with specific names)
|
||||
- Page structure (match the existing page organization pattern)
|
||||
|
||||
### Neither: Negotiate
|
||||
|
||||
When neither is clearly correct, propose a resolution and ask:
|
||||
> "I'd suggest [option]. This way both the code token name and the Figma naming convention are preserved. Does that work?"
|
||||
+834
@@ -0,0 +1,834 @@
|
||||
> Part of the [figma-generate-library skill](../SKILL.md).
|
||||
|
||||
# Documentation Creation Reference
|
||||
|
||||
This reference covers Phase 2 of the design system build: the cover page, foundations documentation page (color swatches, type specimens, spacing bars, shadow cards, radius demo), page layout dimensions, and inline component documentation. Every code block is complete `use_figma`-ready JavaScript (helper-function form — meant to be embedded in a larger script that uses `return` to send results back).
|
||||
|
||||
---
|
||||
|
||||
## 1. Cover Page
|
||||
|
||||
The cover page is always the first page in the file. It is a branded title card that sets context for anyone opening the file.
|
||||
|
||||
### What to include
|
||||
|
||||
- File/system name as a large heading (48–72px)
|
||||
- Version string or date
|
||||
- Brief tagline (1 sentence)
|
||||
- Optional: color block background using the primary brand color variable
|
||||
|
||||
### Cover page dimensions
|
||||
|
||||
The cover frame should be **1440 × 900px** — this matches the default Figma canvas and looks correct in the page thumbnail.
|
||||
|
||||
### use_figma for cover page
|
||||
|
||||
```javascript
|
||||
async function createCoverPage(systemName, tagline, version, primaryColorVar) {
|
||||
// primaryColorVar: a Figma Variable object for the brand primary fill
|
||||
const page = figma.createPage();
|
||||
page.name = 'Cover';
|
||||
await figma.setCurrentPageAsync(page);
|
||||
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
|
||||
|
||||
const frame = figma.createFrame();
|
||||
frame.name = 'Cover';
|
||||
frame.resize(1440, 900);
|
||||
frame.x = 0;
|
||||
frame.y = 0;
|
||||
frame.layoutMode = 'VERTICAL';
|
||||
frame.primaryAxisAlignItems = 'CENTER';
|
||||
frame.counterAxisAlignItems = 'CENTER';
|
||||
frame.itemSpacing = 16;
|
||||
frame.paddingTop = 0;
|
||||
frame.paddingBottom = 0;
|
||||
frame.paddingLeft = 0;
|
||||
frame.paddingRight = 0;
|
||||
|
||||
// Background: bind to primary variable if provided, else solid dark
|
||||
if (primaryColorVar) {
|
||||
const bgPaint = figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 0.05, g: 0.05, b: 0.05 } },
|
||||
'color',
|
||||
primaryColorVar
|
||||
);
|
||||
frame.fills = [bgPaint];
|
||||
} else {
|
||||
frame.fills = [{ type: 'SOLID', color: { r: 0.06, g: 0.06, b: 0.07 } }];
|
||||
}
|
||||
page.appendChild(frame);
|
||||
|
||||
// System name heading
|
||||
const title = figma.createText();
|
||||
title.fontName = { family: 'Inter', style: 'Bold' };
|
||||
title.characters = systemName;
|
||||
title.fontSize = 64;
|
||||
title.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
|
||||
title.textAlignHorizontal = 'CENTER';
|
||||
frame.appendChild(title);
|
||||
|
||||
// Tagline
|
||||
const tag = figma.createText();
|
||||
tag.fontName = { family: 'Inter', style: 'Regular' };
|
||||
tag.characters = tagline;
|
||||
tag.fontSize = 20;
|
||||
tag.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1, a: 0.7 } }];
|
||||
tag.textAlignHorizontal = 'CENTER';
|
||||
frame.appendChild(tag);
|
||||
|
||||
// Version
|
||||
const ver = figma.createText();
|
||||
ver.fontName = { family: 'Inter', style: 'Medium' };
|
||||
ver.characters = version;
|
||||
ver.fontSize = 13;
|
||||
ver.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1, a: 0.45 } }];
|
||||
ver.textAlignHorizontal = 'CENTER';
|
||||
frame.appendChild(ver);
|
||||
|
||||
return { page, frameId: frame.id };
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Foundations Page
|
||||
|
||||
The Foundations page is always placed **before any component pages**. It visually documents the design tokens — colors, typography, spacing, shadows, and border radii — so designers and engineers can see available primitives at a glance.
|
||||
|
||||
### Page layout dimensions
|
||||
|
||||
The outer documentation frame should be **1440px wide**. Sections stack vertically with **64–100px gaps** between them. Each section frame fills the full 1440px width and hugs its content vertically.
|
||||
|
||||
### Full Foundations page skeleton
|
||||
|
||||
```javascript
|
||||
async function createFoundationsPage() {
|
||||
const page = figma.createPage();
|
||||
page.name = 'Foundations';
|
||||
await figma.setCurrentPageAsync(page);
|
||||
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
|
||||
|
||||
// Root scroll frame
|
||||
const root = figma.createFrame();
|
||||
root.name = 'Foundations';
|
||||
root.layoutMode = 'VERTICAL';
|
||||
root.primaryAxisAlignItems = 'MIN';
|
||||
root.counterAxisAlignItems = 'MIN';
|
||||
root.itemSpacing = 80;
|
||||
root.paddingTop = 80;
|
||||
root.paddingBottom = 120;
|
||||
root.paddingLeft = 80;
|
||||
root.paddingRight = 80;
|
||||
root.layoutSizingHorizontal = 'FIXED';
|
||||
root.layoutSizingVertical = 'HUG';
|
||||
root.resize(1440, 1);
|
||||
root.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
|
||||
page.appendChild(root);
|
||||
|
||||
return { page, root };
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Color Swatches (bound to variables)
|
||||
|
||||
Color swatches must be **bound to actual Figma variables** — never hardcode hex values in swatch fills. This keeps documentation in sync automatically when variable values change.
|
||||
|
||||
### Single color swatch
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Creates a single color swatch card (rectangle + variable name label).
|
||||
* The swatch rectangle fill is bound to the provided variable.
|
||||
*
|
||||
* @param {FrameNode} parent - The auto-layout row to append to.
|
||||
* @param {string} varName - Display name (e.g. "color/bg/primary").
|
||||
* @param {Variable} variable - The Figma Variable object to bind to.
|
||||
* @returns {FrameNode} The swatch frame.
|
||||
*/
|
||||
async function createColorSwatch(parent, varName, variable) {
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
|
||||
|
||||
const swatchFrame = figma.createFrame();
|
||||
swatchFrame.name = `Swatch/${varName}`;
|
||||
swatchFrame.layoutMode = 'VERTICAL';
|
||||
swatchFrame.primaryAxisAlignItems = 'MIN';
|
||||
swatchFrame.counterAxisAlignItems = 'MIN';
|
||||
swatchFrame.itemSpacing = 6;
|
||||
swatchFrame.layoutSizingHorizontal = 'FIXED';
|
||||
swatchFrame.layoutSizingVertical = 'HUG';
|
||||
swatchFrame.resize(88, 1);
|
||||
swatchFrame.fills = [];
|
||||
|
||||
// Color rectangle — bound to variable
|
||||
const rect = figma.createRectangle();
|
||||
rect.resize(88, 88);
|
||||
rect.cornerRadius = 8;
|
||||
const paint = figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 0.5, g: 0.5, b: 0.5 } },
|
||||
'color',
|
||||
variable
|
||||
);
|
||||
rect.fills = [paint];
|
||||
swatchFrame.appendChild(rect);
|
||||
|
||||
// Name label
|
||||
const label = figma.createText();
|
||||
label.fontName = { family: 'Inter', style: 'Regular' };
|
||||
label.characters = varName.split('/').pop(); // show leaf name only
|
||||
label.fontSize = 10;
|
||||
label.fills = [{ type: 'SOLID', color: { r: 0.35, g: 0.35, b: 0.35 } }];
|
||||
label.layoutSizingHorizontal = 'FILL';
|
||||
swatchFrame.appendChild(label);
|
||||
|
||||
// Full path tooltip label (smaller, lighter)
|
||||
const pathLabel = figma.createText();
|
||||
pathLabel.fontName = { family: 'Inter', style: 'Regular' };
|
||||
pathLabel.characters = varName;
|
||||
pathLabel.fontSize = 9;
|
||||
pathLabel.fills = [{ type: 'SOLID', color: { r: 0.6, g: 0.6, b: 0.6 } }];
|
||||
pathLabel.layoutSizingHorizontal = 'FILL';
|
||||
swatchFrame.appendChild(pathLabel);
|
||||
|
||||
parent.appendChild(swatchFrame);
|
||||
return swatchFrame;
|
||||
}
|
||||
```
|
||||
|
||||
### Color section builder (primitives row + semantic grid)
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Creates a complete color documentation section with a section heading,
|
||||
* a row of primitive swatches, and a grid of semantic swatches.
|
||||
*
|
||||
* @param {FrameNode} root - The root vertical stack frame.
|
||||
* @param {Variable[]} primitiveVars - Variables from the Primitives collection.
|
||||
* @param {Variable[]} semanticVars - Variables from the semantic Color collection.
|
||||
*/
|
||||
async function createColorSection(root, primitiveVars, semanticVars) {
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
|
||||
|
||||
// Section container
|
||||
const section = figma.createFrame();
|
||||
section.name = 'Section/Colors';
|
||||
section.layoutMode = 'VERTICAL';
|
||||
section.itemSpacing = 24;
|
||||
section.layoutSizingHorizontal = 'FILL';
|
||||
section.layoutSizingVertical = 'HUG';
|
||||
section.fills = [];
|
||||
root.appendChild(section);
|
||||
|
||||
// Section heading
|
||||
const heading = figma.createText();
|
||||
heading.fontName = { family: 'Inter', style: 'Bold' };
|
||||
heading.characters = 'Colors';
|
||||
heading.fontSize = 32;
|
||||
heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
|
||||
section.appendChild(heading);
|
||||
|
||||
// Description
|
||||
const desc = figma.createText();
|
||||
desc.fontName = { family: 'Inter', style: 'Regular' };
|
||||
desc.characters = 'Primitive color palette and semantic color tokens. Semantic tokens reference primitives — always use semantic tokens in components.';
|
||||
desc.fontSize = 14;
|
||||
desc.fills = [{ type: 'SOLID', color: { r: 0.4, g: 0.4, b: 0.4 } }];
|
||||
desc.layoutSizingHorizontal = 'FILL';
|
||||
section.appendChild(desc);
|
||||
|
||||
// Primitive swatches row
|
||||
const primLabel = figma.createText();
|
||||
primLabel.fontName = { family: 'Inter', style: 'Bold' };
|
||||
primLabel.characters = 'Primitives';
|
||||
primLabel.fontSize = 13;
|
||||
primLabel.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
|
||||
section.appendChild(primLabel);
|
||||
|
||||
const primRow = figma.createFrame();
|
||||
primRow.name = 'Primitives/Row';
|
||||
primRow.layoutMode = 'HORIZONTAL';
|
||||
primRow.itemSpacing = 12;
|
||||
primRow.layoutSizingHorizontal = 'FILL';
|
||||
primRow.layoutSizingVertical = 'HUG';
|
||||
primRow.fills = [];
|
||||
primRow.layoutWrap = 'WRAP';
|
||||
section.appendChild(primRow);
|
||||
|
||||
for (const v of primitiveVars) {
|
||||
await createColorSwatch(primRow, v.name, v);
|
||||
}
|
||||
|
||||
// Semantic swatches grid
|
||||
if (semanticVars.length > 0) {
|
||||
const semLabel = figma.createText();
|
||||
semLabel.fontName = { family: 'Inter', style: 'Bold' };
|
||||
semLabel.characters = 'Semantic';
|
||||
semLabel.fontSize = 13;
|
||||
semLabel.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
|
||||
section.appendChild(semLabel);
|
||||
|
||||
const semRow = figma.createFrame();
|
||||
semRow.name = 'Semantic/Row';
|
||||
semRow.layoutMode = 'HORIZONTAL';
|
||||
semRow.itemSpacing = 12;
|
||||
semRow.layoutSizingHorizontal = 'FILL';
|
||||
semRow.layoutSizingVertical = 'HUG';
|
||||
semRow.fills = [];
|
||||
semRow.layoutWrap = 'WRAP';
|
||||
section.appendChild(semRow);
|
||||
|
||||
for (const v of semanticVars) {
|
||||
await createColorSwatch(semRow, v.name, v);
|
||||
}
|
||||
}
|
||||
|
||||
return section;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Type Specimens
|
||||
|
||||
Typography specimens show each text style rendered at its actual size with a sample string, the style name, and its specifications.
|
||||
|
||||
### Single type specimen row
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Creates a single type specimen row: style name (small label) + sample text +
|
||||
* specification line (family · style · size · line-height).
|
||||
*
|
||||
* @param {FrameNode} parent - The parent vertical stack.
|
||||
* @param {string} styleName - The text style name (e.g. "Display Large").
|
||||
* @param {string} fontFamily - Font family (e.g. "Inter").
|
||||
* @param {string} fontStyle - Font style (e.g. "Bold").
|
||||
* @param {number} fontSize - Font size in pixels.
|
||||
* @param {number} lineHeight - Line height in pixels.
|
||||
* @returns {FrameNode} The specimen row frame.
|
||||
*/
|
||||
async function createTypeSpecimen(parent, styleName, fontFamily, fontStyle, fontSize, lineHeight) {
|
||||
await figma.loadFontAsync({ family: fontFamily, style: fontStyle });
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
|
||||
|
||||
const row = figma.createFrame();
|
||||
row.name = `Type/${styleName}`;
|
||||
row.layoutMode = 'VERTICAL';
|
||||
row.itemSpacing = 6;
|
||||
row.paddingTop = 16;
|
||||
row.paddingBottom = 16;
|
||||
row.layoutSizingHorizontal = 'FILL';
|
||||
row.layoutSizingVertical = 'HUG';
|
||||
row.fills = [];
|
||||
parent.appendChild(row);
|
||||
|
||||
// Style name label (small, muted)
|
||||
const nameText = figma.createText();
|
||||
nameText.fontName = { family: 'Inter', style: 'Medium' };
|
||||
nameText.characters = styleName;
|
||||
nameText.fontSize = 11;
|
||||
nameText.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
|
||||
nameText.layoutSizingHorizontal = 'FILL';
|
||||
row.appendChild(nameText);
|
||||
|
||||
// Sample text rendered in the actual style
|
||||
const specimen = figma.createText();
|
||||
specimen.fontName = { family: fontFamily, style: fontStyle };
|
||||
specimen.characters = 'The quick brown fox jumps over the lazy dog';
|
||||
specimen.fontSize = fontSize;
|
||||
specimen.lineHeight = { value: lineHeight, unit: 'PIXELS' };
|
||||
specimen.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
|
||||
specimen.layoutSizingHorizontal = 'FILL';
|
||||
row.appendChild(specimen);
|
||||
|
||||
// Specification line
|
||||
const specs = figma.createText();
|
||||
specs.fontName = { family: 'Inter', style: 'Regular' };
|
||||
specs.characters = `${fontFamily} ${fontStyle} · ${fontSize}px · ${lineHeight}px line height`;
|
||||
specs.fontSize = 11;
|
||||
specs.fills = [{ type: 'SOLID', color: { r: 0.65, g: 0.65, b: 0.65 } }];
|
||||
specs.layoutSizingHorizontal = 'FILL';
|
||||
row.appendChild(specs);
|
||||
|
||||
// Divider line
|
||||
const divider = figma.createRectangle();
|
||||
divider.resize(1280, 1);
|
||||
divider.fills = [{ type: 'SOLID', color: { r: 0.9, g: 0.9, b: 0.9 } }];
|
||||
divider.layoutSizingHorizontal = 'FILL';
|
||||
row.appendChild(divider);
|
||||
|
||||
return row;
|
||||
}
|
||||
```
|
||||
|
||||
### Typography section builder
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Creates a complete typography documentation section.
|
||||
* Pass an array of style definitions; the function renders one specimen per entry.
|
||||
*
|
||||
* @param {FrameNode} root - Root vertical stack.
|
||||
* @param {Array<{name, family, style, size, lineHeight}>} typeStyles - Style definitions.
|
||||
*/
|
||||
async function createTypographySection(root, typeStyles) {
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
|
||||
|
||||
const section = figma.createFrame();
|
||||
section.name = 'Section/Typography';
|
||||
section.layoutMode = 'VERTICAL';
|
||||
section.itemSpacing = 0;
|
||||
section.layoutSizingHorizontal = 'FILL';
|
||||
section.layoutSizingVertical = 'HUG';
|
||||
section.fills = [];
|
||||
root.appendChild(section);
|
||||
|
||||
const heading = figma.createText();
|
||||
heading.fontName = { family: 'Inter', style: 'Bold' };
|
||||
heading.characters = 'Typography';
|
||||
heading.fontSize = 32;
|
||||
heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
|
||||
section.appendChild(heading);
|
||||
|
||||
for (const ts of typeStyles) {
|
||||
await createTypeSpecimen(section, ts.name, ts.family, ts.style, ts.size, ts.lineHeight);
|
||||
}
|
||||
|
||||
return section;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Spacing Bars
|
||||
|
||||
Spacing bars show each spacing token as a filled rectangle whose width equals the spacing value. Shorter bars for small values, longer bars for large values — the visual encoding is immediate.
|
||||
|
||||
### Spacing bar row
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Creates a single spacing bar: a colored rectangle sized to the spacing value,
|
||||
* with a label showing name + pixel value + code syntax.
|
||||
*
|
||||
* @param {FrameNode} parent - Parent vertical stack.
|
||||
* @param {string} name - Token name (e.g. "spacing/sm").
|
||||
* @param {number} value - Spacing value in pixels.
|
||||
* @param {Variable} variable - Figma Variable to bind the width to.
|
||||
* @param {string} codeSyntax - CSS variable string (e.g. "var(--spacing-sm)").
|
||||
*/
|
||||
async function createSpacingBar(parent, name, value, variable, codeSyntax) {
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
|
||||
|
||||
const row = figma.createFrame();
|
||||
row.name = `Spacing/${name}`;
|
||||
row.layoutMode = 'HORIZONTAL';
|
||||
row.counterAxisAlignItems = 'CENTER';
|
||||
row.itemSpacing = 16;
|
||||
row.layoutSizingHorizontal = 'FILL';
|
||||
row.layoutSizingVertical = 'HUG';
|
||||
row.fills = [];
|
||||
parent.appendChild(row);
|
||||
|
||||
// The bar rectangle — width bound to spacing variable
|
||||
const bar = figma.createRectangle();
|
||||
bar.resize(value, 16);
|
||||
bar.cornerRadius = 3;
|
||||
bar.fills = [{ type: 'SOLID', color: { r: 0.22, g: 0.47, b: 0.98 } }];
|
||||
// Bind width to the spacing variable so it reflects the actual token value
|
||||
if (variable) {
|
||||
bar.setBoundVariable('width', variable);
|
||||
}
|
||||
row.appendChild(bar);
|
||||
|
||||
// Label: "spacing/sm 8px var(--spacing-sm)"
|
||||
const label = figma.createText();
|
||||
label.fontName = { family: 'Inter', style: 'Regular' };
|
||||
label.characters = `${name} ${value}px ${codeSyntax}`;
|
||||
label.fontSize = 12;
|
||||
label.fills = [{ type: 'SOLID', color: { r: 0.35, g: 0.35, b: 0.35 } }];
|
||||
row.appendChild(label);
|
||||
|
||||
return row;
|
||||
}
|
||||
```
|
||||
|
||||
### Spacing section builder
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Creates the full spacing documentation section.
|
||||
*
|
||||
* @param {FrameNode} root - Root vertical stack.
|
||||
* @param {Array<{name, value, variable, codeSyntax}>} spacingTokens - Token definitions.
|
||||
*/
|
||||
async function createSpacingSection(root, spacingTokens) {
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
|
||||
|
||||
const section = figma.createFrame();
|
||||
section.name = 'Section/Spacing';
|
||||
section.layoutMode = 'VERTICAL';
|
||||
section.itemSpacing = 12;
|
||||
section.layoutSizingHorizontal = 'FILL';
|
||||
section.layoutSizingVertical = 'HUG';
|
||||
section.fills = [];
|
||||
root.appendChild(section);
|
||||
|
||||
const heading = figma.createText();
|
||||
heading.fontName = { family: 'Inter', style: 'Bold' };
|
||||
heading.characters = 'Spacing';
|
||||
heading.fontSize = 32;
|
||||
heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
|
||||
section.appendChild(heading);
|
||||
|
||||
for (const tok of spacingTokens) {
|
||||
await createSpacingBar(section, tok.name, tok.value, tok.variable, tok.codeSyntax);
|
||||
}
|
||||
|
||||
return section;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Shadow Cards (Elevation)
|
||||
|
||||
Elevation documentation shows cards with progressively stronger drop shadows, labeled with name and effect parameters.
|
||||
|
||||
### Single shadow card
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Creates a shadow card: a white rectangle with a drop shadow effect,
|
||||
* labeled with the elevation name and shadow parameters.
|
||||
*
|
||||
* @param {FrameNode} parent - The horizontal row to append to.
|
||||
* @param {string} name - Elevation name (e.g. "Shadow/Medium").
|
||||
* @param {DropShadowEffect[]} effects - Array of Figma effect objects.
|
||||
*/
|
||||
async function createShadowCard(parent, name, effects) {
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
|
||||
|
||||
const card = figma.createFrame();
|
||||
card.name = `ShadowCard/${name}`;
|
||||
card.layoutMode = 'VERTICAL';
|
||||
card.primaryAxisAlignItems = 'CENTER';
|
||||
card.counterAxisAlignItems = 'CENTER';
|
||||
card.itemSpacing = 8;
|
||||
card.paddingTop = 16;
|
||||
card.paddingBottom = 16;
|
||||
card.resize(120, 120);
|
||||
card.cornerRadius = 8;
|
||||
card.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
|
||||
card.effects = effects;
|
||||
parent.appendChild(card);
|
||||
|
||||
// Elevation name
|
||||
const nameLabel = figma.createText();
|
||||
nameLabel.fontName = { family: 'Inter', style: 'Medium' };
|
||||
nameLabel.characters = name.split('/').pop();
|
||||
nameLabel.fontSize = 12;
|
||||
nameLabel.textAlignHorizontal = 'CENTER';
|
||||
nameLabel.fills = [{ type: 'SOLID', color: { r: 0.2, g: 0.2, b: 0.2 } }];
|
||||
card.appendChild(nameLabel);
|
||||
|
||||
// Effect parameters as small text
|
||||
if (effects.length > 0) {
|
||||
const e = effects[0];
|
||||
if (e.type === 'DROP_SHADOW') {
|
||||
const params = figma.createText();
|
||||
params.fontName = { family: 'Inter', style: 'Regular' };
|
||||
params.characters = `x:${e.offset.x} y:${e.offset.y}\nblur:${e.radius}`;
|
||||
params.fontSize = 10;
|
||||
params.textAlignHorizontal = 'CENTER';
|
||||
params.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
|
||||
card.appendChild(params);
|
||||
}
|
||||
}
|
||||
|
||||
return card;
|
||||
}
|
||||
```
|
||||
|
||||
### Shadow section builder
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Creates the full elevation/shadow documentation section.
|
||||
*
|
||||
* @param {FrameNode} root - Root vertical stack.
|
||||
* @param {Array<{name, effects}>} shadowTokens - Shadow definitions.
|
||||
*/
|
||||
async function createShadowSection(root, shadowTokens) {
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
|
||||
|
||||
const section = figma.createFrame();
|
||||
section.name = 'Section/Elevation';
|
||||
section.layoutMode = 'VERTICAL';
|
||||
section.itemSpacing = 24;
|
||||
section.layoutSizingHorizontal = 'FILL';
|
||||
section.layoutSizingVertical = 'HUG';
|
||||
section.fills = [];
|
||||
root.appendChild(section);
|
||||
|
||||
const heading = figma.createText();
|
||||
heading.fontName = { family: 'Inter', style: 'Bold' };
|
||||
heading.characters = 'Elevation';
|
||||
heading.fontSize = 32;
|
||||
heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
|
||||
section.appendChild(heading);
|
||||
|
||||
// Cards row — extra top padding so shadows are visible
|
||||
const row = figma.createFrame();
|
||||
row.name = 'Elevation/Row';
|
||||
row.layoutMode = 'HORIZONTAL';
|
||||
row.itemSpacing = 32;
|
||||
row.paddingTop = 24;
|
||||
row.paddingBottom = 40;
|
||||
row.layoutSizingHorizontal = 'FILL';
|
||||
row.layoutSizingVertical = 'HUG';
|
||||
row.fills = [{ type: 'SOLID', color: { r: 0.97, g: 0.97, b: 0.97 } }];
|
||||
row.cornerRadius = 8;
|
||||
row.paddingLeft = 24;
|
||||
row.paddingRight = 24;
|
||||
section.appendChild(row);
|
||||
|
||||
for (const tok of shadowTokens) {
|
||||
await createShadowCard(row, tok.name, tok.effects);
|
||||
}
|
||||
|
||||
return section;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Border Radius Demo
|
||||
|
||||
Border radius documentation shows rectangles at each corner radius value, labeled with the token name and pixel value.
|
||||
|
||||
### Single radius card
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Creates a single border radius card: a square with corner radius applied,
|
||||
* labeled with the token name and pixel value.
|
||||
*
|
||||
* @param {FrameNode} parent - The horizontal row to append to.
|
||||
* @param {string} name - Token name (e.g. "radius/md").
|
||||
* @param {number} value - Corner radius in pixels (0 for none, 9999 for full).
|
||||
* @param {Variable} [variable] - Optional Figma Variable to bind corner radius.
|
||||
*/
|
||||
async function createRadiusCard(parent, name, value, variable) {
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
|
||||
|
||||
const wrapper = figma.createFrame();
|
||||
wrapper.name = `Radius/${name}`;
|
||||
wrapper.layoutMode = 'VERTICAL';
|
||||
wrapper.primaryAxisAlignItems = 'CENTER';
|
||||
wrapper.counterAxisAlignItems = 'CENTER';
|
||||
wrapper.itemSpacing = 8;
|
||||
wrapper.fills = [];
|
||||
wrapper.layoutSizingHorizontal = 'FIXED';
|
||||
wrapper.layoutSizingVertical = 'HUG';
|
||||
wrapper.resize(96, 1);
|
||||
parent.appendChild(wrapper);
|
||||
|
||||
const rect = figma.createRectangle();
|
||||
rect.resize(72, 72);
|
||||
rect.fills = [{ type: 'SOLID', color: { r: 0.22, g: 0.47, b: 0.98, a: 0.15 } }];
|
||||
rect.strokes = [{ type: 'SOLID', color: { r: 0.22, g: 0.47, b: 0.98 } }];
|
||||
rect.strokeWeight = 1.5;
|
||||
|
||||
// Cap display value — 9999 is how Figma represents "full/pill"
|
||||
const displayRadius = Math.min(value, 36);
|
||||
rect.cornerRadius = displayRadius;
|
||||
|
||||
// Bind to variable if provided
|
||||
if (variable) {
|
||||
rect.setBoundVariable('cornerRadius', variable);
|
||||
}
|
||||
wrapper.appendChild(rect);
|
||||
|
||||
const nameLabel = figma.createText();
|
||||
nameLabel.fontName = { family: 'Inter', style: 'Medium' };
|
||||
nameLabel.characters = name.split('/').pop();
|
||||
nameLabel.fontSize = 11;
|
||||
nameLabel.textAlignHorizontal = 'CENTER';
|
||||
nameLabel.fills = [{ type: 'SOLID', color: { r: 0.2, g: 0.2, b: 0.2 } }];
|
||||
wrapper.appendChild(nameLabel);
|
||||
|
||||
const valueLabel = figma.createText();
|
||||
valueLabel.fontName = { family: 'Inter', style: 'Regular' };
|
||||
valueLabel.characters = value >= 9999 ? 'full' : `${value}px`;
|
||||
valueLabel.fontSize = 10;
|
||||
valueLabel.textAlignHorizontal = 'CENTER';
|
||||
valueLabel.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
|
||||
wrapper.appendChild(valueLabel);
|
||||
|
||||
return wrapper;
|
||||
}
|
||||
```
|
||||
|
||||
### Radius section builder
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Creates the full border radius documentation section.
|
||||
*
|
||||
* @param {FrameNode} root - Root vertical stack.
|
||||
* @param {Array<{name, value, variable}>} radiusTokens - Radius token definitions.
|
||||
*/
|
||||
async function createRadiusSection(root, radiusTokens) {
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
|
||||
|
||||
const section = figma.createFrame();
|
||||
section.name = 'Section/Radius';
|
||||
section.layoutMode = 'VERTICAL';
|
||||
section.itemSpacing = 24;
|
||||
section.layoutSizingHorizontal = 'FILL';
|
||||
section.layoutSizingVertical = 'HUG';
|
||||
section.fills = [];
|
||||
root.appendChild(section);
|
||||
|
||||
const heading = figma.createText();
|
||||
heading.fontName = { family: 'Inter', style: 'Bold' };
|
||||
heading.characters = 'Border Radius';
|
||||
heading.fontSize = 32;
|
||||
heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
|
||||
section.appendChild(heading);
|
||||
|
||||
const row = figma.createFrame();
|
||||
row.name = 'Radius/Row';
|
||||
row.layoutMode = 'HORIZONTAL';
|
||||
row.itemSpacing = 24;
|
||||
row.paddingTop = 24;
|
||||
row.paddingBottom = 24;
|
||||
row.paddingLeft = 24;
|
||||
row.paddingRight = 24;
|
||||
row.layoutSizingHorizontal = 'FILL';
|
||||
row.layoutSizingVertical = 'HUG';
|
||||
row.fills = [{ type: 'SOLID', color: { r: 0.97, g: 0.97, b: 0.97 } }];
|
||||
row.cornerRadius = 8;
|
||||
section.appendChild(row);
|
||||
|
||||
for (const tok of radiusTokens) {
|
||||
await createRadiusCard(row, tok.name, tok.value, tok.variable);
|
||||
}
|
||||
|
||||
return section;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Documentation Alongside Components
|
||||
|
||||
Each component page should include a documentation frame directly on the canvas, placed to the left of the component set. This keeps docs and the component in sync without requiring a separate file.
|
||||
|
||||
### Component page documentation frame
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Creates the documentation frame for a component page: title, description,
|
||||
* and usage notes, positioned at x=0 with the component set to its right.
|
||||
*
|
||||
* @param {PageNode} page - The component page (must already be current).
|
||||
* @param {string} componentName - The component name.
|
||||
* @param {string} description - What the component does and when to use it.
|
||||
* @param {string[]} usageNotes - Bullet points for usage guidance.
|
||||
* @returns {FrameNode} The documentation frame.
|
||||
*/
|
||||
async function createComponentDocFrame(page, componentName, description, usageNotes) {
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
|
||||
|
||||
const doc = figma.createFrame();
|
||||
doc.name = '_Doc';
|
||||
doc.layoutMode = 'VERTICAL';
|
||||
doc.itemSpacing = 16;
|
||||
doc.paddingTop = 40;
|
||||
doc.paddingBottom = 40;
|
||||
doc.paddingLeft = 40;
|
||||
doc.paddingRight = 40;
|
||||
doc.layoutSizingHorizontal = 'FIXED';
|
||||
doc.layoutSizingVertical = 'HUG';
|
||||
doc.resize(360, 1);
|
||||
doc.fills = [];
|
||||
doc.x = 0;
|
||||
doc.y = 0;
|
||||
page.appendChild(doc);
|
||||
|
||||
// Component name — large heading
|
||||
const title = figma.createText();
|
||||
title.fontName = { family: 'Inter', style: 'Bold' };
|
||||
title.characters = componentName;
|
||||
title.fontSize = 28;
|
||||
title.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
|
||||
title.layoutSizingHorizontal = 'FILL';
|
||||
doc.appendChild(title);
|
||||
|
||||
// Description
|
||||
const descText = figma.createText();
|
||||
descText.fontName = { family: 'Inter', style: 'Regular' };
|
||||
descText.characters = description;
|
||||
descText.fontSize = 13;
|
||||
descText.lineHeight = { value: 20, unit: 'PIXELS' };
|
||||
descText.fills = [{ type: 'SOLID', color: { r: 0.35, g: 0.35, b: 0.35 } }];
|
||||
descText.layoutSizingHorizontal = 'FILL';
|
||||
doc.appendChild(descText);
|
||||
|
||||
// Divider
|
||||
const divider = figma.createRectangle();
|
||||
divider.resize(280, 1);
|
||||
divider.fills = [{ type: 'SOLID', color: { r: 0.88, g: 0.88, b: 0.88 } }];
|
||||
divider.layoutSizingHorizontal = 'FILL';
|
||||
doc.appendChild(divider);
|
||||
|
||||
// Usage notes
|
||||
if (usageNotes.length > 0) {
|
||||
const usageHeading = figma.createText();
|
||||
usageHeading.fontName = { family: 'Inter', style: 'Bold' };
|
||||
usageHeading.characters = 'Usage';
|
||||
usageHeading.fontSize = 13;
|
||||
usageHeading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
|
||||
doc.appendChild(usageHeading);
|
||||
|
||||
for (const note of usageNotes) {
|
||||
const noteText = figma.createText();
|
||||
noteText.fontName = { family: 'Inter', style: 'Regular' };
|
||||
noteText.characters = `• ${note}`;
|
||||
noteText.fontSize = 12;
|
||||
noteText.lineHeight = { value: 18, unit: 'PIXELS' };
|
||||
noteText.fills = [{ type: 'SOLID', color: { r: 0.4, g: 0.4, b: 0.4 } }];
|
||||
noteText.layoutSizingHorizontal = 'FILL';
|
||||
doc.appendChild(noteText);
|
||||
}
|
||||
}
|
||||
|
||||
return doc;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Critical Rules
|
||||
|
||||
1. **Bind swatches to variables** — use `setBoundVariableForPaint` for color fills, `setBoundVariable('width', ...)` for spacing bars, and `setBoundVariable('cornerRadius', ...)` for radius cards. Never hardcode values that have corresponding variables.
|
||||
2. **Foundations page comes before component pages** — always insert it between the file structure separators and the first component page.
|
||||
3. **Show both primitive and semantic layers** — if the system has a Primitives collection and a semantic Color collection, document both on the Foundations page with clear section labels.
|
||||
4. **Page frame width = 1440px** — this is the convention across Simple DS, Polaris, and Material 3. Use it unless you detect a different existing convention via `get_metadata`.
|
||||
5. **Section spacing = 64–80px** — the gap between color / typography / spacing / shadow / radius sections should be at minimum 64px so the page is scannable.
|
||||
6. **Match existing page style** — if the target file uses emoji page name prefixes or a decorative separator style, carry that through to the Foundations page name.
|
||||
7. **Include code syntax in labels** — where variables have code syntax set, display the CSS variable name in the swatch/bar label so developers can copy it directly.
|
||||
+514
@@ -0,0 +1,514 @@
|
||||
> Part of the [figma-generate-library skill](../SKILL.md).
|
||||
|
||||
# Error Recovery Reference
|
||||
|
||||
Protocol for handling failures and incomplete runs across a 20–100+ call design system build.
|
||||
|
||||
---
|
||||
|
||||
## 1. Core Protocol: STOP → Inspect → Fix → Retry
|
||||
|
||||
**`use_figma` is atomic — a failed script does not execute.** If a script errors, no changes are made to the file. There are no partial nodes or half-built state from the failed call itself. Retrying after a fix is safe.
|
||||
|
||||
However, in multi-step workflows (20–100+ calls), **previously successful calls** will have created state that persists. If a workflow is abandoned mid-way, nodes from earlier successful calls remain in the file. The cleanup and idempotency patterns in this document handle that scenario.
|
||||
|
||||
The recovery sequence for a failed script:
|
||||
|
||||
```
|
||||
1. STOP — Do not run any more use_figma writes.
|
||||
2. INSPECT — Read the error message carefully. Optionally call get_metadata or get_screenshot to understand the current file state.
|
||||
3. FIX — Correct the script that failed.
|
||||
4. RETRY — Re-run the corrected script.
|
||||
5. PERSIST — Update the state ledger with the outcome.
|
||||
```
|
||||
|
||||
For **abandoned multi-step workflows** (where you need to roll back nodes from previous *successful* calls), use the cleanup protocol in Section 2.
|
||||
|
||||
---
|
||||
|
||||
## 2. `sharedPluginData`-Based Cleanup: Why Name Matching is Dangerous
|
||||
|
||||
### Why name-prefix matching fails
|
||||
|
||||
A cleanup script that deletes "all nodes whose name starts with `Button`" will also delete nodes the user may have created manually with that name, or nodes from a previous approved phase. Name-based cleanup has no way to distinguish "orphan from a failed attempt" from "intentional user node."
|
||||
|
||||
Furthermore, variant names (`Size=Medium, Style=Primary, State=Default`) do not have consistent prefixes that are safe to target without also hitting legitimate nodes.
|
||||
|
||||
### How `setSharedPluginData` / `getSharedPluginData` works
|
||||
|
||||
`sharedPluginData` is a key-value store attached to individual nodes. It persists across sessions and is invisible to the user in the Figma UI. Data is scoped by namespace — we use `'dsb'`. Use three keys:
|
||||
|
||||
```javascript
|
||||
node.setSharedPluginData('dsb', 'run_id', 'ds-build-2024-001'); // identifies the build run
|
||||
node.setSharedPluginData('dsb', 'phase', 'phase3'); // which phase created this node
|
||||
node.setSharedPluginData('dsb', 'key', 'componentset/button');// unique logical key
|
||||
|
||||
// Reading:
|
||||
const runId = node.getSharedPluginData('dsb', 'run_id'); // returns '' if never set
|
||||
const key = node.getSharedPluginData('dsb', 'key');
|
||||
```
|
||||
|
||||
`getSharedPluginData` returns `''` (empty string, not null) for unset keys. Always check for `!== ''`.
|
||||
|
||||
**Tag every created node immediately after creation** — this enables safe cleanup if the multi-step workflow is abandoned later. Tag in the same statement sequence as creation:
|
||||
|
||||
```javascript
|
||||
const comp = figma.createComponent();
|
||||
comp.setSharedPluginData('dsb', 'run_id', RUN_ID); // tag immediately
|
||||
comp.setSharedPluginData('dsb', 'key', key); // tag immediately
|
||||
// ... then do the rest of the setup
|
||||
```
|
||||
|
||||
### Complete `cleanupOrphans` script using `run_id`
|
||||
|
||||
This script finds all nodes tagged with a given `run_id` and optionally a `phase` filter, then removes them. Run it on the specific page where the failure occurred.
|
||||
|
||||
```javascript
|
||||
const TARGET_RUN_ID = 'ds-build-2024-001'; // run ID to clean
|
||||
const TARGET_PHASE = 'phase3'; // optionally filter by phase ('' = all phases)
|
||||
const PAGE_NAME = 'Button'; // page to clean (or null for all pages)
|
||||
|
||||
const pagesToSearch = PAGE_NAME
|
||||
? [figma.root.children.find(p => p.name === PAGE_NAME)].filter(Boolean)
|
||||
: figma.root.children;
|
||||
|
||||
const removed = [];
|
||||
const skipped = [];
|
||||
|
||||
for (const page of pagesToSearch) {
|
||||
await figma.setCurrentPageAsync(page);
|
||||
|
||||
const orphans = page.findAll(node => {
|
||||
const runId = node.getSharedPluginData('dsb', 'run_id');
|
||||
if (runId !== TARGET_RUN_ID) return false;
|
||||
if (TARGET_PHASE && node.getSharedPluginData('dsb', 'phase') !== TARGET_PHASE) return false;
|
||||
return true;
|
||||
});
|
||||
|
||||
// Remove leaf-first to avoid removing parents before children
|
||||
// Sort by depth (deepest first) to avoid double-remove errors
|
||||
const sorted = orphans.slice().sort((a, b) => {
|
||||
let depthA = 0, depthB = 0;
|
||||
let n = a; while (n.parent) { depthA++; n = n.parent; }
|
||||
n = b; while (n.parent) { depthB++; n = n.parent; }
|
||||
return depthB - depthA;
|
||||
});
|
||||
|
||||
for (const node of sorted) {
|
||||
try {
|
||||
if (node.removed) continue; // already removed (was a child of removed parent)
|
||||
node.remove();
|
||||
removed.push({ id: node.id, name: node.name, key: node.getSharedPluginData('dsb', 'key') });
|
||||
} catch (e) {
|
||||
skipped.push({ id: node.id, name: node.name, error: e.message });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return { removed: removed.length, skipped: skipped.length, details: removed };
|
||||
```
|
||||
|
||||
After running cleanup, call `get_metadata` on the target page to confirm the orphaned nodes are gone before retrying.
|
||||
|
||||
---
|
||||
|
||||
## 3. Idempotency Patterns: Check-Before-Create
|
||||
|
||||
Run an idempotency check at the start of every create operation. If the entity already exists (tagged with the expected `key`), skip creation and return the existing ID.
|
||||
|
||||
### Check-before-create for a variable collection
|
||||
|
||||
```javascript
|
||||
const KEY = 'collection/color';
|
||||
const RUN_ID = 'ds-build-2024-001';
|
||||
const COLLECTION_NAME = 'Color';
|
||||
|
||||
// Check: does a collection tagged with this key already exist?
|
||||
const allCollections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
// Variables/collections support sharedPluginData too — check by name as fallback
|
||||
// Note: VariableCollection sharedPluginData is set via collection.setSharedPluginData(...)
|
||||
const existing = allCollections.find(c =>
|
||||
c.getSharedPluginData('dsb', 'key') === KEY
|
||||
);
|
||||
|
||||
if (existing) {
|
||||
return {
|
||||
collectionId: existing.id,
|
||||
modeIds: existing.modes.map(m => ({ name: m.name, id: m.modeId })),
|
||||
alreadyExisted: true,
|
||||
};
|
||||
}
|
||||
|
||||
// Create fresh
|
||||
const collection = figma.variables.createVariableCollection(COLLECTION_NAME);
|
||||
collection.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
collection.setSharedPluginData('dsb', 'key', KEY);
|
||||
|
||||
// Rename default mode, add second mode
|
||||
collection.renameMode(collection.modes[0].modeId, 'Light');
|
||||
const darkModeId = collection.addMode('Dark');
|
||||
|
||||
return {
|
||||
collectionId: collection.id,
|
||||
modeIds: [
|
||||
{ name: 'Light', id: collection.modes[0].modeId },
|
||||
{ name: 'Dark', id: darkModeId },
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### Check-before-create for a page
|
||||
|
||||
```javascript
|
||||
const KEY = 'page/button';
|
||||
const PAGE_NAME = 'Button';
|
||||
const RUN_ID = 'ds-build-2024-001';
|
||||
|
||||
// Check by sharedPluginData key first, then by name as fallback
|
||||
let page = figma.root.children.find(p => p.getSharedPluginData('dsb', 'key') === KEY);
|
||||
if (!page) {
|
||||
page = figma.root.children.find(p => p.name === PAGE_NAME);
|
||||
}
|
||||
|
||||
if (page) {
|
||||
// Ensure it's tagged if it was found by name only
|
||||
if (!page.getSharedPluginData('dsb', 'key')) {
|
||||
page.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
page.setSharedPluginData('dsb', 'key', KEY);
|
||||
}
|
||||
return { pageId: page.id, alreadyExisted: true };
|
||||
}
|
||||
|
||||
page = figma.createPage();
|
||||
page.name = PAGE_NAME;
|
||||
page.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
page.setSharedPluginData('dsb', 'key', KEY);
|
||||
|
||||
return { pageId: page.id, alreadyExisted: false };
|
||||
```
|
||||
|
||||
### Check-before-create for a component set
|
||||
|
||||
```javascript
|
||||
const KEY = 'componentset/button';
|
||||
const PAGE_ID = 'PAGE_ID_FROM_STATE';
|
||||
const RUN_ID = 'ds-build-2024-001';
|
||||
|
||||
const page = await figma.getNodeByIdAsync(PAGE_ID);
|
||||
await figma.setCurrentPageAsync(page);
|
||||
|
||||
const existing = page.findAll(n =>
|
||||
n.type === 'COMPONENT_SET' && n.getSharedPluginData('dsb', 'key') === KEY
|
||||
);
|
||||
|
||||
if (existing.length > 0) {
|
||||
return {
|
||||
componentSetId: existing[0].id,
|
||||
alreadyExisted: true,
|
||||
};
|
||||
}
|
||||
|
||||
// ... proceed with creation
|
||||
return { componentSetId: null, alreadyExisted: false };
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. State Ledger
|
||||
|
||||
### JSON Schema
|
||||
|
||||
Maintain a state ledger in your context (not in the Figma file) across calls. This is your source of truth for node IDs, completed steps, and pending validations.
|
||||
|
||||
```json
|
||||
{
|
||||
"runId": "ds-build-2024-001",
|
||||
"phase": "phase3",
|
||||
"step": "component-button/combine-variants",
|
||||
"completedSteps": [
|
||||
"phase0",
|
||||
"phase1/collections",
|
||||
"phase1/primitives",
|
||||
"phase1/semantics",
|
||||
"phase2/pages",
|
||||
"phase2/foundations-docs",
|
||||
"phase3/component-avatar",
|
||||
"phase3/component-icon"
|
||||
],
|
||||
"entities": {
|
||||
"collections": {
|
||||
"primitives": "VariableCollectionId:1234:5678",
|
||||
"color": "VariableCollectionId:1234:5679",
|
||||
"spacing": "VariableCollectionId:1234:5680"
|
||||
},
|
||||
"variables": {
|
||||
"color/bg/primary": "VariableId:2345:1",
|
||||
"color/bg/secondary": "VariableId:2345:2",
|
||||
"color/bg/disabled": "VariableId:2345:3",
|
||||
"color/text/on-primary": "VariableId:2345:4",
|
||||
"color/text/on-secondary": "VariableId:2345:5",
|
||||
"color/text/disabled": "VariableId:2345:6",
|
||||
"spacing/sm": "VariableId:2345:7",
|
||||
"spacing/md": "VariableId:2345:8",
|
||||
"spacing/lg": "VariableId:2345:9",
|
||||
"radius/md": "VariableId:2345:10"
|
||||
},
|
||||
"modes": {
|
||||
"color/light": "2345:1",
|
||||
"color/dark": "2345:2"
|
||||
},
|
||||
"pages": {
|
||||
"Cover": "0:1",
|
||||
"Foundations": "0:2",
|
||||
"Button": "0:3"
|
||||
},
|
||||
"components": {
|
||||
"Icon": "3456:1",
|
||||
"Avatar": "3456:2",
|
||||
"Button": "3456:3"
|
||||
},
|
||||
"componentSets": {
|
||||
"Button": "4567:1"
|
||||
}
|
||||
},
|
||||
"pendingValidations": [
|
||||
"Button:metadata",
|
||||
"Button:screenshot"
|
||||
],
|
||||
"userCheckpoints": {
|
||||
"phase0": "approved-2024-01-15",
|
||||
"phase1": "approved-2024-01-15",
|
||||
"phase2": "approved-2024-01-15",
|
||||
"component-avatar": "approved-2024-01-15"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Persisting between calls
|
||||
|
||||
After every successful `use_figma` call:
|
||||
1. Extract all IDs from the return value
|
||||
2. Add them to the appropriate `entities` section of the ledger
|
||||
3. Add the completed step to `completedSteps`
|
||||
4. Remove from `pendingValidations` if this call validated something
|
||||
5. Update `phase` and `step` to the current position
|
||||
|
||||
### Rehydrating at session start
|
||||
|
||||
If a conversation is interrupted and resumed, read the state ledger and verify key entities still exist:
|
||||
|
||||
```javascript
|
||||
// Verify that critical nodes from the ledger still exist
|
||||
const toVerify = {
|
||||
'color-collection': 'VariableCollectionId:1234:5679',
|
||||
'button-page': '0:3',
|
||||
'button-componentset': '4567:1',
|
||||
};
|
||||
|
||||
const results = {};
|
||||
for (const [label, id] of Object.entries(toVerify)) {
|
||||
const node = await figma.getNodeByIdAsync(id)
|
||||
.catch(() => null);
|
||||
results[label] = node ? { found: true, name: node.name } : { found: false };
|
||||
}
|
||||
|
||||
return results;
|
||||
```
|
||||
|
||||
If any entity is missing, treat the phase that created it as incomplete and re-run from that checkpoint.
|
||||
|
||||
---
|
||||
|
||||
## 5. Resume Protocol
|
||||
|
||||
### Step 1: Inspect the file for `run_id` tags
|
||||
|
||||
```javascript
|
||||
const TARGET_RUN_ID = 'ds-build-2024-001';
|
||||
const inventory = { pages: [], variables: [], componentSets: [], frames: [] };
|
||||
|
||||
// Scan pages
|
||||
for (const page of figma.root.children) {
|
||||
if (page.getSharedPluginData('dsb', 'run_id') === TARGET_RUN_ID) {
|
||||
inventory.pages.push({ id: page.id, name: page.name, key: page.getSharedPluginData('dsb', 'key') });
|
||||
}
|
||||
}
|
||||
|
||||
// Scan variables
|
||||
const allVars = await figma.variables.getLocalVariablesAsync();
|
||||
for (const v of allVars) {
|
||||
if (v.getSharedPluginData('dsb', 'run_id') === TARGET_RUN_ID) {
|
||||
inventory.variables.push({ id: v.id, name: v.name, key: v.getSharedPluginData('dsb', 'key') });
|
||||
}
|
||||
}
|
||||
|
||||
// Scan all component sets and frames on each page
|
||||
for (const page of figma.root.children) {
|
||||
await figma.setCurrentPageAsync(page);
|
||||
const nodes = page.findAll(n => n.getSharedPluginData('dsb', 'run_id') === TARGET_RUN_ID);
|
||||
for (const n of nodes) {
|
||||
if (n.type === 'COMPONENT_SET') {
|
||||
inventory.componentSets.push({ id: n.id, name: n.name, key: n.getSharedPluginData('dsb', 'key') });
|
||||
} else if (n.type === 'FRAME') {
|
||||
inventory.frames.push({ id: n.id, name: n.name, key: n.getSharedPluginData('dsb', 'key') });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return inventory;
|
||||
```
|
||||
|
||||
### Step 2: Reconstruct state from inventory
|
||||
|
||||
Map the inventory keys back to the state ledger schema. For each entity found with a `key`, add its ID to the appropriate section. Mark the corresponding step as `completedSteps`.
|
||||
|
||||
Example mapping:
|
||||
```
|
||||
key: 'collection/color' → entities.collections.color
|
||||
key: 'variable/color/bg/primary' → entities.variables['color/bg/primary']
|
||||
key: 'page/button' → entities.pages.Button
|
||||
key: 'componentset/button' → entities.componentSets.Button
|
||||
```
|
||||
|
||||
### Step 3: Identify the resume point
|
||||
|
||||
The resume point is the first step in the workflow that is NOT in `completedSteps`. If the inventory shows the Button component set exists but the pending validations list shows `'Button:screenshot'`, the resume point is the screenshot validation call, not re-creation.
|
||||
|
||||
Use the checkpoint table from the workflow to determine which phase to continue from:
|
||||
|
||||
```
|
||||
Phase 0 complete: all planned pages listed in entities.pages
|
||||
Phase 1 complete: all planned variables listed in entities.variables with correct scopes
|
||||
Phase 2 complete: all structural pages + foundations doc frames present
|
||||
Phase 3 complete (per component): componentSet exists + no pending validations + user checkpoint recorded
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Failure Taxonomy
|
||||
|
||||
### Recoverable Errors
|
||||
|
||||
These can be fixed and retried without affecting already-created entities:
|
||||
|
||||
| Category | Examples | Recovery |
|
||||
|---|---|---|
|
||||
| Layout errors | Variants stacked at (0,0), wrong padding values | Re-run the positioning step only |
|
||||
| Naming issues | Typo in variant name, wrong casing | Find nodes by `dsb_key`, update `name` property |
|
||||
| Missing property wiring | `componentPropertyReferences` not set | Find component set by ID, re-run the property wiring step |
|
||||
| Variable binding omission | A fill was hardcoded instead of bound | Find nodes by `dsb_key`, re-bind the fill |
|
||||
| Wrong variable bound | Bound to wrong variable ID | Re-bind with correct variable ID |
|
||||
| Text not visible | Font not loaded before text write | Re-run text creation with `loadFontAsync` first |
|
||||
| Script timeout | Script exceeded time limit before completing | Script is atomic — nothing was created. Reduce scope (fewer nodes per call) and retry |
|
||||
|
||||
### Structural Corruption (Requires Rollback or Restart)
|
||||
|
||||
These errors leave the file in a state where continuing forward is unreliable:
|
||||
|
||||
| Category | Examples | Recovery |
|
||||
|---|---|---|
|
||||
| Component cycle | A component instance was accidentally nested inside itself | Full cleanup of the affected component, restart that component from Call 1 |
|
||||
| combineAsVariants with non-components | Mixed node types passed to combineAsVariants, causing unexpected merges | Remove the malformed component set, re-run from variant creation |
|
||||
| Variable collection ID drift | Collection was deleted and re-created, old IDs in state ledger are stale | Re-run Phase 1 completely; update all IDs in state ledger |
|
||||
| Page deletion | A page was deleted after component sets were created on it | Treat as Phase 2 incomplete; re-create the page + re-run affected component creations |
|
||||
| Mode limit exceeded | `addMode` threw because the plan is Starter or Professional | Redesign variable collection architecture to fit mode limits, restart Phase 1 |
|
||||
|
||||
**Recovery from structural corruption**: run `cleanupOrphans` for the entire run ID, then restart from the affected phase. Do NOT attempt to patch corrupted structure in-place.
|
||||
|
||||
---
|
||||
|
||||
## 7. Common Error Table
|
||||
|
||||
| Error message | Likely cause | Fix |
|
||||
|---|---|---|
|
||||
| `"Cannot create component from node"` | Tried to call `createComponentFromNode` on a node inside a component | Create a fresh component instead: `figma.createComponent()` |
|
||||
| `"in addMode: Limited to N modes only"` | Plan mode limit hit (Starter=1, Professional=4) | Redesign to use fewer modes or upgrade plan |
|
||||
| `"setCurrentPageAsync: page does not exist"` | Page was deleted or wrong ID | Re-create the page using the idempotency pattern |
|
||||
| `"Cannot read properties of null"` | `getNodeByIdAsync` returned null — node was deleted | Run the resume protocol to find what exists, update state ledger |
|
||||
| `"Expected nodes to be component nodes"` | Passed a non-ComponentNode to `combineAsVariants` | Filter the array: `nodes.filter(n => n.type === 'COMPONENT')` |
|
||||
| `"in createVariable: Cannot create variable"` | Collection was deleted or ID is wrong | Verify collection exists with `getVariableCollectionByIdAsync` |
|
||||
| `"font not loaded"` | Called a text property setter without `loadFontAsync` first | Add `await figma.loadFontAsync({ family, style })` before the text operation |
|
||||
| `"Cannot set properties of a read-only array"` | Tried to mutate fills/strokes in-place | Clone first: `const fills = JSON.parse(JSON.stringify(node.fills))` |
|
||||
| `"Expected RGBA color"` | Color value out of 0–1 range | Divide RGB 0–255 values by 255: `{ r: 65/255, g: 85/255, b: 143/255 }` |
|
||||
| `"Cannot add children to a non-parent node"` | Tried to append a child to a leaf node (text, rect) | Ensure the parent is a FrameNode, ComponentNode, or GroupNode |
|
||||
| `"in combineAsVariants: nodes must be in the same parent"` | Components are on different pages | Move all components to the same page before combining |
|
||||
| `"Script exceeded time limit"` | Loop creating too many nodes in one call | Split the work: create N/2 variants per call |
|
||||
| Component set deletes itself | Tried to create a component set with no children | `combineAsVariants` requires at least 1 node — always pass 1+ |
|
||||
| `addComponentProperty` returns unexpected name | This is normal — `BOOLEAN`/`TEXT`/`INSTANCE_SWAP` get `#id:id` suffix | Save the returned key immediately and use that, not the input name |
|
||||
|
||||
---
|
||||
|
||||
## 8. Per-Phase Recovery Guidance
|
||||
|
||||
### Phase 1 fails (variable creation)
|
||||
|
||||
Since `use_figma` is atomic, a failed call creates nothing. The most common scenario is that some calls in Phase 1 succeeded (creating some variables) while a later call failed.
|
||||
|
||||
Recovery steps:
|
||||
1. Run inspection script to find all variables tagged with your `run_id`
|
||||
2. Compare against the plan to identify which variables were successfully created and which are still missing
|
||||
3. If a successfully created variable has wrong values, call `variable.remove()` and recreate it
|
||||
4. Fix the failed script and retry — it's safe since the failed call created nothing
|
||||
5. Do NOT proceed to Phase 2 until ALL planned variables exist with correct scopes and code syntax
|
||||
|
||||
**The most common Phase 1 failure:** script timeout when creating many variables. Fix: batch variable creation — create at most 20–30 variables per call.
|
||||
|
||||
### Phase 2 fails mid-execution (page/file structure)
|
||||
|
||||
Symptoms: some pages exist, others are missing; foundations doc frames are incomplete.
|
||||
|
||||
Recovery steps:
|
||||
1. Identify which pages were successfully created (check for `key` tags)
|
||||
2. Mark remaining pages as pending and create them in subsequent calls
|
||||
3. If a foundations doc frame is malformed, run `cleanupOrphans` for `dsb_phase: 'phase2'` on that page, then recreate
|
||||
|
||||
Phase 2 failures rarely require Phase 1 rollback unless the page structure itself is corrupted (which is unusual).
|
||||
|
||||
### Phase 3 fails (component creation)
|
||||
|
||||
This is the most common failure mode in long builds. Since `use_figma` is atomic, a failed call creates nothing — but previous successful calls in the component creation sequence will have created state. Handle by which call in the sequence failed:
|
||||
|
||||
```
|
||||
If failure in Call 1 (page creation):
|
||||
→ Nothing was created. Fix the script and retry.
|
||||
|
||||
If failure in Call 2 (doc frame):
|
||||
→ Call 1's page exists. Fix Call 2 and retry — idempotency check handles it.
|
||||
|
||||
If failure in Call 3 (base component):
|
||||
→ Calls 1-2 succeeded. Fix Call 3 and retry.
|
||||
|
||||
If failure in Call 4 (variant creation):
|
||||
→ Call 3's base component exists. Fix Call 4 and retry.
|
||||
→ If you need to restart from Call 3, clean up Call 3's nodes first
|
||||
using cleanupOrphans scoped to the component page.
|
||||
|
||||
If failure in Call 5 (combineAsVariants + layout):
|
||||
→ Variant ComponentNodes from Call 4 exist but aren't combined yet.
|
||||
→ Fix Call 5 and retry.
|
||||
→ If the component set was already created by a prior attempt of Call 5
|
||||
that succeeded, remove it first, then re-run.
|
||||
|
||||
If failure in Call 6 (component properties):
|
||||
→ The component set already exists and is structurally sound.
|
||||
→ Fix Call 6 and retry — addComponentProperty is safe to retry if
|
||||
you first check componentPropertyDefinitions for existing properties.
|
||||
→ Idempotency check: if 'Label' property already exists, skip addComponentProperty.
|
||||
```
|
||||
|
||||
**Idempotency for component properties (Call 6 retry):**
|
||||
|
||||
```javascript
|
||||
const existingDefs = cs.componentPropertyDefinitions;
|
||||
const labelKey = existingDefs['Label']
|
||||
? Object.keys(existingDefs).find(k => k.startsWith('Label'))
|
||||
: cs.addComponentProperty('Label', 'TEXT', 'Button');
|
||||
```
|
||||
|
||||
### Phase 4 fails mid-execution (QA / Code Connect)
|
||||
|
||||
Phase 4 is non-destructive. Failures here do not corrupt Phase 3 work. Common failures:
|
||||
|
||||
- **Accessibility audit finds contrast failures:** do not attempt auto-fix. Report the specific variable IDs and token names that fail, then ask the user which value to update.
|
||||
- **Naming audit finds duplicates:** list all duplicates with their `key` values, ask user which to keep, then remove the duplicates.
|
||||
- **Code Connect mapping fails:** treat as incomplete, not broken. Continue and leave as pending.
|
||||
+527
@@ -0,0 +1,527 @@
|
||||
> Part of the [figma-generate-library skill](../SKILL.md).
|
||||
|
||||
# Naming Conventions Reference
|
||||
|
||||
This reference documents every naming convention used in the figma-generate-library workflow. Cover all naming decisions in order: variables, components, pages, variants, styles, separators, status indicators. The last section explains when to match an existing file's conventions vs. using the defaults here.
|
||||
|
||||
---
|
||||
|
||||
## 1. Variable Naming
|
||||
|
||||
### Slash hierarchy (the universal pattern)
|
||||
|
||||
All Figma variables use slash-separated paths. The slash creates visual grouping in the Variables panel and maps directly to the token hierarchy in code.
|
||||
|
||||
```
|
||||
{category}/{subcategory}/{role}
|
||||
```
|
||||
|
||||
Real examples from Simple DS and Material 3:
|
||||
|
||||
```
|
||||
color/bg/primary
|
||||
color/bg/secondary
|
||||
color/text/primary
|
||||
color/text/muted
|
||||
color/border/default
|
||||
color/border/focus
|
||||
color/feedback/error
|
||||
color/feedback/success
|
||||
spacing/xs
|
||||
spacing/sm
|
||||
spacing/md
|
||||
spacing/lg
|
||||
spacing/xl
|
||||
spacing/2xl
|
||||
radius/none
|
||||
radius/sm
|
||||
radius/md
|
||||
radius/lg
|
||||
radius/full
|
||||
typography/body/font-size
|
||||
typography/body/line-height
|
||||
typography/heading/font-size
|
||||
typography/heading/font-weight
|
||||
```
|
||||
|
||||
### Primitives collection
|
||||
|
||||
Primitive variables hold raw values and are **not** exposed to consumers (scope = `[]`). They use a flat `{family}/{step}` format matching the color scale convention from Simple DS:
|
||||
|
||||
```
|
||||
blue/50
|
||||
blue/100
|
||||
blue/200
|
||||
...
|
||||
blue/900
|
||||
gray/50
|
||||
gray/100
|
||||
...
|
||||
gray/900
|
||||
red/500
|
||||
green/500
|
||||
```
|
||||
|
||||
Step numbers follow the convention of the target codebase. If the codebase uses `100–900`, use that. If it uses `50–950`, use that. If there is no codebase convention, use `100–900` in increments of 100.
|
||||
|
||||
### Semantic collection
|
||||
|
||||
Semantic variables alias primitives. They use the role-based `{category}/{role}` or `{category}/{subcategory}/{role}` pattern:
|
||||
|
||||
```
|
||||
color/bg/primary → alias: primitives/white (light), primitives/gray/900 (dark)
|
||||
color/bg/secondary → alias: primitives/gray/100 (light), primitives/gray/800 (dark)
|
||||
color/text/primary → alias: primitives/gray/900 (light), primitives/white (dark)
|
||||
color/text/secondary → alias: primitives/gray/600 (light), primitives/gray/400 (dark)
|
||||
color/border/default → alias: primitives/gray/200 (light), primitives/gray/700 (dark)
|
||||
```
|
||||
|
||||
**Rule:** Semantic variables must never hold raw hex values — they always alias a primitive. If you need a new color value, create the primitive first, then create the semantic alias.
|
||||
|
||||
### Casing
|
||||
|
||||
**Default:** Use **lowercase** with forward slashes: `color/bg/primary`, `spacing/2xl`.
|
||||
|
||||
**When to deviate:**
|
||||
- If the existing file uses PascalCase (e.g., Material 3 uses `Schemes/Primary`) — match it.
|
||||
- If the design team prefers PascalCase for readability in the Variables panel — acceptable as long as the code syntax is separately defined and uses the platform-correct case.
|
||||
- Mode names can use spaces and mixed case (e.g., `SDS Light`, `Mode 1 → Light`) — these are labels, not identifiers.
|
||||
|
||||
**Never:** camelCase inside variable names (`colorBgPrimary` as a Figma name is wrong — that belongs in Android code syntax only). Never use spaces inside a path segment: `color/bg primary` is wrong; `color/bg/primary` is correct.
|
||||
|
||||
**Key distinction:** The casing rule applies to *Figma variable names*. Code syntax names follow *platform conventions* regardless of the Figma name case — see §9 for the full picture.
|
||||
|
||||
---
|
||||
|
||||
## 2. Component Naming
|
||||
|
||||
### Main components: PascalCase, no prefix
|
||||
|
||||
Published components intended for library consumers use plain PascalCase names:
|
||||
|
||||
```
|
||||
Button
|
||||
Input
|
||||
Checkbox
|
||||
Toggle
|
||||
Avatar
|
||||
Badge
|
||||
Card
|
||||
Dialog
|
||||
Tooltip
|
||||
Banner
|
||||
```
|
||||
|
||||
Do not use a namespace prefix for public components (e.g., do not name them `DS/Button` or `sds-Button`). Slashes in component names create nested grouping in the Assets panel, which is correct for sub-components but not for top-level public components.
|
||||
|
||||
### Sub-components: underscore prefix + slash namespace
|
||||
|
||||
Internal sub-components that are NOT meant for library consumers use the `_` prefix. This hides them from the Assets panel by default and signals to other designers that they should not be used directly.
|
||||
|
||||
```
|
||||
_Button/Slot (internal icon slot for Button)
|
||||
_Input/Indicator (internal state indicator for Input)
|
||||
_Badge/Dot (internal dot sub-component of Badge)
|
||||
_Parts/Avatar.Status (UI3 pattern: _Parts/{ParentName}.{SubPart})
|
||||
_Slider/Handle (UI3 pattern: _{ParentName}/{SubPart})
|
||||
```
|
||||
|
||||
Pattern rules:
|
||||
- Use `_` prefix for ALL internal sub-components — no exceptions.
|
||||
- Use slash namespacing to group sub-components under their parent: `_Button/IconSlot`.
|
||||
- For sub-components shared by multiple parents, use `_Parts/{ComponentName}.{SubPart}`.
|
||||
|
||||
### Private documentation components
|
||||
|
||||
Components used only for internal documentation (not for production use) use the `.` prefix:
|
||||
|
||||
```
|
||||
.ExampleCard
|
||||
.GuidelineHeader
|
||||
.DemoFrame
|
||||
```
|
||||
|
||||
This hides them from consumers while keeping them accessible on the canvas.
|
||||
|
||||
---
|
||||
|
||||
## 3. Page Naming
|
||||
|
||||
Five reference design systems use three distinct naming patterns. Choose one pattern and apply it consistently across all pages in the file.
|
||||
|
||||
### Pattern 1: Plain names (Simple DS, Material 3, Polaris)
|
||||
|
||||
The most common pattern. Clean, readable, no decoration.
|
||||
|
||||
```
|
||||
Cover
|
||||
---
|
||||
Foundations
|
||||
Icons
|
||||
---
|
||||
Accordion
|
||||
Avatars
|
||||
Buttons
|
||||
Cards
|
||||
Dialog
|
||||
Inputs
|
||||
Menu
|
||||
---
|
||||
Utilities
|
||||
Component Playground
|
||||
```
|
||||
|
||||
Use this pattern when starting from scratch or when the target file already uses this style.
|
||||
|
||||
### Pattern 2: Emoji prefix + status (UI3 Library)
|
||||
|
||||
The most expressive pattern. The page name encodes asset type, design status, and code readiness.
|
||||
|
||||
Anatomy: `[Asset Type Emoji] [Optional FPL Label] [Status Circle] Component Name [Code Status Bracket]`
|
||||
|
||||
| Segment | Values |
|
||||
|---------|--------|
|
||||
| Asset type | Component pages use the C-flag emoji; pattern pages use the P-flag emoji |
|
||||
| Design status | Green circle = Ready, Yellow circle = WIP, Red circle = Do not use |
|
||||
| Code status | (none) = Ready in code, `[beta]` = Beta, `[future]` = Not yet built |
|
||||
|
||||
Examples:
|
||||
```
|
||||
Overview
|
||||
Status Key
|
||||
---
|
||||
FPL COMPONENTS (go/fpl)
|
||||
[C-flag] FPL [Green] Buttons
|
||||
[C-flag] FPL [Green] Inputs
|
||||
[C-flag] FPL [Yellow] Popovers [future]
|
||||
---
|
||||
UI3 COMPONENTS
|
||||
[C-flag] [Green] Comments
|
||||
---
|
||||
PATTERNS
|
||||
[P-flag] [Green] Editor / Layers
|
||||
---
|
||||
[Book] Cover
|
||||
[Headstone] Deprecated
|
||||
```
|
||||
|
||||
Use this pattern only when building a large, multi-team design system where lifecycle tracking is needed, or when the target file already uses it.
|
||||
|
||||
### Pattern 3: Emoji prefix (Shop Minis)
|
||||
|
||||
A lighter version of the UI3 pattern without status circles.
|
||||
|
||||
```
|
||||
📔 Cover
|
||||
ℹ️ About
|
||||
🚀 Getting started
|
||||
——— THEME ———
|
||||
Color
|
||||
Typography
|
||||
Spacing
|
||||
——— COMPONENTS ———
|
||||
Button
|
||||
Input
|
||||
Card
|
||||
```
|
||||
|
||||
Use this pattern when the target file already uses emoji prefixes but does not need lifecycle tracking.
|
||||
|
||||
### Universal rules (all patterns)
|
||||
|
||||
- **Cover** is always first.
|
||||
- **Separator pages** come before and after each logical section.
|
||||
- **Foundation/token pages** always come before component pages.
|
||||
- **Utility and internal pages** always come last.
|
||||
- Pick one convention and do not mix patterns within a file.
|
||||
|
||||
---
|
||||
|
||||
## 4. Variant Naming
|
||||
|
||||
### Property=Value format
|
||||
|
||||
All component variant properties and their values use `Property=Value` format in the Figma component set:
|
||||
|
||||
```
|
||||
Size=Small, Style=Primary, State=Default
|
||||
Size=Medium, Style=Secondary, State=Hover
|
||||
Size=Large, Style=Ghost, State=Disabled
|
||||
```
|
||||
|
||||
Actual property names match code prop names where possible:
|
||||
|
||||
| Figma Property | Code Prop Equivalent |
|
||||
|---------------|---------------------|
|
||||
| `Size` | `size` |
|
||||
| `Style` / `Variant` | `variant` |
|
||||
| `State` | Typically controlled by `:hover`, `:focus`, `:disabled` in CSS, but `state` in some systems |
|
||||
| `Type` | `type` |
|
||||
| `Disabled` | `disabled` (boolean) |
|
||||
| `Icon` | `icon` (boolean or instance swap) |
|
||||
|
||||
### Property value casing
|
||||
|
||||
Property values use **Title Case** in Figma (to be readable in the Variants panel), mapping to lowercase in code:
|
||||
|
||||
| Figma value | Code value |
|
||||
|-------------|-----------|
|
||||
| `Small` | `"small"` / `"sm"` |
|
||||
| `Medium` | `"medium"` / `"md"` |
|
||||
| `Large` | `"large"` / `"lg"` |
|
||||
| `Primary` | `"primary"` |
|
||||
| `Disabled` | `disabled` (boolean prop) |
|
||||
| `Default` | *(typically the absent/unset case)* |
|
||||
|
||||
### Boolean properties
|
||||
|
||||
Boolean component properties in Figma use `true` / `false` as values (Figma's native boolean), not `Yes` / `No` or `On` / `Off`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Style Naming (Text and Effect Styles)
|
||||
|
||||
### Text styles: category/name
|
||||
|
||||
```
|
||||
Display/Large
|
||||
Display/Medium
|
||||
Display/Small
|
||||
Heading/1
|
||||
Heading/2
|
||||
Heading/3
|
||||
Body/Large
|
||||
Body/Medium
|
||||
Body/Small
|
||||
Label/Large
|
||||
Label/Small
|
||||
Code/Inline
|
||||
```
|
||||
|
||||
The category segment maps to the typographic role. Use the same category names as the codebase's typography scale where possible.
|
||||
|
||||
### Effect styles (shadows): category/name
|
||||
|
||||
```
|
||||
Shadow/None
|
||||
Shadow/Subtle
|
||||
Shadow/Medium
|
||||
Shadow/Strong
|
||||
Shadow/Overlay
|
||||
Elevation/0
|
||||
Elevation/1
|
||||
Elevation/2
|
||||
Elevation/3
|
||||
Elevation/4
|
||||
Elevation/5
|
||||
```
|
||||
|
||||
Use `Shadow/` for named semantic shadows. Use `Elevation/N` for Material Design-style numbered elevation levels.
|
||||
|
||||
---
|
||||
|
||||
## 6. Separator Pages
|
||||
|
||||
Separator pages are empty pages whose sole purpose is to create visual breaks in the Figma page panel. Two conventions:
|
||||
|
||||
| Convention | Example | Used by |
|
||||
|------------|---------|---------|
|
||||
| Three dashes | `---` | Simple DS, UI3, Polaris, Material 3 |
|
||||
| Decorated text | `——— COMPONENTS ———` | Shop Minis |
|
||||
|
||||
The three-dash convention (`---`) is the most common and the default for new files. Use it unless the target file uses the decorated-text style.
|
||||
|
||||
**Where to place separators:**
|
||||
|
||||
```
|
||||
Cover
|
||||
--- ← after cover
|
||||
Foundations
|
||||
Icons
|
||||
--- ← before components
|
||||
[component pages]
|
||||
--- ← before utilities
|
||||
Utilities
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Status Indicators (UI3 Emoji System)
|
||||
|
||||
The UI3 Library uses colored circle emojis in page names to communicate design readiness at a glance. This system is optional but powerful for large teams.
|
||||
|
||||
| Emoji | Meaning | When to use |
|
||||
|-------|---------|-------------|
|
||||
| Green circle | Ready / Approved | Design is stable, reviewed, and safe to use |
|
||||
| Yellow circle | WIP / In Progress | Design is being actively worked on, may change |
|
||||
| Red circle | Do not use | Not ready, do not reference; may be deprecated |
|
||||
|
||||
Code readiness is communicated via brackets appended to the component name:
|
||||
|
||||
| Bracket | Meaning |
|
||||
|---------|---------|
|
||||
| (none) | Component is implemented in code and stable |
|
||||
| `[beta]` | Component is in code but not yet stable (~3 weeks from ready) |
|
||||
| `[future]` | Not yet implemented in code |
|
||||
|
||||
**Documentation status (within component pages):**
|
||||
|
||||
If building a UI3-style system, each documentation frame gets a status banner with one of these labels:
|
||||
|
||||
- `APPROVED` — fully vetted
|
||||
- `READY FOR REVIEW` — awaiting sign-off
|
||||
- `WORK IN PROGRESS` — actively being designed
|
||||
- `NEEDS UPDATE` — outdated, requires revision
|
||||
- `DO NOT REFERENCE` — should not be used
|
||||
|
||||
This system is only recommended for large, multi-team systems where lifecycle tracking provides real value. For smaller systems, skip the emoji status indicators and use plain page names.
|
||||
|
||||
---
|
||||
|
||||
## 8. When to Match Existing vs. Use Defaults
|
||||
|
||||
**Always inspect before naming anything.** Run `get_metadata` or `inspectFileStructure` to discover existing conventions before creating any pages or variables.
|
||||
|
||||
### Match the existing file when:
|
||||
|
||||
- The file already has pages with a consistent naming pattern (emoji prefixes, separator style, casing).
|
||||
- The file already has variable collections with an established naming scheme.
|
||||
- The file was started by a design team and carries intentional decisions.
|
||||
- Any existing component names use a specific pattern (PascalCase, kebab-case, namespace prefixes).
|
||||
|
||||
### Use the defaults from this document when:
|
||||
|
||||
- Starting a brand-new Figma file with no existing content.
|
||||
- The existing conventions are inconsistent (mix of styles = no convention to match).
|
||||
- The user explicitly asks for a fresh design system following best practices.
|
||||
|
||||
### When code and Figma disagree:
|
||||
|
||||
If the codebase uses `button-primary` but Figma has a component named `Button`, do not rename the Figma component. Instead:
|
||||
- Keep the Figma name as `Button` (PascalCase, human-readable).
|
||||
- Set variable code syntax to match the exact CSS token name from the codebase.
|
||||
- Set Code Connect source path to the actual code file and use the exact code component name.
|
||||
|
||||
**The rule:** Figma names are for designers; code syntax and Code Connect source paths carry the exact code identifiers. These two identity systems operate in parallel.
|
||||
|
||||
---
|
||||
|
||||
## 9. Figma Variable Names vs Code Names — The Full Picture
|
||||
|
||||
This is one of the most misunderstood areas. Figma names and code names follow **different conventions on purpose** — they serve different audiences and live in different environments.
|
||||
|
||||
### Why they differ
|
||||
|
||||
| | Figma variable name | Code syntax (WEB) |
|
||||
|---|---|---|
|
||||
| **Audience** | Designers in the Variables panel | Developers in CSS/Swift/Kotlin |
|
||||
| **Separator** | `/` (slash) — creates visual grouping in Figma UI | `-` (hyphen) — required by CSS custom property syntax |
|
||||
| **Case** | lowercase (or PascalCase for display — see below) | kebab-case for CSS; camelCase for JS/Android |
|
||||
| **Depth** | 2–4 levels | Flat for CSS; dot-notation for JS |
|
||||
| **Namespace** | Implicit (by collection) | Explicit prefix (`--p-`, `--md-`, `--cds-`) |
|
||||
|
||||
### The transformation
|
||||
|
||||
```
|
||||
Figma variable name Code syntax (WEB)
|
||||
────────────────── ─────────────────
|
||||
color/bg/primary → var(--color-bg-primary)
|
||||
spacing/xs → var(--spacing-xs)
|
||||
radius/md → var(--radius-md)
|
||||
typography/body/font-size → var(--typography-body-font-size)
|
||||
|
||||
Pattern: replace "/" with "-", wrap in var(--)
|
||||
|
||||
**CRITICAL: The `var()` wrapper is REQUIRED for WEB code syntax.** Figma expects the full CSS function syntax — not just the property name. If you set `--color-bg-primary` (without `var()`), Dev Mode will show raw hex values instead of the variable reference. Always set `var(--color-bg-primary)`.
|
||||
```
|
||||
|
||||
```
|
||||
Figma variable name Code syntax (ANDROID)
|
||||
────────────────── ─────────────────────
|
||||
color/bg/primary → colorBgPrimary
|
||||
spacing/xs → spacingXs
|
||||
radius/md → radiusMd
|
||||
|
||||
Pattern: replace "/" with "", capitalize each word after first
|
||||
```
|
||||
|
||||
```
|
||||
Figma variable name Code syntax (iOS)
|
||||
────────────────── ─────────────────
|
||||
color/bg/primary → Color.bgPrimary
|
||||
spacing/xs → Spacing.xs
|
||||
radius/md → Radius.md
|
||||
|
||||
Pattern: first segment becomes class name, remainder becomes property (camelCase)
|
||||
```
|
||||
|
||||
### Real-world examples from the 5 reference files
|
||||
|
||||
| File | Figma variable name | WEB code syntax | ANDROID code syntax |
|
||||
|------|--------------------|-----------------|--------------------|
|
||||
| Simple DS | `color/bg/primary` | `var(--color-bg-primary)` | `colorBgPrimary` |
|
||||
| Simple DS | `spacing/sm` | `var(--spacing-sm)` | `spacingSm` |
|
||||
| Material 3 | `Schemes/Primary` | `var(--md-sys-color-primary)` | `colorPrimary` |
|
||||
| Material 3 | `Corner/Extra-small` | `var(--md-sys-shape-corner-extra-small)` | `shapeCornerExtraSmall` |
|
||||
| Polaris | `color/bg/surface` | `var(--p-color-bg-surface)` | — |
|
||||
|
||||
**Key observation from Material 3:** The Figma name `Schemes/Primary` uses PascalCase with a space, but the WEB code syntax is `var(--md-sys-color-primary)` — entirely kebab-case with a vendor prefix `md-sys-`. The Figma name and the code syntax bear almost no resemblance. This is intentional and common in mature design systems.
|
||||
|
||||
### Casing in Figma: lowercase is default, PascalCase is valid for display
|
||||
|
||||
The guideline to use lowercase is a default, not a universal rule. Evidence from real files:
|
||||
|
||||
| File | Figma case | Code output case | Why |
|
||||
|------|-----------|------------------|-----|
|
||||
| Simple DS | `color/bg/primary` (lowercase) | `var(--color-bg-primary)` | Direct mapping — simple |
|
||||
| Material 3 | `Schemes/Primary` (PascalCase) | `var(--md-sys-color-primary)` | PascalCase reads better in Variables panel; code name is independently defined |
|
||||
| Polaris | `color/bg/surface` (lowercase) | `var(--p-color-bg-surface)` | Direct mapping with vendor prefix |
|
||||
|
||||
**Rule:** Use lowercase when the Figma name will map directly to the CSS name. Use PascalCase (or match existing file) when the design system has human-readable variable names that are distinct from the technical code names.
|
||||
|
||||
### When the codebase doesn't use CSS custom properties
|
||||
|
||||
Some JavaScript-first systems (Chakra, Ant Design, MUI) don't use CSS `var(--...)` at all. Their tokens live in JS theme objects:
|
||||
|
||||
```
|
||||
Chakra: colors.gray[500] → JS: theme.colors.gray[500]
|
||||
Ant: colorPrimary → JS: token.colorPrimary
|
||||
MUI: palette.primary.main → JS: theme.palette.primary.main
|
||||
```
|
||||
|
||||
In these cases, set WEB code syntax to the JS property path rather than a CSS variable:
|
||||
```javascript
|
||||
// For a JS-object-based system like Chakra:
|
||||
v.setVariableCodeSyntax('WEB', 'colors.gray.500');
|
||||
|
||||
// For Ant Design:
|
||||
v.setVariableCodeSyntax('WEB', 'colorPrimary');
|
||||
```
|
||||
|
||||
### Hierarchy depth: match the codebase
|
||||
|
||||
The number of slash levels should mirror the codebase's nesting depth:
|
||||
|
||||
| Codebase pattern | Figma depth | Example |
|
||||
|-----------------|------------|---------|
|
||||
| `--primary` (flat) | 1–2 levels | `color/primary` |
|
||||
| `--color-bg-surface` (3-part) | 3 levels | `color/bg/surface` |
|
||||
| `--md-sys-color-primary` (vendor + 3-part) | 3 levels (vendor prefix goes in code syntax only) | `color/primary` |
|
||||
| `theme.palette.primary.main` (4-part) | 3–4 levels | `color/palette/primary/main` |
|
||||
|
||||
**Important:** Vendor prefixes (`--p-`, `--md-sys-`, `--cds-`) belong in the **code syntax**, not the Figma variable name. The Figma name `color/bg/surface` + code syntax `var(--p-color-bg-surface)` is the correct pattern.
|
||||
|
||||
### Action at discovery time
|
||||
|
||||
During Phase 0 discovery, capture both sides of the mapping explicitly:
|
||||
|
||||
```
|
||||
For each token found in the codebase:
|
||||
CSS variable: --sds-color-background-brand-default
|
||||
Figma name: color/bg/brand/default (slash hierarchy, no vendor prefix)
|
||||
WEB syntax: var(--sds-color-background-brand-default) (exact CSS name)
|
||||
ANDROID syntax: sdsColorBackgroundBrandDefault (camelCase)
|
||||
iOS syntax: Color.backgroundBrandDefault (dot-notation)
|
||||
```
|
||||
|
||||
Store this mapping in the state ledger. Use it when calling `setVariableCodeSyntax` in Phase 1. Never derive the code syntax from the Figma name if you have the original CSS variable name — always use the original.
|
||||
+888
@@ -0,0 +1,888 @@
|
||||
> Part of the [figma-generate-library skill](../SKILL.md).
|
||||
|
||||
# Token Creation Reference
|
||||
|
||||
This document covers Phase 1: creating variable collections, modes, primitives, semantic aliases, scopes, code syntax, styles, and validation. All code is copy-paste ready for `use_figma`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Collection Architecture
|
||||
|
||||
Choose the pattern that matches your token count and complexity:
|
||||
|
||||
### Simple Pattern (< 50 tokens)
|
||||
|
||||
One collection, 2 modes. Appropriate for small projects or brand kits.
|
||||
|
||||
```
|
||||
Collection: "Tokens" modes: ["Light", "Dark"]
|
||||
color/bg/primary → Light: #FFFFFF, Dark: #1A1A1A
|
||||
spacing/sm = 8
|
||||
```
|
||||
|
||||
### Standard Pattern (50–200 tokens) — Recommended Starting Point
|
||||
|
||||
Separate primitives from semantics. The real-world reference is Figma's Simple Design System (SDS): 7 collections, 368 variables, light/dark modes on semantic colors, single-mode primitives.
|
||||
|
||||
```
|
||||
Collection: "Primitives" modes: ["Value"] ← raw hex values, no modes
|
||||
blue/500 = #3B82F6
|
||||
gray/900 = #111827
|
||||
white/1000 = #FFFFFF
|
||||
|
||||
Collection: "Color" modes: ["Light", "Dark"] ← aliases to Primitives
|
||||
color/bg/primary → Light: alias Primitives/white/1000, Dark: alias Primitives/gray/900
|
||||
color/text/primary → Light: alias Primitives/gray/900, Dark: alias Primitives/white/1000
|
||||
|
||||
Collection: "Spacing" modes: ["Value"]
|
||||
spacing/xs = 4, spacing/sm = 8, spacing/md = 16, spacing/lg = 24, spacing/xl = 32
|
||||
|
||||
Collection: "Typography Primitives" modes: ["Value"]
|
||||
family/sans = "Inter", scale/01 = 12, scale/02 = 14, scale/03 = 16, weight/regular = 400
|
||||
|
||||
Collection: "Typography" modes: ["Value"] ← aliases to Typography Primitives
|
||||
body/font-family → alias family/sans
|
||||
body/size-md → alias scale/03
|
||||
```
|
||||
|
||||
### Advanced Pattern (200+ tokens) — M3 Model
|
||||
|
||||
Multiple semantic collections, 4–8 modes. Use when you need light/dark × contrast × brand or responsive breakpoints.
|
||||
|
||||
```
|
||||
Collection: "M3" modes: ["Light", "Dark", "Light High Contrast", "Dark High Contrast", ...]
|
||||
Collection: "Typeface" modes: ["Baseline", "Wireframe"]
|
||||
Collection: "Typescale" modes: ["Value"] ← aliases into Typeface
|
||||
Collection: "Shape" modes: ["Value"]
|
||||
```
|
||||
|
||||
Key insight from M3: ALL 196 semantic color variables live in a SINGLE collection with 8 modes. Switching a frame's mode once updates every color simultaneously.
|
||||
|
||||
---
|
||||
|
||||
## 2. Creating Collections + Modes
|
||||
|
||||
### Creating a Primitives Collection
|
||||
|
||||
```javascript
|
||||
const RUN_ID = "ds-build-2024-001"; // use the same RUN_ID throughout the build
|
||||
|
||||
// Create the collection
|
||||
const primColl = figma.variables.createVariableCollection("Primitives");
|
||||
|
||||
// Rename the default "Mode 1" to "Value"
|
||||
primColl.renameMode(primColl.modes[0].modeId, "Value");
|
||||
const valueMode = primColl.modes[0].modeId;
|
||||
|
||||
// Tag for idempotency
|
||||
primColl.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
primColl.setSharedPluginData('dsb', 'key', 'collection/primitives');
|
||||
|
||||
return {
|
||||
collectionId: primColl.id,
|
||||
modeId: valueMode,
|
||||
name: primColl.name
|
||||
};
|
||||
```
|
||||
|
||||
### Creating a Semantic Color Collection with Light/Dark Modes
|
||||
|
||||
```javascript
|
||||
const RUN_ID = "ds-build-2024-001";
|
||||
|
||||
const colorColl = figma.variables.createVariableCollection("Color");
|
||||
|
||||
// Rename default "Mode 1" to "Light"
|
||||
colorColl.renameMode(colorColl.modes[0].modeId, "Light");
|
||||
const lightModeId = colorColl.modes[0].modeId;
|
||||
|
||||
// Add "Dark" mode — requires Professional plan or higher
|
||||
// Throws "in addMode: Limited to N modes only" on Starter plan
|
||||
const darkModeId = colorColl.addMode("Dark");
|
||||
|
||||
colorColl.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
colorColl.setSharedPluginData('dsb', 'key', 'collection/color');
|
||||
|
||||
return {
|
||||
collectionId: colorColl.id,
|
||||
lightModeId,
|
||||
darkModeId
|
||||
};
|
||||
```
|
||||
|
||||
**Mode plan limits:** Starter = 1 mode, Professional = 4 modes, Organization/Enterprise = 40 modes. If `addMode` throws, the file is on a Starter plan — tell the user and ask how to proceed.
|
||||
|
||||
### Creating a Spacing Collection (single mode)
|
||||
|
||||
```javascript
|
||||
const RUN_ID = "ds-build-2024-001";
|
||||
|
||||
const spacingColl = figma.variables.createVariableCollection("Spacing");
|
||||
spacingColl.renameMode(spacingColl.modes[0].modeId, "Value");
|
||||
const valueMode = spacingColl.modes[0].modeId;
|
||||
|
||||
spacingColl.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
spacingColl.setSharedPluginData('dsb', 'key', 'collection/spacing');
|
||||
|
||||
return {
|
||||
collectionId: spacingColl.id,
|
||||
modeId: valueMode
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Creating All Variable Types
|
||||
|
||||
### hex → {r, g, b} Conversion Helper
|
||||
|
||||
Colors in the Figma Plugin API are 0–1 range, not 0–255. Embed this helper in any script that creates color variables:
|
||||
|
||||
```javascript
|
||||
function hexToRgb(hex) {
|
||||
const clean = hex.replace('#', '');
|
||||
return {
|
||||
r: parseInt(clean.substring(0, 2), 16) / 255,
|
||||
g: parseInt(clean.substring(2, 4), 16) / 255,
|
||||
b: parseInt(clean.substring(4, 6), 16) / 255
|
||||
};
|
||||
}
|
||||
|
||||
// With alpha channel (for semi-transparent primitives like Black/200 at 10%):
|
||||
function hexToRgba(hex) {
|
||||
const clean = hex.replace('#', '');
|
||||
const hasAlpha = clean.length === 8;
|
||||
return {
|
||||
r: parseInt(clean.substring(0, 2), 16) / 255,
|
||||
g: parseInt(clean.substring(2, 4), 16) / 255,
|
||||
b: parseInt(clean.substring(4, 6), 16) / 255,
|
||||
a: hasAlpha ? parseInt(clean.substring(6, 8), 16) / 255 : 1
|
||||
};
|
||||
}
|
||||
|
||||
// Usage:
|
||||
// hexToRgb('#3B82F6') → {r: 0.231, g: 0.510, b: 0.965}
|
||||
// hexToRgb('#14AE5C') → {r: 0.078, g: 0.682, b: 0.361}
|
||||
// hexToRgba('#0c0c0d1a') → {r: 0.047, g: 0.047, b: 0.051, a: 0.102}
|
||||
```
|
||||
|
||||
### Creating Primitive Color Variables (Real SDS Data)
|
||||
|
||||
This creates a subset of the Simple Design System's `Color Primitives` collection (Blue family, from the Standard pattern used by real design systems):
|
||||
|
||||
```javascript
|
||||
function hexToRgb(hex) {
|
||||
const c = hex.replace('#', '');
|
||||
return { r: parseInt(c.slice(0,2),16)/255, g: parseInt(c.slice(2,4),16)/255, b: parseInt(c.slice(4,6),16)/255 };
|
||||
}
|
||||
|
||||
const RUN_ID = "ds-build-2024-001";
|
||||
|
||||
// Get the Primitives collection created in the previous step
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
const primColl = collections.find(c => c.getSharedPluginData('dsb', 'key') === 'collection/primitives');
|
||||
if (!primColl) throw new Error("Primitives collection not found — run collection creation first");
|
||||
const valueMode = primColl.modes[0].modeId;
|
||||
|
||||
// Define primitives — use real values from your codebase
|
||||
const primitiveColors = [
|
||||
// Blue scale
|
||||
{ name: 'blue/100', hex: '#EFF6FF' },
|
||||
{ name: 'blue/200', hex: '#DBEAFE' },
|
||||
{ name: 'blue/300', hex: '#93C5FD' },
|
||||
{ name: 'blue/400', hex: '#60A5FA' },
|
||||
{ name: 'blue/500', hex: '#3B82F6' },
|
||||
{ name: 'blue/600', hex: '#2563EB' },
|
||||
{ name: 'blue/700', hex: '#1D4ED8' },
|
||||
{ name: 'blue/800', hex: '#1E40AF' },
|
||||
{ name: 'blue/900', hex: '#1E3A8A' },
|
||||
// Gray scale
|
||||
{ name: 'gray/100', hex: '#F9FAFB' },
|
||||
{ name: 'gray/200', hex: '#F3F4F6' },
|
||||
{ name: 'gray/300', hex: '#D1D5DB' },
|
||||
{ name: 'gray/400', hex: '#9CA3AF' },
|
||||
{ name: 'gray/500', hex: '#6B7280' },
|
||||
{ name: 'gray/600', hex: '#4B5563' },
|
||||
{ name: 'gray/700', hex: '#374151' },
|
||||
{ name: 'gray/800', hex: '#1F2937' },
|
||||
{ name: 'gray/900', hex: '#111827' },
|
||||
// White / Black
|
||||
{ name: 'white/1000', hex: '#FFFFFF' },
|
||||
{ name: 'black/1000', hex: '#000000' },
|
||||
];
|
||||
|
||||
const created = [];
|
||||
for (const { name, hex } of primitiveColors) {
|
||||
const v = figma.variables.createVariable(name, primColl, 'COLOR');
|
||||
v.setValueForMode(valueMode, hexToRgb(hex));
|
||||
// Primitives: EMPTY scopes (hidden from all pickers — designers use semantics)
|
||||
v.scopes = [];
|
||||
// Code syntax from the actual CSS variable name
|
||||
v.setVariableCodeSyntax('WEB', `var(--color-${name.replace('/', '-')})`);
|
||||
v.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
v.setSharedPluginData('dsb', 'key', `primitive/${name}`);
|
||||
created.push({ name, id: v.id });
|
||||
}
|
||||
|
||||
return { created, count: created.length };
|
||||
```
|
||||
|
||||
**Critical scope rule for primitives:** Set `v.scopes = []`. This hides primitives from every picker. Designers should only see semantic tokens. The exception is semi-transparent overlay primitives (Black/White with alpha) — those get `["EFFECT_COLOR"]` so they appear in shadow pickers.
|
||||
|
||||
### Creating FLOAT Variables (Spacing, Radius, Font Size)
|
||||
|
||||
```javascript
|
||||
const RUN_ID = "ds-build-2024-001";
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
const spacingColl = collections.find(c => c.getSharedPluginData('dsb', 'key') === 'collection/spacing');
|
||||
if (!spacingColl) throw new Error("Spacing collection not found");
|
||||
const valueMode = spacingColl.modes[0].modeId;
|
||||
|
||||
const spacingTokens = [
|
||||
{ name: 'spacing/xs', value: 4, scope: 'GAP', cssVar: '--spacing-xs' },
|
||||
{ name: 'spacing/sm', value: 8, scope: 'GAP', cssVar: '--spacing-sm' },
|
||||
{ name: 'spacing/md', value: 16, scope: 'GAP', cssVar: '--spacing-md' },
|
||||
{ name: 'spacing/lg', value: 24, scope: 'GAP', cssVar: '--spacing-lg' },
|
||||
{ name: 'spacing/xl', value: 32, scope: 'GAP', cssVar: '--spacing-xl' },
|
||||
{ name: 'spacing/2xl', value: 48, scope: 'GAP', cssVar: '--spacing-2xl' },
|
||||
];
|
||||
|
||||
const radiusTokens = [
|
||||
{ name: 'radius/none', value: 0, scope: 'CORNER_RADIUS', cssVar: '--radius-none' },
|
||||
{ name: 'radius/sm', value: 4, scope: 'CORNER_RADIUS', cssVar: '--radius-sm' },
|
||||
{ name: 'radius/md', value: 8, scope: 'CORNER_RADIUS', cssVar: '--radius-md' },
|
||||
{ name: 'radius/lg', value: 16, scope: 'CORNER_RADIUS', cssVar: '--radius-lg' },
|
||||
{ name: 'radius/full', value: 9999, scope: 'CORNER_RADIUS', cssVar: '--radius-full' },
|
||||
];
|
||||
|
||||
const created = [];
|
||||
for (const { name, value, scope, cssVar } of [...spacingTokens, ...radiusTokens]) {
|
||||
const v = figma.variables.createVariable(name, spacingColl, 'FLOAT');
|
||||
v.setValueForMode(valueMode, value);
|
||||
v.scopes = [scope];
|
||||
v.setVariableCodeSyntax('WEB', `var(${cssVar})`);
|
||||
v.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
v.setSharedPluginData('dsb', 'key', name);
|
||||
created.push({ name, value, id: v.id });
|
||||
}
|
||||
|
||||
return { created, count: created.length };
|
||||
```
|
||||
|
||||
### Creating STRING Variables (Font Family, Font Style)
|
||||
|
||||
```javascript
|
||||
const RUN_ID = "ds-build-2024-001";
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
const typoPrimColl = collections.find(c => c.getSharedPluginData('dsb', 'key') === 'collection/typography-primitives');
|
||||
if (!typoPrimColl) throw new Error("Typography Primitives collection not found");
|
||||
const valueMode = typoPrimColl.modes[0].modeId;
|
||||
|
||||
const fontTokens = [
|
||||
{ name: 'family/sans', value: 'Inter', scope: 'FONT_FAMILY', cssVar: '--font-family-sans' },
|
||||
{ name: 'family/mono', value: 'Roboto Mono', scope: 'FONT_FAMILY', cssVar: '--font-family-mono' },
|
||||
// Font style strings — these are the Figma fontName.style values:
|
||||
{ name: 'weight/regular', value: 'Regular', scope: 'FONT_STYLE', cssVar: '--font-weight-regular' },
|
||||
{ name: 'weight/medium', value: 'Medium', scope: 'FONT_STYLE', cssVar: '--font-weight-medium' },
|
||||
{ name: 'weight/semibold', value: 'Semi Bold', scope: 'FONT_STYLE', cssVar: '--font-weight-semibold' },
|
||||
{ name: 'weight/bold', value: 'Bold', scope: 'FONT_STYLE', cssVar: '--font-weight-bold' },
|
||||
];
|
||||
|
||||
const created = [];
|
||||
for (const { name, value, scope, cssVar } of fontTokens) {
|
||||
const v = figma.variables.createVariable(name, typoPrimColl, 'STRING');
|
||||
v.setValueForMode(valueMode, value);
|
||||
v.scopes = [scope];
|
||||
v.setVariableCodeSyntax('WEB', `var(${cssVar})`);
|
||||
v.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
v.setSharedPluginData('dsb', 'key', `typo-prim/${name}`);
|
||||
created.push({ name, value, id: v.id });
|
||||
}
|
||||
|
||||
return { created, count: created.length };
|
||||
```
|
||||
|
||||
### Creating BOOLEAN Variables
|
||||
|
||||
BOOLEAN variables have no scopes (scopes are not supported for BOOLEAN type).
|
||||
|
||||
```javascript
|
||||
const RUN_ID = "ds-build-2024-001";
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
const coll = collections.find(c => c.getSharedPluginData('dsb', 'key') === 'collection/tokens');
|
||||
if (!coll) throw new Error("Collection not found");
|
||||
const valueMode = coll.modes[0].modeId;
|
||||
|
||||
const v = figma.variables.createVariable('feature-flags/show-beta-badge', coll, 'BOOLEAN');
|
||||
v.setValueForMode(valueMode, false);
|
||||
// No scopes — BOOLEAN does not support scopes
|
||||
v.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
v.setSharedPluginData('dsb', 'key', 'feature-flags/show-beta-badge');
|
||||
|
||||
return { id: v.id, name: v.name };
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Variable Aliasing (VARIABLE_ALIAS) — Primitive → Semantic Chain
|
||||
|
||||
Semantic tokens reference primitives via `VARIABLE_ALIAS`. This is the core pattern that makes light/dark theming work.
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
Color Primitives collection (1 mode: Value)
|
||||
blue/500 = #3B82F6 ← raw value
|
||||
|
||||
Color collection (2 modes: Light, Dark)
|
||||
color/bg/accent/default:
|
||||
Light → VARIABLE_ALIAS → Primitives/blue/500
|
||||
Dark → VARIABLE_ALIAS → Primitives/blue/300
|
||||
```
|
||||
|
||||
### Complete Semantic Alias Creation Script (SDS-style)
|
||||
|
||||
```javascript
|
||||
function hexToRgb(hex) {
|
||||
const c = hex.replace('#', '');
|
||||
return { r: parseInt(c.slice(0,2),16)/255, g: parseInt(c.slice(2,4),16)/255, b: parseInt(c.slice(4,6),16)/255 };
|
||||
}
|
||||
|
||||
const RUN_ID = "ds-build-2024-001";
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
|
||||
const primColl = collections.find(c => c.getSharedPluginData('dsb', 'key') === 'collection/primitives');
|
||||
const colorColl = collections.find(c => c.getSharedPluginData('dsb', 'key') === 'collection/color');
|
||||
if (!primColl || !colorColl) throw new Error("Collections not found — run primitive/color collection creation first");
|
||||
|
||||
const primValueMode = primColl.modes[0].modeId;
|
||||
const lightModeId = colorColl.modes.find(m => m.name === 'Light').modeId;
|
||||
const darkModeId = colorColl.modes.find(m => m.name === 'Dark').modeId;
|
||||
|
||||
// Load all primitive variables for lookup
|
||||
const allVars = await figma.variables.getLocalVariablesAsync();
|
||||
const primsByKey = {};
|
||||
for (const v of allVars) {
|
||||
if (v.variableCollectionId === primColl.id) {
|
||||
primsByKey[v.getSharedPluginData('dsb', 'key')] = v;
|
||||
}
|
||||
}
|
||||
|
||||
function getPrim(name) {
|
||||
const v = primsByKey[`primitive/${name}`];
|
||||
if (!v) throw new Error(`Primitive not found: primitive/${name}`);
|
||||
return v;
|
||||
}
|
||||
|
||||
// Define semantic → [lightPrimitiveName, darkPrimitiveName]
|
||||
// Following the SDS pattern: Background/{Intent}/{Emphasis}
|
||||
const semanticColors = [
|
||||
// Background
|
||||
{ name: 'color/bg/default/default', lightPrim: 'white/1000', darkPrim: 'gray/900',
|
||||
cssVar: '--color-bg-default-default', scopes: ['FRAME_FILL', 'SHAPE_FILL'] },
|
||||
{ name: 'color/bg/default/secondary', lightPrim: 'gray/100', darkPrim: 'gray/800',
|
||||
cssVar: '--color-bg-default-secondary', scopes: ['FRAME_FILL', 'SHAPE_FILL'] },
|
||||
{ name: 'color/bg/brand/default', lightPrim: 'blue/600', darkPrim: 'blue/300',
|
||||
cssVar: '--color-bg-brand-default', scopes: ['FRAME_FILL', 'SHAPE_FILL'] },
|
||||
// Text
|
||||
{ name: 'color/text/default/default', lightPrim: 'gray/900', darkPrim: 'white/1000',
|
||||
cssVar: '--color-text-default-default', scopes: ['TEXT_FILL'] },
|
||||
{ name: 'color/text/default/secondary', lightPrim: 'gray/500', darkPrim: 'gray/400',
|
||||
cssVar: '--color-text-default-secondary', scopes: ['TEXT_FILL'] },
|
||||
{ name: 'color/text/brand/default', lightPrim: 'blue/700', darkPrim: 'blue/200',
|
||||
cssVar: '--color-text-brand-default', scopes: ['TEXT_FILL'] },
|
||||
// Border
|
||||
{ name: 'color/border/default/default', lightPrim: 'gray/300', darkPrim: 'gray/600',
|
||||
cssVar: '--color-border-default-default', scopes: ['STROKE_COLOR'] },
|
||||
{ name: 'color/border/brand/default', lightPrim: 'blue/500', darkPrim: 'blue/400',
|
||||
cssVar: '--color-border-brand-default', scopes: ['STROKE_COLOR'] },
|
||||
];
|
||||
|
||||
const created = [];
|
||||
for (const { name, lightPrim, darkPrim, cssVar, scopes } of semanticColors) {
|
||||
const v = figma.variables.createVariable(name, colorColl, 'COLOR');
|
||||
// Alias to primitive in Light mode
|
||||
v.setValueForMode(lightModeId, figma.variables.createVariableAlias(getPrim(lightPrim)));
|
||||
// Alias to primitive in Dark mode
|
||||
v.setValueForMode(darkModeId, figma.variables.createVariableAlias(getPrim(darkPrim)));
|
||||
// Set scopes (semantic layer — these ARE shown in pickers)
|
||||
v.scopes = scopes;
|
||||
// Code syntax
|
||||
v.setVariableCodeSyntax('WEB', `var(${cssVar})`);
|
||||
v.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
v.setSharedPluginData('dsb', 'key', name);
|
||||
created.push({ name, id: v.id });
|
||||
}
|
||||
|
||||
return { created, count: created.length };
|
||||
```
|
||||
|
||||
**Key API points:**
|
||||
- `figma.variables.createVariableAlias(variable)` — takes a Variable object, returns `{type:'VARIABLE_ALIAS', id: variable.id}`
|
||||
- The aliased variable MUST have the same `resolvedType` as the semantic variable
|
||||
- Never duplicate raw values in the semantic layer — always alias
|
||||
|
||||
---
|
||||
|
||||
## 5. Variable Scopes — Complete Reference Table
|
||||
|
||||
| Semantic Role | Recommended Scopes | Variable Type |
|
||||
|---|---|---|
|
||||
| Primitive colors (raw) | `[]` — empty, hidden from all pickers | COLOR |
|
||||
| Semi-transparent overlay primitives | `["EFFECT_COLOR"]` | COLOR |
|
||||
| Background fills (frame, shape) | `["FRAME_FILL", "SHAPE_FILL"]` | COLOR |
|
||||
| Text color | `["TEXT_FILL"]` | COLOR |
|
||||
| Icon / shape fill | `["SHAPE_FILL", "STROKE_COLOR"]` | COLOR |
|
||||
| Border / stroke color | `["STROKE_COLOR"]` | COLOR |
|
||||
| Background + border combined | `["FRAME_FILL", "SHAPE_FILL", "STROKE_COLOR"]` | COLOR |
|
||||
| Shadow color | `["EFFECT_COLOR"]` | COLOR |
|
||||
| Spacing / gap between items | `["GAP"]` | FLOAT |
|
||||
| Padding (if separate from gap) | `["GAP"]` | FLOAT |
|
||||
| Corner radius | `["CORNER_RADIUS"]` | FLOAT |
|
||||
| Width / height dimensions | `["WIDTH_HEIGHT"]` | FLOAT |
|
||||
| Font size | `["FONT_SIZE"]` | FLOAT |
|
||||
| Line height | `["LINE_HEIGHT"]` | FLOAT |
|
||||
| Letter spacing | `["LETTER_SPACING"]` | FLOAT |
|
||||
| Font weight (numeric) | `["FONT_WEIGHT"]` | FLOAT |
|
||||
| Stroke width | `["STROKE_FLOAT"]` | FLOAT |
|
||||
| Effect blur radius | `["EFFECT_FLOAT"]` | FLOAT |
|
||||
| Opacity | `["OPACITY"]` | FLOAT |
|
||||
| Font family | `["FONT_FAMILY"]` | STRING |
|
||||
| Font style (e.g. "Semi Bold") | `["FONT_STYLE"]` | STRING |
|
||||
| Boolean flags | *(scopes not supported)* | BOOLEAN |
|
||||
|
||||
**Never use `ALL_SCOPES`** on any variable. It pollutes every picker with irrelevant tokens. The Simple Design System (SDS), the gold standard, uses targeted scopes on every variable.
|
||||
|
||||
**`ALL_FILLS` note:** `ALL_FILLS` is exclusive among fill scopes — it covers `FRAME_FILL`, `SHAPE_FILL`, and `TEXT_FILL` together. If set, you cannot also add individual fill scopes. Prefer specifying individual scopes for precision.
|
||||
|
||||
### Batch Scope-Setting (After Variables are Created)
|
||||
|
||||
If you created variables without scopes and need to set them in batch:
|
||||
|
||||
```javascript
|
||||
const allVars = await figma.variables.getLocalVariablesAsync();
|
||||
|
||||
// Scope mapping: partial name match → scopes
|
||||
const scopeRules = [
|
||||
{ match: 'color/bg/', scopes: ['FRAME_FILL', 'SHAPE_FILL'] },
|
||||
{ match: 'color/text/', scopes: ['TEXT_FILL'] },
|
||||
{ match: 'color/icon/', scopes: ['SHAPE_FILL', 'STROKE_COLOR'] },
|
||||
{ match: 'color/border/', scopes: ['STROKE_COLOR'] },
|
||||
{ match: 'spacing/', scopes: ['GAP'] },
|
||||
{ match: 'radius/', scopes: ['CORNER_RADIUS'] },
|
||||
{ match: 'blue/', scopes: [] }, // primitives — hide
|
||||
{ match: 'gray/', scopes: [] },
|
||||
{ match: 'white/', scopes: [] },
|
||||
{ match: 'black/', scopes: [] },
|
||||
];
|
||||
|
||||
const updated = [];
|
||||
for (const v of allVars) {
|
||||
if (v.remote) continue; // skip library variables
|
||||
for (const rule of scopeRules) {
|
||||
if (v.name.startsWith(rule.match)) {
|
||||
v.scopes = rule.scopes;
|
||||
updated.push({ name: v.name, scopes: rule.scopes });
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return { updated, count: updated.length };
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Code Syntax — WEB/ANDROID/iOS
|
||||
|
||||
Every variable must have code syntax set. This is what powers the developer handoff experience:
|
||||
|
||||
**What code syntax does:** When a developer inspects any element in Figma Dev Mode that has a variable-bound property (fill, padding, radius, etc.), the code snippet shown uses the variable's code syntax name — not the Figma variable name. For example, a button's background fill bound to `color/bg/primary` will show `background: var(--color-bg-primary)` in the CSS snippet, not `color/bg/primary`. Without code syntax set, Dev Mode shows raw hex values or nothing useful.
|
||||
|
||||
You can set up to **3 syntaxes per variable** — one per platform (Web, iOS, Android). Set all three if the codebase targets multiple platforms; set only WEB if it's a web-only project.
|
||||
|
||||
```javascript
|
||||
// WEB: MUST include the var() wrapper — this is the full CSS function syntax
|
||||
variable.setVariableCodeSyntax('WEB', 'var(--color-bg-primary)');
|
||||
// ^^^^ ^
|
||||
// var() wrapper is REQUIRED
|
||||
|
||||
// ANDROID: Kotlin property name — camelCase, no wrapper
|
||||
variable.setVariableCodeSyntax('ANDROID', 'colorBgPrimary');
|
||||
|
||||
// iOS: Swift property — dot-notation, no wrapper
|
||||
variable.setVariableCodeSyntax('iOS', 'Color.bgPrimary');
|
||||
```
|
||||
|
||||
> **CRITICAL — WEB code syntax MUST use the `var()` wrapper.** Setting just `--color-bg-primary` (without `var()`) will cause Dev Mode to show raw hex values instead of the CSS variable reference. Always use the full `var(--name)` form. ANDROID and iOS do NOT use a wrapper.
|
||||
|
||||
**Platform derivation rules from the CSS variable name:**
|
||||
|
||||
| Platform | Pattern | Example |
|
||||
|---|---|---|
|
||||
| WEB | **`var(--{css-var-name})`** — `var()` wrapper required | `var(--sds-color-bg-primary)` |
|
||||
| ANDROID | camelCase, no wrapper, strip `--` prefix | `sdsColorBgPrimary` |
|
||||
| iOS | PascalCase after `.`, no wrapper, strip `--` prefix | `Color.SdsColorBgPrimary` or `Color.bgPrimary` |
|
||||
|
||||
**Always use the actual CSS variable name from the codebase** — do not derive it from the Figma variable name. If the code uses `--sds-color-background-brand-default`, that exact string is the WEB code syntax (minus the `var()` wrapper that you add).
|
||||
|
||||
### Batch Code Syntax Setting
|
||||
|
||||
```javascript
|
||||
const allVars = await figma.variables.getLocalVariablesAsync();
|
||||
const updated = [];
|
||||
|
||||
for (const v of allVars) {
|
||||
if (v.remote) continue;
|
||||
// If code syntax already set, skip
|
||||
if (v.codeSyntax['WEB']) continue;
|
||||
|
||||
// FALLBACK: derive from Figma name: color/bg/primary → var(--color-bg-primary)
|
||||
// PREFERRED: pass in a cssVarMap built from actual codebase CSS variable names
|
||||
// e.g. cssVarMap = { 'color/bg/primary': '--color-bg-primary', ... }
|
||||
const cssName = cssVarMap?.[v.name]
|
||||
?? v.name.replace(/\//g, '-').replace(/\s/g, '-').toLowerCase();
|
||||
v.setVariableCodeSyntax('WEB', `var(--${cssName})`);
|
||||
updated.push({ name: v.name, web: `var(--${cssName})` });
|
||||
}
|
||||
|
||||
return { updated, count: updated.length };
|
||||
```
|
||||
|
||||
Note: derived names are a fallback only. Always prefer overriding with actual CSS variable names from the codebase when they are known.
|
||||
|
||||
---
|
||||
|
||||
## 7. Effect Styles (Shadows) and Text Styles
|
||||
|
||||
Shadows and composite typography cannot be variables — they are Styles.
|
||||
|
||||
### Creating Effect Styles (Shadows)
|
||||
|
||||
Reference from SDS (15 effect styles) and the SDS shadow pattern `Shadow/{Level}`:
|
||||
|
||||
```javascript
|
||||
const RUN_ID = "ds-build-2024-001";
|
||||
|
||||
// Shadow definitions — CSS equivalent in comments
|
||||
// CSS: 0 1px 2px rgba(0,0,0,0.05)
|
||||
const shadows = [
|
||||
{
|
||||
name: 'Shadow/Subtle',
|
||||
effects: [{
|
||||
type: 'DROP_SHADOW',
|
||||
color: { r: 0, g: 0, b: 0, a: 0.05 },
|
||||
offset: { x: 0, y: 1 },
|
||||
radius: 2,
|
||||
spread: 0,
|
||||
visible: true,
|
||||
blendMode: 'NORMAL'
|
||||
}]
|
||||
},
|
||||
{
|
||||
// CSS: 0 4px 6px -1px rgba(0,0,0,0.10), 0 2px 4px -1px rgba(0,0,0,0.06)
|
||||
name: 'Shadow/Medium',
|
||||
effects: [
|
||||
{
|
||||
type: 'DROP_SHADOW',
|
||||
color: { r: 0, g: 0, b: 0, a: 0.10 },
|
||||
offset: { x: 0, y: 4 },
|
||||
radius: 6,
|
||||
spread: -1,
|
||||
visible: true,
|
||||
blendMode: 'NORMAL'
|
||||
},
|
||||
{
|
||||
type: 'DROP_SHADOW',
|
||||
color: { r: 0, g: 0, b: 0, a: 0.06 },
|
||||
offset: { x: 0, y: 2 },
|
||||
radius: 4,
|
||||
spread: -1,
|
||||
visible: true,
|
||||
blendMode: 'NORMAL'
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
// CSS: 0 10px 15px -3px rgba(0,0,0,0.10), 0 4px 6px -2px rgba(0,0,0,0.05)
|
||||
name: 'Shadow/Strong',
|
||||
effects: [
|
||||
{
|
||||
type: 'DROP_SHADOW',
|
||||
color: { r: 0, g: 0, b: 0, a: 0.10 },
|
||||
offset: { x: 0, y: 10 },
|
||||
radius: 15,
|
||||
spread: -3,
|
||||
visible: true,
|
||||
blendMode: 'NORMAL'
|
||||
},
|
||||
{
|
||||
type: 'DROP_SHADOW',
|
||||
color: { r: 0, g: 0, b: 0, a: 0.05 },
|
||||
offset: { x: 0, y: 4 },
|
||||
radius: 6,
|
||||
spread: -2,
|
||||
visible: true,
|
||||
blendMode: 'NORMAL'
|
||||
}
|
||||
]
|
||||
}
|
||||
];
|
||||
|
||||
// M3-style dual shadow (umbra + penumbra pattern):
|
||||
const m3Shadows = [
|
||||
{
|
||||
name: 'Elevation/1',
|
||||
effects: [
|
||||
{ type: 'DROP_SHADOW', color: {r:0,g:0,b:0,a:0.30}, offset:{x:0,y:1}, radius:2, spread:0, visible:true, blendMode:'NORMAL' },
|
||||
{ type: 'DROP_SHADOW', color: {r:0,g:0,b:0,a:0.15}, offset:{x:0,y:1}, radius:3, spread:1, visible:true, blendMode:'NORMAL' }
|
||||
]
|
||||
},
|
||||
{
|
||||
name: 'Elevation/2',
|
||||
effects: [
|
||||
{ type: 'DROP_SHADOW', color: {r:0,g:0,b:0,a:0.30}, offset:{x:0,y:1}, radius:2, spread:0, visible:true, blendMode:'NORMAL' },
|
||||
{ type: 'DROP_SHADOW', color: {r:0,g:0,b:0,a:0.15}, offset:{x:0,y:2}, radius:6, spread:2, visible:true, blendMode:'NORMAL' }
|
||||
]
|
||||
},
|
||||
{
|
||||
name: 'Elevation/3',
|
||||
effects: [
|
||||
{ type: 'DROP_SHADOW', color: {r:0,g:0,b:0,a:0.30}, offset:{x:0,y:1}, radius:3, spread:0, visible:true, blendMode:'NORMAL' },
|
||||
{ type: 'DROP_SHADOW', color: {r:0,g:0,b:0,a:0.15}, offset:{x:0,y:4}, radius:8, spread:3, visible:true, blendMode:'NORMAL' }
|
||||
]
|
||||
}
|
||||
];
|
||||
|
||||
const created = [];
|
||||
for (const { name, effects } of shadows) {
|
||||
const style = figma.createEffectStyle();
|
||||
style.name = name;
|
||||
style.effects = effects;
|
||||
style.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
style.setSharedPluginData('dsb', 'key', `effect-style/${name}`);
|
||||
created.push({ name, id: style.id });
|
||||
}
|
||||
|
||||
return { created, count: created.length };
|
||||
```
|
||||
|
||||
### Creating Text Styles
|
||||
|
||||
Fonts must be loaded before creating text styles.
|
||||
|
||||
```javascript
|
||||
const RUN_ID = "ds-build-2024-001";
|
||||
|
||||
// Define text styles — based on SDS typography hierarchy
|
||||
const textStyles = [
|
||||
// Display / Hero
|
||||
{ name: 'Display/Hero', family: 'Inter', style: 'Bold', size: 72, lineHeight: 80, letterSpacing: -1.5 },
|
||||
// Headings
|
||||
{ name: 'Heading/H1', family: 'Inter', style: 'Bold', size: 48, lineHeight: 56, letterSpacing: -1.0 },
|
||||
{ name: 'Heading/H2', family: 'Inter', style: 'Bold', size: 40, lineHeight: 48, letterSpacing: -0.5 },
|
||||
{ name: 'Heading/H3', family: 'Inter', style: 'Semi Bold', size: 32, lineHeight: 40, letterSpacing: 0 },
|
||||
{ name: 'Heading/H4', family: 'Inter', style: 'Semi Bold', size: 24, lineHeight: 32, letterSpacing: 0 },
|
||||
// Body
|
||||
{ name: 'Body/Large', family: 'Inter', style: 'Regular', size: 18, lineHeight: 28, letterSpacing: 0 },
|
||||
{ name: 'Body/Medium', family: 'Inter', style: 'Regular', size: 16, lineHeight: 24, letterSpacing: 0 },
|
||||
{ name: 'Body/Small', family: 'Inter', style: 'Regular', size: 14, lineHeight: 20, letterSpacing: 0 },
|
||||
// Label
|
||||
{ name: 'Label/Large', family: 'Inter', style: 'Medium', size: 14, lineHeight: 20, letterSpacing: 0.1 },
|
||||
{ name: 'Label/Medium', family: 'Inter', style: 'Medium', size: 12, lineHeight: 16, letterSpacing: 0.5 },
|
||||
{ name: 'Label/Small', family: 'Inter', style: 'Medium', size: 11, lineHeight: 16, letterSpacing: 0.5 },
|
||||
// Code
|
||||
{ name: 'Code/Base', family: 'Roboto Mono', style: 'Regular', size: 14, lineHeight: 20, letterSpacing: 0 },
|
||||
];
|
||||
|
||||
// Load all required fonts first
|
||||
const fontSet = new Set(textStyles.map(s => JSON.stringify({ family: s.family, style: s.style })));
|
||||
await Promise.all([...fontSet].map(f => figma.loadFontAsync(JSON.parse(f))));
|
||||
|
||||
const created = [];
|
||||
for (const { name, family, style, size, lineHeight, letterSpacing } of textStyles) {
|
||||
const ts = figma.createTextStyle();
|
||||
ts.name = name;
|
||||
ts.fontName = { family, style };
|
||||
ts.fontSize = size;
|
||||
ts.lineHeight = { value: lineHeight, unit: 'PIXELS' };
|
||||
ts.letterSpacing = { value: letterSpacing, unit: 'PIXELS' };
|
||||
ts.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
ts.setSharedPluginData('dsb', 'key', `text-style/${name}`);
|
||||
created.push({ name, id: ts.id });
|
||||
}
|
||||
|
||||
return { created, count: created.length };
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Idempotency — Check-Before-Create Pattern
|
||||
|
||||
Every creation script should check whether the entity already exists before creating it. This prevents duplicates when a script is re-run after partial failure.
|
||||
|
||||
### Check-Before-Create for Collections
|
||||
|
||||
```javascript
|
||||
const DSB_KEY = 'collection/primitives';
|
||||
const RUN_ID = "ds-build-2024-001";
|
||||
|
||||
// Check if already exists
|
||||
const existing = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
let primColl = existing.find(c => c.getSharedPluginData('dsb', 'key') === DSB_KEY);
|
||||
|
||||
if (primColl) {
|
||||
return { status: 'already_exists', collectionId: primColl.id, name: primColl.name };
|
||||
}
|
||||
|
||||
// Create only if not found
|
||||
primColl = figma.variables.createVariableCollection("Primitives");
|
||||
primColl.renameMode(primColl.modes[0].modeId, "Value");
|
||||
primColl.setSharedPluginData('dsb', 'run_id', RUN_ID);
|
||||
primColl.setSharedPluginData('dsb', 'key', DSB_KEY);
|
||||
|
||||
return { status: 'created', collectionId: primColl.id };
|
||||
```
|
||||
|
||||
### Check-Before-Create for Variables
|
||||
|
||||
```javascript
|
||||
const VARIABLE_KEY = 'primitive/blue/500';
|
||||
const RUN_ID = "ds-build-2024-001";
|
||||
|
||||
// Check if already exists by sharedPluginData key
|
||||
const allVars = await figma.variables.getLocalVariablesAsync();
|
||||
const existing = allVars.find(v => v.getSharedPluginData('dsb', 'key') === VARIABLE_KEY);
|
||||
|
||||
if (existing) {
|
||||
return { status: 'already_exists', id: existing.id, name: existing.name };
|
||||
}
|
||||
|
||||
// ... create the variable ...
|
||||
return { status: 'created' };
|
||||
```
|
||||
|
||||
### sharedPluginData Tagging Strategy
|
||||
|
||||
Tag every created node immediately after creation. The `key` is the stable logical identifier used for idempotency checks. The `run_id` identifies which build run created it (useful for cleanup).
|
||||
|
||||
```javascript
|
||||
node.setSharedPluginData('dsb', 'run_id', RUN_ID); // build run ID
|
||||
node.setSharedPluginData('dsb', 'phase', 'phase1'); // which phase
|
||||
node.setSharedPluginData('dsb', 'key', 'color/bg/primary'); // stable logical key
|
||||
```
|
||||
|
||||
**Cleanup by run ID (safe — targets only tagged nodes, never user-owned nodes):**
|
||||
|
||||
```javascript
|
||||
const TARGET_RUN_ID = "ds-build-2024-001"; // run to remove
|
||||
const allVars = await figma.variables.getLocalVariablesAsync();
|
||||
const removed = [];
|
||||
for (const v of allVars) {
|
||||
if (v.getSharedPluginData('dsb', 'run_id') === TARGET_RUN_ID) {
|
||||
removed.push(v.name);
|
||||
v.remove();
|
||||
}
|
||||
}
|
||||
return { removed, count: removed.length };
|
||||
```
|
||||
|
||||
**Never clean up by name prefix** (e.g., deleting everything starting with `color/`). This will destroy user-created variables that happen to share the prefix.
|
||||
|
||||
---
|
||||
|
||||
## 9. Validation — Verify Counts, Aliases, and Scopes
|
||||
|
||||
Run these scripts after Phase 1 to verify everything was created correctly before proceeding to Phase 2.
|
||||
|
||||
### Verify Collection and Variable Counts
|
||||
|
||||
```javascript
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
const allVars = await figma.variables.getLocalVariablesAsync();
|
||||
|
||||
const summary = collections.map(c => {
|
||||
const vars = allVars.filter(v => v.variableCollectionId === c.id);
|
||||
return {
|
||||
name: c.name,
|
||||
id: c.id,
|
||||
modes: c.modes.map(m => m.name),
|
||||
variableCount: vars.length,
|
||||
missingScopes: vars.filter(v => v.scopes.length === 0 && v.resolvedType !== 'BOOLEAN').length,
|
||||
missingCodeSyntax: vars.filter(v => !v.codeSyntax['WEB'] && !v.remote).length,
|
||||
sampleVariables: vars.slice(0, 3).map(v => v.name)
|
||||
};
|
||||
});
|
||||
|
||||
return {
|
||||
collectionCount: collections.length,
|
||||
totalVariables: allVars.length,
|
||||
collections: summary
|
||||
};
|
||||
```
|
||||
|
||||
Interpret: `missingScopes > 0` (for non-primitives and non-BOOLEANs) → scope-setting failed, re-run scope script. `missingCodeSyntax > 0` → code syntax not set, run batch code syntax script.
|
||||
|
||||
Note: primitives correctly have `scopes = []` (empty, hidden). `missingScopes` above counts non-BOOLEAN variables with empty scopes — review the list to confirm they are all primitives.
|
||||
|
||||
### Verify Aliases Resolve
|
||||
|
||||
```javascript
|
||||
const allVars = await figma.variables.getLocalVariablesAsync();
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
|
||||
const brokenAliases = [];
|
||||
const aliasedVars = [];
|
||||
|
||||
for (const v of allVars) {
|
||||
if (v.remote) continue;
|
||||
const coll = collections.find(c => c.id === v.variableCollectionId);
|
||||
if (!coll) continue;
|
||||
|
||||
for (const [modeId, val] of Object.entries(v.valuesByMode)) {
|
||||
if (val && typeof val === 'object' && val.type === 'VARIABLE_ALIAS') {
|
||||
aliasedVars.push({ name: v.name, aliasTargetId: val.id });
|
||||
// Verify the target exists
|
||||
const target = allVars.find(t => t.id === val.id);
|
||||
if (!target) {
|
||||
brokenAliases.push({ variable: v.name, modeId, missingTargetId: val.id });
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
totalAliased: aliasedVars.length,
|
||||
brokenAliases,
|
||||
brokenCount: brokenAliases.length,
|
||||
status: brokenAliases.length === 0 ? 'all_aliases_resolve' : 'BROKEN_ALIASES_FOUND'
|
||||
};
|
||||
```
|
||||
|
||||
Interpret: `brokenCount > 0` means a semantic variable references a primitive that was deleted or not yet created. Create the missing primitives, then re-run alias creation for the affected semantic variables.
|
||||
|
||||
### Verify Style Counts
|
||||
|
||||
```javascript
|
||||
const [textStyles, effectStyles] = await Promise.all([
|
||||
figma.getLocalTextStylesAsync(),
|
||||
figma.getLocalEffectStylesAsync()
|
||||
]);
|
||||
|
||||
return {
|
||||
textStyles: textStyles.map(s => ({ name: s.name, fontSize: s.fontSize, fontFamily: s.fontName.family })),
|
||||
effectStyles: effectStyles.map(s => ({ name: s.name, effectCount: s.effects.length })),
|
||||
counts: { text: textStyles.length, effect: effectStyles.length }
|
||||
};
|
||||
```
|
||||
|
||||
### Phase 1 Exit Criteria Checklist
|
||||
|
||||
Before proceeding to Phase 2, verify all of the following:
|
||||
|
||||
- Every planned collection exists with the correct number of modes
|
||||
- Primitive variables: `scopes = []`, code syntax set
|
||||
- Semantic variables: targeted scopes set, code syntax set, aliases pointing to primitives (not raw values)
|
||||
- All broken alias count = 0
|
||||
- All planned text styles exist with correct font family/size/weight
|
||||
- All planned effect styles exist with correct shadow values
|
||||
- No variable has `ALL_SCOPES` unless explicitly approved by the user
|
||||
+110
@@ -0,0 +1,110 @@
|
||||
/**
|
||||
* bindVariablesToComponent
|
||||
*
|
||||
* Binds design token variables to the visual properties of a component node.
|
||||
* Supports fills, strokes, all padding directions, item spacing, and corner radius.
|
||||
* Only binds properties for which a variable ID is provided in `bindings`.
|
||||
*
|
||||
* This function should be called on each variant individually within a component
|
||||
* set, OR on the component set itself for properties shared by all variants.
|
||||
*
|
||||
* @param {ComponentNode | FrameNode | RectangleNode} component
|
||||
* The Figma node to mutate. Usually a ComponentNode or one of its children.
|
||||
* @param {{
|
||||
* fills?: string,
|
||||
* strokes?: string,
|
||||
* paddingTop?: string,
|
||||
* paddingBottom?: string,
|
||||
* paddingLeft?: string,
|
||||
* paddingRight?: string,
|
||||
* itemSpacing?: string,
|
||||
* cornerRadius?: string
|
||||
* }} bindings
|
||||
* Each key is a visual property name; each value is a Figma Variable ID
|
||||
* (e.g. "VariableID:123:456"). Omit a key to skip binding that property.
|
||||
* @returns {Promise<{ mutatedNodeIds: string[] }>}
|
||||
* List of node IDs that were mutated (for audit/validation purposes).
|
||||
*/
|
||||
async function bindVariablesToComponent(component, bindings) {
|
||||
const mutatedNodeIds = []
|
||||
|
||||
if (!component) {
|
||||
return { mutatedNodeIds }
|
||||
}
|
||||
|
||||
// --- Fills ---
|
||||
if (bindings.fills) {
|
||||
const fillVar = await figma.variables.getVariableByIdAsync(bindings.fills)
|
||||
if (fillVar) {
|
||||
const existingFills = component.fills
|
||||
if (Array.isArray(existingFills) && existingFills.length > 0) {
|
||||
// Bind the color of the first fill to the variable
|
||||
const boundFill = figma.variables.setBoundVariableForPaint(
|
||||
existingFills[0],
|
||||
'color',
|
||||
fillVar,
|
||||
)
|
||||
component.fills = [boundFill, ...existingFills.slice(1)]
|
||||
} else {
|
||||
// No existing fill — create a solid fill bound to the variable
|
||||
const boundFill = figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 0.5, g: 0.5, b: 0.5 } },
|
||||
'color',
|
||||
fillVar,
|
||||
)
|
||||
component.fills = [boundFill]
|
||||
}
|
||||
mutatedNodeIds.push(component.id)
|
||||
}
|
||||
}
|
||||
|
||||
// --- Strokes ---
|
||||
if (bindings.strokes) {
|
||||
const strokeVar = await figma.variables.getVariableByIdAsync(bindings.strokes)
|
||||
if (strokeVar) {
|
||||
const existingStrokes = component.strokes
|
||||
if (Array.isArray(existingStrokes) && existingStrokes.length > 0) {
|
||||
const boundStroke = figma.variables.setBoundVariableForPaint(
|
||||
existingStrokes[0],
|
||||
'color',
|
||||
strokeVar,
|
||||
)
|
||||
component.strokes = [boundStroke, ...existingStrokes.slice(1)]
|
||||
} else {
|
||||
const boundStroke = figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 0.5, g: 0.5, b: 0.5 } },
|
||||
'color',
|
||||
strokeVar,
|
||||
)
|
||||
component.strokes = [boundStroke]
|
||||
}
|
||||
if (!mutatedNodeIds.includes(component.id)) {
|
||||
mutatedNodeIds.push(component.id)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// --- Spacing properties (FLOAT variables bound via setBoundVariable) ---
|
||||
const floatBindings = [
|
||||
['paddingTop', 'paddingTop'],
|
||||
['paddingBottom', 'paddingBottom'],
|
||||
['paddingLeft', 'paddingLeft'],
|
||||
['paddingRight', 'paddingRight'],
|
||||
['itemSpacing', 'itemSpacing'],
|
||||
['cornerRadius', 'cornerRadius'],
|
||||
]
|
||||
|
||||
for (const [bindingKey, figmaProp] of floatBindings) {
|
||||
if (bindings[bindingKey]) {
|
||||
const variable = await figma.variables.getVariableByIdAsync(bindings[bindingKey])
|
||||
if (variable) {
|
||||
component.setBoundVariable(figmaProp, variable)
|
||||
if (!mutatedNodeIds.includes(component.id)) {
|
||||
mutatedNodeIds.push(component.id)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return { mutatedNodeIds }
|
||||
}
|
||||
@@ -0,0 +1,127 @@
|
||||
/**
|
||||
* cleanupOrphans
|
||||
*
|
||||
* Finds and removes all Figma nodes (pages, frames, components, variables,
|
||||
* and variable collections) that were tagged with the given `dsb_run_id`
|
||||
* by a previous build run. This is safe cleanup: it uses plugin data tags,
|
||||
* never name-prefix matching, so it cannot accidentally delete user-owned nodes.
|
||||
*
|
||||
* Use this when a build run fails mid-way and you need to reset to a clean
|
||||
* slate before retrying. The function traverses the entire document looking
|
||||
* for `dsb_run_id` plugin data matching `runId`.
|
||||
*
|
||||
* Variables and variable collections are handled separately (they are not
|
||||
* scene nodes and cannot be discovered via node traversal).
|
||||
*
|
||||
* @param {string} runId - The dsb_run_id value to match (e.g. "ds-build-2024-001").
|
||||
* @returns {Promise<{
|
||||
* removedCount: number,
|
||||
* removedIds: string[]
|
||||
* }>}
|
||||
*/
|
||||
async function cleanupOrphans(runId) {
|
||||
if (!runId) {
|
||||
throw new Error('cleanupOrphans: runId is required.')
|
||||
}
|
||||
|
||||
const removedIds = []
|
||||
const originalPage = figma.currentPage
|
||||
|
||||
// --- Remove tagged scene nodes (pages, frames, components, etc.) ---
|
||||
// Collect pages to remove (can't remove during iteration)
|
||||
const pagesToRemove = []
|
||||
|
||||
for (const page of figma.root.children) {
|
||||
if (page.getPluginData('dsb_run_id') === runId) {
|
||||
pagesToRemove.push(page)
|
||||
continue
|
||||
}
|
||||
|
||||
// Traverse all nodes on this page
|
||||
await figma.setCurrentPageAsync(page)
|
||||
|
||||
const nodesToRemove = []
|
||||
page.findAll((node) => {
|
||||
if (node.getPluginData('dsb_run_id') === runId) {
|
||||
nodesToRemove.push(node)
|
||||
return false // Don't descend — removing the parent removes its children
|
||||
}
|
||||
return true
|
||||
})
|
||||
|
||||
// Remove deepest nodes first (children before parents) to avoid
|
||||
// "parent no longer exists" errors
|
||||
const sorted = nodesToRemove.sort((a, b) => {
|
||||
// Sort by depth descending: deeper nodes first
|
||||
return getDepth(b) - getDepth(a)
|
||||
})
|
||||
|
||||
for (const node of sorted) {
|
||||
if (node && node.parent) {
|
||||
removedIds.push(node.id)
|
||||
node.remove()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Remove tagged pages last
|
||||
for (const page of pagesToRemove) {
|
||||
// Cannot remove the last page in the document
|
||||
if (figma.root.children.length <= 1) {
|
||||
break
|
||||
}
|
||||
removedIds.push(page.id)
|
||||
page.remove()
|
||||
}
|
||||
|
||||
// --- Remove tagged variables ---
|
||||
const allVariables = await figma.variables.getLocalVariablesAsync()
|
||||
for (const variable of allVariables) {
|
||||
if (variable.getPluginData('dsb_run_id') === runId) {
|
||||
removedIds.push(variable.id)
|
||||
variable.remove()
|
||||
}
|
||||
}
|
||||
|
||||
// --- Remove tagged variable collections ---
|
||||
// Must be done after variables are removed
|
||||
const allCollections = await figma.variables.getLocalVariableCollectionsAsync()
|
||||
for (const collection of allCollections) {
|
||||
if (collection.getPluginData('dsb_run_id') === runId) {
|
||||
removedIds.push(collection.id)
|
||||
collection.remove()
|
||||
}
|
||||
}
|
||||
|
||||
// Restore original page (if it still exists)
|
||||
try {
|
||||
await figma.setCurrentPageAsync(originalPage)
|
||||
} catch (_) {
|
||||
// Original page was removed — switch to first available page
|
||||
if (figma.root.children.length > 0) {
|
||||
await figma.setCurrentPageAsync(figma.root.children[0])
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
removedCount: removedIds.length,
|
||||
removedIds,
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the depth of a node in the document tree.
|
||||
* Root children (pages) have depth 1; their children have depth 2; etc.
|
||||
*
|
||||
* @param {BaseNode} node
|
||||
* @returns {number}
|
||||
*/
|
||||
function getDepth(node) {
|
||||
let depth = 0
|
||||
let current = node
|
||||
while (current.parent) {
|
||||
depth++
|
||||
current = current.parent
|
||||
}
|
||||
return depth
|
||||
}
|
||||
+148
@@ -0,0 +1,148 @@
|
||||
/**
|
||||
* createComponentWithVariants
|
||||
*
|
||||
* Creates a component set by generating all combinations of `variantAxes`,
|
||||
* building one Figma component per combination, then calling
|
||||
* `figma.combineAsVariants` to produce the component set. After combining,
|
||||
* the variants are repositioned into a grid so they don't all stack at (0, 0).
|
||||
*
|
||||
* @param {{
|
||||
* name: string,
|
||||
* variantAxes: Record<string, string[]>,
|
||||
* baseProps: {
|
||||
* width: number,
|
||||
* height: number,
|
||||
* fills?: Paint[],
|
||||
* padding?: {top?: number, bottom?: number, left?: number, right?: number},
|
||||
* radius?: number,
|
||||
* layoutMode?: 'HORIZONTAL' | 'VERTICAL' | 'NONE',
|
||||
* itemSpacing?: number
|
||||
* },
|
||||
* page: PageNode
|
||||
* }} config
|
||||
* - `name`: Component set name (e.g. "Button").
|
||||
* - `variantAxes`: Each key is a variant property name; each value is an array of
|
||||
* allowed values. All combinations are generated (Cartesian product).
|
||||
* Example: { Size: ['Small', 'Medium', 'Large'], Style: ['Primary', 'Ghost'] }
|
||||
* produces 6 variants.
|
||||
* - `baseProps`: Visual properties applied to every variant.
|
||||
* - `page`: The PageNode to create components on (must be set as current page by caller).
|
||||
* @param {string} [runId] - Optional dsb_run_id to tag every node.
|
||||
* @returns {Promise<{
|
||||
* componentSet: ComponentSetNode,
|
||||
* variants: ComponentNode[]
|
||||
* }>}
|
||||
*/
|
||||
async function createComponentWithVariants(config, runId) {
|
||||
const { name, variantAxes, baseProps, page } = config
|
||||
|
||||
// Ensure we are on the correct page
|
||||
await figma.setCurrentPageAsync(page)
|
||||
|
||||
// Compute Cartesian product of variant axes
|
||||
const axisNames = Object.keys(variantAxes)
|
||||
const axisValues = axisNames.map((k) => variantAxes[k])
|
||||
const combinations = cartesianProduct(axisValues)
|
||||
|
||||
// Build one component per combination
|
||||
const components = []
|
||||
for (const combo of combinations) {
|
||||
const comp = figma.createComponent()
|
||||
|
||||
// Name: "Property=Value, Property=Value, ..."
|
||||
comp.name = axisNames.map((ax, i) => `${ax}=${combo[i]}`).join(', ')
|
||||
|
||||
// Base geometry
|
||||
comp.resize(baseProps.width, baseProps.height)
|
||||
|
||||
// Fills
|
||||
if (baseProps.fills !== undefined) {
|
||||
comp.fills = baseProps.fills
|
||||
} else {
|
||||
comp.fills = [{ type: 'SOLID', color: { r: 0.9, g: 0.9, b: 0.9 } }]
|
||||
}
|
||||
|
||||
// Corner radius
|
||||
if (baseProps.radius !== undefined) {
|
||||
comp.cornerRadius = baseProps.radius
|
||||
}
|
||||
|
||||
// Auto-layout
|
||||
if (baseProps.layoutMode && baseProps.layoutMode !== 'NONE') {
|
||||
comp.layoutMode = baseProps.layoutMode
|
||||
comp.primaryAxisAlignItems = 'CENTER'
|
||||
comp.counterAxisAlignItems = 'CENTER'
|
||||
if (baseProps.itemSpacing !== undefined) {
|
||||
comp.itemSpacing = baseProps.itemSpacing
|
||||
}
|
||||
}
|
||||
|
||||
// Padding
|
||||
if (baseProps.padding) {
|
||||
comp.paddingTop = baseProps.padding.top ?? 0
|
||||
comp.paddingBottom = baseProps.padding.bottom ?? 0
|
||||
comp.paddingLeft = baseProps.padding.left ?? 0
|
||||
comp.paddingRight = baseProps.padding.right ?? 0
|
||||
}
|
||||
|
||||
// Plugin data
|
||||
const variantKey = axisNames.map((ax, i) => `${ax}:${combo[i]}`).join('|')
|
||||
comp.setPluginData('dsb_key', `component/${name}/${variantKey}`)
|
||||
if (runId) {
|
||||
comp.setPluginData('dsb_run_id', runId)
|
||||
}
|
||||
|
||||
page.appendChild(comp)
|
||||
components.push(comp)
|
||||
}
|
||||
|
||||
// Combine into a component set
|
||||
const componentSet = figma.combineAsVariants(components, page)
|
||||
componentSet.name = name
|
||||
componentSet.setPluginData('dsb_key', `componentSet/${name}`)
|
||||
if (runId) {
|
||||
componentSet.setPluginData('dsb_run_id', runId)
|
||||
}
|
||||
|
||||
// Grid layout — variants stack at (0, 0) after combineAsVariants; reposition them.
|
||||
const GRID_GAP = 16
|
||||
const cols = Math.max(1, axisValues[axisValues.length - 1]?.length ?? 1)
|
||||
const variantWidth = baseProps.width
|
||||
const variantHeight = baseProps.height
|
||||
|
||||
componentSet.children.forEach((variant, idx) => {
|
||||
const col = idx % cols
|
||||
const row = Math.floor(idx / cols)
|
||||
variant.x = col * (variantWidth + GRID_GAP)
|
||||
variant.y = row * (variantHeight + GRID_GAP)
|
||||
})
|
||||
|
||||
// Resize component set to wrap its children with padding
|
||||
const totalCols = Math.min(cols, combinations.length)
|
||||
const totalRows = Math.ceil(combinations.length / cols)
|
||||
const PADDING = 40
|
||||
componentSet.resize(
|
||||
totalCols * variantWidth + (totalCols - 1) * GRID_GAP + PADDING * 2,
|
||||
totalRows * variantHeight + (totalRows - 1) * GRID_GAP + PADDING * 2,
|
||||
)
|
||||
|
||||
// Position component set at a safe canvas location
|
||||
componentSet.x = 480
|
||||
componentSet.y = 80
|
||||
|
||||
return { componentSet, variants: componentSet.children }
|
||||
}
|
||||
|
||||
/**
|
||||
* Computes the Cartesian product of multiple arrays.
|
||||
* cartesianProduct([[A, B], [1, 2]]) → [[A,1], [A,2], [B,1], [B,2]]
|
||||
*
|
||||
* @param {Array<string[]>} arrays
|
||||
* @returns {string[][]}
|
||||
*/
|
||||
function cartesianProduct(arrays) {
|
||||
return arrays.reduce(
|
||||
(acc, curr) => acc.flatMap((combo) => curr.map((val) => [...combo, val])),
|
||||
[[]],
|
||||
)
|
||||
}
|
||||
+139
@@ -0,0 +1,139 @@
|
||||
/**
|
||||
* createDocumentationPage
|
||||
*
|
||||
* Creates a new Figma page with a standardized documentation layout: a page
|
||||
* title, optional description, and an ordered list of sections each built by
|
||||
* a caller-supplied `contentFn`. The content function receives the section
|
||||
* frame and may append any nodes to it.
|
||||
*
|
||||
* This function is used for standalone documentation pages (e.g. a Foundations
|
||||
* page, a Getting Started page, or a component page with documentation).
|
||||
* It does not handle component sets — those live on separate pages created by
|
||||
* createComponentWithVariants.
|
||||
*
|
||||
* @param {string} pageName - The Figma page name (e.g. "Foundations", "Getting Started").
|
||||
* @param {{
|
||||
* title: string,
|
||||
* description?: string,
|
||||
* sections: Array<{
|
||||
* name: string,
|
||||
* contentFn: (sectionFrame: FrameNode) => Promise<void>
|
||||
* }>
|
||||
* }} config
|
||||
* - `title`: Large heading displayed at the top of the page.
|
||||
* - `description`: Optional subtitle displayed below the heading.
|
||||
* - `sections`: Ordered list of sections. Each section gets its own frame
|
||||
* with a heading and is passed to `contentFn` for population.
|
||||
* @param {string} [runId] - Optional dsb_run_id to tag every created node.
|
||||
* @returns {Promise<{
|
||||
* page: PageNode,
|
||||
* titleNode: TextNode,
|
||||
* frameIds: string[]
|
||||
* }>}
|
||||
* `frameIds` is an ordered list of IDs for the root frame and each section frame.
|
||||
*/
|
||||
async function createDocumentationPage(pageName, config, runId) {
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Bold' })
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' })
|
||||
await figma.loadFontAsync({ family: 'Inter', style: 'Medium' })
|
||||
|
||||
// Create and activate the page
|
||||
const page = figma.createPage()
|
||||
page.name = pageName
|
||||
await figma.setCurrentPageAsync(page)
|
||||
|
||||
if (runId) {
|
||||
page.setPluginData('dsb_run_id', runId)
|
||||
page.setPluginData('dsb_key', `page/${pageName}`)
|
||||
}
|
||||
|
||||
const frameIds = []
|
||||
|
||||
// Root scroll container — 1440px wide, auto-height
|
||||
const root = figma.createFrame()
|
||||
root.name = pageName
|
||||
root.layoutMode = 'VERTICAL'
|
||||
root.primaryAxisAlignItems = 'MIN'
|
||||
root.counterAxisAlignItems = 'MIN'
|
||||
root.itemSpacing = 80
|
||||
root.paddingTop = 80
|
||||
root.paddingBottom = 120
|
||||
root.paddingLeft = 80
|
||||
root.paddingRight = 80
|
||||
root.layoutSizingHorizontal = 'FIXED'
|
||||
root.layoutSizingVertical = 'HUG'
|
||||
root.resize(1440, 1)
|
||||
root.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }]
|
||||
root.x = 0
|
||||
root.y = 0
|
||||
page.appendChild(root)
|
||||
|
||||
if (runId) {
|
||||
root.setPluginData('dsb_run_id', runId)
|
||||
root.setPluginData('dsb_key', `frame/root/${pageName}`)
|
||||
}
|
||||
|
||||
frameIds.push(root.id)
|
||||
|
||||
// Page header: title + optional description
|
||||
const header = figma.createFrame()
|
||||
header.name = 'Header'
|
||||
header.layoutMode = 'VERTICAL'
|
||||
header.itemSpacing = 12
|
||||
header.layoutSizingHorizontal = 'FILL'
|
||||
header.layoutSizingVertical = 'HUG'
|
||||
header.fills = []
|
||||
root.appendChild(header)
|
||||
|
||||
const titleNode = figma.createText()
|
||||
titleNode.fontName = { family: 'Inter', style: 'Bold' }
|
||||
titleNode.characters = config.title
|
||||
titleNode.fontSize = 40
|
||||
titleNode.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }]
|
||||
titleNode.layoutSizingHorizontal = 'FILL'
|
||||
header.appendChild(titleNode)
|
||||
|
||||
if (config.description) {
|
||||
const descNode = figma.createText()
|
||||
descNode.fontName = { family: 'Inter', style: 'Regular' }
|
||||
descNode.characters = config.description
|
||||
descNode.fontSize = 16
|
||||
descNode.lineHeight = { value: 24, unit: 'PIXELS' }
|
||||
descNode.fills = [{ type: 'SOLID', color: { r: 0.4, g: 0.4, b: 0.4 } }]
|
||||
descNode.layoutSizingHorizontal = 'FILL'
|
||||
header.appendChild(descNode)
|
||||
}
|
||||
|
||||
// Sections
|
||||
for (const section of config.sections) {
|
||||
const sectionFrame = figma.createFrame()
|
||||
sectionFrame.name = `Section/${section.name}`
|
||||
sectionFrame.layoutMode = 'VERTICAL'
|
||||
sectionFrame.itemSpacing = 20
|
||||
sectionFrame.layoutSizingHorizontal = 'FILL'
|
||||
sectionFrame.layoutSizingVertical = 'HUG'
|
||||
sectionFrame.fills = []
|
||||
root.appendChild(sectionFrame)
|
||||
|
||||
if (runId) {
|
||||
sectionFrame.setPluginData('dsb_run_id', runId)
|
||||
sectionFrame.setPluginData('dsb_key', `frame/section/${pageName}/${section.name}`)
|
||||
}
|
||||
|
||||
// Section heading
|
||||
const sectionHeading = figma.createText()
|
||||
sectionHeading.fontName = { family: 'Inter', style: 'Bold' }
|
||||
sectionHeading.characters = section.name
|
||||
sectionHeading.fontSize = 24
|
||||
sectionHeading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }]
|
||||
sectionHeading.layoutSizingHorizontal = 'FILL'
|
||||
sectionFrame.appendChild(sectionHeading)
|
||||
|
||||
// Invoke the caller's content function to populate the section
|
||||
await section.contentFn(sectionFrame)
|
||||
|
||||
frameIds.push(sectionFrame.id)
|
||||
}
|
||||
|
||||
return { page, titleNode, frameIds }
|
||||
}
|
||||
+108
@@ -0,0 +1,108 @@
|
||||
/**
|
||||
* createSemanticTokens
|
||||
*
|
||||
* Creates a batch of Figma variables in the given collection, one per entry in
|
||||
* `tokenMap`. Supports raw values, variable alias references, code syntax, and
|
||||
* scopes. Returns a map of token name → Variable for use in subsequent steps.
|
||||
*
|
||||
* @param {VariableCollection} collection - The target variable collection.
|
||||
* @param {Record<string, string>} modeIds - Map of {modeName: modeId} from createVariableCollection.
|
||||
* @param {Array<{
|
||||
* name: string,
|
||||
* type: 'COLOR' | 'FLOAT' | 'STRING' | 'BOOLEAN',
|
||||
* values: Record<string, string | number | boolean | {type: 'VARIABLE_ALIAS', id: string}>,
|
||||
* scopes?: VariableScope[],
|
||||
* codeSyntax?: {WEB?: string, ANDROID?: string, iOS?: string}
|
||||
* }>} tokenMap - Ordered list of token definitions.
|
||||
* - `name`: Variable name using slash hierarchy (e.g. "color/bg/primary").
|
||||
* - `type`: Figma variable type.
|
||||
* - `values`: Map of {modeName: value}. Values can be raw (hex string for COLOR,
|
||||
* number for FLOAT) or alias objects {type: 'VARIABLE_ALIAS', id: variableId}.
|
||||
* For COLOR, raw values are accepted as hex strings ("#rrggbb" or "#rrggbbaa")
|
||||
* and converted to {r, g, b, a} automatically.
|
||||
* - `scopes`: Array of VariableScope strings. Omit to use [] (hidden/primitive).
|
||||
* - `codeSyntax`: Platform code syntax strings. Omit to skip.
|
||||
* @param {string} [runId] - Optional dsb_run_id to tag every variable.
|
||||
* @returns {Promise<{variables: Record<string, Variable>}>}
|
||||
* `variables` maps each token name to its created Variable object.
|
||||
*/
|
||||
async function createSemanticTokens(collection, modeIds, tokenMap, runId) {
|
||||
const variables = {}
|
||||
|
||||
for (const token of tokenMap) {
|
||||
// Create the variable
|
||||
const variable = figma.variables.createVariable(token.name, collection, token.type)
|
||||
|
||||
// Tag for cleanup
|
||||
variable.setPluginData('dsb_key', `variable/${token.name}`)
|
||||
if (runId) {
|
||||
variable.setPluginData('dsb_run_id', runId)
|
||||
}
|
||||
|
||||
// Set values for each mode
|
||||
for (const [modeName, rawValue] of Object.entries(token.values)) {
|
||||
const modeId = modeIds[modeName]
|
||||
if (!modeId) {
|
||||
throw new Error(
|
||||
`createSemanticTokens: mode "${modeName}" not found in modeIds for token "${token.name}". ` +
|
||||
`Available modes: ${Object.keys(modeIds).join(', ')}`,
|
||||
)
|
||||
}
|
||||
|
||||
let value = rawValue
|
||||
|
||||
// Convert hex strings to Figma RGBA for COLOR type
|
||||
if (token.type === 'COLOR' && typeof rawValue === 'string' && rawValue.startsWith('#')) {
|
||||
value = hexToFigmaColor(rawValue)
|
||||
}
|
||||
|
||||
variable.setValueForMode(modeId, value)
|
||||
}
|
||||
|
||||
// Set scopes (default: empty array = hidden from property pickers / primitives)
|
||||
variable.scopes = token.scopes || []
|
||||
|
||||
// Set code syntax per platform
|
||||
if (token.codeSyntax) {
|
||||
if (token.codeSyntax.WEB) {
|
||||
variable.setVariableCodeSyntax('WEB', token.codeSyntax.WEB)
|
||||
}
|
||||
if (token.codeSyntax.ANDROID) {
|
||||
variable.setVariableCodeSyntax('ANDROID', token.codeSyntax.ANDROID)
|
||||
}
|
||||
if (token.codeSyntax.iOS) {
|
||||
variable.setVariableCodeSyntax('iOS', token.codeSyntax.iOS)
|
||||
}
|
||||
}
|
||||
|
||||
variables[token.name] = variable
|
||||
}
|
||||
|
||||
return { variables }
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts a hex color string to a Figma RGBA object.
|
||||
* Supports "#rgb", "#rrggbb", and "#rrggbbaa".
|
||||
*
|
||||
* @param {string} hex
|
||||
* @returns {{ r: number, g: number, b: number, a: number }}
|
||||
*/
|
||||
function hexToFigmaColor(hex) {
|
||||
let h = hex.replace('#', '')
|
||||
|
||||
// Expand shorthand #rgb → #rrggbb
|
||||
if (h.length === 3) {
|
||||
h = h
|
||||
.split('')
|
||||
.map((c) => c + c)
|
||||
.join('')
|
||||
}
|
||||
|
||||
const r = parseInt(h.substring(0, 2), 16) / 255
|
||||
const g = parseInt(h.substring(2, 4), 16) / 255
|
||||
const b = parseInt(h.substring(4, 6), 16) / 255
|
||||
const a = h.length === 8 ? parseInt(h.substring(6, 8), 16) / 255 : 1
|
||||
|
||||
return { r, g, b, a }
|
||||
}
|
||||
+49
@@ -0,0 +1,49 @@
|
||||
/**
|
||||
* createVariableCollection
|
||||
*
|
||||
* Creates a new Figma variable collection with the specified name and modes.
|
||||
* If `modeNames` has more than one entry, the first mode is renamed from
|
||||
* Figma's default "Mode 1" to the first name, and additional modes are added.
|
||||
*
|
||||
* Every created collection is tagged with `dsb_key` plugin data so it can be
|
||||
* found and cleaned up idempotently by `cleanupOrphans`.
|
||||
*
|
||||
* @param {string} name - The display name of the collection (e.g. "Color", "Spacing").
|
||||
* @param {string[]} modeNames - Ordered list of mode names (e.g. ["Light", "Dark"] or ["Value"]).
|
||||
* @param {string} [runId] - Optional dsb_run_id to tag for cleanup.
|
||||
* @returns {Promise<{
|
||||
* collection: VariableCollection,
|
||||
* modeIds: Record<string, string>
|
||||
* }>}
|
||||
* `modeIds` maps each mode name to its modeId string.
|
||||
*/
|
||||
async function createVariableCollection(name, modeNames, runId) {
|
||||
if (!modeNames || modeNames.length === 0) {
|
||||
throw new Error('createVariableCollection: modeNames must have at least one entry.')
|
||||
}
|
||||
|
||||
// Create the collection — Figma always creates it with one mode named "Mode 1".
|
||||
const collection = figma.variables.createVariableCollection(name)
|
||||
|
||||
// Tag for idempotent cleanup
|
||||
collection.setPluginData('dsb_key', `collection/${name}`)
|
||||
if (runId) {
|
||||
collection.setPluginData('dsb_run_id', runId)
|
||||
}
|
||||
|
||||
// modeIds accumulator
|
||||
const modeIds = {}
|
||||
|
||||
// Rename the default first mode
|
||||
const defaultMode = collection.modes[0]
|
||||
collection.renameMode(defaultMode.modeId, modeNames[0])
|
||||
modeIds[modeNames[0]] = defaultMode.modeId
|
||||
|
||||
// Add additional modes
|
||||
for (let i = 1; i < modeNames.length; i++) {
|
||||
const newModeId = collection.addMode(modeNames[i])
|
||||
modeIds[modeNames[i]] = newModeId
|
||||
}
|
||||
|
||||
return { collection, modeIds }
|
||||
}
|
||||
+121
@@ -0,0 +1,121 @@
|
||||
/**
|
||||
* inspectFileStructure
|
||||
*
|
||||
* Reads the current Figma file and returns a structural inventory:
|
||||
* all pages (with child counts), all local variable collections (with mode
|
||||
* names and variable counts), all component sets, all local text styles,
|
||||
* and all local effect styles.
|
||||
*
|
||||
* This is a read-only discovery function — it never creates or mutates nodes.
|
||||
* Run it at the start of Phase 0 to understand what already exists before
|
||||
* planning any creation work.
|
||||
*
|
||||
* @returns {Promise<{
|
||||
* pages: Array<{id: string, name: string, childCount: number}>,
|
||||
* variableCollections: Array<{
|
||||
* id: string,
|
||||
* name: string,
|
||||
* modes: Array<{modeId: string, name: string}>,
|
||||
* variableCount: number,
|
||||
* variableNames: string[]
|
||||
* }>,
|
||||
* componentSets: Array<{id: string, name: string, variantCount: number, pageId: string, pageName: string}>,
|
||||
* textStyles: Array<{id: string, name: string, fontFamily: string, fontStyle: string, fontSize: number}>,
|
||||
* effectStyles: Array<{id: string, name: string, effectCount: number}>
|
||||
* }>}
|
||||
*/
|
||||
async function inspectFileStructure() {
|
||||
const result = {
|
||||
pages: [],
|
||||
variableCollections: [],
|
||||
componentSets: [],
|
||||
textStyles: [],
|
||||
effectStyles: [],
|
||||
}
|
||||
|
||||
// --- Pages ---
|
||||
for (const page of figma.root.children) {
|
||||
result.pages.push({
|
||||
id: page.id,
|
||||
name: page.name,
|
||||
childCount: page.children.length,
|
||||
})
|
||||
}
|
||||
|
||||
// --- Variable collections ---
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync()
|
||||
for (const coll of collections) {
|
||||
const variables = await Promise.all(
|
||||
coll.variableIds.map((id) => figma.variables.getVariableByIdAsync(id)),
|
||||
)
|
||||
const variableNames = variables.filter(Boolean).map((v) => v.name)
|
||||
|
||||
result.variableCollections.push({
|
||||
id: coll.id,
|
||||
name: coll.name,
|
||||
modes: coll.modes.map((m) => ({ modeId: m.modeId, name: m.name })),
|
||||
variableCount: coll.variableIds.length,
|
||||
variableNames,
|
||||
})
|
||||
}
|
||||
|
||||
// --- Component sets (and standalone components) ---
|
||||
// We need to load all pages to inspect components across the whole file.
|
||||
const originalPage = figma.currentPage
|
||||
|
||||
for (const page of figma.root.children) {
|
||||
await figma.setCurrentPageAsync(page)
|
||||
|
||||
const componentSetsOnPage = page.findAllWithCriteria({ types: ['COMPONENT_SET'] })
|
||||
for (const cs of componentSetsOnPage) {
|
||||
result.componentSets.push({
|
||||
id: cs.id,
|
||||
name: cs.name,
|
||||
variantCount: cs.children.length,
|
||||
pageId: page.id,
|
||||
pageName: page.name,
|
||||
})
|
||||
}
|
||||
|
||||
// Also capture standalone components (not inside a component set)
|
||||
const standaloneComponents = page
|
||||
.findAllWithCriteria({ types: ['COMPONENT'] })
|
||||
.filter((c) => c.parent && c.parent.type !== 'COMPONENT_SET')
|
||||
for (const comp of standaloneComponents) {
|
||||
result.componentSets.push({
|
||||
id: comp.id,
|
||||
name: comp.name,
|
||||
variantCount: 1,
|
||||
pageId: page.id,
|
||||
pageName: page.name,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// Restore original page
|
||||
await figma.setCurrentPageAsync(originalPage)
|
||||
|
||||
// --- Text styles ---
|
||||
const textStyles = figma.getLocalTextStyles()
|
||||
for (const ts of textStyles) {
|
||||
result.textStyles.push({
|
||||
id: ts.id,
|
||||
name: ts.name,
|
||||
fontFamily: ts.fontName.family,
|
||||
fontStyle: ts.fontName.style,
|
||||
fontSize: ts.fontSize,
|
||||
})
|
||||
}
|
||||
|
||||
// --- Effect styles ---
|
||||
const effectStyles = figma.getLocalEffectStyles()
|
||||
for (const es of effectStyles) {
|
||||
result.effectStyles.push({
|
||||
id: es.id,
|
||||
name: es.name,
|
||||
effectCount: es.effects.length,
|
||||
})
|
||||
}
|
||||
|
||||
return result
|
||||
}
|
||||
@@ -0,0 +1,92 @@
|
||||
/**
|
||||
* Scans the entire Figma file for nodes tagged with dsb_* pluginData
|
||||
* and returns a complete state map for session recovery.
|
||||
*
|
||||
* Use this at the start of every new session, after context truncation,
|
||||
* or when resuming an interrupted build.
|
||||
*
|
||||
* @param {string} runId - The run ID to filter by (optional — if omitted, returns ALL dsb-tagged nodes)
|
||||
* @returns {{ runId: string, taggedNodes: Object<string, {nodeId: string, type: string, name: string, phase: string}>, variableCollections: Array, variables: Array, styles: Array }}
|
||||
*/
|
||||
async function rehydrateState(runId) {
|
||||
const taggedNodes = {}
|
||||
const variableCollections = []
|
||||
const variables = []
|
||||
const styles = []
|
||||
|
||||
// Scan all pages for dsb-tagged scene nodes
|
||||
for (const page of figma.root.children) {
|
||||
await figma.setCurrentPageAsync(page)
|
||||
|
||||
// Check the page itself
|
||||
const pageRunId = page.getPluginData('dsb_run_id')
|
||||
const pageKey = page.getPluginData('dsb_key')
|
||||
if (pageKey && (!runId || pageRunId === runId)) {
|
||||
taggedNodes[pageKey] = {
|
||||
nodeId: page.id,
|
||||
type: page.type,
|
||||
name: page.name,
|
||||
phase: page.getPluginData('dsb_phase') || 'unknown',
|
||||
}
|
||||
}
|
||||
|
||||
// Scan all descendants
|
||||
page.findAll((node) => {
|
||||
const nodeRunId = node.getPluginData('dsb_run_id')
|
||||
const nodeKey = node.getPluginData('dsb_key')
|
||||
if (nodeKey && (!runId || nodeRunId === runId)) {
|
||||
taggedNodes[nodeKey] = {
|
||||
nodeId: node.id,
|
||||
type: node.type,
|
||||
name: node.name,
|
||||
phase: node.getPluginData('dsb_phase') || 'unknown',
|
||||
}
|
||||
}
|
||||
return false // don't collect, just scan
|
||||
})
|
||||
}
|
||||
|
||||
// Inventory variable collections (variables don't support pluginData — use name-based lookup)
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync()
|
||||
for (const coll of collections) {
|
||||
variableCollections.push({
|
||||
id: coll.id,
|
||||
name: coll.name,
|
||||
modes: coll.modes.map((m) => ({ modeId: m.modeId, name: m.name })),
|
||||
variableCount: coll.variableIds.length,
|
||||
})
|
||||
}
|
||||
|
||||
// Inventory variables (name + collection for idempotency key)
|
||||
const allVars = await figma.variables.getLocalVariablesAsync()
|
||||
for (const v of allVars) {
|
||||
variables.push({
|
||||
id: v.id,
|
||||
name: v.name,
|
||||
collectionId: v.variableCollectionId,
|
||||
resolvedType: v.resolvedType,
|
||||
})
|
||||
}
|
||||
|
||||
// Inventory styles
|
||||
for (const s of figma.getLocalTextStyles()) {
|
||||
styles.push({ id: s.id, name: s.name, type: 'TEXT' })
|
||||
}
|
||||
for (const s of figma.getLocalEffectStyles()) {
|
||||
styles.push({ id: s.id, name: s.name, type: 'EFFECT' })
|
||||
}
|
||||
for (const s of figma.getLocalPaintStyles()) {
|
||||
styles.push({ id: s.id, name: s.name, type: 'PAINT' })
|
||||
}
|
||||
|
||||
return {
|
||||
runId: runId || 'all',
|
||||
taggedNodes,
|
||||
taggedNodeCount: Object.keys(taggedNodes).length,
|
||||
variableCollections,
|
||||
variableCount: variables.length,
|
||||
variables,
|
||||
styleCount: styles.length,
|
||||
styles,
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,83 @@
|
||||
/**
|
||||
* validateCreation
|
||||
*
|
||||
* Verifies that a set of nodes exist and match expected structural properties.
|
||||
* Designed to run immediately after a creation script to catch partial failures
|
||||
* before proceeding to the next build phase.
|
||||
*
|
||||
* Each check specifies a node ID and any combination of expected properties.
|
||||
* A check passes when all specified expectations are met; it fails (with a
|
||||
* reason string) as soon as any expectation is violated.
|
||||
*
|
||||
* @param {Array<{
|
||||
* nodeId: string,
|
||||
* expectedChildCount?: number,
|
||||
* expectedName?: string,
|
||||
* expectedType?: NodeType
|
||||
* }>} checks
|
||||
* - `nodeId`: The Figma node ID to look up via figma.getNodeById.
|
||||
* - `expectedChildCount`: If set, the node must have exactly this many direct children.
|
||||
* Applies to any node with a `children` property (frames, component sets, etc.).
|
||||
* - `expectedName`: If set, the node's `.name` must exactly match this string.
|
||||
* - `expectedType`: If set, the node's `.type` must exactly match this string.
|
||||
* @returns {{
|
||||
* passed: string[],
|
||||
* failed: Array<{nodeId: string, reason: string}>
|
||||
* }}
|
||||
* `passed`: Array of nodeIds that passed all checks.
|
||||
* `failed`: Array of objects with the nodeId and a human-readable reason string.
|
||||
*/
|
||||
function validateCreation(checks) {
|
||||
const passed = []
|
||||
const failed = []
|
||||
|
||||
for (const check of checks) {
|
||||
const node = figma.getNodeById(check.nodeId)
|
||||
|
||||
// Node must exist
|
||||
if (!node) {
|
||||
failed.push({
|
||||
nodeId: check.nodeId,
|
||||
reason: `Node not found. It may not have been created, or was deleted.`,
|
||||
})
|
||||
continue
|
||||
}
|
||||
|
||||
const reasons = []
|
||||
|
||||
// Type check
|
||||
if (check.expectedType !== undefined && node.type !== check.expectedType) {
|
||||
reasons.push(`type is "${node.type}", expected "${check.expectedType}"`)
|
||||
}
|
||||
|
||||
// Name check
|
||||
if (check.expectedName !== undefined && node.name !== check.expectedName) {
|
||||
reasons.push(`name is "${node.name}", expected "${check.expectedName}"`)
|
||||
}
|
||||
|
||||
// Child count check
|
||||
if (check.expectedChildCount !== undefined) {
|
||||
if (!('children' in node)) {
|
||||
reasons.push(
|
||||
`node type "${node.type}" does not have children, but expectedChildCount=${check.expectedChildCount} was specified`,
|
||||
)
|
||||
} else {
|
||||
const actualCount = node.children.length
|
||||
if (actualCount !== check.expectedChildCount) {
|
||||
reasons.push(`has ${actualCount} children, expected ${check.expectedChildCount}`)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (reasons.length > 0) {
|
||||
failed.push({
|
||||
nodeId: check.nodeId,
|
||||
reason: reasons.join('; '),
|
||||
})
|
||||
} else {
|
||||
passed.push(check.nodeId)
|
||||
}
|
||||
}
|
||||
|
||||
return { passed, failed }
|
||||
}
|
||||
@@ -0,0 +1,259 @@
|
||||
---
|
||||
name: figma-implement-design
|
||||
description: Translates Figma designs into production-ready application code with 1:1 visual fidelity. Use when implementing UI code from Figma files, when user mentions "implement design", "generate code", "implement component", provides Figma URLs, or asks to build components matching Figma specs. For Figma canvas writes via `use_figma`, use `figma-use`.
|
||||
disable-model-invocation: false
|
||||
---
|
||||
|
||||
# Implement Design
|
||||
|
||||
## Overview
|
||||
|
||||
This skill provides a structured workflow for translating Figma designs into production-ready code with pixel-perfect accuracy. It ensures consistent integration with the Figma MCP server, proper use of design tokens, and 1:1 visual parity with designs.
|
||||
|
||||
## Skill Boundaries
|
||||
|
||||
- Use this skill when the deliverable is code in the user's repository.
|
||||
- If the user asks to create/edit/delete nodes inside Figma itself, switch to [figma-use](../figma-use/SKILL.md).
|
||||
- If the user asks to build or update a full-page screen in Figma from code or a description, switch to [figma-generate-design](../figma-generate-design/SKILL.md).
|
||||
- If the user asks only for Code Connect mappings, switch to [figma-code-connect-components](../figma-code-connect-components/SKILL.md).
|
||||
- If the user asks to author reusable agent rules (`CLAUDE.md`/`AGENTS.md`), switch to [figma-create-design-system-rules](../figma-create-design-system-rules/SKILL.md).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Figma MCP server must be connected and accessible
|
||||
- User must provide a Figma URL in the format: `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
|
||||
- `:fileKey` is the file key
|
||||
- `1-2` is the node ID (the specific component or frame to implement)
|
||||
- **OR** when using `figma-desktop` MCP: User can select a node directly in the Figma desktop app (no URL required)
|
||||
- Project should have an established design system or component library (preferred)
|
||||
|
||||
## Required Workflow
|
||||
|
||||
**Follow these steps in order. Do not skip steps.**
|
||||
|
||||
### Step 1: Get Node ID
|
||||
|
||||
#### Option A: Parse from Figma URL
|
||||
|
||||
When the user provides a Figma URL, extract the file key and node ID to pass as arguments to MCP tools.
|
||||
|
||||
**URL format:** `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
|
||||
|
||||
**Extract:**
|
||||
|
||||
- **File key:** `:fileKey` (the segment after `/design/`)
|
||||
- **Node ID:** `1-2` (the value of the `node-id` query parameter)
|
||||
|
||||
**Note:** When using the local desktop MCP (`figma-desktop`), `fileKey` is not passed as a parameter to tool calls. The server automatically uses the currently open file, so only `nodeId` is needed.
|
||||
|
||||
**Example:**
|
||||
|
||||
- URL: `https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15`
|
||||
- File key: `kL9xQn2VwM8pYrTb4ZcHjF`
|
||||
- Node ID: `42-15`
|
||||
|
||||
#### Option B: Use Current Selection from Figma Desktop App (figma-desktop MCP only)
|
||||
|
||||
When using the `figma-desktop` MCP and the user has NOT provided a URL, the tools automatically use the currently selected node from the open Figma file in the desktop app.
|
||||
|
||||
**Note:** Selection-based prompting only works with the `figma-desktop` MCP server. The remote server requires a link to a frame or layer to extract context. The user must have the Figma desktop app open with a node selected.
|
||||
|
||||
### Step 2: Fetch Design Context
|
||||
|
||||
Run `get_design_context` with the extracted file key and node ID.
|
||||
|
||||
```
|
||||
get_design_context(fileKey=":fileKey", nodeId="1-2")
|
||||
```
|
||||
|
||||
This provides the structured data including:
|
||||
|
||||
- Layout properties (Auto Layout, constraints, sizing)
|
||||
- Typography specifications
|
||||
- Color values and design tokens
|
||||
- Component structure and variants
|
||||
- Spacing and padding values
|
||||
|
||||
**If the response is too large or truncated:**
|
||||
|
||||
1. Run `get_metadata(fileKey=":fileKey", nodeId="1-2")` to get the high-level node map
|
||||
2. Identify the specific child nodes needed from the metadata
|
||||
3. Fetch individual child nodes with `get_design_context(fileKey=":fileKey", nodeId=":childNodeId")`
|
||||
|
||||
### Step 3: Capture Visual Reference
|
||||
|
||||
Run `get_screenshot` with the same file key and node ID for a visual reference.
|
||||
|
||||
```
|
||||
get_screenshot(fileKey=":fileKey", nodeId="1-2")
|
||||
```
|
||||
|
||||
This screenshot serves as the source of truth for visual validation. Keep it accessible throughout implementation.
|
||||
|
||||
### Step 4: Download Required Assets
|
||||
|
||||
Download any assets (images, icons, SVGs) returned by the Figma MCP server.
|
||||
|
||||
**IMPORTANT:** Follow these asset rules:
|
||||
|
||||
- If the Figma MCP server returns a `localhost` source for an image or SVG, use that source directly
|
||||
- DO NOT import or add new icon packages - all assets should come from the Figma payload
|
||||
- DO NOT use or create placeholders if a `localhost` source is provided
|
||||
- Assets are served through the Figma MCP server's built-in assets endpoint
|
||||
|
||||
### Step 5: Translate to Project Conventions
|
||||
|
||||
Translate the Figma output into this project's framework, styles, and conventions.
|
||||
|
||||
**Key principles:**
|
||||
|
||||
- Treat the Figma MCP output (typically React + Tailwind) as a representation of design and behavior, not as final code style
|
||||
- Replace Tailwind utility classes with the project's preferred utilities or design system tokens
|
||||
- Reuse existing components (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
|
||||
|
||||
### Step 6: Achieve 1:1 Visual Parity
|
||||
|
||||
Strive for pixel-perfect visual parity with the Figma design.
|
||||
|
||||
**Guidelines:**
|
||||
|
||||
- Prioritize Figma fidelity to match designs exactly
|
||||
- Avoid hardcoded values - use design tokens from Figma where available
|
||||
- When conflicts arise between design system tokens and Figma specs, prefer design system tokens but adjust spacing or sizes minimally to match visuals
|
||||
- Follow WCAG requirements for accessibility
|
||||
- Add component documentation as needed
|
||||
|
||||
### Step 7: Validate Against Figma
|
||||
|
||||
Before marking complete, validate the final UI against the Figma screenshot.
|
||||
|
||||
**Validation checklist:**
|
||||
|
||||
- [ ] Layout matches (spacing, alignment, sizing)
|
||||
- [ ] Typography matches (font, size, weight, line height)
|
||||
- [ ] Colors match exactly
|
||||
- [ ] Interactive states work as designed (hover, active, disabled)
|
||||
- [ ] Responsive behavior follows Figma constraints
|
||||
- [ ] Assets render correctly
|
||||
- [ ] Accessibility standards met
|
||||
|
||||
## Implementation Rules
|
||||
|
||||
### Component Organization
|
||||
|
||||
- Place UI components in the project's designated design system directory
|
||||
- Follow the project's component naming conventions
|
||||
- Avoid inline styles unless truly necessary for dynamic values
|
||||
|
||||
### Design System Integration
|
||||
|
||||
- ALWAYS use components from the project's design system when possible
|
||||
- Map Figma design tokens to project design tokens
|
||||
- When a matching component exists, extend it rather than creating a new one
|
||||
- Document any new components added to the design system
|
||||
|
||||
### Code Quality
|
||||
|
||||
- Avoid hardcoded values - extract to constants or design tokens
|
||||
- Keep components composable and reusable
|
||||
- Add TypeScript types for component props
|
||||
- Include JSDoc comments for exported components
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Implementing a Button Component
|
||||
|
||||
User says: "Implement this Figma button component: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15"
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Parse URL to extract fileKey=`kL9xQn2VwM8pYrTb4ZcHjF` and nodeId=`42-15`
|
||||
2. Run `get_design_context(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")`
|
||||
3. Run `get_screenshot(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")` for visual reference
|
||||
4. Download any button icons from the assets endpoint
|
||||
5. Check if project has existing button component
|
||||
6. If yes, extend it with new variant; if no, create new component using project conventions
|
||||
7. Map Figma colors to project design tokens (e.g., `primary-500`, `primary-hover`)
|
||||
8. Validate against screenshot for padding, border radius, typography
|
||||
|
||||
**Result:** Button component matching Figma design, integrated with project design system.
|
||||
|
||||
### Example 2: Building a Dashboard Layout
|
||||
|
||||
User says: "Build this dashboard: https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Dashboard?node-id=10-5"
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Parse URL to extract fileKey=`pR8mNv5KqXzGwY2JtCfL4D` and nodeId=`10-5`
|
||||
2. Run `get_metadata(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")` to understand the page structure
|
||||
3. Identify main sections from metadata (header, sidebar, content area, cards) and their child node IDs
|
||||
4. Run `get_design_context(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId=":childNodeId")` for each major section
|
||||
5. Run `get_screenshot(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")` for the full page
|
||||
6. Download all assets (logos, icons, charts)
|
||||
7. Build layout using project's layout primitives
|
||||
8. Implement each section using existing components where possible
|
||||
9. Validate responsive behavior against Figma constraints
|
||||
|
||||
**Result:** Complete dashboard matching Figma design with responsive layout.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Always Start with Context
|
||||
|
||||
Never implement based on assumptions. Always fetch `get_design_context` and `get_screenshot` first.
|
||||
|
||||
### Incremental Validation
|
||||
|
||||
Validate frequently during implementation, not just at the end. This catches issues early.
|
||||
|
||||
### Document Deviations
|
||||
|
||||
If you must deviate from the Figma design (e.g., for accessibility or technical constraints), document why in code comments.
|
||||
|
||||
### Reuse Over Recreation
|
||||
|
||||
Always check for existing components before creating new ones. Consistency across the codebase is more important than exact Figma replication.
|
||||
|
||||
### Design System First
|
||||
|
||||
When in doubt, prefer the project's design system patterns over literal Figma translation.
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Issue: Figma output is truncated
|
||||
|
||||
**Cause:** The design is too complex or has too many nested layers to return in a single response.
|
||||
**Solution:** Use `get_metadata` to get the node structure, then fetch specific nodes individually with `get_design_context`.
|
||||
|
||||
### Issue: Design doesn't match after implementation
|
||||
|
||||
**Cause:** Visual discrepancies between the implemented code and the original Figma design.
|
||||
**Solution:** Compare side-by-side with the screenshot from Step 3. Check spacing, colors, and typography values in the design context data.
|
||||
|
||||
### Issue: Assets not loading
|
||||
|
||||
**Cause:** The Figma MCP server's assets endpoint is not accessible or the URLs are being modified.
|
||||
**Solution:** Verify the Figma MCP server's assets endpoint is accessible. The server serves assets at `localhost` URLs. Use these directly without modification.
|
||||
|
||||
### Issue: Design token values differ from Figma
|
||||
|
||||
**Cause:** The project's design system tokens have different values than those specified in the Figma design.
|
||||
**Solution:** When project tokens differ from Figma values, prefer project tokens for consistency but adjust spacing/sizing to maintain visual fidelity.
|
||||
|
||||
## Understanding Design Implementation
|
||||
|
||||
The Figma implementation workflow establishes a reliable process for translating designs to code:
|
||||
|
||||
**For designers:** Confidence that implementations will match their designs with pixel-perfect accuracy.
|
||||
**For developers:** A structured approach that eliminates guesswork and reduces back-and-forth revisions.
|
||||
**For teams:** Consistent, high-quality implementations that maintain design system integrity.
|
||||
|
||||
By following this workflow, you ensure that every Figma design is implemented with the same level of care and attention to detail.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server/)
|
||||
- [Figma MCP Server Tools and Prompts](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/)
|
||||
- [Figma Variables and Design Tokens](https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma)
|
||||
@@ -0,0 +1,234 @@
|
||||
---
|
||||
name: figma-use
|
||||
description: "**MANDATORY prerequisite** — you MUST invoke this skill BEFORE every `use_figma` tool call. NEVER call `use_figma` directly without loading this skill first. Skipping it causes common, hard-to-debug failures. Trigger whenever the user wants to perform a write action or a unique read action that requires JavaScript execution in the Figma file context — e.g. create/edit/delete nodes, set up variables or tokens, build components and variants, modify auto-layout or fills, bind variables to properties, or inspect file structure programmatically."
|
||||
disable-model-invocation: false
|
||||
---
|
||||
|
||||
# use_figma — Figma Plugin API Skill
|
||||
|
||||
Use `use_figma` MCP to execute JavaScript in Figma files via the Plugin API. All detailed reference docs live in `references/`.
|
||||
|
||||
**Always pass `skillNames: "figma-use"` when calling `use_figma`.** This is a logging parameter used to track skill usage — it does not affect execution.
|
||||
|
||||
**If the task involves building or updating a full page, screen, or multi-section layout in Figma from code**, also load [figma-generate-design](../figma-generate-design/SKILL.md). It provides the workflow for discovering design system components via `search_design_system`, importing them, and assembling screens incrementally. Both skills work together: this one for the API rules, that one for the screen-building workflow.
|
||||
|
||||
Before anything, load [plugin-api-standalone.index.md](references/plugin-api-standalone.index.md) to understand what is possible. When you are asked to write plugin API code, use this context to grep [plugin-api-standalone.d.ts](references/plugin-api-standalone.d.ts) for relevant types, methods, and properties. This is the definitive source of truth for the API surface. It is a large typings file, so do not load it all at once, grep for relevant sections as needed.
|
||||
|
||||
IMPORTANT: Whenever you work with design systems, start with [working-with-design-systems/wwds.md](references/working-with-design-systems/wwds.md) to understand the key concepts, processes, and guidelines for working with design systems in Figma. Then load the more specific references for components, variables, text styles, and effect styles as needed.
|
||||
|
||||
## 1. Critical Rules
|
||||
|
||||
1. **Use `return` to send data back.** The return value is JSON-serialized automatically (objects, arrays, strings, numbers). Do NOT call `figma.closePlugin()` or wrap code in an async IIFE — this is handled for you.
|
||||
2. **Write plain JavaScript with top-level `await` and `return`.** Code is automatically wrapped in an async context. Do NOT wrap in `(async () => { ... })()`.
|
||||
3. `figma.notify()` **throws "not implemented"** — never use it
|
||||
3a. `getPluginData()` / `setPluginData()` are **not supported** in `use_figma` — do not use them. Use `getSharedPluginData()` / `setSharedPluginData()` instead (these ARE supported), or track node IDs by returning them and passing them to subsequent calls.
|
||||
4. `console.log()` is NOT returned — use `return` for output
|
||||
5. **Work incrementally in small steps.** Break large operations into multiple `use_figma` calls. Validate after each step. This is the single most important practice for avoiding bugs.
|
||||
6. Colors are **0–1 range** (not 0–255): `{r: 1, g: 0, b: 0}` = red
|
||||
7. Fills/strokes are **read-only arrays** — clone, modify, reassign
|
||||
8. Font **MUST** be loaded before any text operation: `await figma.loadFontAsync({family, style})`
|
||||
9. **Pages load incrementally** — use `await figma.setCurrentPageAsync(page)` to switch pages and load their content (see Page Rules below)
|
||||
10. `setBoundVariableForPaint` returns a **NEW** paint — must capture and reassign
|
||||
11. `createVariable` accepts collection **object or ID string** (object preferred)
|
||||
12. **`layoutSizingHorizontal/Vertical = 'FILL'` MUST be set AFTER `parent.appendChild(child)`** — setting before append throws. Same applies to `'HUG'` on non-auto-layout nodes.
|
||||
13. **Position new top-level nodes away from (0,0).** Nodes appended directly to the page default to (0,0). Scan `figma.currentPage.children` to find a clear position (e.g., to the right of the rightmost node). This only applies to page-level nodes — nodes nested inside other frames or auto-layout containers are positioned by their parent. See [Gotchas](references/gotchas.md).
|
||||
14. **On `use_figma` error, STOP. Do NOT immediately retry.** Failed scripts are **atomic** — if a script errors, it is not executed at all and no changes are made to the file. Read the error message carefully, fix the script, then retry. See [Error Recovery](#6-error-recovery--self-correction).
|
||||
15. **MUST `return` ALL created/mutated node IDs.** Whenever a script creates new nodes or mutates existing ones on the canvas, collect every affected node ID and return them in a structured object (e.g. `return { createdNodeIds: [...], mutatedNodeIds: [...] }`). This is essential for subsequent calls to reference, validate, or clean up those nodes.
|
||||
16. **Always set `variable.scopes` explicitly when creating variables.** The default `ALL_SCOPES` pollutes every property picker — almost never what you want. Use specific scopes like `["FRAME_FILL", "SHAPE_FILL"]` for backgrounds, `["TEXT_FILL"]` for text colors, `["GAP"]` for spacing, etc. See [variable-patterns.md](references/variable-patterns.md) for the full list.
|
||||
17. **`await` every Promise.** Never leave a Promise unawaited — unawaited async calls (e.g. `figma.loadFontAsync(...)` without `await`, or `figma.setCurrentPageAsync(page)` without `await`) will fire-and-forget, causing silent failures or race conditions. The script may return before the async operation completes, leading to missing data or half-applied changes.
|
||||
|
||||
> For detailed WRONG/CORRECT examples of each rule, see [Gotchas & Common Mistakes](references/gotchas.md).
|
||||
|
||||
## 2. Page Rules (Critical)
|
||||
|
||||
**Page context resets between `use_figma` calls** — `figma.currentPage` starts on the first page each time.
|
||||
|
||||
### Switching pages
|
||||
|
||||
Use `await figma.setCurrentPageAsync(page)` to switch pages and load their content. The sync setter `figma.currentPage = page` **throws an error** in `use_figma` runtimes.
|
||||
|
||||
```js
|
||||
// Switch to a specific page (loads its content)
|
||||
const targetPage = figma.root.children.find((p) => p.name === "My Page");
|
||||
await figma.setCurrentPageAsync(targetPage);
|
||||
// targetPage.children is now populated
|
||||
|
||||
// Iterate over all pages
|
||||
for (const page of figma.root.children) {
|
||||
await figma.setCurrentPageAsync(page);
|
||||
// page.children is now loaded — read or modify them here
|
||||
}
|
||||
```
|
||||
|
||||
### Across script runs
|
||||
|
||||
`figma.currentPage` resets to the **first page** at the start of each `use_figma` call. If your workflow spans multiple calls and targets a non-default page, call `await figma.setCurrentPageAsync(page)` at the start of each invocation.
|
||||
|
||||
You can call `use_figma` multiple times to incrementally build on the file state, or to retrieve information before writing another script. For example, write a script to get metadata about existing nodes, `return` that data, then use it in a subsequent script to modify those nodes.
|
||||
|
||||
## 3. `return` Is Your Output Channel
|
||||
|
||||
The agent sees **ONLY** the value you `return`. Everything else is invisible.
|
||||
|
||||
- **Returning IDs (CRITICAL)**: Every script that creates or mutates canvas nodes **MUST** return all affected node IDs — e.g. `return { createdNodeIds: [...], mutatedNodeIds: [...] }`. This is a hard requirement, not optional.
|
||||
- **Progress reporting**: `return { createdNodeIds: [...], count: 5, errors: [] }`
|
||||
- **Error info**: Thrown errors are automatically captured and returned — just let them propagate or `throw` explicitly.
|
||||
- `console.log()` output is **never** returned to the agent
|
||||
- Always return actionable data (IDs, counts, status) so subsequent calls can reference created objects
|
||||
|
||||
## 4. Editor Mode
|
||||
|
||||
`use_figma` works in **design mode** (editorType `"figma"`, the default). FigJam (`"figjam"`) has a different set of available node types — most design nodes are blocked there.
|
||||
|
||||
Available in design mode: Rectangle, Frame, Component, Text, Ellipse, Star, Line, Vector, Polygon, BooleanOperation, Slice, Page, Section, TextPath.
|
||||
|
||||
**Blocked** in design mode: Sticky, Connector, ShapeWithText, CodeBlock, Slide, SlideRow, Webpage.
|
||||
|
||||
## 5. Incremental Workflow (How to Avoid Bugs)
|
||||
|
||||
The most common cause of bugs is trying to do too much in a single `use_figma` call. **Work in small steps and validate after each one.**
|
||||
|
||||
### The pattern
|
||||
|
||||
1. **Inspect first.** Before creating anything, run a read-only `use_figma` to discover what already exists in the file — pages, components, variables, naming conventions. Match what's there.
|
||||
2. **Do one thing per call.** Create variables in one call, create components in the next, compose layouts in another. Don't try to build an entire screen in one script.
|
||||
3. **Return IDs from every call.** Always `return` created node IDs, variable IDs, collection IDs as objects (e.g. `return { createdNodeIds: [...] }`). You'll need these as inputs to subsequent calls.
|
||||
4. **Validate after each step.** Use `get_metadata` to verify structure (counts, names, hierarchy, positions). Use `get_screenshot` after major milestones to catch visual issues.
|
||||
5. **Fix before moving on.** If validation reveals a problem, fix it before proceeding to the next step. Don't build on a broken foundation.
|
||||
|
||||
### Suggested step order for complex tasks
|
||||
|
||||
```
|
||||
Step 1: Inspect file — discover existing pages, components, variables, conventions
|
||||
Step 2: Create tokens/variables (if needed)
|
||||
→ validate with get_metadata
|
||||
Step 3: Create individual components
|
||||
→ validate with get_metadata + get_screenshot
|
||||
Step 4: Compose layouts from component instances
|
||||
→ validate with get_screenshot
|
||||
Step 5: Final verification
|
||||
```
|
||||
|
||||
### What to validate at each step
|
||||
|
||||
| After... | Check with `get_metadata` | Check with `get_screenshot` |
|
||||
|---|---|---|
|
||||
| Creating variables | Collection count, variable count, mode names | — |
|
||||
| Creating components | Child count, variant names, property definitions | Variants visible, not collapsed, grid readable |
|
||||
| Binding variables | Node properties reflect bindings | Colors/tokens resolved correctly |
|
||||
| Composing layouts | Instance nodes have mainComponent, hierarchy correct | No cropped/clipped text, no overlapping elements, correct spacing |
|
||||
|
||||
## 6. Error Recovery & Self-Correction
|
||||
|
||||
**`use_figma` is atomic — failed scripts do not execute.** If a script errors, no changes are made to the file. The file remains in the same state as before the call. This means there are no partial nodes, no orphaned elements from the failed script, and retrying after a fix is safe.
|
||||
|
||||
### When `use_figma` returns an error
|
||||
|
||||
1. **STOP.** Do not immediately fix the code and retry.
|
||||
2. **Read the error message carefully.** Understand exactly what went wrong — wrong API usage, missing font, invalid property value, etc.
|
||||
3. **If the error is unclear**, call `get_metadata` or `get_screenshot` to understand the current file state.
|
||||
4. **Fix the script** based on the error message.
|
||||
5. **Retry** the corrected script.
|
||||
|
||||
### Common self-correction patterns
|
||||
|
||||
| Error message | Likely cause | How to fix |
|
||||
|---|---|---|
|
||||
| `"not implemented"` | Used `figma.notify()` | Remove it — use `return` for output |
|
||||
| `"node must be an auto-layout frame..."` | Set `FILL`/`HUG` before appending to auto-layout parent | Move `appendChild` before `layoutSizingX = 'FILL'` |
|
||||
| `"Setting figma.currentPage is not supported"` | Used sync page setter | Use `await figma.setCurrentPageAsync(page)` |
|
||||
| Property value out of range | Color channel > 1 (used 0–255 instead of 0–1) | Divide by 255 |
|
||||
| `"Cannot read properties of null"` | Node doesn't exist (wrong ID, wrong page) | Check page context, verify ID |
|
||||
| Script hangs / no response | Infinite loop or unresolved promise | Check for `while(true)` or missing `await`; ensure code terminates |
|
||||
| `"The node with id X does not exist"` | Parent instance was implicitly detached by a child `detachInstance()`, changing IDs | Re-discover nodes by traversal from a stable (non-instance) parent frame |
|
||||
|
||||
### When the script succeeds but the result looks wrong
|
||||
|
||||
1. Call `get_metadata` to check structural correctness (hierarchy, counts, positions).
|
||||
2. Call `get_screenshot` to check visual correctness. Look closely for cropped/clipped text (line heights cutting off content) and overlapping elements — these are common and easy to miss.
|
||||
3. Identify the discrepancy — is it structural (wrong hierarchy, missing nodes) or visual (wrong colors, broken layout, clipped content)?
|
||||
4. Write a targeted fix script that modifies only the broken parts — don't recreate everything.
|
||||
|
||||
> For the full validation workflow, see [Validation & Error Recovery](references/validation-and-recovery.md).
|
||||
|
||||
## 7. Pre-Flight Checklist
|
||||
|
||||
Before submitting ANY `use_figma` call, verify:
|
||||
|
||||
- [ ] Code uses `return` to send data back (NOT `figma.closePlugin()`)
|
||||
- [ ] Code is NOT wrapped in an async IIFE (auto-wrapped for you)
|
||||
- [ ] `return` value includes structured data with actionable info (IDs, counts)
|
||||
- [ ] NO usage of `figma.notify()` anywhere
|
||||
- [ ] NO usage of `console.log()` as output (use `return` instead)
|
||||
- [ ] All colors use 0–1 range (not 0–255)
|
||||
- [ ] Fills/strokes are reassigned as new arrays (not mutated in place)
|
||||
- [ ] Page switches use `await figma.setCurrentPageAsync(page)` (sync setter throws)
|
||||
- [ ] `layoutSizingVertical/Horizontal = 'FILL'` is set AFTER `parent.appendChild(child)`
|
||||
- [ ] `loadFontAsync()` called BEFORE any text property changes
|
||||
- [ ] `lineHeight`/`letterSpacing` use `{unit, value}` format (not bare numbers)
|
||||
- [ ] `resize()` is called BEFORE setting sizing modes (resize resets them to FIXED)
|
||||
- [ ] For multi-step workflows: IDs from previous calls are passed as string literals (not variables)
|
||||
- [ ] New top-level nodes are positioned away from (0,0) to avoid overlapping existing content
|
||||
- [ ] ALL created/mutated node IDs are collected and included in the `return` value
|
||||
- [ ] Every async call (`loadFontAsync`, `setCurrentPageAsync`, `importComponentByKeyAsync`, etc.) is `await`ed — no fire-and-forget Promises
|
||||
|
||||
## 8. Discover Conventions Before Creating
|
||||
|
||||
**Always inspect the Figma file before creating anything.** Different files use different naming conventions, variable structures, and component patterns. Your code should match what's already there, not impose new conventions.
|
||||
|
||||
When in doubt about any convention (naming, scoping, structure), check the Figma file first, then the user's codebase. Only fall back to common patterns when neither exists.
|
||||
|
||||
### Quick inspection scripts
|
||||
|
||||
**List all pages and top-level nodes:**
|
||||
```js
|
||||
const pages = figma.root.children.map(p => `${p.name} id=${p.id} children=${p.children.length}`);
|
||||
return pages.join('\n');
|
||||
```
|
||||
|
||||
**List existing components across all pages:**
|
||||
```js
|
||||
const results = [];
|
||||
for (const page of figma.root.children) {
|
||||
await figma.setCurrentPageAsync(page);
|
||||
page.findAll(n => {
|
||||
if (n.type === 'COMPONENT' || n.type === 'COMPONENT_SET')
|
||||
results.push(`[${page.name}] ${n.name} (${n.type}) id=${n.id}`);
|
||||
return false;
|
||||
});
|
||||
}
|
||||
return results.join('\n');
|
||||
```
|
||||
|
||||
**List existing variable collections and their conventions:**
|
||||
```js
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
const results = collections.map(c => ({
|
||||
name: c.name, id: c.id,
|
||||
varCount: c.variableIds.length,
|
||||
modes: c.modes.map(m => m.name)
|
||||
}));
|
||||
return results;
|
||||
```
|
||||
|
||||
## 9. Reference Docs
|
||||
|
||||
Load these as needed based on what your task involves:
|
||||
|
||||
| Doc | When to load | What it covers |
|
||||
|-----|-------------|----------------|
|
||||
| [gotchas.md](references/gotchas.md) | Before any `use_figma` | Every known pitfall with WRONG/CORRECT code examples |
|
||||
| [common-patterns.md](references/common-patterns.md) | Need working code examples | Script scaffolds: shapes, text, auto-layout, variables, components, multi-step workflows |
|
||||
| [plugin-api-patterns.md](references/plugin-api-patterns.md) | Creating/editing nodes | Fills, strokes, Auto Layout, effects, grouping, cloning, styles |
|
||||
| [api-reference.md](references/api-reference.md) | Need exact API surface | Node creation, variables API, core properties, what works and what doesn't |
|
||||
| [validation-and-recovery.md](references/validation-and-recovery.md) | Multi-step writes or error recovery | `get_metadata` vs `get_screenshot` workflow, mandatory error recovery steps |
|
||||
| [component-patterns.md](references/component-patterns.md) | Creating components/variants | combineAsVariants, component properties, INSTANCE_SWAP, variant layout, discovering existing components, metadata traversal |
|
||||
| [variable-patterns.md](references/variable-patterns.md) | Creating/binding variables | Collections, modes, scopes, aliasing, binding patterns, discovering existing variables |
|
||||
| [text-style-patterns.md](references/text-style-patterns.md) | Creating/applying text styles | Type ramps, font probing, listing styles, applying styles to nodes |
|
||||
| [effect-style-patterns.md](references/effect-style-patterns.md) | Creating/applying effect styles | Drop shadows, listing styles, applying styles to nodes |
|
||||
| [plugin-api-standalone.index.md](references/plugin-api-standalone.index.md) | Need to understand the full API surface | Index of all types, methods, and properties in the Plugin API |
|
||||
| [plugin-api-standalone.d.ts](references/plugin-api-standalone.d.ts) | Need exact type signatures | Full typings file — grep for specific symbols, don't load all at once |
|
||||
|
||||
## 10. Snippet examples
|
||||
|
||||
You will see snippets throughout documentation here. These snippets contain useful plugin API code that can be repurposed. Use them as is, or as starter code as you go. If there are key concepts that are best documented as generic snippets, call them out and write to disk so you can reuse in the future.
|
||||
@@ -0,0 +1,304 @@
|
||||
# Figma Plugin API Reference
|
||||
|
||||
> Part of the [use_figma skill](../SKILL.md). What works and what doesn't in the `use_figma` environment.
|
||||
|
||||
## Contents
|
||||
|
||||
- Node Creation
|
||||
- Grouping and Boolean Operations
|
||||
- Library Imports
|
||||
- Variables API
|
||||
- Core Properties
|
||||
- Node Manipulation
|
||||
- Descriptions and Documentation Links
|
||||
- SVG and Images
|
||||
- Utilities and Plugin Lifecycle
|
||||
- Node Traversal
|
||||
- Unsupported APIs
|
||||
|
||||
|
||||
## Node Creation (Design Mode)
|
||||
|
||||
```js
|
||||
figma.createRectangle()
|
||||
figma.createFrame()
|
||||
figma.createComponent() // Creates a ComponentNode
|
||||
figma.createText()
|
||||
figma.createEllipse()
|
||||
figma.createStar()
|
||||
figma.createLine()
|
||||
figma.createVector()
|
||||
figma.createPolygon()
|
||||
figma.createBooleanOperation()
|
||||
figma.createSlice()
|
||||
figma.createPage() // Page node can be created, but child persistence is limited in headless mode
|
||||
figma.createSection()
|
||||
figma.createTextPath()
|
||||
```
|
||||
|
||||
## Grouping & Boolean Operations
|
||||
|
||||
```js
|
||||
figma.group(nodes, parent, index?) // Group nodes
|
||||
figma.flatten(nodes, parent?, index?) // Flatten to vector
|
||||
figma.union(nodes, parent?, index?) // Boolean union
|
||||
figma.subtract(nodes, parent?, index?) // Boolean subtract
|
||||
figma.intersect(nodes, parent?, index?) // Boolean intersect
|
||||
figma.exclude(nodes, parent?, index?) // Boolean exclude
|
||||
figma.combineAsVariants(components, parent?) // Combine ComponentNodes into ComponentSet (Design/Sites only)
|
||||
```
|
||||
|
||||
## Library Component Import
|
||||
|
||||
These methods import components from **team libraries** (not the same file you're working in). For components in the current file, use `use_figma` with `figma.getNodeByIdAsync()` or `findOne()`/`findAll()` to locate them directly.
|
||||
|
||||
```js
|
||||
// Import a published component from a team library by key
|
||||
const comp = await figma.importComponentByKeyAsync("COMPONENT_KEY")
|
||||
const instance = comp.createInstance()
|
||||
|
||||
// Import a published component set from a team library by key
|
||||
const compSet = await figma.importComponentSetByKeyAsync("COMPONENT_SET_KEY")
|
||||
const variant =
|
||||
compSet.children.find((c) => c.type === "COMPONENT" && c.name.includes("size=md")) ||
|
||||
compSet.defaultVariant
|
||||
const variantInstance = variant.createInstance()
|
||||
```
|
||||
|
||||
## Library Style Import (Team Libraries)
|
||||
|
||||
These methods import styles from **team libraries** (not the same file). For styles in the current file, use `figma.getLocalPaintStyles()`, `figma.getLocalTextStyles()`, etc.
|
||||
|
||||
```js
|
||||
// Import a published style from a team library by key
|
||||
const style = await figma.importStyleByKeyAsync("STYLE_KEY")
|
||||
|
||||
// Apply the imported style to a node
|
||||
await node.setFillStyleIdAsync(style.id) // for PaintStyle as fill
|
||||
await node.setStrokeStyleIdAsync(style.id) // for PaintStyle as stroke
|
||||
await node.setTextStyleIdAsync(style.id) // for TextStyle
|
||||
await node.setEffectStyleIdAsync(style.id) // for EffectStyle
|
||||
await node.setGridStyleIdAsync(style.id) // for GridStyle
|
||||
```
|
||||
|
||||
## Library Variable Import (Team Libraries)
|
||||
|
||||
This imports variables from **team libraries** (not the same file). For variables in the current file, use `figma.variables.getLocalVariablesAsync()` or `figma.variables.getVariableByIdAsync()`.
|
||||
|
||||
```js
|
||||
// Import a published variable from a team library by key
|
||||
const variable = await figma.variables.importVariableByKeyAsync("VARIABLE_KEY")
|
||||
|
||||
// Bind the imported variable to node properties
|
||||
node.setBoundVariable("width", variable) // FLOAT variable
|
||||
|
||||
// Bind to fills/strokes (COLOR variable) — returns a NEW paint, must capture it
|
||||
const newPaint = figma.variables.setBoundVariableForPaint(paintCopy, "color", variable)
|
||||
node.fills = [newPaint]
|
||||
```
|
||||
|
||||
## Variables API
|
||||
|
||||
```js
|
||||
// Collections
|
||||
const collection = figma.variables.createVariableCollection("Name")
|
||||
collection.name // Get/set name
|
||||
collection.modes // Array of {modeId, name} — starts with 1 mode
|
||||
collection.addMode("Dark") // Returns new modeId string
|
||||
collection.renameMode(modeId, "Light")
|
||||
|
||||
// Variables
|
||||
const variable = figma.variables.createVariable("name", collection, "COLOR")
|
||||
// ^ must be a collection object (passing an ID string is deprecated)
|
||||
// resolvedType: "COLOR" | "FLOAT" | "STRING" | "BOOLEAN"
|
||||
variable.setValueForMode(modeId, value)
|
||||
|
||||
// Scopes — controls where variable appears in property pickers
|
||||
variable.scopes = ["FRAME_FILL", "SHAPE_FILL"] // only fill pickers
|
||||
variable.scopes = ["TEXT_FILL"] // only text color picker
|
||||
variable.scopes = ["STROKE_COLOR"] // only stroke picker
|
||||
variable.scopes = [] // hidden from all pickers (use for primitives)
|
||||
// All valid scope values:
|
||||
// ALL_SCOPES, TEXT_CONTENT, CORNER_RADIUS, WIDTH_HEIGHT, GAP,
|
||||
// ALL_FILLS, FRAME_FILL, SHAPE_FILL, TEXT_FILL,
|
||||
// STROKE_COLOR, STROKE_FLOAT, EFFECT_FLOAT, EFFECT_COLOR,
|
||||
// OPACITY, FONT_FAMILY, FONT_STYLE, FONT_WEIGHT, FONT_SIZE,
|
||||
// LINE_HEIGHT, LETTER_SPACING, PARAGRAPH_SPACING, PARAGRAPH_INDENT
|
||||
|
||||
// Querying (always use the Async variants — sync versions are deprecated)
|
||||
await figma.variables.getVariableByIdAsync(id)
|
||||
await figma.variables.getLocalVariablesAsync(resolvedType?)
|
||||
await figma.variables.getVariableCollectionByIdAsync(id)
|
||||
await figma.variables.getLocalVariableCollectionsAsync()
|
||||
|
||||
// Binding variables to paints (COLOR variables)
|
||||
const newPaint = figma.variables.setBoundVariableForPaint(paintCopy, "color", variable)
|
||||
// ⚠️ Returns a NEW paint — must capture return value!
|
||||
node.fills = [newPaint]
|
||||
|
||||
// Binding variables to effects (COLOR/FLOAT variables)
|
||||
const newEffect = figma.variables.setBoundVariableForEffect(effectCopy, field, variable)
|
||||
// field for shadows: "color" (COLOR), "radius" | "spread" | "offsetX" | "offsetY" (FLOAT)
|
||||
// field for blurs: "radius" (FLOAT)
|
||||
// ⚠️ Returns a NEW effect — must capture return value!
|
||||
node.effects = [newEffect]
|
||||
|
||||
// Binding variables to layout grids (FLOAT variables)
|
||||
const newGrid = figma.variables.setBoundVariableForLayoutGrid(gridCopy, field, variable)
|
||||
// field: "sectionSize" | "offset" | "count" | "gutterSize"
|
||||
// ⚠️ Returns a NEW layout grid — must capture return value!
|
||||
node.layoutGrids = [newGrid]
|
||||
|
||||
// Binding variables to node properties (FLOAT/STRING/BOOLEAN)
|
||||
// Layout & sizing (FLOAT):
|
||||
node.setBoundVariable("width", variable)
|
||||
node.setBoundVariable("height", variable)
|
||||
node.setBoundVariable("minWidth", variable)
|
||||
node.setBoundVariable("maxWidth", variable)
|
||||
node.setBoundVariable("minHeight", variable)
|
||||
node.setBoundVariable("maxHeight", variable)
|
||||
node.setBoundVariable("paddingLeft", variable)
|
||||
node.setBoundVariable("paddingRight", variable)
|
||||
node.setBoundVariable("paddingTop", variable)
|
||||
node.setBoundVariable("paddingBottom", variable)
|
||||
node.setBoundVariable("itemSpacing", variable)
|
||||
node.setBoundVariable("counterAxisSpacing", variable)
|
||||
// Corner radii (FLOAT) — use individual corners, NOT cornerRadius:
|
||||
node.setBoundVariable("topLeftRadius", variable)
|
||||
node.setBoundVariable("topRightRadius", variable)
|
||||
node.setBoundVariable("bottomLeftRadius", variable)
|
||||
node.setBoundVariable("bottomRightRadius", variable)
|
||||
// Other (FLOAT):
|
||||
node.setBoundVariable("opacity", variable)
|
||||
node.setBoundVariable("strokeWeight", variable)
|
||||
// ⚠️ fontSize, fontWeight, lineHeight are NOT bindable via setBoundVariable
|
||||
// — set these directly as values on text nodes
|
||||
|
||||
// Aliases
|
||||
figma.variables.createVariableAlias(variable)
|
||||
|
||||
// Explicit modes — CRITICAL for variant components
|
||||
node.setExplicitVariableModeForCollection(collection, modeId) // pass collection object, NOT an ID string
|
||||
// Without this, all nodes use the default (first) mode of the collection
|
||||
```
|
||||
|
||||
## Core Properties
|
||||
|
||||
```js
|
||||
figma.root // DocumentNode
|
||||
figma.currentPage // Current page (read-only in use_figma; sync setter throws)
|
||||
figma.setCurrentPageAsync(page) // Switch page and load its content (MUST await)
|
||||
figma.fileKey // File key string
|
||||
figma.mixed // Mixed sentinel value
|
||||
```
|
||||
|
||||
## Node Manipulation
|
||||
|
||||
```js
|
||||
// Fills & Strokes (read-only arrays — must clone)
|
||||
node.fills = [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 } }]
|
||||
node.strokes = [{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }]
|
||||
node.strokeWeight = 1
|
||||
node.strokeAlign = 'INSIDE' // 'INSIDE' | 'CENTER' | 'OUTSIDE'
|
||||
|
||||
// Effects
|
||||
node.effects = [{ type: 'DROP_SHADOW', color: {r:0,g:0,b:0,a:0.25}, offset:{x:0,y:4}, radius:4, visible:true }]
|
||||
|
||||
// Layout
|
||||
node.layoutMode = 'HORIZONTAL' // 'NONE' | 'HORIZONTAL' | 'VERTICAL'
|
||||
node.primaryAxisAlignItems = 'CENTER' // 'MIN' | 'CENTER' | 'MAX' | 'SPACE_BETWEEN'
|
||||
node.counterAxisAlignItems = 'CENTER' // 'MIN' | 'CENTER' | 'MAX' | 'BASELINE'
|
||||
node.paddingLeft = 8
|
||||
node.paddingRight = 8
|
||||
node.paddingTop = 4
|
||||
node.paddingBottom = 4
|
||||
node.itemSpacing = 4
|
||||
node.layoutSizingHorizontal = 'HUG' // 'FIXED' | 'HUG' | 'FILL'
|
||||
node.layoutSizingVertical = 'HUG' // 'FIXED' | 'HUG' | 'FILL'
|
||||
|
||||
// Sizing
|
||||
node.resize(width, height) // ⚠️ Resets sizing modes to FIXED
|
||||
node.resizeWithoutConstraints(width, height) // Doesn't affect constraints
|
||||
|
||||
// Corner radius
|
||||
node.cornerRadius = 8
|
||||
|
||||
// Visibility & Opacity
|
||||
node.visible = true
|
||||
node.opacity = 0.5
|
||||
|
||||
// Naming & Hierarchy
|
||||
node.name = "My Node"
|
||||
parent.appendChild(child)
|
||||
parent.insertChild(index, child)
|
||||
node.remove()
|
||||
```
|
||||
|
||||
## Descriptions & Documentation Links
|
||||
|
||||
```js
|
||||
// Description — plain text, shown in Figma's component panel
|
||||
node.description = "A short summary of this component's purpose and usage."
|
||||
|
||||
// Documentation links — array of {uri, label} shown as clickable links
|
||||
componentSet.documentationLinks = [
|
||||
{ uri: "https://example.com/docs", label: "Component Docs" }
|
||||
]
|
||||
// ⚠️ uri MUST be a valid URL (https://...) — relative paths will throw
|
||||
```
|
||||
|
||||
## SVG Import
|
||||
|
||||
```js
|
||||
const svgNode = figma.createNodeFromSvg('<svg>...</svg>')
|
||||
```
|
||||
|
||||
## Images
|
||||
|
||||
```js
|
||||
const image = figma.createImage(uint8Array)
|
||||
node.fills = [{ type: 'IMAGE', scaleMode: 'FILL', imageHash: image.hash }]
|
||||
```
|
||||
|
||||
## Utilities
|
||||
|
||||
```js
|
||||
figma.base64Encode(uint8Array) // Uint8Array → base64 string
|
||||
figma.base64Decode(base64String) // base64 string → Uint8Array
|
||||
figma.createComponentFromNode(node) // Convert existing node to component (Design/Sites only)
|
||||
```
|
||||
|
||||
## Plugin Lifecycle
|
||||
|
||||
Scripts are automatically wrapped in an async IIFE with error handling. Use `return` to send data back:
|
||||
|
||||
```js
|
||||
return { nodeId: frame.id } // Return object — auto-serialized to JSON
|
||||
return "success message" // Return string
|
||||
// Errors are auto-captured — no try/catch or closePlugin needed
|
||||
```
|
||||
|
||||
## Node Traversal
|
||||
|
||||
```js
|
||||
node.findAll(pred?) // Find all descendants matching predicate
|
||||
node.findOne(pred?) // Find first descendant matching predicate
|
||||
node.findChildren(pred?) // Find direct children matching predicate
|
||||
node.findChild(pred?) // Find first direct child matching predicate
|
||||
node.children // Direct children array
|
||||
node.parent // Parent node
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What Does NOT Work
|
||||
|
||||
| API | Status |
|
||||
|-----|--------|
|
||||
| `figma.notify()` | **Throws "not implemented"** — most common mistake |
|
||||
| `figma.showUI()` | No-op (silently ignored) |
|
||||
| `figma.openExternal()` | No-op (silently ignored) |
|
||||
| `figma.listAvailableFontsAsync()` | Not implemented |
|
||||
| `figma.loadAllPagesAsync()` | Not implemented |
|
||||
| `figma.variables.extendLibraryCollectionByKeyAsync()` | Not implemented |
|
||||
| `figma.teamLibrary.*` | Not implemented (requires LiveGraph) |
|
||||
@@ -0,0 +1,441 @@
|
||||
# Common Patterns
|
||||
|
||||
> Part of the [use_figma skill](../SKILL.md). Working code examples for frequently used operations.
|
||||
|
||||
## Contents
|
||||
|
||||
- Basic Script Structure
|
||||
- Create a Styled Shape
|
||||
- Create a Text Node
|
||||
- Create Frame with Auto-Layout
|
||||
- Create Variable Collections and Bindings
|
||||
- Create Components and Import by Key
|
||||
- Component Sets with Variable Modes
|
||||
- Multi-Step Large ComponentSet Pattern
|
||||
- Read Existing Nodes and Return Data
|
||||
|
||||
|
||||
## Basic Script Structure
|
||||
|
||||
```js
|
||||
const createdNodeIds = []
|
||||
const mutatedNodeIds = []
|
||||
|
||||
// Your code here — track every node you create or mutate
|
||||
// createdNodeIds.push(newNode.id)
|
||||
// mutatedNodeIds.push(existingNode.id)
|
||||
|
||||
return {
|
||||
success: true,
|
||||
createdNodeIds,
|
||||
mutatedNodeIds,
|
||||
// Plus any other useful data for subsequent calls
|
||||
count: createdNodeIds.length
|
||||
}
|
||||
```
|
||||
|
||||
## Create a Styled Shape
|
||||
|
||||
```js
|
||||
// Find clear space to the right of existing content
|
||||
const page = figma.currentPage
|
||||
let maxX = 0
|
||||
for (const child of page.children) {
|
||||
maxX = Math.max(maxX, child.x + child.width)
|
||||
}
|
||||
|
||||
const rect = figma.createRectangle()
|
||||
rect.name = "Blue Box"
|
||||
rect.resize(200, 100)
|
||||
rect.fills = [{ type: 'SOLID', color: { r: 0.047, g: 0.549, b: 0.914 } }]
|
||||
rect.cornerRadius = 8
|
||||
rect.x = maxX + 100 // offset from existing content
|
||||
rect.y = 0
|
||||
figma.currentPage.appendChild(rect)
|
||||
return { nodeId: rect.id }
|
||||
```
|
||||
|
||||
## Create a Text Node
|
||||
|
||||
```js
|
||||
// Find clear space to the right of existing content
|
||||
const page = figma.currentPage
|
||||
let maxX = 0
|
||||
for (const child of page.children) {
|
||||
maxX = Math.max(maxX, child.x + child.width)
|
||||
}
|
||||
|
||||
await figma.loadFontAsync({ family: "Inter", style: "Regular" })
|
||||
const text = figma.createText()
|
||||
text.characters = "Hello World"
|
||||
text.fontSize = 16
|
||||
text.fills = [{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }]
|
||||
text.textAutoResize = 'WIDTH_AND_HEIGHT'
|
||||
text.x = maxX + 100
|
||||
text.y = 0
|
||||
figma.currentPage.appendChild(text)
|
||||
return { nodeId: text.id }
|
||||
```
|
||||
|
||||
## Create Frame with Auto-Layout
|
||||
|
||||
```js
|
||||
// Find clear space to the right of existing content
|
||||
const page = figma.currentPage
|
||||
let maxX = 0
|
||||
for (const child of page.children) {
|
||||
maxX = Math.max(maxX, child.x + child.width)
|
||||
}
|
||||
|
||||
const frame = figma.createFrame()
|
||||
frame.name = "Card"
|
||||
frame.layoutMode = 'VERTICAL'
|
||||
frame.primaryAxisAlignItems = 'MIN'
|
||||
frame.counterAxisAlignItems = 'MIN'
|
||||
frame.paddingLeft = 16
|
||||
frame.paddingRight = 16
|
||||
frame.paddingTop = 12
|
||||
frame.paddingBottom = 12
|
||||
frame.itemSpacing = 8
|
||||
frame.layoutSizingHorizontal = 'HUG'
|
||||
frame.layoutSizingVertical = 'HUG'
|
||||
frame.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }]
|
||||
frame.cornerRadius = 8
|
||||
frame.x = maxX + 100
|
||||
frame.y = 0
|
||||
figma.currentPage.appendChild(frame)
|
||||
return { nodeId: frame.id }
|
||||
```
|
||||
|
||||
## Create Variable Collection with Multiple Modes
|
||||
|
||||
```js
|
||||
const collection = figma.variables.createVariableCollection("Theme/Colors")
|
||||
// Rename the default mode
|
||||
collection.renameMode(collection.modes[0].modeId, "Light")
|
||||
const darkModeId = collection.addMode("Dark")
|
||||
const lightModeId = collection.modes[0].modeId
|
||||
|
||||
const bgVar = figma.variables.createVariable("bg", collection, "COLOR")
|
||||
bgVar.setValueForMode(lightModeId, { r: 1, g: 1, b: 1, a: 1 })
|
||||
bgVar.setValueForMode(darkModeId, { r: 0.1, g: 0.1, b: 0.1, a: 1 })
|
||||
|
||||
const textVar = figma.variables.createVariable("text", collection, "COLOR")
|
||||
textVar.setValueForMode(lightModeId, { r: 0, g: 0, b: 0, a: 1 })
|
||||
textVar.setValueForMode(darkModeId, { r: 1, g: 1, b: 1, a: 1 })
|
||||
|
||||
return {
|
||||
collectionId: collection.id,
|
||||
lightModeId,
|
||||
darkModeId,
|
||||
bgVarId: bgVar.id,
|
||||
textVarId: textVar.id
|
||||
}
|
||||
```
|
||||
|
||||
## Bind Color Variable to a Fill
|
||||
|
||||
```js
|
||||
const variable = await figma.variables.getVariableByIdAsync("VariableID:1:2")
|
||||
const rect = figma.createRectangle()
|
||||
const basePaint = { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }
|
||||
|
||||
// setBoundVariableForPaint returns a NEW paint — capture it!
|
||||
const boundPaint = figma.variables.setBoundVariableForPaint(basePaint, "color", variable)
|
||||
rect.fills = [boundPaint]
|
||||
|
||||
return { nodeId: rect.id }
|
||||
```
|
||||
|
||||
## Create Component Variants with Component Properties
|
||||
|
||||
Component properties (TEXT, BOOLEAN, INSTANCE_SWAP) MUST be added inside the per-variant loop, BEFORE `combineAsVariants`. The component set inherits them from its children.
|
||||
|
||||
```js
|
||||
await figma.loadFontAsync({ family: "Inter", style: "Regular" })
|
||||
|
||||
// Assume defaultIconComp is an existing icon component (discovered earlier)
|
||||
const defaultIconComp = figma.getNodeById('ICON_COMPONENT_ID')
|
||||
|
||||
const components = []
|
||||
const variants = ["primary", "secondary"]
|
||||
|
||||
for (const variant of variants) {
|
||||
const comp = figma.createComponent()
|
||||
comp.name = `variant=${variant}`
|
||||
comp.layoutMode = 'HORIZONTAL'
|
||||
comp.primaryAxisAlignItems = 'CENTER'
|
||||
comp.counterAxisAlignItems = 'CENTER'
|
||||
comp.paddingLeft = 12
|
||||
comp.paddingRight = 12
|
||||
comp.paddingTop = 8
|
||||
comp.paddingBottom = 8
|
||||
comp.layoutSizingHorizontal = 'HUG'
|
||||
comp.layoutSizingVertical = 'HUG'
|
||||
comp.cornerRadius = 6
|
||||
comp.itemSpacing = 8
|
||||
|
||||
// TEXT property — label
|
||||
const labelKey = comp.addComponentProperty('Label', 'TEXT', 'Button')
|
||||
const label = figma.createText()
|
||||
label.characters = "Button"
|
||||
label.fontSize = 14
|
||||
comp.appendChild(label)
|
||||
label.componentPropertyReferences = { characters: labelKey }
|
||||
|
||||
// BOOLEAN + INSTANCE_SWAP — icon slot
|
||||
const showIconKey = comp.addComponentProperty('Show Icon', 'BOOLEAN', false)
|
||||
const iconSlotKey = comp.addComponentProperty('Icon', 'INSTANCE_SWAP', defaultIconComp.id)
|
||||
const iconInstance = defaultIconComp.createInstance()
|
||||
comp.insertChild(0, iconInstance) // icon before label
|
||||
iconInstance.componentPropertyReferences = {
|
||||
visible: showIconKey,
|
||||
mainComponent: iconSlotKey
|
||||
}
|
||||
|
||||
components.push(comp)
|
||||
}
|
||||
|
||||
const componentSet = figma.combineAsVariants(components, figma.currentPage)
|
||||
componentSet.name = "Button"
|
||||
|
||||
// Layout variants in a row after combining (they stack at 0,0 by default)
|
||||
const colW = 140
|
||||
componentSet.children.forEach((child, i) => {
|
||||
child.x = i * colW
|
||||
child.y = 0
|
||||
})
|
||||
// Resize from actual child bounds — formula-based sizing is error-prone
|
||||
let maxX = 0, maxY = 0
|
||||
for (const c of componentSet.children) {
|
||||
maxX = Math.max(maxX, c.x + c.width)
|
||||
maxY = Math.max(maxY, c.y + c.height)
|
||||
}
|
||||
componentSet.resizeWithoutConstraints(maxX + 40, maxY + 40)
|
||||
|
||||
return {
|
||||
componentSetId: componentSet.id,
|
||||
componentIds: components.map(c => c.id)
|
||||
}
|
||||
```
|
||||
|
||||
## Import a Component by Key (Team Libraries)
|
||||
|
||||
`importComponentByKeyAsync` and `importComponentSetByKeyAsync` import components from **team libraries** (not the same file you're working in). For components in the current file, use `figma.getNodeByIdAsync()` or `findOne()`/`findAll()` to locate them directly.
|
||||
|
||||
```js
|
||||
// Import a single published component by key
|
||||
const comp = await figma.importComponentByKeyAsync("COMPONENT_KEY")
|
||||
const instance = comp.createInstance()
|
||||
instance.x = 40
|
||||
instance.y = 40
|
||||
figma.currentPage.appendChild(instance)
|
||||
|
||||
// Import a published component set by key and select a variant
|
||||
const compSet = await figma.importComponentSetByKeyAsync("COMPONENT_SET_KEY")
|
||||
const variant =
|
||||
compSet.children.find((c) =>
|
||||
c.type === "COMPONENT" && c.name.includes("size=md")
|
||||
) || compSet.defaultVariant
|
||||
|
||||
const variantInstance = variant.createInstance()
|
||||
variantInstance.x = 240
|
||||
variantInstance.y = 40
|
||||
figma.currentPage.appendChild(variantInstance)
|
||||
|
||||
return {
|
||||
componentId: comp.id,
|
||||
componentSetId: compSet.id,
|
||||
placedInstanceIds: [instance.id, variantInstance.id]
|
||||
}
|
||||
```
|
||||
|
||||
## Component Set with Variable Modes (Full Pattern)
|
||||
|
||||
```js
|
||||
await figma.loadFontAsync({ family: "Inter", style: "Medium" })
|
||||
|
||||
// 1. Create color collection with modes per variant
|
||||
const colors = figma.variables.createVariableCollection("Component/Colors")
|
||||
colors.renameMode(colors.modes[0].modeId, "primary")
|
||||
const primaryMode = colors.modes[0].modeId
|
||||
const secondaryMode = colors.addMode("secondary")
|
||||
|
||||
const bgVar = figma.variables.createVariable("bg", colors, "COLOR")
|
||||
bgVar.setValueForMode(primaryMode, { r: 0, g: 0.4, b: 0.9, a: 1 })
|
||||
bgVar.setValueForMode(secondaryMode, { r: 0, g: 0, b: 0, a: 0 })
|
||||
|
||||
const textVar = figma.variables.createVariable("text-color", colors, "COLOR")
|
||||
textVar.setValueForMode(primaryMode, { r: 1, g: 1, b: 1, a: 1 })
|
||||
textVar.setValueForMode(secondaryMode, { r: 0.1, g: 0.1, b: 0.1, a: 1 })
|
||||
|
||||
// 2. Create components with variable bindings
|
||||
const modeMap = { primary: primaryMode, secondary: secondaryMode }
|
||||
const components = []
|
||||
|
||||
for (const [variantName, modeId] of Object.entries(modeMap)) {
|
||||
const comp = figma.createComponent()
|
||||
comp.name = "variant=" + variantName
|
||||
comp.layoutMode = "HORIZONTAL"
|
||||
comp.primaryAxisAlignItems = "CENTER"
|
||||
comp.counterAxisAlignItems = "CENTER"
|
||||
comp.paddingLeft = 12; comp.paddingRight = 12
|
||||
comp.layoutSizingHorizontal = "HUG"
|
||||
comp.layoutSizingVertical = "HUG"
|
||||
comp.cornerRadius = 6
|
||||
|
||||
// Bind background fill to variable
|
||||
const bgPaint = figma.variables.setBoundVariableForPaint(
|
||||
{ type: "SOLID", color: { r: 0, g: 0, b: 0 } }, "color", bgVar
|
||||
)
|
||||
comp.fills = [bgPaint]
|
||||
|
||||
// Add text with bound color
|
||||
const label = figma.createText()
|
||||
label.fontName = { family: "Inter", style: "Medium" }
|
||||
label.characters = "Button"
|
||||
label.fontSize = 14
|
||||
const textPaint = figma.variables.setBoundVariableForPaint(
|
||||
{ type: "SOLID", color: { r: 0, g: 0, b: 0 } }, "color", textVar
|
||||
)
|
||||
label.fills = [textPaint]
|
||||
comp.appendChild(label)
|
||||
|
||||
// 3. CRITICAL: Set explicit mode so this variant renders correctly
|
||||
comp.setExplicitVariableModeForCollection(colors, modeId)
|
||||
|
||||
components.push(comp)
|
||||
}
|
||||
|
||||
// 4. Combine into component set
|
||||
const componentSet = figma.combineAsVariants(components, figma.currentPage)
|
||||
componentSet.name = "Button"
|
||||
|
||||
return {
|
||||
componentSetId: componentSet.id,
|
||||
colorCollectionId: colors.id
|
||||
}
|
||||
```
|
||||
|
||||
## Large ComponentSet with Variable Modes (Multi-Step Pattern)
|
||||
|
||||
For component sets with many variants (50+), split into multiple `use_figma` calls:
|
||||
|
||||
**Call 1: Create variable collections and return IDs**
|
||||
|
||||
```js
|
||||
// Hex-to-0-1 helper
|
||||
const hex = (h) => {
|
||||
if (!h) return { r: 0, g: 0, b: 0, a: 0 }; // transparent
|
||||
return {
|
||||
r: parseInt(h.slice(1,3), 16) / 255,
|
||||
g: parseInt(h.slice(3,5), 16) / 255,
|
||||
b: parseInt(h.slice(5,7), 16) / 255,
|
||||
a: 1
|
||||
};
|
||||
};
|
||||
|
||||
const coll = figma.variables.createVariableCollection("MyComponent/Colors");
|
||||
coll.renameMode(coll.modes[0].modeId, "mode1");
|
||||
const mode2Id = coll.addMode("mode2");
|
||||
|
||||
// Create variables from data map
|
||||
const colorData = { "bg/default": ["#0B6BCB", "#636B74"], /* ... */ };
|
||||
const modeOrder = ["mode1", "mode2"];
|
||||
const modeIds = { mode1: coll.modes[0].modeId, mode2: mode2Id };
|
||||
const varIds = {};
|
||||
|
||||
for (const [name, values] of Object.entries(colorData)) {
|
||||
const v = figma.variables.createVariable(name, coll, "COLOR");
|
||||
values.forEach((hex_val, i) => {
|
||||
v.setValueForMode(modeIds[modeOrder[i]], hex_val ? hex(hex_val) : { r:0, g:0, b:0, a:0 });
|
||||
});
|
||||
varIds[name] = v.id;
|
||||
}
|
||||
|
||||
// Return ALL IDs — needed by subsequent calls
|
||||
return { collId: coll.id, modeIds, varIds };
|
||||
```
|
||||
|
||||
**Call 2: Create components using stored IDs, combine and layout**
|
||||
|
||||
```js
|
||||
await figma.loadFontAsync({ family: "Inter", style: "Semi Bold" });
|
||||
|
||||
// Paste IDs from Call 1 as literals
|
||||
const collId = "VariableCollectionId:X:Y";
|
||||
const modeIds = { mode1: "X:0", mode2: "X:1" };
|
||||
const varIds = { /* ... from Call 1 ... */ };
|
||||
|
||||
const getVar = async (id) => await figma.variables.getVariableByIdAsync(id);
|
||||
const bindColor = async (varId) => figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', await getVar(varId)
|
||||
);
|
||||
const collection = await figma.variables.getVariableCollectionByIdAsync(collId);
|
||||
|
||||
const components = [];
|
||||
for (const mode of ["mode1", "mode2"]) {
|
||||
for (const state of ["default", "hover"]) {
|
||||
const comp = figma.createComponent();
|
||||
comp.name = `mode=${mode}, state=${state}`;
|
||||
comp.layoutMode = 'HORIZONTAL';
|
||||
comp.primaryAxisAlignItems = 'CENTER';
|
||||
comp.counterAxisAlignItems = 'CENTER';
|
||||
comp.layoutSizingHorizontal = 'HUG';
|
||||
comp.layoutSizingVertical = 'HUG';
|
||||
comp.fills = [await bindColor(varIds[`bg/${state}`])];
|
||||
comp.setExplicitVariableModeForCollection(collection, modeIds[mode]);
|
||||
// ... add text children ...
|
||||
components.push(comp);
|
||||
}
|
||||
}
|
||||
|
||||
// Combine — all children stack at (0,0)!
|
||||
const cs = figma.combineAsVariants(components, figma.currentPage);
|
||||
cs.name = "MyComponent";
|
||||
|
||||
// CRITICAL: layout variants in a structured grid mapped to variant axes.
|
||||
const stateOrder = ["default", "hover"];
|
||||
const modeOrder2 = ["mode1", "mode2"];
|
||||
const colW = 140, rowH = 56;
|
||||
|
||||
for (const child of cs.children) {
|
||||
const props = Object.fromEntries(
|
||||
child.name.split(', ').map(p => p.split('='))
|
||||
);
|
||||
const col = stateOrder.indexOf(props.state);
|
||||
const row = modeOrder2.indexOf(props.mode);
|
||||
child.x = col * colW;
|
||||
child.y = row * rowH;
|
||||
}
|
||||
// Resize from actual child bounds
|
||||
let maxX = 0, maxY = 0;
|
||||
for (const child of cs.children) {
|
||||
maxX = Math.max(maxX, child.x + child.width);
|
||||
maxY = Math.max(maxY, child.y + child.height);
|
||||
}
|
||||
cs.resizeWithoutConstraints(maxX + 40, maxY + 40);
|
||||
|
||||
// Wrap in section
|
||||
const section = figma.createSection();
|
||||
section.name = "MyComponent Section";
|
||||
section.appendChild(cs);
|
||||
section.resizeWithoutConstraints(cs.width + 200, cs.height + 200);
|
||||
|
||||
return { csId: cs.id, count: components.length };
|
||||
```
|
||||
|
||||
## Read Existing Nodes and Return Data
|
||||
|
||||
```js
|
||||
const page = figma.currentPage
|
||||
const nodes = page.findAll(n => n.type === 'FRAME')
|
||||
const data = nodes.map(n => ({
|
||||
id: n.id,
|
||||
name: n.name,
|
||||
width: n.width,
|
||||
height: n.height,
|
||||
childCount: n.children?.length || 0
|
||||
}))
|
||||
return { frames: data }
|
||||
```
|
||||
@@ -0,0 +1,472 @@
|
||||
# Component & Variant API Patterns
|
||||
|
||||
> Part of the [use_figma skill](../SKILL.md). How to correctly use the Plugin API for components, variants, and component properties.
|
||||
>
|
||||
> For design system context (when to use variants vs properties, code-to-Figma translation, property model), see [wwds-components](working-with-design-systems/wwds-components.md).
|
||||
|
||||
## Contents
|
||||
|
||||
- Creating a Component
|
||||
- Combining Components into a Component Set (Variants)
|
||||
- Laying Out Variants After combineAsVariants (Required)
|
||||
- Component Properties: addComponentProperty API
|
||||
- Linking Properties to Child Nodes (Required)
|
||||
- INSTANCE_SWAP: Avoiding Variant Explosion
|
||||
- Discovering Existing Conventions in the File
|
||||
- Importing Components by Key
|
||||
- Working with Instances (finding variants, setProperties, text overrides, detachInstance)
|
||||
|
||||
|
||||
## Creating a Component
|
||||
|
||||
`figma.createComponent()` returns a `ComponentNode`, which behaves like a `FrameNode` but can be published, instanced, and combined into variant sets.
|
||||
|
||||
```javascript
|
||||
const comp = figma.createComponent();
|
||||
comp.name = "MyComponent";
|
||||
comp.layoutMode = "HORIZONTAL";
|
||||
comp.primaryAxisAlignItems = "CENTER";
|
||||
comp.counterAxisAlignItems = "CENTER";
|
||||
comp.paddingLeft = 12;
|
||||
comp.paddingRight = 12;
|
||||
comp.layoutSizingHorizontal = "HUG";
|
||||
comp.layoutSizingVertical = "HUG";
|
||||
comp.fills = [{ type: "SOLID", color: { r: 0.2, g: 0.36, b: 0.96 } }];
|
||||
```
|
||||
|
||||
## Combining Components into a Component Set (Variants)
|
||||
|
||||
`figma.combineAsVariants(components, parent)` takes an array of `ComponentNode`s (not frames — frames will throw) and groups them into a `ComponentSetNode`.
|
||||
|
||||
Variant names use a `Property=Value` format. Every unique combination must exist as a child component — missing ones show as blank gaps in the variant picker.
|
||||
|
||||
```javascript
|
||||
// Each component's name encodes its variant properties
|
||||
const comp1 = figma.createComponent();
|
||||
comp1.name = "size=md, style=primary";
|
||||
const comp2 = figma.createComponent();
|
||||
comp2.name = "size=md, style=secondary";
|
||||
|
||||
const componentSet = figma.combineAsVariants([comp1, comp2], figma.currentPage);
|
||||
componentSet.name = "Button";
|
||||
```
|
||||
|
||||
**Before creating variants, inspect the file** for existing naming patterns. Different files use different conventions (`State=Default` vs `state=default` vs `State/Default`). Always match what's already there.
|
||||
|
||||
## Laying Out Variants After combineAsVariants (Required)
|
||||
|
||||
After `combineAsVariants`, all children stack at `(0, 0)`. You **must** position them or the component set will appear as a single collapsed element with all variants overlapping.
|
||||
|
||||
```javascript
|
||||
const cs = figma.combineAsVariants(components, figma.currentPage);
|
||||
|
||||
// Simple row layout
|
||||
cs.children.forEach((child, i) => {
|
||||
child.x = i * 150;
|
||||
child.y = 0;
|
||||
});
|
||||
|
||||
// CRITICAL: resize the component set from actual child bounds
|
||||
let maxX = 0, maxY = 0;
|
||||
for (const child of cs.children) {
|
||||
maxX = Math.max(maxX, child.x + child.width);
|
||||
maxY = Math.max(maxY, child.y + child.height);
|
||||
}
|
||||
cs.resizeWithoutConstraints(maxX + 40, maxY + 40);
|
||||
```
|
||||
|
||||
For multi-axis variants (e.g., size × style × state), parse the child's name to determine grid position:
|
||||
|
||||
```javascript
|
||||
for (const child of cs.children) {
|
||||
const props = Object.fromEntries(
|
||||
child.name.split(', ').map(p => p.split('='))
|
||||
);
|
||||
const col = stateValues.indexOf(props.state);
|
||||
const row = styleValues.indexOf(props.style);
|
||||
child.x = col * colWidth;
|
||||
child.y = row * rowHeight;
|
||||
}
|
||||
```
|
||||
|
||||
## Component Properties: addComponentProperty API
|
||||
|
||||
`addComponentProperty` adds a TEXT, BOOLEAN, or INSTANCE_SWAP property to a component. It returns a **string key** (e.g., `"label#4:0"`) — never hardcode or guess this key.
|
||||
|
||||
```javascript
|
||||
// Returns the key as a string — capture it!
|
||||
const labelKey = comp.addComponentProperty('Label', 'TEXT', 'Default text');
|
||||
const showIconKey = comp.addComponentProperty('Show Icon', 'BOOLEAN', true);
|
||||
const iconSlotKey = comp.addComponentProperty('Icon', 'INSTANCE_SWAP', iconComponentId);
|
||||
```
|
||||
|
||||
**Timing**: Add component properties to each variant component **before** calling `combineAsVariants`. After combining, the component set inherits all properties from its children. Do not add properties to the `ComponentSetNode` directly.
|
||||
|
||||
## Linking Properties to Child Nodes (Required)
|
||||
|
||||
A property that is added but not linked to a child node does **nothing**. You must set `componentPropertyReferences` on the child:
|
||||
|
||||
```javascript
|
||||
// TEXT property → link to a text node's characters
|
||||
const labelKey = comp.addComponentProperty('Label', 'TEXT', 'Button');
|
||||
const textNode = figma.createText();
|
||||
textNode.characters = "Button";
|
||||
comp.appendChild(textNode);
|
||||
textNode.componentPropertyReferences = { characters: labelKey };
|
||||
|
||||
// BOOLEAN + INSTANCE_SWAP → link to an instance node
|
||||
const showIconKey = comp.addComponentProperty('Show Icon', 'BOOLEAN', true);
|
||||
const iconSlotKey = comp.addComponentProperty('Icon', 'INSTANCE_SWAP', iconComp.id);
|
||||
const iconInstance = iconComp.createInstance();
|
||||
comp.appendChild(iconInstance);
|
||||
iconInstance.componentPropertyReferences = {
|
||||
visible: showIconKey, // BOOLEAN controls show/hide
|
||||
mainComponent: iconSlotKey // INSTANCE_SWAP controls which component
|
||||
};
|
||||
```
|
||||
|
||||
**Valid `componentPropertyReferences` keys:**
|
||||
- `characters` — TEXT property on a TextNode
|
||||
- `visible` — BOOLEAN property (any node)
|
||||
- `mainComponent` — INSTANCE_SWAP property on an InstanceNode
|
||||
|
||||
## INSTANCE_SWAP: Avoiding Variant Explosion
|
||||
|
||||
When a component has many possible sub-elements (e.g., 30 different icons), **never** create a variant per sub-element. Use a single INSTANCE_SWAP property instead — the user picks from any compatible component at design time.
|
||||
|
||||
```javascript
|
||||
// Create icon as its own ComponentNode
|
||||
const iconComp = figma.createComponent();
|
||||
iconComp.name = "Icon/Search";
|
||||
iconComp.resize(24, 24);
|
||||
const svgNode = figma.createNodeFromSvg('<svg>...</svg>');
|
||||
iconComp.appendChild(svgNode);
|
||||
|
||||
// Use it as the default for INSTANCE_SWAP
|
||||
const iconSlotKey = comp.addComponentProperty('Icon', 'INSTANCE_SWAP', iconComp.id);
|
||||
const instance = iconComp.createInstance();
|
||||
comp.appendChild(instance);
|
||||
instance.componentPropertyReferences = { mainComponent: iconSlotKey };
|
||||
```
|
||||
|
||||
This works for icons, avatars, badges, or any swappable nested element.
|
||||
|
||||
## Discovering Existing Conventions in the File
|
||||
|
||||
**Always inspect the file before creating components.** Different files have different naming styles, structures, and conventions. Your code should match what's already there.
|
||||
|
||||
### List all existing components across all pages
|
||||
|
||||
```javascript
|
||||
const results = [];
|
||||
for (const page of figma.root.children) {
|
||||
await figma.setCurrentPageAsync(page);
|
||||
page.findAll(n => {
|
||||
if (n.type === 'COMPONENT') results.push(`[${page.name}] ${n.name} (COMPONENT) id=${n.id}`);
|
||||
if (n.type === 'COMPONENT_SET') results.push(`[${page.name}] ${n.name} (COMPONENT_SET) id=${n.id}`);
|
||||
return false;
|
||||
});
|
||||
}
|
||||
return results.join('\n');
|
||||
```
|
||||
|
||||
### Inspect an existing component set's variant naming pattern
|
||||
|
||||
```javascript
|
||||
const cs = await figma.getNodeByIdAsync('COMPONENT_SET_ID');
|
||||
const variantNames = cs.children.map(c => c.name);
|
||||
const propDefs = cs.componentPropertyDefinitions;
|
||||
return { variantNames, propDefs };
|
||||
```
|
||||
|
||||
### Find existing components in the file
|
||||
|
||||
```javascript
|
||||
const components = [];
|
||||
for (const page of figma.root.children) {
|
||||
await figma.setCurrentPageAsync(page);
|
||||
page.findAll(n => {
|
||||
if (n.type === 'COMPONENT') {
|
||||
components.push({ name: n.name, id: n.id, page: page.name, w: n.width, h: n.height });
|
||||
}
|
||||
return false;
|
||||
});
|
||||
}
|
||||
return components;
|
||||
```
|
||||
|
||||
## Importing Components by Key (Team Libraries)
|
||||
|
||||
`importComponentByKeyAsync` and `importComponentSetByKeyAsync` import components from **team libraries** (not the same file you're working in). For components in the current file, use `figma.getNodeByIdAsync()` or `findOne()`/`findAll()` to locate them directly.
|
||||
|
||||
```javascript
|
||||
// Import a component from a team library
|
||||
const comp = await figma.importComponentByKeyAsync("COMPONENT_KEY");
|
||||
const instance = comp.createInstance();
|
||||
|
||||
// Import a component set from a team library and pick a variant
|
||||
const set = await figma.importComponentSetByKeyAsync("COMPONENT_SET_KEY");
|
||||
const variant = set.children.find(c =>
|
||||
c.type === "COMPONENT" && c.name.includes("size=md")
|
||||
) || set.defaultVariant;
|
||||
const variantInstance = variant.createInstance();
|
||||
```
|
||||
|
||||
## Working with Instances
|
||||
|
||||
### Finding the right variant in a component set
|
||||
|
||||
Parse variant names to match on multiple properties simultaneously:
|
||||
|
||||
```javascript
|
||||
const compSet = await figma.importComponentSetByKeyAsync("KEY");
|
||||
|
||||
const variant = compSet.children.find(c => {
|
||||
const props = Object.fromEntries(
|
||||
c.name.split(', ').map(p => p.split('='))
|
||||
);
|
||||
return props.variant === "primary" && props.size === "md";
|
||||
}) || compSet.defaultVariant;
|
||||
|
||||
const instance = variant.createInstance();
|
||||
```
|
||||
|
||||
### Setting variant properties on an instance
|
||||
|
||||
After creating an instance from a component set, you can set variant properties via `setProperties`:
|
||||
|
||||
```javascript
|
||||
const instance = defaultVariant.createInstance();
|
||||
instance.setProperties({
|
||||
"variant": "primary",
|
||||
"size": "medium"
|
||||
});
|
||||
```
|
||||
|
||||
### Overriding text in a component instance
|
||||
|
||||
**Always discover component properties BEFORE writing text overrides.** Components expose text as `TEXT`-type component properties, and `setProperties()` is the correct way to override them. Direct `node.characters` changes on property-managed text may be overridden by the component property system on render.
|
||||
|
||||
**Step 1: Inspect componentProperties on a sample instance:**
|
||||
|
||||
```javascript
|
||||
const instance = comp.createInstance();
|
||||
const propDefs = instance.componentProperties;
|
||||
// Returns e.g.: { "Label#2:0": { type: "TEXT", value: "Button" }, "Has Icon#4:64": { type: "BOOLEAN", value: true } }
|
||||
return propDefs;
|
||||
```
|
||||
|
||||
Also check nested instances — a parent component may not expose text properties directly, but its nested child instances might:
|
||||
|
||||
```javascript
|
||||
const nestedInstances = instance.findAll(n => n.type === "INSTANCE");
|
||||
const nestedProps = nestedInstances.map(ni => ({
|
||||
name: ni.name,
|
||||
id: ni.id,
|
||||
properties: ni.componentProperties
|
||||
}));
|
||||
```
|
||||
|
||||
**Step 2: Use setProperties() for TEXT-type properties:**
|
||||
|
||||
```javascript
|
||||
const instance = comp.createInstance();
|
||||
const propDefs = instance.componentProperties;
|
||||
for (const [key, def] of Object.entries(propDefs)) {
|
||||
if (def.type === "TEXT") {
|
||||
instance.setProperties({ [key]: "New text value" });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For nested instances that expose their own TEXT properties, call `setProperties()` on the nested instance:
|
||||
|
||||
```javascript
|
||||
const nestedHeading = instance.findOne(n => n.type === "INSTANCE" && n.name === "Text Heading");
|
||||
if (nestedHeading) {
|
||||
nestedHeading.setProperties({ "Text#2104:5": "Actual heading text" });
|
||||
}
|
||||
```
|
||||
|
||||
**Step 3: Only fall back to direct node.characters for unmanaged text.** If text is NOT controlled by any component property, find text nodes directly. **Always load the node's actual font first** — instance text nodes inherit fonts from the source component, so don't assume Inter Regular:
|
||||
|
||||
```javascript
|
||||
const textNodes = instance.findAll(n => n.type === "TEXT");
|
||||
for (const t of textNodes) {
|
||||
await figma.loadFontAsync(t.fontName);
|
||||
t.characters = "Updated text";
|
||||
}
|
||||
```
|
||||
|
||||
### detachInstance() invalidates ancestor node IDs
|
||||
|
||||
**Warning:** When `detachInstance()` is called on a nested instance inside a library component instance, the parent instance may also get implicitly detached (converted from INSTANCE to FRAME with a **new ID**). Subsequent `getNodeByIdAsync(oldParentId)` returns null.
|
||||
|
||||
```javascript
|
||||
// WRONG — cached parent ID becomes invalid after child detach
|
||||
const parentId = parentInstance.id;
|
||||
nestedChild.detachInstance();
|
||||
const parent = await figma.getNodeByIdAsync(parentId); // null!
|
||||
|
||||
// CORRECT — re-discover nodes by traversal from a stable (non-instance) parent
|
||||
const stableFrame = await figma.getNodeByIdAsync(manualFrameId); // a frame YOU created
|
||||
nestedChild.detachInstance();
|
||||
// Re-find the parent by traversing from the stable frame
|
||||
const parent = stableFrame.findOne(n => n.name === "ParentName");
|
||||
```
|
||||
|
||||
If you must detach multiple nested instances across sibling components, do it in a **single** `use_figma` call — discover all targets by traversal at the start before any detachment mutates the tree.
|
||||
|
||||
## Inspecting Component Metadata (Deep Traversal)
|
||||
|
||||
These helpers extract the full property schema and descendant structure of a component. Useful for understanding complex components before creating instances or setting properties.
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Imports a component or component set from a library by its published key.
|
||||
* Tries COMPONENT first, then falls back to COMPONENT_SET.
|
||||
*
|
||||
* @param {string} componentKey - The published key of the component or component set.
|
||||
* @returns {Promise<ComponentNode|ComponentSetNode>}
|
||||
*/
|
||||
async function importComponentByKey(componentKey) {
|
||||
try {
|
||||
return await figma.importComponentByKeyAsync(componentKey);
|
||||
} catch {
|
||||
try {
|
||||
return await figma.importComponentSetByKeyAsync(componentKey);
|
||||
} catch {
|
||||
throw new Error(`No Component or Component Set available with key '${componentKey}'`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Given a main component node, returns the component set parent if one exists,
|
||||
* otherwise returns the component itself. Used to get the top-level node that
|
||||
* holds `componentPropertyDefinitions`.
|
||||
*
|
||||
* @param {ComponentNode} mainComponent
|
||||
* @returns {ComponentNode|ComponentSetNode}
|
||||
*/
|
||||
function getRelevantComponentNode(mainComponent) {
|
||||
return mainComponent.parent.type === "COMPONENT_SET"
|
||||
? mainComponent.parent
|
||||
: mainComponent;
|
||||
}
|
||||
|
||||
/**
|
||||
* Extracts `componentPropertyDefinitions` from a component or component set node
|
||||
* into a flat map keyed by property key.
|
||||
*
|
||||
* @param {ComponentNode|ComponentSetNode} node
|
||||
* @returns {Record<string, {name: string, type: string, key: string, variantOptions?: string[]}>}
|
||||
*/
|
||||
function getComponentProps(node) {
|
||||
const result = {};
|
||||
for (let key in node.componentPropertyDefinitions) {
|
||||
const prop = {
|
||||
name: key.replace(/#[^#]+$/, ""),
|
||||
type: node.componentPropertyDefinitions[key].type,
|
||||
key: key
|
||||
};
|
||||
if (prop.type === "VARIANT") {
|
||||
prop.variantOptions = node.componentPropertyDefinitions[key].variantOptions;
|
||||
}
|
||||
result[key] = prop;
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Recursively walks a component tree and collects all INSTANCE and TEXT nodes
|
||||
* into `result`, keyed by `TYPE[name]`. Handles variant namespacing and
|
||||
* deduplicates nodes with identical names but differing property references.
|
||||
*
|
||||
* @param {SceneNode} node - The node to traverse.
|
||||
* @param {string[]} namespace - Accumulated variant names for the current path.
|
||||
* @param {Record<string, object>} result - Accumulator object populated in place.
|
||||
*/
|
||||
function collectDescendants(node, namespace, result) {
|
||||
if (node.type === "INSTANCE" || node.type === "TEXT") {
|
||||
const references = node.componentPropertyReferences || {};
|
||||
if (!node.visible && !references.visible) return;
|
||||
|
||||
const object = { type: node.type, name: node.name, references };
|
||||
let key = `${node.type}[${node.name}]`;
|
||||
|
||||
if (result[key] && JSON.stringify(references) !== JSON.stringify(result[key].references)) {
|
||||
key += btoa(btoa(unescape(encodeURIComponent(JSON.stringify(references)))));
|
||||
}
|
||||
|
||||
if (node.type === "INSTANCE") {
|
||||
const mainComponent = getRelevantComponentNode(node.mainComponent);
|
||||
object.properties = getComponentProps(mainComponent);
|
||||
object.descendants = {};
|
||||
object.mainComponentName = mainComponent.name;
|
||||
collectDescendants(mainComponent, [], object.descendants);
|
||||
}
|
||||
|
||||
const start = namespace.length ? { variants: [] } : {};
|
||||
result[key] = Object.assign(object, result[key] || start);
|
||||
if (namespace.length) result[key].variants.push(namespace[namespace.length - 1]);
|
||||
} else if ("children" in node && node.visible) {
|
||||
if (node.type === "COMPONENT" && node.parent.type === "COMPONENT_SET") namespace.push(node.name);
|
||||
node.children.forEach(child => collectDescendants(child, namespace, result));
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns structured metadata for a component or component set defined in the current file.
|
||||
*
|
||||
* @param {string} componentId - The node ID of a COMPONENT or COMPONENT_SET node.
|
||||
* @returns {Promise<{name: string, nodeId: string, properties: object, descendants: object}|undefined>}
|
||||
*/
|
||||
async function getLocalComponentMetadata(componentId) {
|
||||
const node = await figma.getNodeByIdAsync(componentId);
|
||||
if (node.type === "COMPONENT_SET" || node.type === "COMPONENT") {
|
||||
const result = {
|
||||
name: node.name,
|
||||
nodeId: node.id,
|
||||
properties: {},
|
||||
descendants: {}
|
||||
};
|
||||
result.properties = getComponentProps(node);
|
||||
collectDescendants(node, [], result.descendants);
|
||||
return result;
|
||||
} else {
|
||||
throw new Error("Node is not a Component or Component Set");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns structured metadata for a published component or component set loaded by its key.
|
||||
*
|
||||
* @param {string} componentKey - The published key of the component or component set.
|
||||
* @returns {Promise<{name: string, nodeId: string, properties: object, descendants: object}>}
|
||||
*/
|
||||
async function getPublishedComponentMetadata(componentKey) {
|
||||
const node = await importComponentByKey(componentKey);
|
||||
const result = {
|
||||
name: node.name,
|
||||
nodeId: node.id,
|
||||
properties: {},
|
||||
descendants: {}
|
||||
};
|
||||
result.properties = getComponentProps(node);
|
||||
collectDescendants(node, [], result.descendants);
|
||||
return result;
|
||||
}
|
||||
```
|
||||
|
||||
### Full metadata extraction script
|
||||
|
||||
```javascript
|
||||
// For local components, use getLocalComponentMetadata:
|
||||
const result = await getLocalComponentMetadata('COMPONENT_OR_SET_ID');
|
||||
return result;
|
||||
|
||||
// For published components, use getPublishedComponentMetadata:
|
||||
// const result = await getPublishedComponentMetadata('COMPONENT_KEY');
|
||||
// return result;
|
||||
```
|
||||
@@ -0,0 +1,125 @@
|
||||
# Effect Style API Patterns
|
||||
|
||||
> Part of the [use_figma skill](../SKILL.md). How to create, apply, and inspect effect styles using the Plugin API.
|
||||
>
|
||||
> For design system context (effect types, variable bindings on effects, gotchas), see [wwds-effect-styles](working-with-design-systems/wwds-effect-styles.md).
|
||||
|
||||
## Contents
|
||||
|
||||
- Listing Effect Styles
|
||||
- Creating a Drop Shadow Style
|
||||
- Importing Library Effect Styles
|
||||
- Applying Effect Styles to Nodes
|
||||
|
||||
## Listing Effect Styles
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Lists all local effect styles.
|
||||
*
|
||||
* @returns {Promise<Array<{id: string, name: string, key: string, effectCount: number}>>}
|
||||
*/
|
||||
async function listEffectStyles() {
|
||||
const styles = await figma.getLocalEffectStylesAsync();
|
||||
return styles.map(s => ({
|
||||
id: s.id,
|
||||
name: s.name,
|
||||
key: s.key,
|
||||
effectCount: s.effects.length
|
||||
}));
|
||||
}
|
||||
```
|
||||
|
||||
Full runnable script:
|
||||
|
||||
```javascript
|
||||
const results = await listEffectStyles();
|
||||
return results;
|
||||
```
|
||||
|
||||
## Creating a Drop Shadow Style
|
||||
|
||||
Colors are **RGBA 0–1 range**. `effects` is a read-only array — always reassign, never mutate in place.
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Creates a drop shadow effect style.
|
||||
*
|
||||
* @param {string} name - e.g. "Elevation/200"
|
||||
* @param {{ r: number, g: number, b: number, a: number }} color - RGBA, 0-1 range
|
||||
* @param {{ x: number, y: number }} offset
|
||||
* @param {number} radius - blur radius
|
||||
* @param {number} [spread=0]
|
||||
* @returns {EffectStyle}
|
||||
*/
|
||||
function createDropShadowStyle(name, color, offset, radius, spread) {
|
||||
const style = figma.createEffectStyle();
|
||||
style.name = name;
|
||||
style.effects = [{
|
||||
type: "DROP_SHADOW",
|
||||
color,
|
||||
offset,
|
||||
radius,
|
||||
spread: spread || 0,
|
||||
visible: true,
|
||||
blendMode: "NORMAL"
|
||||
}];
|
||||
return style;
|
||||
}
|
||||
```
|
||||
|
||||
Full runnable script:
|
||||
|
||||
```javascript
|
||||
const style = createDropShadowStyle(
|
||||
"Elevation/200",
|
||||
{ r: 0, g: 0, b: 0, a: 0.15 },
|
||||
{ x: 0, y: 4 },
|
||||
12,
|
||||
0
|
||||
);
|
||||
return { id: style.id, name: style.name };
|
||||
```
|
||||
|
||||
## Importing Library Effect Styles
|
||||
|
||||
For effect styles from **team libraries**, use `importStyleByKeyAsync`:
|
||||
|
||||
```javascript
|
||||
// Import a library effect style by key
|
||||
const shadowStyle = await figma.importStyleByKeyAsync("EFFECT_STYLE_KEY");
|
||||
// Apply to a node
|
||||
node.effectStyleId = shadowStyle.id;
|
||||
```
|
||||
|
||||
`search_design_system` with `includeStyles: true` returns style keys you can import this way. Prefer importing library styles over creating new ones.
|
||||
|
||||
## Applying Effect Styles to Nodes
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Applies an effect style to all nodes on the current page that match a given name pattern.
|
||||
*
|
||||
* @param {string} styleId - The ID of an EffectStyle.
|
||||
* @param {string} nodeNamePattern - Substring match against node names.
|
||||
* @returns {number} - Number of nodes the style was applied to.
|
||||
*/
|
||||
function applyEffectStyleToMatchingNodes(styleId, nodeNamePattern) {
|
||||
const nodes = figma.currentPage.findAll(n => n.name.includes(nodeNamePattern));
|
||||
let applied = 0;
|
||||
for (const node of nodes) {
|
||||
if ('effectStyleId' in node) {
|
||||
node.effectStyleId = styleId;
|
||||
applied++;
|
||||
}
|
||||
}
|
||||
return applied;
|
||||
}
|
||||
```
|
||||
|
||||
Full runnable script:
|
||||
|
||||
```javascript
|
||||
const applied = applyEffectStyleToMatchingNodes('STYLE_ID', 'Card');
|
||||
return { applied };
|
||||
```
|
||||
@@ -0,0 +1,622 @@
|
||||
# Gotchas & Common Mistakes
|
||||
|
||||
> Part of the [use_figma skill](../SKILL.md). Every known pitfall with WRONG/CORRECT code examples.
|
||||
|
||||
## Contents
|
||||
|
||||
- Component properties and variant creation pitfalls
|
||||
- Paint, color, and variable binding pitfalls
|
||||
- Page context and plugin lifecycle pitfalls
|
||||
- Auto Layout and sizing order pitfalls (including HUG/FILL interactions)
|
||||
- Variant layout and geometry pitfalls
|
||||
- Variable scopes and mode pitfalls
|
||||
- Node cleanup and empty-fill pitfalls
|
||||
- detachInstance() and node ID invalidation
|
||||
|
||||
|
||||
## New nodes default to (0,0) and overlap existing content
|
||||
|
||||
Every `figma.create*()` call places the node at position (0,0). If you append multiple nodes directly to the page, they all stack on top of each other and on top of any existing content.
|
||||
|
||||
**This only matters for nodes appended directly to the page** (i.e., top-level nodes). Nodes appended as children of other frames, components, or auto-layout containers are positioned by their parent — don't scan for overlaps when nesting nodes.
|
||||
|
||||
```js
|
||||
// WRONG — top-level node lands at (0,0), overlapping existing page content
|
||||
const frame = figma.createFrame()
|
||||
frame.name = "My New Frame"
|
||||
frame.resize(400, 300)
|
||||
figma.currentPage.appendChild(frame)
|
||||
|
||||
// CORRECT — find existing content bounds and place the new top-level node to the right
|
||||
const page = figma.currentPage
|
||||
let maxX = 0
|
||||
for (const child of page.children) {
|
||||
const right = child.x + child.width
|
||||
if (right > maxX) maxX = right
|
||||
}
|
||||
const frame = figma.createFrame()
|
||||
frame.name = "My New Frame"
|
||||
frame.resize(400, 300)
|
||||
figma.currentPage.appendChild(frame)
|
||||
frame.x = maxX + 100 // 100px gap from rightmost existing content
|
||||
frame.y = 0
|
||||
|
||||
// NOT NEEDED — child nodes inside a parent don't need overlap scanning
|
||||
const card = figma.createFrame()
|
||||
card.layoutMode = 'VERTICAL'
|
||||
const label = figma.createText()
|
||||
card.appendChild(label) // positioned by auto-layout, no x/y needed
|
||||
```
|
||||
|
||||
## `addComponentProperty` returns a string key, not an object — never hardcode or guess it
|
||||
|
||||
Figma generates the property key dynamically (e.g. `"label#4:0"`). The suffix is unpredictable. Always capture and use the return value directly.
|
||||
|
||||
```js
|
||||
// WRONG — guessing / hardcoding the key
|
||||
comp.addComponentProperty('label', 'TEXT', 'Button')
|
||||
labelNode.componentPropertyReferences = { characters: 'label#0:1' } // Error: key not found
|
||||
|
||||
// WRONG — treating the return value as an object
|
||||
const result = comp.addComponentProperty('Label', 'TEXT', 'Button')
|
||||
const propKey = Object.keys(result)[0] // BUG: returns '0' (first char index of string!)
|
||||
labelNode.componentPropertyReferences = { characters: propKey } // Error: property '0' not found
|
||||
|
||||
// CORRECT — the return value IS the key string, use it directly
|
||||
const propKey = comp.addComponentProperty('Label', 'TEXT', 'Button')
|
||||
// propKey === "label#4:0" (exact value varies; never assume it)
|
||||
labelNode.componentPropertyReferences = { characters: propKey }
|
||||
```
|
||||
|
||||
The same applies to `COMPONENT_SET` nodes — `addComponentProperty` always returns the property key as a string.
|
||||
|
||||
## MUST return ALL created/mutated node IDs
|
||||
|
||||
Every script that creates or mutates nodes on the canvas must track and return all affected node IDs in the return value. Without these IDs, subsequent calls cannot reference, validate, or clean up those nodes.
|
||||
|
||||
```js
|
||||
// WRONG — only returns the parent frame ID, loses track of children
|
||||
const frame = figma.createFrame()
|
||||
const rect = figma.createRectangle()
|
||||
const text = figma.createText()
|
||||
frame.appendChild(rect)
|
||||
frame.appendChild(text)
|
||||
return { nodeId: frame.id }
|
||||
|
||||
// CORRECT — returns all created node IDs in a structured response
|
||||
const frame = figma.createFrame()
|
||||
const rect = figma.createRectangle()
|
||||
const text = figma.createText()
|
||||
frame.appendChild(rect)
|
||||
frame.appendChild(text)
|
||||
return {
|
||||
createdNodeIds: [frame.id, rect.id, text.id],
|
||||
rootNodeId: frame.id
|
||||
}
|
||||
|
||||
// CORRECT — when mutating existing nodes, return those IDs too
|
||||
const nodes = figma.currentPage.findAll(n => n.name === 'Card')
|
||||
for (const n of nodes) {
|
||||
n.fills = [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 } }]
|
||||
}
|
||||
return {
|
||||
mutatedNodeIds: nodes.map(n => n.id),
|
||||
count: nodes.length
|
||||
}
|
||||
```
|
||||
|
||||
## Colors are 0–1 range
|
||||
|
||||
```js
|
||||
// WRONG — will throw validation error (ZeroToOne enforced)
|
||||
node.fills = [{ type: 'SOLID', color: { r: 255, g: 0, b: 0 } }]
|
||||
|
||||
// CORRECT
|
||||
node.fills = [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 } }]
|
||||
```
|
||||
|
||||
## Fills/strokes are immutable arrays
|
||||
|
||||
```js
|
||||
// WRONG — modifying in place does nothing
|
||||
node.fills[0].color = { r: 1, g: 0, b: 0 }
|
||||
|
||||
// CORRECT — clone, modify, reassign
|
||||
const fills = JSON.parse(JSON.stringify(node.fills))
|
||||
fills[0].color = { r: 1, g: 0, b: 0 }
|
||||
node.fills = fills
|
||||
```
|
||||
|
||||
## setBoundVariableForPaint returns a NEW paint
|
||||
|
||||
```js
|
||||
// WRONG — ignoring return value
|
||||
figma.variables.setBoundVariableForPaint(paint, "color", colorVar)
|
||||
node.fills = [paint] // paint is unchanged!
|
||||
|
||||
// CORRECT — capture the returned new paint
|
||||
const boundPaint = figma.variables.setBoundVariableForPaint(paint, "color", colorVar)
|
||||
node.fills = [boundPaint]
|
||||
```
|
||||
|
||||
## Variable collection starts with 1 mode
|
||||
|
||||
```js
|
||||
// A new collection already has one mode — rename it, don't try to add first
|
||||
const collection = figma.variables.createVariableCollection("Colors")
|
||||
// collection.modes = [{ modeId: "...", name: "Mode 1" }]
|
||||
collection.renameMode(collection.modes[0].modeId, "Light")
|
||||
const darkModeId = collection.addMode("Dark")
|
||||
```
|
||||
|
||||
## combineAsVariants requires ComponentNodes
|
||||
|
||||
```js
|
||||
// WRONG — passing frames
|
||||
const f1 = figma.createFrame()
|
||||
figma.combineAsVariants([f1], figma.currentPage) // Error!
|
||||
|
||||
// CORRECT — passing components
|
||||
const c1 = figma.createComponent()
|
||||
c1.name = "variant=primary, size=md"
|
||||
const c2 = figma.createComponent()
|
||||
c2.name = "variant=secondary, size=md"
|
||||
figma.combineAsVariants([c1, c2], figma.currentPage)
|
||||
```
|
||||
|
||||
## Page switching: sync setter throws
|
||||
|
||||
The sync setter `figma.currentPage = page` **throws an error** in `use_figma` runtimes (MCP, evals, assistant). Use `await figma.setCurrentPageAsync(page)` instead — it switches the page and loads its content.
|
||||
|
||||
```js
|
||||
// WRONG — throws "Setting figma.currentPage is not supported in this runtime"
|
||||
figma.currentPage = targetPage
|
||||
|
||||
// CORRECT — async method switches and loads content
|
||||
await figma.setCurrentPageAsync(targetPage)
|
||||
```
|
||||
|
||||
## `get_metadata` only sees one page — use `use_figma` to discover all pages
|
||||
|
||||
A Figma file can have multiple pages (canvas nodes). `get_metadata` operates on a single node/page — it cannot scan the entire document. To discover all pages and their top-level contents, use `use_figma`:
|
||||
|
||||
```js
|
||||
// WRONG — calling get_metadata with the file root or expecting it to list all pages
|
||||
// get_metadata only returns the subtree of the node you pass it
|
||||
|
||||
// CORRECT — use use_figma to list pages, then inspect each one
|
||||
const pages = figma.root.children.map(p => `${p.name} id=${p.id} children=${p.children.length}`);
|
||||
return pages.join('\n');
|
||||
```
|
||||
|
||||
Icons, variables, and components may live on pages other than the first. Always enumerate all pages before concluding that the file has no existing assets.
|
||||
|
||||
## Never use figma.notify()
|
||||
|
||||
```js
|
||||
// WRONG — throws "not implemented" error
|
||||
figma.notify("Done!")
|
||||
|
||||
// CORRECT — return a value to send data back to the agent
|
||||
return "Done!"
|
||||
```
|
||||
|
||||
## `getPluginData()` / `setPluginData()` are not supported
|
||||
|
||||
These APIs are not available in the `use_figma` runtime. Use `getSharedPluginData()` / `setSharedPluginData()` instead (these ARE supported), or track nodes by returning IDs.
|
||||
|
||||
```js
|
||||
// WRONG — not supported in use_figma
|
||||
node.setPluginData('my_key', 'my_value')
|
||||
const val = node.getPluginData('my_key')
|
||||
|
||||
// CORRECT — use shared plugin data (requires a namespace)
|
||||
node.setSharedPluginData('my_namespace', 'my_key', 'my_value')
|
||||
const val = node.getSharedPluginData('my_namespace', 'my_key')
|
||||
|
||||
// ALSO CORRECT — return node IDs and track them across calls
|
||||
const rect = figma.createRectangle()
|
||||
return { nodeId: rect.id }
|
||||
// Then pass nodeId as a string literal in the next use_figma call
|
||||
```
|
||||
|
||||
## Script must always return a value
|
||||
|
||||
```js
|
||||
// WRONG — no return, caller gets no useful response
|
||||
figma.createRectangle()
|
||||
|
||||
// CORRECT — return a result (objects are auto-serialized, errors are auto-captured)
|
||||
const rect = figma.createRectangle()
|
||||
return { nodeId: rect.id }
|
||||
```
|
||||
|
||||
## setBoundVariable for paint fields only works on SOLID paints
|
||||
|
||||
```js
|
||||
// Only SOLID paint type supports color variable binding
|
||||
// Gradient paints, image paints, etc. will throw
|
||||
const solidPaint = { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }
|
||||
const bound = figma.variables.setBoundVariableForPaint(solidPaint, "color", colorVar)
|
||||
```
|
||||
|
||||
## Explicit variable modes must be set per component
|
||||
|
||||
```js
|
||||
// WRONG — all variants render with the default (first) mode
|
||||
const colorCollection = figma.variables.createVariableCollection("Colors")
|
||||
// ... create variables and modes ...
|
||||
// Components all show the first mode's values by default!
|
||||
|
||||
// CORRECT — set explicit mode on each component to get variant-specific values
|
||||
component.setExplicitVariableModeForCollection(colorCollection, targetModeId)
|
||||
```
|
||||
|
||||
## `TextStyle.setBoundVariable` is not available in headless use_figma
|
||||
|
||||
`setBoundVariable` exists on `TextStyle` in the typed API but is **not available** when running scripts through `use_figma` (MCP, headless assistant mode). Calling it will throw `"not a function"`.
|
||||
|
||||
```js
|
||||
// WRONG — throws "not a function" in use_figma / headless
|
||||
const ts = figma.createTextStyle()
|
||||
ts.setBoundVariable("fontSize", fontSizeVar)
|
||||
|
||||
// CORRECT (headless) — set raw values; bind variables interactively in Figma later
|
||||
const ts = figma.createTextStyle()
|
||||
ts.fontSize = 24
|
||||
```
|
||||
|
||||
This only affects `TextStyle`. Variable binding on **nodes** (`node.setBoundVariable(...)`) and on **paint objects** (`figma.variables.setBoundVariableForPaint(...)`) still works in headless mode as expected.
|
||||
|
||||
If live variable binding on text styles is required, create the styles with raw values via `use_figma`, then bind variables interactively through the Figma Styles panel or a full interactive plugin.
|
||||
|
||||
## `lineHeight` and `letterSpacing` must be objects, not bare numbers
|
||||
|
||||
```js
|
||||
// WRONG — throws or silently does nothing
|
||||
style.lineHeight = 1.5
|
||||
style.lineHeight = 24
|
||||
style.letterSpacing = 0
|
||||
|
||||
// CORRECT
|
||||
style.lineHeight = { unit: "AUTO" } // auto/intrinsic
|
||||
style.lineHeight = { value: 24, unit: "PIXELS" } // fixed pixel height
|
||||
style.lineHeight = { value: 150, unit: "PERCENT" } // percentage of font size
|
||||
|
||||
style.letterSpacing = { value: 0, unit: "PIXELS" } // no tracking
|
||||
style.letterSpacing = { value: -0.5, unit: "PIXELS" } // tight
|
||||
style.letterSpacing = { value: 5, unit: "PERCENT" } // percent-based
|
||||
```
|
||||
|
||||
This applies to both `TextStyle` and `TextNode` properties. The same rule applies inside `use_figma`, interactive plugins, and any other plugin API context.
|
||||
|
||||
## Font style names are file-dependent — probe before assuming
|
||||
|
||||
Font style names vary per provider and per Figma file. `"SemiBold"` and `"Semi Bold"` are different strings. Loading a font with the wrong style string **throws silently or errors** — there is no canonical list.
|
||||
|
||||
```js
|
||||
// WRONG — guessing style names
|
||||
await figma.loadFontAsync({ family: "Inter", style: "SemiBold" }) // may throw
|
||||
|
||||
// CORRECT — probe which style names are available
|
||||
const candidates = ["SemiBold", "Semi Bold", "Semibold"]
|
||||
for (const style of candidates) {
|
||||
try {
|
||||
await figma.loadFontAsync({ family: "Inter", style })
|
||||
// capture the one that works
|
||||
break
|
||||
} catch (_) {}
|
||||
}
|
||||
```
|
||||
|
||||
When building a type ramp script, always verify font styles against the target file before hardcoding them.
|
||||
|
||||
## combineAsVariants does NOT auto-layout in headless mode
|
||||
|
||||
```js
|
||||
// WRONG — all variants stack at position (0, 0), resulting in a tiny ComponentSet
|
||||
const components = [comp1, comp2, comp3]
|
||||
const cs = figma.combineAsVariants(components, figma.currentPage)
|
||||
// cs.width/height will be the size of a SINGLE variant!
|
||||
|
||||
// CORRECT — manually layout children in a grid after combining
|
||||
const cs = figma.combineAsVariants(components, figma.currentPage)
|
||||
const colWidth = 120
|
||||
const rowHeight = 56
|
||||
cs.children.forEach((child, i) => {
|
||||
const col = i % numCols
|
||||
const row = Math.floor(i / numCols)
|
||||
child.x = col * colWidth
|
||||
child.y = row * rowHeight
|
||||
})
|
||||
// CRITICAL: resize from actual child bounds, not formula — formula errors leave variants outside the boundary
|
||||
let maxX = 0, maxY = 0
|
||||
for (const child of cs.children) {
|
||||
maxX = Math.max(maxX, child.x + child.width)
|
||||
maxY = Math.max(maxY, child.y + child.height)
|
||||
}
|
||||
cs.resizeWithoutConstraints(maxX + 40, maxY + 40)
|
||||
```
|
||||
|
||||
## COLOR variable values use {r, g, b, a} (with alpha)
|
||||
|
||||
```js
|
||||
// Paint colors use {r, g, b} (no alpha — opacity is a separate paint property)
|
||||
node.fills = [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 } }]
|
||||
|
||||
// But COLOR variable values use {r, g, b, a} — alpha maps to paint opacity
|
||||
const colorVar = figma.variables.createVariable("bg", collection, "COLOR")
|
||||
colorVar.setValueForMode(modeId, { r: 1, g: 0, b: 0, a: 1 }) // opaque red
|
||||
colorVar.setValueForMode(modeId, { r: 0, g: 0, b: 0, a: 0 }) // fully transparent
|
||||
|
||||
// ⚠️ Don't confuse: {r, g, b} for paint colors vs {r, g, b, a} for variable values
|
||||
```
|
||||
|
||||
## `layoutSizingVertical`/`layoutSizingHorizontal` = `'FILL'` requires auto-layout parent FIRST
|
||||
|
||||
```js
|
||||
// WRONG — setting FILL before the node is a child of an auto-layout frame
|
||||
const child = figma.createFrame()
|
||||
child.layoutSizingVertical = 'FILL' // ERROR: "FILL can only be set on children of auto-layout frames"
|
||||
parent.appendChild(child)
|
||||
|
||||
// CORRECT — append to auto-layout parent FIRST, then set FILL
|
||||
const child = figma.createFrame()
|
||||
parent.appendChild(child) // parent must have layoutMode set
|
||||
child.layoutSizingVertical = 'FILL' // Works!
|
||||
```
|
||||
|
||||
## HUG parents collapse FILL children
|
||||
|
||||
A `HUG` parent cannot give `FILL` children meaningful size. If children have `layoutSizingHorizontal = "FILL"` but the parent is `"HUG"`, the children collapse to minimum size. The parent must be `"FILL"` or `"FIXED"` for FILL children to expand. This is a common cause of truncated text in select fields, inputs, and action rows.
|
||||
|
||||
```js
|
||||
// WRONG — parent hugs, so FILL children get zero extra space
|
||||
const parent = figma.createFrame()
|
||||
parent.layoutMode = 'HORIZONTAL'
|
||||
parent.layoutSizingHorizontal = 'HUG'
|
||||
const child = figma.createFrame()
|
||||
parent.appendChild(child)
|
||||
child.layoutSizingHorizontal = 'FILL' // collapses to min size!
|
||||
|
||||
// CORRECT — parent must be FIXED or FILL for FILL children to expand
|
||||
const parent = figma.createFrame()
|
||||
parent.layoutMode = 'HORIZONTAL'
|
||||
parent.resize(400, 50)
|
||||
parent.layoutSizingHorizontal = 'FIXED' // or 'FILL' if inside another auto-layout
|
||||
const child = figma.createFrame()
|
||||
parent.appendChild(child)
|
||||
child.layoutSizingHorizontal = 'FILL' // expands to fill remaining 400px
|
||||
```
|
||||
|
||||
## `layoutGrow` with a hugging parent causes content compression
|
||||
|
||||
```js
|
||||
// WRONG — layoutGrow on a child when parent has primaryAxisSizingMode='AUTO' (hug)
|
||||
// causes the child to SHRINK below its natural size instead of expanding
|
||||
const parent = figma.createComponent()
|
||||
parent.layoutMode = 'VERTICAL'
|
||||
parent.primaryAxisSizingMode = 'AUTO' // hug contents
|
||||
const content = figma.createFrame()
|
||||
content.layoutMode = 'VERTICAL'
|
||||
content.primaryAxisSizingMode = 'AUTO'
|
||||
parent.appendChild(content)
|
||||
content.layoutGrow = 1 // BUG: content compresses, children hidden!
|
||||
|
||||
// CORRECT — only use layoutGrow when parent has FIXED sizing with extra space
|
||||
content.layoutGrow = 0 // let content take its natural size
|
||||
// OR: set parent to FIXED sizing first
|
||||
parent.primaryAxisSizingMode = 'FIXED'
|
||||
parent.resizeWithoutConstraints(300, 500)
|
||||
content.layoutGrow = 1 // NOW it correctly fills remaining space
|
||||
```
|
||||
|
||||
## `resize()` resets `primaryAxisSizingMode` and `counterAxisSizingMode` to FIXED
|
||||
|
||||
`resize(w, h)` silently resets **both** sizing modes to `FIXED`. If you call it after setting `HUG`, the frame locks to the exact pixel value you passed — even a throwaway like `1`.
|
||||
|
||||
```js
|
||||
// WRONG — resize() after setting sizing mode overwrites it back to FIXED
|
||||
const frame = figma.createComponent()
|
||||
frame.layoutMode = 'VERTICAL'
|
||||
frame.primaryAxisSizingMode = 'AUTO' // hug height
|
||||
frame.counterAxisSizingMode = 'FIXED'
|
||||
frame.resize(300, 10) // BUG: resets BOTH axes to 'FIXED'! Height stays at 10px forever.
|
||||
|
||||
// ESPECIALLY DANGEROUS — throwaway values when you only care about one axis
|
||||
const comp = figma.createComponent()
|
||||
comp.layoutMode = 'VERTICAL'
|
||||
comp.layoutSizingHorizontal = 'FIXED'
|
||||
comp.layoutSizingVertical = 'HUG'
|
||||
comp.resize(280, 1) // BUG: "I only want width=280" but this locks height to 1px!
|
||||
// HUG was reset to FIXED by resize(), frame is now permanently 280×1
|
||||
|
||||
// CORRECT — call resize() FIRST, then set sizing modes
|
||||
const frame = figma.createComponent()
|
||||
frame.layoutMode = 'VERTICAL'
|
||||
frame.resize(300, 40) // use a reasonable default, never 0 or 1
|
||||
frame.counterAxisSizingMode = 'FIXED' // keep width fixed at 300
|
||||
frame.primaryAxisSizingMode = 'AUTO' // NOW set height to hug — this sticks!
|
||||
// Or use the modern shorthand (equivalent):
|
||||
// frame.layoutSizingHorizontal = 'FIXED'
|
||||
// frame.layoutSizingVertical = 'HUG'
|
||||
```
|
||||
|
||||
**Rule of thumb**: Never pass a throwaway/garbage value (like `1` or `0`) to `resize()` for an axis you intend to be `HUG`. Either call `resize()` before setting sizing modes, or use a reasonable default that won't cause visual bugs if the mode reset goes unnoticed.
|
||||
|
||||
## Node positions don't auto-reset after reparenting
|
||||
|
||||
```js
|
||||
// WRONG — assuming positions reset when moving a node into a new parent
|
||||
const node = figma.createRectangle()
|
||||
node.x = 500; node.y = 500;
|
||||
figma.currentPage.appendChild(node)
|
||||
section.appendChild(node) // node still at (500, 500) relative to section!
|
||||
|
||||
// CORRECT — explicitly set x/y after ANY reparenting operation
|
||||
section.appendChild(node)
|
||||
node.x = 80; node.y = 80; // reset to desired position within section
|
||||
```
|
||||
|
||||
## Grid layout with mixed-width rows causes overlaps
|
||||
|
||||
```js
|
||||
// WRONG — using a single column offset for rows with different-width items
|
||||
// e.g. vertical cards (320px) and horizontal cards (500px) in a 2-row grid
|
||||
for (let i = 0; i < allCards.length; i++) {
|
||||
allCards[i].x = (i % 4) * 370 // 370 works for 320px cards but NOT 500px cards!
|
||||
}
|
||||
|
||||
// CORRECT — compute each row's spacing independently based on actual child widths
|
||||
const gap = 50
|
||||
let x = 0
|
||||
for (const card of horizontalCards) {
|
||||
card.x = x
|
||||
x += card.width + gap // use actual width, not a fixed column size
|
||||
}
|
||||
```
|
||||
|
||||
## Sections don't auto-resize to fit content
|
||||
|
||||
```js
|
||||
// WRONG — section stays at default size, content overflows
|
||||
const section = figma.createSection()
|
||||
section.name = "My Section"
|
||||
section.appendChild(someNode) // node may be outside section bounds
|
||||
|
||||
// CORRECT — explicitly resize after adding content
|
||||
const section = figma.createSection()
|
||||
section.name = "My Section"
|
||||
section.appendChild(someNode)
|
||||
section.resizeWithoutConstraints(
|
||||
Math.max(someNode.width + 100, 800),
|
||||
Math.max(someNode.height + 100, 600)
|
||||
)
|
||||
```
|
||||
|
||||
## `counterAxisAlignItems` does NOT support `'STRETCH'`
|
||||
|
||||
```js
|
||||
// WRONG — 'STRETCH' is not a valid enum value
|
||||
comp.counterAxisAlignItems = 'STRETCH'
|
||||
// Error: Invalid enum value. Expected 'MIN' | 'MAX' | 'CENTER' | 'BASELINE', received 'STRETCH'
|
||||
|
||||
// CORRECT — use 'MIN' on the parent, then set children to FILL on the cross axis
|
||||
comp.counterAxisAlignItems = 'MIN'
|
||||
comp.appendChild(child)
|
||||
// For vertical layout, stretch width:
|
||||
child.layoutSizingHorizontal = 'FILL'
|
||||
// For horizontal layout, stretch height:
|
||||
child.layoutSizingVertical = 'FILL'
|
||||
```
|
||||
|
||||
## Variable collection mode limits are plan-dependent
|
||||
|
||||
```js
|
||||
// Figma limits modes per collection based on the team/org plan:
|
||||
// Free: 1 mode only (no addMode)
|
||||
// Professional: up to 4 modes
|
||||
// Organization/Enterprise: up to 40+ modes
|
||||
//
|
||||
// WRONG — creating 20 modes on a Professional plan will fail silently or throw
|
||||
const coll = figma.variables.createVariableCollection("Variants")
|
||||
for (let i = 0; i < 20; i++) coll.addMode("mode" + i) // May fail!
|
||||
|
||||
// CORRECT — if you need many modes, split across multiple collections
|
||||
// E.g., instead of 1 collection with 20 modes (variant×color):
|
||||
// Collection A: 4 modes (variant: plain/outlined/soft/solid)
|
||||
// Collection B: 5 modes (color: neutral/primary/danger/success/warning)
|
||||
// Then use setExplicitVariableModeForCollection for BOTH on each component
|
||||
```
|
||||
|
||||
## Variables default to `ALL_SCOPES` — always set scopes explicitly
|
||||
|
||||
```js
|
||||
// WRONG — variable appears in every property picker (fills, text, strokes, spacing, etc.)
|
||||
const bgColor = figma.variables.createVariable("Background/Default", coll, "COLOR")
|
||||
// bgColor.scopes defaults to ["ALL_SCOPES"] — pollutes all dropdowns
|
||||
|
||||
// CORRECT — restrict to relevant property pickers
|
||||
const bgColor = figma.variables.createVariable("Background/Default", coll, "COLOR")
|
||||
bgColor.scopes = ["FRAME_FILL", "SHAPE_FILL"] // fill pickers only
|
||||
|
||||
const textColor = figma.variables.createVariable("Text/Default", coll, "COLOR")
|
||||
textColor.scopes = ["TEXT_FILL"] // text color picker only
|
||||
|
||||
const borderColor = figma.variables.createVariable("Border/Default", coll, "COLOR")
|
||||
borderColor.scopes = ["STROKE_COLOR"] // stroke picker only
|
||||
|
||||
const spacing = figma.variables.createVariable("Space/400", coll, "FLOAT")
|
||||
spacing.scopes = ["GAP"] // gap/spacing pickers only
|
||||
|
||||
// Hide primitives that are only referenced via aliases
|
||||
const primitive = figma.variables.createVariable("Brand/500", coll, "COLOR")
|
||||
primitive.scopes = [] // hidden from all pickers
|
||||
```
|
||||
|
||||
## Binding fills on nodes with empty fills
|
||||
|
||||
```js
|
||||
// WRONG — binding to a node with no fills does nothing
|
||||
const comp = figma.createComponent()
|
||||
comp.fills = [] // transparent
|
||||
// Can't bind a color variable to fills that don't exist
|
||||
|
||||
// CORRECT — add a placeholder SOLID fill, then bind the variable
|
||||
const comp = figma.createComponent()
|
||||
const basePaint = { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }
|
||||
const boundPaint = figma.variables.setBoundVariableForPaint(basePaint, "color", colorVar)
|
||||
comp.fills = [boundPaint]
|
||||
// The variable's resolved value (which may be transparent) will control the actual color
|
||||
```
|
||||
|
||||
## Mode names must be descriptive — never leave 'Mode 1'
|
||||
|
||||
Every new `VariableCollection` starts with one mode named `'Mode 1'`. Always rename it immediately. For single-mode collections use `'Default'`; for multi-mode collections use names from the source (e.g. `'Light'`/`'Dark'`, `'Desktop'`/`'Tablet'`/`'Mobile'`).
|
||||
|
||||
// WRONG — generic names give no semantic meaning
|
||||
const coll = figma.variables.createVariableCollection('Colors')
|
||||
// coll.modes[0].name === 'Mode 1' — left as-is
|
||||
const darkId = coll.addMode('Mode 2')
|
||||
|
||||
// CORRECT — rename immediately to match the source
|
||||
const coll = figma.variables.createVariableCollection('Colors')
|
||||
coll.renameMode(coll.modes[0].modeId, 'Light') // was 'Mode 1'
|
||||
const darkId = coll.addMode('Dark')
|
||||
|
||||
// For single-mode collections (primitives, spacing, etc.)
|
||||
const spacing = figma.variables.createVariableCollection('Spacing')
|
||||
spacing.renameMode(spacing.modes[0].modeId, 'Default') // was 'Mode 1'
|
||||
|
||||
## CSS variable names must not contain spaces
|
||||
|
||||
When constructing a `var(--name)` string from a Figma variable name, replace BOTH slashes AND spaces with hyphens and convert to lowercase.
|
||||
|
||||
// WRONG — only replacing slashes leaves spaces like 'var(--color-bg-brand secondary hover)'
|
||||
v.setVariableCodeSyntax('WEB', `var(--${figmaName.replace(/\//g, '-').toLowerCase()})`)
|
||||
|
||||
// CORRECT — replace all whitespace and slashes in one pass
|
||||
v.setVariableCodeSyntax('WEB', `var(--${figmaName.replace(/[\s\/]+/g, '-').toLowerCase()})`)
|
||||
|
||||
**Best practice**: Preserve the original CSS variable name from the source token file rather than deriving it from the Figma name.
|
||||
|
||||
// Preferred — use the source CSS name directly
|
||||
v.setVariableCodeSyntax('WEB', `var(${token.cssVar})`) // e.g. '--color-bg-brand-secondary-hover'
|
||||
|
||||
## `detachInstance()` invalidates ancestor node IDs
|
||||
|
||||
When `detachInstance()` is called on a nested instance inside a library component instance, the parent instance may also get implicitly detached (converted from INSTANCE to FRAME with a **new ID**). Any previously cached ID for the parent becomes invalid.
|
||||
|
||||
```js
|
||||
// WRONG — using cached parent ID after child detach
|
||||
const parentId = parentInstance.id;
|
||||
nestedChild.detachInstance();
|
||||
const parent = await figma.getNodeByIdAsync(parentId); // null! ID changed.
|
||||
|
||||
// CORRECT — re-discover by traversal from a stable (non-instance) frame
|
||||
const stableFrame = await figma.getNodeByIdAsync(manualFrameId);
|
||||
nestedChild.detachInstance();
|
||||
const parent = stableFrame.findOne(n => n.name === "ParentName");
|
||||
```
|
||||
|
||||
If detaching multiple nested instances across siblings, do it in a **single** `use_figma` call — discover all targets by traversal before any detachment mutates the tree.
|
||||
@@ -0,0 +1,516 @@
|
||||
# Plugin API Patterns
|
||||
|
||||
> Part of the [use_figma skill](../SKILL.md). Quick reference for common Figma Plugin API operations.
|
||||
|
||||
## Contents
|
||||
|
||||
- Execution Basics
|
||||
- Creating Nodes
|
||||
- Fills and Strokes
|
||||
- Auto Layout
|
||||
- Effects
|
||||
- Opacity and Blend Modes
|
||||
- Corner Radius and Clipping
|
||||
- Grouping and Organization
|
||||
- Components and Variants
|
||||
- Styles
|
||||
- Cloning, Finding Nodes, and Grids
|
||||
- Constraints and Viewport
|
||||
|
||||
|
||||
## Execution Basics
|
||||
|
||||
### Page Context
|
||||
|
||||
Page context resets between `use_figma` calls — `figma.currentPage` always starts on the first page. Use `await figma.setCurrentPageAsync(page)` at the start of each invocation to switch to the correct page.
|
||||
|
||||
```javascript
|
||||
const targetPage = figma.root.children.find(p => p.name === "My Page");
|
||||
await figma.setCurrentPageAsync(targetPage);
|
||||
// targetPage.children is now populated
|
||||
```
|
||||
|
||||
### Returning Results
|
||||
|
||||
Scripts are automatically wrapped in an async IIFE with error handling. Just write plain JS and use `return` to send data back to the agent:
|
||||
|
||||
```javascript
|
||||
// Return an object — auto-serialized to JSON
|
||||
return { nodeId: frame.id, count: 5 }
|
||||
|
||||
// Return a string
|
||||
return "Created 3 components"
|
||||
```
|
||||
|
||||
Errors are automatically captured — no try/catch needed. `figma.notify()` does **not** exist. Return all information via the `return` value.
|
||||
|
||||
### Working Incrementally
|
||||
|
||||
Don't build an entire screen in one call. Break work into small steps:
|
||||
1. Create tokens/variables
|
||||
2. Create text styles
|
||||
3. Build individual components
|
||||
4. Compose sections
|
||||
5. Assemble screens
|
||||
|
||||
Verify structure with `get_metadata` between steps. Use `get_screenshot` after each major creation milestone to catch visual problems early.
|
||||
|
||||
## Creating Nodes
|
||||
|
||||
### Frames
|
||||
|
||||
```javascript
|
||||
const frame = figma.createFrame();
|
||||
frame.name = "Container";
|
||||
frame.resize(1440, 900);
|
||||
frame.x = 0;
|
||||
frame.y = 0;
|
||||
frame.fills = [{ type: "SOLID", color: { r: 0.98, g: 0.98, b: 0.99 } }];
|
||||
```
|
||||
|
||||
### Text
|
||||
|
||||
```javascript
|
||||
// MUST load font before any text operations
|
||||
await figma.loadFontAsync({ family: "Inter", style: "Regular" });
|
||||
|
||||
const text = figma.createText();
|
||||
text.fontName = { family: "Inter", style: "Regular" };
|
||||
text.fontSize = 16;
|
||||
text.lineHeight = { value: 24, unit: "PIXELS" };
|
||||
text.letterSpacing = { value: 0, unit: "PERCENT" };
|
||||
text.characters = "Hello World";
|
||||
text.fills = [{ type: "SOLID", color: { r: 0.1, g: 0.1, b: 0.12 } }];
|
||||
```
|
||||
|
||||
### Rectangles
|
||||
|
||||
```javascript
|
||||
const rect = figma.createRectangle();
|
||||
rect.name = "Background";
|
||||
rect.resize(400, 300);
|
||||
rect.cornerRadius = 12;
|
||||
rect.fills = [{ type: "SOLID", color: { r: 0.95, g: 0.95, b: 0.96 } }];
|
||||
```
|
||||
|
||||
### Ellipses
|
||||
|
||||
```javascript
|
||||
const circle = figma.createEllipse();
|
||||
circle.name = "Avatar Circle";
|
||||
circle.resize(48, 48);
|
||||
circle.fills = [{ type: "SOLID", color: { r: 0.85, g: 0.87, b: 0.90 } }];
|
||||
```
|
||||
|
||||
### Lines
|
||||
|
||||
```javascript
|
||||
const line = figma.createLine();
|
||||
line.name = "Divider";
|
||||
line.resize(400, 0);
|
||||
line.strokes = [{ type: "SOLID", color: { r: 0, g: 0, b: 0 }, opacity: 0.08 }];
|
||||
line.strokeWeight = 1;
|
||||
```
|
||||
|
||||
### SVG Import
|
||||
|
||||
```javascript
|
||||
const svgString = `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path d="M5 12h14M12 5l7 7-7 7" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</svg>`;
|
||||
|
||||
const node = figma.createNodeFromSvg(svgString);
|
||||
node.name = "Icon/Arrow Right";
|
||||
node.resize(24, 24);
|
||||
```
|
||||
|
||||
## Fills & Strokes
|
||||
|
||||
### Solid Fill
|
||||
|
||||
```javascript
|
||||
node.fills = [{ type: "SOLID", color: { r: 0.2, g: 0.2, b: 0.25 } }];
|
||||
```
|
||||
|
||||
### Fill with Opacity
|
||||
|
||||
```javascript
|
||||
node.fills = [{ type: "SOLID", color: { r: 0.2, g: 0.2, b: 0.25 }, opacity: 0.5 }];
|
||||
```
|
||||
|
||||
### No Fill (Transparent)
|
||||
|
||||
```javascript
|
||||
node.fills = [];
|
||||
```
|
||||
|
||||
### Linear Gradient
|
||||
|
||||
```javascript
|
||||
node.fills = [{
|
||||
type: "GRADIENT_LINEAR",
|
||||
gradientStops: [
|
||||
{ color: { r: 0.2, g: 0.36, b: 0.96, a: 1 }, position: 0 },
|
||||
{ color: { r: 0.56, g: 0.24, b: 0.88, a: 1 }, position: 1 }
|
||||
],
|
||||
gradientTransform: [[1, 0, 0], [0, 1, 0]]
|
||||
}];
|
||||
```
|
||||
|
||||
### Strokes
|
||||
|
||||
```javascript
|
||||
node.strokes = [{ type: "SOLID", color: { r: 0.85, g: 0.85, b: 0.87 } }];
|
||||
node.strokeWeight = 1;
|
||||
node.strokeAlign = "INSIDE"; // "CENTER", "OUTSIDE"
|
||||
```
|
||||
|
||||
### Multiple Fills (Layered)
|
||||
|
||||
```javascript
|
||||
node.fills = [
|
||||
{ type: "SOLID", color: { r: 0.95, g: 0.95, b: 0.96 } },
|
||||
{ type: "SOLID", color: { r: 0.2, g: 0.36, b: 0.96 }, opacity: 0.05 }
|
||||
];
|
||||
```
|
||||
|
||||
## Auto Layout
|
||||
|
||||
### Setting Up Auto Layout
|
||||
|
||||
```javascript
|
||||
const frame = figma.createFrame();
|
||||
frame.layoutMode = "VERTICAL"; // or "HORIZONTAL"
|
||||
frame.primaryAxisSizingMode = "AUTO"; // Hug main axis
|
||||
frame.counterAxisSizingMode = "FIXED"; // Fixed cross axis
|
||||
frame.resize(360, 1); // Width fixed, height auto
|
||||
frame.itemSpacing = 16; // Gap between children
|
||||
frame.paddingTop = 24;
|
||||
frame.paddingBottom = 24;
|
||||
frame.paddingLeft = 24;
|
||||
frame.paddingRight = 24;
|
||||
```
|
||||
|
||||
### Alignment
|
||||
|
||||
```javascript
|
||||
// Main axis (direction of layout)
|
||||
frame.primaryAxisAlignItems = "MIN"; // Start
|
||||
frame.primaryAxisAlignItems = "CENTER"; // Center
|
||||
frame.primaryAxisAlignItems = "MAX"; // End
|
||||
frame.primaryAxisAlignItems = "SPACE_BETWEEN"; // Distribute
|
||||
|
||||
// Cross axis
|
||||
frame.counterAxisAlignItems = "MIN"; // Start
|
||||
frame.counterAxisAlignItems = "CENTER"; // Center
|
||||
frame.counterAxisAlignItems = "MAX"; // End
|
||||
// NOTE: 'STRETCH' is NOT valid — use 'MIN' + child.layoutSizingX = 'FILL'
|
||||
```
|
||||
|
||||
### Child Sizing
|
||||
|
||||
```javascript
|
||||
// IMPORTANT: FILL can only be set AFTER the child is appended to an auto-layout parent
|
||||
parent.appendChild(child)
|
||||
child.layoutSizingHorizontal = "FILL"; // Stretch to parent
|
||||
child.layoutSizingHorizontal = "HUG"; // Shrink to content
|
||||
child.layoutSizingHorizontal = "FIXED"; // Manual width
|
||||
|
||||
child.layoutSizingVertical = "FILL";
|
||||
child.layoutSizingVertical = "HUG";
|
||||
child.layoutSizingVertical = "FIXED";
|
||||
```
|
||||
|
||||
### Wrapping (Grid-like Layout)
|
||||
|
||||
```javascript
|
||||
frame.layoutMode = "HORIZONTAL";
|
||||
frame.layoutWrap = "WRAP";
|
||||
frame.itemSpacing = 24; // Horizontal gap
|
||||
frame.counterAxisSpacing = 24; // Vertical gap (between rows)
|
||||
```
|
||||
|
||||
### Absolute Positioning Within Auto Layout
|
||||
|
||||
```javascript
|
||||
child.layoutPositioning = "ABSOLUTE";
|
||||
child.constraints = { horizontal: "MAX", vertical: "MIN" }; // Top-right
|
||||
child.x = parentWidth - childWidth - 8;
|
||||
child.y = 8;
|
||||
```
|
||||
|
||||
## Effects
|
||||
|
||||
### Drop Shadow
|
||||
|
||||
```javascript
|
||||
node.effects = [{
|
||||
type: "DROP_SHADOW",
|
||||
color: { r: 0, g: 0, b: 0, a: 0.08 },
|
||||
offset: { x: 0, y: 4 },
|
||||
radius: 16,
|
||||
spread: -2,
|
||||
visible: true,
|
||||
blendMode: "NORMAL"
|
||||
}];
|
||||
```
|
||||
|
||||
### Inner Shadow
|
||||
|
||||
```javascript
|
||||
node.effects = [{
|
||||
type: "INNER_SHADOW",
|
||||
color: { r: 0, g: 0, b: 0, a: 0.05 },
|
||||
offset: { x: 0, y: 1 },
|
||||
radius: 2,
|
||||
spread: 0,
|
||||
visible: true,
|
||||
blendMode: "NORMAL"
|
||||
}];
|
||||
```
|
||||
|
||||
### Background Blur
|
||||
|
||||
```javascript
|
||||
node.effects = [{
|
||||
type: "BACKGROUND_BLUR",
|
||||
radius: 16,
|
||||
visible: true
|
||||
}];
|
||||
```
|
||||
|
||||
### Layer Blur
|
||||
|
||||
```javascript
|
||||
node.effects = [{
|
||||
type: "LAYER_BLUR",
|
||||
radius: 8,
|
||||
visible: true
|
||||
}];
|
||||
```
|
||||
|
||||
### Multiple Effects
|
||||
|
||||
```javascript
|
||||
node.effects = [
|
||||
{ type: "DROP_SHADOW", color: { r: 0, g: 0, b: 0, a: 0.04 }, offset: { x: 0, y: 1 }, radius: 3, spread: 0, visible: true, blendMode: "NORMAL" },
|
||||
{ type: "DROP_SHADOW", color: { r: 0, g: 0, b: 0, a: 0.06 }, offset: { x: 0, y: 8 }, radius: 24, spread: -4, visible: true, blendMode: "NORMAL" }
|
||||
];
|
||||
```
|
||||
|
||||
## Opacity & Blend Modes
|
||||
|
||||
```javascript
|
||||
node.opacity = 0.5;
|
||||
node.blendMode = "NORMAL"; // "MULTIPLY", "SCREEN", "OVERLAY", "DARKEN", "LIGHTEN", etc.
|
||||
```
|
||||
|
||||
## Corner Radius
|
||||
|
||||
```javascript
|
||||
// Uniform
|
||||
node.cornerRadius = 12;
|
||||
|
||||
// Per-corner
|
||||
node.topLeftRadius = 12;
|
||||
node.topRightRadius = 12;
|
||||
node.bottomLeftRadius = 0;
|
||||
node.bottomRightRadius = 0;
|
||||
```
|
||||
|
||||
## Clipping
|
||||
|
||||
```javascript
|
||||
frame.clipsContent = true; // Children clipped to frame bounds
|
||||
```
|
||||
|
||||
## Grouping & Organization
|
||||
|
||||
### Groups
|
||||
|
||||
```javascript
|
||||
const group = figma.group([node1, node2, node3], figma.currentPage);
|
||||
group.name = "Grouped Elements";
|
||||
```
|
||||
|
||||
### Sections
|
||||
|
||||
```javascript
|
||||
const section = figma.createSection();
|
||||
section.name = "My Section";
|
||||
section.resizeWithoutConstraints(800, 600);
|
||||
section.x = 0;
|
||||
section.y = 0;
|
||||
// IMPORTANT: Sections don't auto-resize — always resize after adding content
|
||||
```
|
||||
|
||||
### Appending Children
|
||||
|
||||
```javascript
|
||||
parentFrame.appendChild(childNode);
|
||||
|
||||
// Insert at a specific index
|
||||
parentFrame.insertChild(0, childNode); // Insert at beginning
|
||||
```
|
||||
|
||||
## Components & Variants
|
||||
|
||||
### Create Component
|
||||
|
||||
```javascript
|
||||
const component = figma.createComponent();
|
||||
component.name = "Button/Primary";
|
||||
component.description = "Primary action button.";
|
||||
```
|
||||
|
||||
### Create Instance
|
||||
|
||||
```javascript
|
||||
const instance = component.createInstance();
|
||||
instance.x = 200;
|
||||
instance.y = 100;
|
||||
```
|
||||
|
||||
### Import Components by Key (Team Libraries)
|
||||
|
||||
These methods import components from **team libraries** (not the same file). For components in the current file, use `figma.getNodeByIdAsync()` or `findOne()`/`findAll()`.
|
||||
|
||||
```javascript
|
||||
// Import a published component from a team library by its key
|
||||
const comp = await figma.importComponentByKeyAsync(componentKey)
|
||||
const instance = comp.createInstance()
|
||||
|
||||
// Import a published component set from a team library by its key
|
||||
const set = await figma.importComponentSetByKeyAsync(componentSetKey)
|
||||
const variant = set.defaultVariant
|
||||
const variantInstance = variant.createInstance()
|
||||
```
|
||||
|
||||
### Combine as Variants
|
||||
|
||||
```javascript
|
||||
// IMPORTANT: Pass ComponentNodes (not frames)
|
||||
const componentSet = figma.combineAsVariants(
|
||||
[variantA, variantB, variantC],
|
||||
figma.currentPage
|
||||
);
|
||||
componentSet.name = "Button";
|
||||
componentSet.description = "Button component with multiple variants.";
|
||||
|
||||
// CRITICAL: Layout variants in a grid after combining (they stack at 0,0)
|
||||
let maxX = 0, maxY = 0;
|
||||
componentSet.children.forEach((child, i) => {
|
||||
child.x = (i % numCols) * colWidth;
|
||||
child.y = Math.floor(i / numCols) * rowHeight;
|
||||
});
|
||||
for (const child of componentSet.children) {
|
||||
maxX = Math.max(maxX, child.x + child.width);
|
||||
maxY = Math.max(maxY, child.y + child.height);
|
||||
}
|
||||
componentSet.resizeWithoutConstraints(maxX + 40, maxY + 40);
|
||||
```
|
||||
|
||||
### Component Properties
|
||||
|
||||
```javascript
|
||||
// addComponentProperty returns a STRING key — capture it!
|
||||
const labelKey = component.addComponentProperty("label", "TEXT", "Button");
|
||||
const showIconKey = component.addComponentProperty("showIcon", "BOOLEAN", true);
|
||||
const iconSlotKey = component.addComponentProperty("iconSlot", "INSTANCE_SWAP", defaultIconId);
|
||||
|
||||
// MUST link properties to child nodes via componentPropertyReferences
|
||||
labelNode.componentPropertyReferences = { characters: labelKey };
|
||||
iconInstance.componentPropertyReferences = {
|
||||
visible: showIconKey,
|
||||
mainComponent: iconSlotKey
|
||||
};
|
||||
```
|
||||
|
||||
## Styles
|
||||
|
||||
### Text Style
|
||||
|
||||
```javascript
|
||||
await figma.loadFontAsync({ family: "Inter", style: "Regular" });
|
||||
|
||||
const style = figma.createTextStyle();
|
||||
style.name = "Body/Default";
|
||||
style.fontName = { family: "Inter", style: "Regular" };
|
||||
style.fontSize = 16;
|
||||
style.lineHeight = { value: 24, unit: "PIXELS" };
|
||||
style.letterSpacing = { value: 0, unit: "PERCENT" };
|
||||
|
||||
// Apply to a text node
|
||||
textNode.textStyleId = style.id;
|
||||
```
|
||||
|
||||
### Effect Style
|
||||
|
||||
```javascript
|
||||
const shadowStyle = figma.createEffectStyle();
|
||||
shadowStyle.name = "Shadow/Subtle";
|
||||
shadowStyle.effects = [{
|
||||
type: "DROP_SHADOW",
|
||||
color: { r: 0, g: 0, b: 0, a: 0.06 },
|
||||
offset: { x: 0, y: 2 },
|
||||
radius: 8,
|
||||
spread: 0,
|
||||
visible: true,
|
||||
blendMode: "NORMAL"
|
||||
}];
|
||||
|
||||
// Apply to a node
|
||||
frame.effectStyleId = shadowStyle.id;
|
||||
```
|
||||
|
||||
## Cloning & Duplication
|
||||
|
||||
```javascript
|
||||
const clone = originalNode.clone();
|
||||
clone.x = originalNode.x + originalNode.width + 40;
|
||||
clone.name = "Copy of " + originalNode.name;
|
||||
```
|
||||
|
||||
## Finding Nodes
|
||||
|
||||
```javascript
|
||||
// Find by name on current page
|
||||
const node = figma.currentPage.findOne(n => n.name === "My Frame");
|
||||
|
||||
// Find all by type
|
||||
const allTexts = figma.currentPage.findAll(n => n.type === "TEXT");
|
||||
|
||||
// Find all by name pattern
|
||||
const allButtons = figma.currentPage.findAll(n => n.name.startsWith("Button/"));
|
||||
```
|
||||
|
||||
## Layout Grids
|
||||
|
||||
```javascript
|
||||
frame.layoutGrids = [
|
||||
{
|
||||
pattern: "COLUMNS",
|
||||
alignment: "STRETCH",
|
||||
count: 12,
|
||||
gutterSize: 24,
|
||||
offset: 80,
|
||||
visible: true
|
||||
}
|
||||
];
|
||||
```
|
||||
|
||||
## Constraints (Non-Auto-Layout Frames)
|
||||
|
||||
```javascript
|
||||
child.constraints = {
|
||||
horizontal: "LEFT_RIGHT", // LEFT, RIGHT, CENTER, LEFT_RIGHT, SCALE
|
||||
vertical: "TOP" // TOP, BOTTOM, CENTER, TOP_BOTTOM, SCALE
|
||||
};
|
||||
```
|
||||
|
||||
## Viewport & Zoom
|
||||
|
||||
```javascript
|
||||
// Zoom to fit specific nodes
|
||||
figma.viewport.scrollAndZoomIntoView([frame1, frame2]);
|
||||
```
|
||||
+11293
File diff suppressed because one or more lines are too long
+437
@@ -0,0 +1,437 @@
|
||||
# Plugin API Index
|
||||
|
||||
> Full typings: `plugin-api-standalone.d.ts` (11,292 lines)
|
||||
> Grep by symbol name to jump to definition. All `L#` line numbers refer to that file.
|
||||
|
||||
---
|
||||
|
||||
## figma.\* — PluginAPI (L24)
|
||||
|
||||
### Identity & State
|
||||
|
||||
| Member | Type |
|
||||
| ------------------------------- | -------------------------------------------------------------------------------- |
|
||||
| `apiVersion` | `'1.0.0'` |
|
||||
| `editorType` | `'figma' \| 'figjam' \| 'dev' \| 'slides' \| 'buzz'` |
|
||||
| `mode` | `'default' \| 'textreview' \| 'inspect' \| 'codegen' \| 'linkpreview' \| 'auth'` |
|
||||
| `fileKey` | `string \| undefined` |
|
||||
| `root` | `DocumentNode` |
|
||||
| `currentPage` | `PageNode` — assign via `setCurrentPageAsync` |
|
||||
| `currentUser` | `User \| null` |
|
||||
| `mixed` | `unique symbol` — sentinel for mixed values in selection |
|
||||
| `skipInvisibleInstanceChildren` | `boolean` |
|
||||
|
||||
### Navigation & Lookup
|
||||
|
||||
| Method | Returns |
|
||||
| --------------------------- | ------------------------------------------------------- |
|
||||
| `setCurrentPageAsync(page)` | `Promise<void>` — **MUST use this**; sync setter throws |
|
||||
| `getNodeByIdAsync(id)` | `Promise<BaseNode \| null>` |
|
||||
| `getNodeById(id)` | `BaseNode \| null` |
|
||||
| `getStyleByIdAsync(id)` | `Promise<BaseStyle \| null>` |
|
||||
| `getStyleById(id)` | `BaseStyle \| null` |
|
||||
|
||||
### Create Nodes
|
||||
|
||||
| Method | Returns |
|
||||
| ----------------------------------- | --------------------------- |
|
||||
| `createFrame()` | `FrameNode` |
|
||||
| `createComponent()` | `ComponentNode` |
|
||||
| `createComponentFromNode(node)` | `ComponentNode` |
|
||||
| `createRectangle()` | `RectangleNode` |
|
||||
| `createEllipse()` | `EllipseNode` |
|
||||
| `createLine()` | `LineNode` |
|
||||
| `createPolygon()` | `PolygonNode` |
|
||||
| `createStar()` | `StarNode` |
|
||||
| `createVector()` | `VectorNode` |
|
||||
| `createText()` | `TextNode` |
|
||||
| `createSection()` | `SectionNode` |
|
||||
| `createPage()` | `PageNode` |
|
||||
| `createSlice()` | `SliceNode` |
|
||||
| `createBooleanOperation()` | `BooleanOperationNode` |
|
||||
| `createTable(rows?, cols?)` | `TableNode` |
|
||||
| `createImage(data: Uint8Array)` | `Image` |
|
||||
| `createNodeFromSvg(svg)` | `FrameNode` |
|
||||
| `createNodeFromJSXAsync(jsx)` | `Promise<SceneNode>` |
|
||||
| `importComponentByKeyAsync(key)` | `Promise<ComponentNode>` |
|
||||
| `importComponentSetByKeyAsync(key)` | `Promise<ComponentSetNode>` |
|
||||
| `importStyleByKeyAsync(key)` | `Promise<BaseStyle>` |
|
||||
|
||||
### Styles (Local)
|
||||
|
||||
| Method | Returns |
|
||||
| ---------------------------------- | --------------- |
|
||||
| `createPaintStyle()` | `PaintStyle` |
|
||||
| `createTextStyle()` | `TextStyle` |
|
||||
| `createEffectStyle()` | `EffectStyle` |
|
||||
| `createGridStyle()` | `GridStyle` |
|
||||
| `getLocalPaintStyles()` / `Async` | `PaintStyle[]` |
|
||||
| `getLocalTextStyles()` / `Async` | `TextStyle[]` |
|
||||
| `getLocalEffectStyles()` / `Async` | `EffectStyle[]` |
|
||||
| `getLocalGridStyles()` / `Async` | `GridStyle[]` |
|
||||
|
||||
### Fonts
|
||||
|
||||
| Method | Notes |
|
||||
| --------------------------- | ---------------------------------- |
|
||||
| `loadFontAsync(fontName)` | **MUST call before any text edit** |
|
||||
| `listAvailableFontsAsync()` | `Promise<Font[]>` |
|
||||
| `hasMissingFont` | `boolean` |
|
||||
|
||||
### Plugin Lifecycle
|
||||
|
||||
| Method | Notes |
|
||||
| --------------------------------------- | ------------------------------------------------------------ |
|
||||
| `closePlugin(message?)` | Auto-called; use `return` instead to pass results back |
|
||||
| `closePluginWithFailure(message?)` | Auto-called on errors; do not call manually |
|
||||
| `commitUndo()` | Snapshot to undo history |
|
||||
| `triggerUndo()` | Revert to last snapshot |
|
||||
| `saveVersionHistoryAsync(title, desc?)` | `Promise<VersionHistoryResult>` |
|
||||
| `notify(message, options?)` | **throws "not implemented" in use_figma — do not use** |
|
||||
| `openExternal(url)` | Opens URL in browser |
|
||||
|
||||
### Sub-APIs (properties on figma)
|
||||
|
||||
| Property | Interface | L# |
|
||||
| --------------------- | ------------------------ | ----- |
|
||||
| `figma.variables` | `VariablesAPI` | L2016 |
|
||||
| `figma.ui` | `UIAPI` | L2604 |
|
||||
| `figma.util` | `UtilAPI` | L2691 |
|
||||
| `figma.constants` | `ConstantsAPI` | L2809 |
|
||||
| `figma.clientStorage` | `ClientStorageAPI` | L2531 |
|
||||
| `figma.viewport` | `ViewportAPI` | L3086 |
|
||||
| `figma.parameters` | `ParametersAPI` | L3292 |
|
||||
| `figma.teamLibrary` | `TeamLibraryAPI` | L2372 |
|
||||
| `figma.annotations` | `AnnotationsAPI` | L2187 |
|
||||
| `figma.codegen` | `CodegenAPI` | L2871 |
|
||||
| `figma.textreview?` | `TextReviewAPI` | L3166 |
|
||||
| `figma.payments?` | `PaymentsAPI` | L2420 |
|
||||
| `figma.buzz` | `BuzzAPI` | L2211 |
|
||||
| `figma.timer?` | `TimerAPI` (FigJam only) | L3053 |
|
||||
|
||||
---
|
||||
|
||||
## VariablesAPI — figma.variables (L2016)
|
||||
|
||||
```
|
||||
getVariableByIdAsync(id) Promise<Variable | null> ← preferred; sync deprecated
|
||||
getVariableCollectionByIdAsync(id) Promise<VariableCollection | null> ← preferred; sync deprecated
|
||||
getLocalVariablesAsync(type?) Promise<Variable[]> ← preferred; filter by VariableResolvedDataType; sync deprecated
|
||||
getLocalVariableCollectionsAsync() Promise<VariableCollection[]> ← preferred; sync deprecated
|
||||
createVariable(name, collection, type) Variable
|
||||
createVariableCollection(name) VariableCollection
|
||||
createVariableAlias(variable) VariableAlias
|
||||
importVariableByKeyAsync(key) Promise<Variable>
|
||||
setBoundVariableForPaint(paint, field, variable) → returns NEW paint — reassign
|
||||
setBoundVariableForEffect(effect, field, variable) → returns NEW effect — reassign
|
||||
setBoundVariableForLayoutGrid(grid, field, variable)
|
||||
```
|
||||
|
||||
**Variable (L10204):** `name`, `resolvedType`, `codeSyntax`, `scopes`, `hiddenFromPublishing`, `valuesByMode`, `variableCollectionId`
|
||||
|
||||
- `setVariableCodeSyntax(platform, value)` — platform: `'WEB' | 'ANDROID' | 'iOS'`
|
||||
- `setValueForMode(collectionId, modeId, value)`
|
||||
- `remove()`
|
||||
|
||||
**VariableCollection (L10418):** `name`, `modes`, `variableIds`, `defaultModeId`, `hiddenFromPublishing`
|
||||
|
||||
- `addMode(name)` → `modeId`; `removeMode(modeId)`; `renameMode(modeId, name)`
|
||||
|
||||
---
|
||||
|
||||
## Node Types
|
||||
|
||||
### Concrete Scene Nodes
|
||||
|
||||
| Node | L# | Key characteristics |
|
||||
| ---------------------- | ------ | -------------------------------------------------- |
|
||||
| `DocumentNode` | L8960 | Root; `children: PageNode[]` |
|
||||
| `PageNode` | L9119 | `children`, local styles, `backgrounds` |
|
||||
| `FrameNode` | L9311 | `DefaultFrameMixin` — auto-layout, clips, children |
|
||||
| `GroupNode` | L9321 | Children only, no auto-layout |
|
||||
| `ComponentNode` | L9678 | Like Frame + publishable |
|
||||
| `ComponentSetNode` | L9653 | Variant set container |
|
||||
| `InstanceNode` | L9719 | Like Frame; `mainComponent`, `detach()` |
|
||||
| `RectangleNode` | L9378 | `DefaultShapeMixin` + corners |
|
||||
| `EllipseNode` | L9410 | + `arcData` |
|
||||
| `LineNode` | L9396 | |
|
||||
| `PolygonNode` | L9430 | |
|
||||
| `StarNode` | L9450 | |
|
||||
| `VectorNode` | L9476 | Vector paths |
|
||||
| `TextNode` | L9493 | Rich text, fonts, segments |
|
||||
| `TextPathNode` | L9564 | Text along path |
|
||||
| `BooleanOperationNode` | L9792 | `booleanOperation` property |
|
||||
| `SliceNode` | L9368 | Export only |
|
||||
| `SectionNode` | L10754 | Grouping + fills |
|
||||
| `TableNode` | L9862 | `TableCellNode` children |
|
||||
|
||||
**FigJam only:** `StickyNode` L9812, `ConnectorNode` L10121, `ShapeWithTextNode` L9999, `StampNode` L9838, `CodeBlockNode` L10080, `EmbedNode` L10661, `LinkUnfurlNode` L10701, `MediaNode` L10721
|
||||
|
||||
**Slides only:** `SlideNode` L10784, `SlideRowNode` L10809, `SlideGridNode` L10822
|
||||
|
||||
**Union types:**
|
||||
|
||||
```
|
||||
type SceneNode (L10917) = FrameNode | GroupNode | SliceNode | RectangleNode | LineNode
|
||||
| EllipseNode | PolygonNode | StarNode | VectorNode | TextNode | ComponentSetNode
|
||||
| ComponentNode | InstanceNode | BooleanOperationNode | SectionNode | ...
|
||||
type BaseNode (L10913) = DocumentNode | PageNode | SceneNode
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mixin Interfaces
|
||||
|
||||
| Mixin | L# | Provides |
|
||||
| ---------------------------- | ----- | ----------------------------------------------------------------------------------------------- |
|
||||
| `BaseNodeMixin` | L5284 | `id`, `name`, `type`, `parent`, `remove()`, plugin data |
|
||||
| `SceneNodeMixin` | L5561 | `visible`, `locked`, `opacity`, variable bindings |
|
||||
| `ChildrenMixin` | L5773 | `children`, `appendChild()`, `insertChild()`, `findAll()`, `findOne()`, `findAllWithCriteria()` |
|
||||
| `LayoutMixin` | L6135 | `x`, `y`, `width`, `height`, `rotation`, `resize()`, `rescale()` |
|
||||
| `AutoLayoutMixin` | L6436 | `layoutMode`, axis alignment, padding, `itemSpacing`, `layoutSizingHorizontal/Vertical` |
|
||||
| `AutoLayoutChildrenMixin` | L7064 | `layoutAlign`, `layoutGrow`, sizing — **set AFTER `appendChild()`** |
|
||||
| `GridLayoutMixin` | L6939 | CSS Grid tracks, gap, template |
|
||||
| `GridChildrenMixin` | L7127 | grid child positioning |
|
||||
| `GeometryMixin` | L7485 | `fills`, `strokes`, `strokeWeight`, `strokeAlign` |
|
||||
| `MinimalFillsMixin` | L7328 | `fills` only |
|
||||
| `MinimalStrokesMixin` | L7246 | `strokes`, `strokeWeight` |
|
||||
| `BlendMixin` | L6339 | `opacity`, `blendMode`, `isMask`, `effects` |
|
||||
| `CornerMixin` | L7537 | `cornerRadius`, `cornerSmoothing` |
|
||||
| `RectangleCornerMixin` | L7560 | Per-corner radii |
|
||||
| `ExportMixin` | L7577 | `exportSettings`, `exportAsync()` |
|
||||
| `ReactionMixin` | L7704 | `reactions` (prototyping) |
|
||||
| `PublishableMixin` | L7875 | `description`, `key`, `getPublishStatusAsync()` |
|
||||
| `VariantMixin` | L8182 | `variantProperties` |
|
||||
| `ComponentPropertiesMixin` | L8229 | `componentProperties`, `addComponentProperty()` |
|
||||
| `PluginDataMixin` | L5443 | `getSharedPluginData()`, `setSharedPluginData()` supported; `getPluginData()`, `setPluginData()` **NOT supported** |
|
||||
| `FramePrototypingMixin` | L7651 | `overflowDirection`, `numberOfFixedChildren` |
|
||||
| `BaseFrameMixin` | L7939 | ChildrenMixin + LayoutMixin + AutoLayoutMixin + GeometryMixin + … |
|
||||
| `DefaultFrameMixin` | L7997 | BaseFrameMixin + FramePrototypingMixin + ReactionMixin |
|
||||
| `DefaultShapeMixin` | L7928 | BlendMixin + GeometryMixin + LayoutMixin + ExportMixin + ReactionMixin |
|
||||
| `ExplicitVariableModesMixin` | L9084 | `setExplicitVariableModeForCollection()` |
|
||||
|
||||
---
|
||||
|
||||
## Paint & Fill (L4302)
|
||||
|
||||
| Type | L# | Notes |
|
||||
| --------------- | ----- | --------------------------------------------------------------------------------- |
|
||||
| `SolidPaint` | L4302 | `type:'SOLID'`, `color: RGB`, `opacity`, `visible`, `blendMode` |
|
||||
| `GradientPaint` | L4357 | `type: 'GRADIENT_LINEAR\|RADIAL\|ANGULAR\|DIAMOND'`, `gradientStops: ColorStop[]` |
|
||||
| `ImagePaint` | L4377 | `type:'IMAGE'`, `imageHash`, `scaleMode` |
|
||||
| `VideoPaint` | L4413 | `type:'VIDEO'` |
|
||||
| `PatternPaint` | L4449 | `type:'PATTERN'` |
|
||||
| `type Paint` | L4481 | Union of all five |
|
||||
| `ColorStop` | L4271 | `{ position: number, color: RGBA }` |
|
||||
| `ImageFilters` | L4290 | exposure, contrast, saturation, etc. |
|
||||
|
||||
> **CRITICAL**: Fills/strokes are **read-only arrays** — clone, modify, reassign.
|
||||
|
||||
---
|
||||
|
||||
## Effects (L3966)
|
||||
|
||||
| Type | L# |
|
||||
| ---------------------------------- | ----- |
|
||||
| `DropShadowEffect` | L3966 |
|
||||
| `InnerShadowEffect` | L4009 |
|
||||
| `BlurEffect` (Normal/Progressive) | L4048 |
|
||||
| `NoiseEffect` (Mono/Duo/Multitone) | L4105 |
|
||||
| `TextureEffect` | L4180 |
|
||||
| `GlassEffect` | L4209 |
|
||||
| `type Effect` | L4250 |
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
| Type | L# | Notes |
|
||||
| ------------------- | ----- | -------------------------------------------------------------------------------------- |
|
||||
| `FontName` | L3697 | `{ family: string, style: string }` |
|
||||
| `TextNode` | L9493 | `characters`, `textAlignHorizontal`, `fontSize`, `fontName`, `getStyledTextSegments()` |
|
||||
| `StyledTextSegment` | L4882 | Per-range text properties |
|
||||
| `LetterSpacing` | L4826 | `{ value, unit: 'PIXELS'\|'PERCENT' }` |
|
||||
| `LineHeight` | L4830 | `{ value, unit } \| { unit: 'AUTO' }` |
|
||||
| `TextCase` | L3701 | `'ORIGINAL'\|'UPPER'\|'LOWER'\|'TITLE'\|'SMALL_CAPS'` |
|
||||
| `TextDecoration` | L3702 | `'NONE'\|'UNDERLINE'\|'STRIKETHROUGH'` |
|
||||
| `OpenTypeFeature` | L3728 | Ligatures, numerals, etc. |
|
||||
|
||||
---
|
||||
|
||||
## Variables & Bindings
|
||||
|
||||
| Type | L# | Notes |
|
||||
| ----------------------------- | ------ | ------------------------------------------------------------- |
|
||||
| `Variable` | L10204 | Core variable object |
|
||||
| `VariableCollection` | L10418 | Collection of variables + modes |
|
||||
| `VariableAlias` | L10172 | Reference to another variable |
|
||||
| `VariableValue` | L10176 | `boolean \| string \| number \| RGB \| RGBA \| VariableAlias` |
|
||||
| `VariableResolvedDataType` | L10171 | `'BOOLEAN' \| 'COLOR' \| 'FLOAT' \| 'STRING'` |
|
||||
| `VariableDataType` | L5023 | Includes `'VARIABLE_ALIAS' \| 'EXPRESSION'` |
|
||||
| `VariableScope` | L10177 | Where variable can be applied |
|
||||
| `CodeSyntaxPlatform` | L10203 | `'WEB' \| 'ANDROID' \| 'iOS'` |
|
||||
| `VariableBindableNodeField` | L5712 | Node fields that accept variable binding |
|
||||
| `VariableBindableTextField` | L5739 | Text-specific bindable fields |
|
||||
| `VariableBindablePaintField` | L5748 | `'color'` |
|
||||
| `VariableBindableEffectField` | L5751 | `'color'\|'radius'\|'spread'\|'offsetX'\|'offsetY'` |
|
||||
|
||||
---
|
||||
|
||||
## Styles
|
||||
|
||||
| Interface | L# | Notes |
|
||||
| ---------------- | ------ | ------------------------------------------------------ |
|
||||
| `BaseStyleMixin` | L10977 | `name`, `id`, `key`, `type`, `description`, `remove()` |
|
||||
| `PaintStyle` | L11002 | `type:'PAINT'`, `paints: Paint[]` |
|
||||
| `TextStyle` | L11018 | `type:'TEXT'`, font properties |
|
||||
| `EffectStyle` | L11087 | `type:'EFFECT'`, `effects: Effect[]` |
|
||||
| `GridStyle` | L11103 | `type:'GRID'`, `layoutGrids` |
|
||||
| `type BaseStyle` | L11119 | Union of all four |
|
||||
| `type StyleType` | L10955 | `'PAINT' \| 'TEXT' \| 'EFFECT' \| 'GRID'` |
|
||||
|
||||
---
|
||||
|
||||
## Primitives & Geometry
|
||||
|
||||
| Type | L# | Shape |
|
||||
| ---------------- | ----- | --------------------------------------------- |
|
||||
| `Vector` | L3667 | `{ x: number, y: number }` |
|
||||
| `Rect` | L3671 | `{ x, y, width, height }` |
|
||||
| `RGB` | L3680 | `{ r, g, b }` — **0–1 range, not 0–255** |
|
||||
| `RGBA` | L3688 | `{ r, g, b, a }` — **0–1 range** |
|
||||
| `Transform` | L3666 | `[[a,b,tx],[c,d,ty]]` 2×3 affine matrix |
|
||||
| `ArcData` | L3958 | `{ startingAngle, endingAngle, innerRadius }` |
|
||||
| `Constraints` | L4264 | `{ horizontal, vertical }: ConstraintType` |
|
||||
| `ConstraintType` | L4260 | `'MIN'\|'CENTER'\|'MAX'\|'STRETCH'\|'SCALE'` |
|
||||
| `VectorPath` | L4792 | `{ windingRule, data: string }` |
|
||||
| `VectorNetwork` | L4775 | vertices + segments + regions |
|
||||
| `Guide` | L4482 | `{ axis, offset }` |
|
||||
|
||||
---
|
||||
|
||||
## Prototyping
|
||||
|
||||
| Type | L# | Notes |
|
||||
| --------------------- | ----- | --------------------------------------------------------- |
|
||||
| `Reaction` | L5015 | trigger + action pair |
|
||||
| `Trigger` | L5146 | what initiates the reaction |
|
||||
| `Action` | L5064 | what happens |
|
||||
| `Transition` | L5145 | `SimpleTransition \| DirectionalTransition` |
|
||||
| `Easing` | L5182 | easing curve definition |
|
||||
| `Navigation` | L5178 | `'NAVIGATE'\|'SWAP'\|'OVERLAY'\|'SCROLL_TO'\|'CHANGE_TO'` |
|
||||
| `OverflowDirection` | L5215 | `'NONE'\|'HORIZONTAL'\|'VERTICAL'\|'BOTH'` |
|
||||
| `OverlayPositionType` | L5219 | overlay placement |
|
||||
|
||||
---
|
||||
|
||||
## Events & Changes
|
||||
|
||||
| Type | L# | Notes |
|
||||
| --------------------- | ----- | --------------------------------------------------------------- |
|
||||
| `ArgFreeEventType` | L11 | `'selectionchange'\|'currentpagechange'\|'close'\|timer events` |
|
||||
| `RunEvent` | L3321 | plugin run with parameters |
|
||||
| `DropEvent` | L3339 | drag-and-drop |
|
||||
| `DocumentChangeEvent` | L3359 | any document change |
|
||||
| `NodeChangeEvent` | L3626 | node property changes |
|
||||
| `NodeChangeProperty` | L3499 | all watchable property names |
|
||||
| `StyleChangeEvent` | L3365 | style create/delete/update |
|
||||
| `DocumentChange` | L3489 | `CreateChange \| DeleteChange \| PropertyChange` |
|
||||
| `TextReviewEvent` | L3657 | text review mode |
|
||||
|
||||
---
|
||||
|
||||
## Export
|
||||
|
||||
| Type | L# | Notes |
|
||||
| --------------------------- | ----- | --------------------------------------------- |
|
||||
| `ExportSettingsImage` | L4561 | PNG/JPG/WEBP/BMP |
|
||||
| `ExportSettingsSVG` | L4634 | |
|
||||
| `ExportSettingsPDF` | L4653 | |
|
||||
| `ExportSettingsREST` | L4667 | |
|
||||
| `ExportSettingsConstraints` | L4554 | `{ type: 'SCALE'\|'WIDTH'\|'HEIGHT', value }` |
|
||||
|
||||
---
|
||||
|
||||
## Key Sub-API Surfaces
|
||||
|
||||
**ClientStorageAPI (L2531):** `getAsync(key)`, `setAsync(key, value)`, `keysAsync()`, `deleteAsync(key)`
|
||||
|
||||
**ViewportAPI (L3086):** `center: Vector`, `zoom: number`, `scrollAndZoomIntoView(nodes)`, `bounds: Rect`
|
||||
|
||||
**UtilAPI (L2691):** `solidPaint(hex, opacity?)`, `rgba(r,g,b,a?)`, `rgb(r,g,b)`, `colorToHex(color)`, `loadImageAsync(url)`, `clone(val)`
|
||||
|
||||
**TeamLibraryAPI (L2372):** `getAvailableLibraryVariableCollectionsAsync()`, `importVariableByKeyAsync(key)`
|
||||
|
||||
**Image (L11120):** `hash`, `getBytesAsync()`, `getSizeAsync()`
|
||||
|
||||
---
|
||||
|
||||
## All Symbols (flat — grep these against the .d.ts file)
|
||||
|
||||
To find any symbol: `grep -n "^interface Foo\|^type Foo\|^declare type Foo" plugin-api-standalone.d.ts`
|
||||
|
||||
```
|
||||
PluginAPI VariablesAPI AnnotationsAPI TeamLibraryAPI
|
||||
UIAPI UtilAPI ViewportAPI ClientStorageAPI
|
||||
ConstantsAPI CodegenAPI PaymentsAPI TextReviewAPI
|
||||
ParametersAPI TimerAPI BuzzAPI DevResourcesAPI
|
||||
|
||||
DocumentNode PageNode FrameNode GroupNode
|
||||
ComponentNode ComponentSetNode InstanceNode RectangleNode
|
||||
EllipseNode LineNode PolygonNode StarNode
|
||||
VectorNode TextNode TextPathNode BooleanOperationNode
|
||||
SliceNode SectionNode TableNode TableCellNode
|
||||
StickyNode ConnectorNode ShapeWithTextNode StampNode
|
||||
CodeBlockNode EmbedNode LinkUnfurlNode MediaNode
|
||||
WidgetNode SlideNode SlideRowNode SlideGridNode
|
||||
TransformGroupNode HighlightNode WashiTapeNode
|
||||
|
||||
BaseNodeMixin SceneNodeMixin ChildrenMixin LayoutMixin
|
||||
AutoLayoutMixin AutoLayoutChildrenMixin GridLayoutMixin GridChildrenMixin
|
||||
GeometryMixin MinimalFillsMixin MinimalStrokesMixin BlendMixin
|
||||
MinimalBlendMixin CornerMixin RectangleCornerMixin ExportMixin
|
||||
ReactionMixin PublishableMixin VariantMixin ComponentPropertiesMixin
|
||||
PluginDataMixin DevResourcesMixin DevStatusMixin StickableMixin
|
||||
ConstraintMixin DimensionAndPositionMixin AspectRatioLockMixin FramePrototypingMixin
|
||||
BaseFrameMixin DefaultFrameMixin DefaultShapeMixin OpaqueNodeMixin
|
||||
VectorLikeMixin ComplexStrokesMixin IndividualStrokesMixin ContainerMixin
|
||||
AnnotationsMixin MeasurementsMixin ExplicitVariableModesMixin
|
||||
|
||||
Variable VariableCollection VariableAlias ExtendedVariableCollection
|
||||
LibraryVariableCollection LibraryVariable
|
||||
VariableValue VariableResolvedDataType VariableDataType VariableScope
|
||||
CodeSyntaxPlatform VariableBindableNodeField VariableBindableTextField
|
||||
VariableBindablePaintField VariableBindableEffectField VariableBindableLayoutGridField
|
||||
|
||||
SolidPaint GradientPaint ImagePaint VideoPaint
|
||||
PatternPaint Paint ColorStop ImageFilters
|
||||
DropShadowEffect InnerShadowEffect BlurEffect NoiseEffect
|
||||
TextureEffect GlassEffect Effect
|
||||
LayoutGrid RowsColsLayoutGrid GridLayoutGrid
|
||||
|
||||
PaintStyle TextStyle EffectStyle GridStyle
|
||||
BaseStyle BaseStyleMixin StyleType
|
||||
|
||||
FontName Font LetterSpacing LineHeight
|
||||
TextCase TextDecoration TextDecorationStyle FontStyle
|
||||
OpenTypeFeature StyledTextSegment LeadingTrim
|
||||
|
||||
Vector Rect RGB RGBA
|
||||
Transform ArcData Constraints ConstraintType
|
||||
VectorPath VectorNetwork VectorVertex VectorSegment
|
||||
VectorRegion Guide BlendMode MaskType
|
||||
|
||||
Reaction Trigger Action Transition
|
||||
Easing Navigation OverflowDirection OverlayPositionType
|
||||
OverlayBackground PublishStatus
|
||||
|
||||
ArgFreeEventType RunEvent DropEvent DocumentChangeEvent
|
||||
NodeChangeEvent NodeChangeProperty StyleChangeEvent DocumentChange
|
||||
TextReviewEvent SlidesViewChangeEvent CanvasViewChangeEvent
|
||||
|
||||
ExportSettingsImage ExportSettingsSVG ExportSettingsPDF ExportSettingsREST
|
||||
ExportSettingsConstraints
|
||||
|
||||
User ActiveUser BaseUser Image
|
||||
Video VersionHistoryResult FindAllCriteria
|
||||
```
|
||||
@@ -0,0 +1,205 @@
|
||||
# Text Style API Patterns
|
||||
|
||||
> Part of the [use_figma skill](../SKILL.md). How to create, apply, and inspect text styles using the Plugin API.
|
||||
>
|
||||
> For design system context (when to create text styles, how they relate to tokens, headless limitations), see [wwds-text-styles](working-with-design-systems/wwds-text-styles.md).
|
||||
|
||||
## Contents
|
||||
|
||||
- Listing Text Styles
|
||||
- Creating a Text Style
|
||||
- Probing Font Styles
|
||||
- Creating a Type Ramp (Multi-Step)
|
||||
- Importing Library Text Styles
|
||||
- Applying Text Styles to Nodes
|
||||
|
||||
## Listing Text Styles
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Lists all local text styles with their key properties.
|
||||
*
|
||||
* @returns {Promise<Array<{id: string, name: string, key: string, fontSize: number, fontName: FontName, lineHeight: LineHeight, letterSpacing: LetterSpacing}>>}
|
||||
*/
|
||||
async function listTextStyles() {
|
||||
const styles = await figma.getLocalTextStylesAsync();
|
||||
return styles.map(s => ({
|
||||
id: s.id,
|
||||
name: s.name,
|
||||
key: s.key,
|
||||
fontSize: s.fontSize,
|
||||
fontName: s.fontName,
|
||||
lineHeight: s.lineHeight,
|
||||
letterSpacing: s.letterSpacing
|
||||
}));
|
||||
}
|
||||
```
|
||||
|
||||
Full runnable script:
|
||||
|
||||
```javascript
|
||||
const results = await listTextStyles();
|
||||
return results;
|
||||
```
|
||||
|
||||
## Creating a Text Style
|
||||
|
||||
Font **MUST** be loaded before setting `fontName`. `lineHeight` and `letterSpacing` must be `{value, unit}` objects — bare numbers throw.
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Creates a text style with all typographic properties set.
|
||||
* Font MUST be loaded before calling.
|
||||
*
|
||||
* @param {string} name - Slash-delimited name, e.g. "body/base"
|
||||
* @param {{ family: string, style: string }} fontName
|
||||
* @param {number} fontSize - In pixels
|
||||
* @param {{ value: number, unit: 'PIXELS' | 'PERCENT' } | { unit: 'AUTO' }} lineHeight
|
||||
* @param {{ value: number, unit: 'PIXELS' | 'PERCENT' }} [letterSpacing]
|
||||
* @param {string} [description] - e.g. the CSS variable name "CSS: var(--font-body-base)"
|
||||
* @returns {TextStyle}
|
||||
*/
|
||||
function createTextStyleFull(name, fontName, fontSize, lineHeight, letterSpacing, description) {
|
||||
const style = figma.createTextStyle();
|
||||
style.name = name;
|
||||
style.fontName = fontName;
|
||||
style.fontSize = fontSize;
|
||||
style.lineHeight = lineHeight; // { unit: 'AUTO' } | { value, unit: 'PIXELS'|'PERCENT' }
|
||||
if (letterSpacing) style.letterSpacing = letterSpacing;
|
||||
if (description) style.description = description;
|
||||
return style;
|
||||
}
|
||||
```
|
||||
|
||||
## Probing Font Styles
|
||||
|
||||
Font style names vary per provider and per file (`"SemiBold"` vs `"Semi Bold"`). Always probe before hardcoding:
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Probes available font styles for a given family.
|
||||
* Useful when font style names are unknown (e.g. "SemiBold" vs "Semi Bold").
|
||||
*
|
||||
* @param {string} family - Font family name, e.g. "Inter"
|
||||
* @param {string[]} stylesToTest - Candidate style names to probe
|
||||
* @returns {Promise<string[]>} - Style names that loaded successfully
|
||||
*/
|
||||
async function probeAvailableFontStyles(family, stylesToTest) {
|
||||
const available = [];
|
||||
for (const style of stylesToTest) {
|
||||
try {
|
||||
await figma.loadFontAsync({ family, style });
|
||||
available.push(style);
|
||||
} catch (_) {}
|
||||
}
|
||||
return available;
|
||||
}
|
||||
```
|
||||
|
||||
## Creating a Type Ramp (Multi-Step)
|
||||
|
||||
Handles font loading, deduplication, and idempotency. Each entry: `[name, fontFamily, fontStyle, fontSize_px, lineHeight, cssVar]`.
|
||||
|
||||
**HEADLESS NOTE:** `setBoundVariable` on `TextStyle` is not supported in `use_figma`. This function sets raw values. To bind variables, do it interactively in Figma after creation.
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Creates a full type ramp from a token definition array.
|
||||
* Handles font loading, deduplication, and idempotency.
|
||||
*
|
||||
* Each entry: [name, fontFamily, fontStyle, fontSize_px, lineHeight, cssVar]
|
||||
* - lineHeight: { unit: 'AUTO' } or { value: number, unit: 'PIXELS' | 'PERCENT' }
|
||||
*
|
||||
* @param {Array} defs - Array of [name, fontFamily, fontStyle, fontSize, lineHeight, cssVar] tuples
|
||||
* @returns {Promise<{ created: string[], skipped: string[] }>}
|
||||
*/
|
||||
async function createTypeRamp(defs) {
|
||||
const uniqueFonts = new Set();
|
||||
for (const [, family, style] of defs) {
|
||||
uniqueFonts.add(JSON.stringify({ family, style }));
|
||||
}
|
||||
await Promise.all(
|
||||
[...uniqueFonts].map(f => figma.loadFontAsync(JSON.parse(f)))
|
||||
);
|
||||
|
||||
const existing = new Set(
|
||||
(await figma.getLocalTextStylesAsync()).map(s => s.name)
|
||||
);
|
||||
|
||||
const created = [];
|
||||
const skipped = [];
|
||||
|
||||
for (const [name, family, style, fontSize, lineHeight, cssVar] of defs) {
|
||||
if (existing.has(name)) {
|
||||
skipped.push(name);
|
||||
continue;
|
||||
}
|
||||
const ts = figma.createTextStyle();
|
||||
ts.name = name;
|
||||
ts.fontName = { family, style };
|
||||
ts.fontSize = fontSize;
|
||||
ts.lineHeight = lineHeight ?? { unit: 'AUTO' };
|
||||
if (cssVar) ts.description = `CSS: var(${cssVar})`;
|
||||
created.push(name);
|
||||
}
|
||||
|
||||
return { created, skipped };
|
||||
}
|
||||
```
|
||||
|
||||
Full runnable script:
|
||||
|
||||
```javascript
|
||||
const defs = [
|
||||
['heading/xl', 'Inter', 'Bold', 48, { unit: 'PIXELS', value: 56 }, '--font-heading-xl'],
|
||||
['heading/lg', 'Inter', 'Bold', 36, { unit: 'PIXELS', value: 44 }, '--font-heading-lg'],
|
||||
['body/base', 'Inter', 'Regular', 16, { unit: 'AUTO' }, '--font-body-base'],
|
||||
['body/sm', 'Inter', 'Regular', 14, { unit: 'AUTO' }, '--font-body-sm'],
|
||||
['code/base', 'Roboto Mono', 'Regular', 14, { unit: 'AUTO' }, '--font-code-base'],
|
||||
];
|
||||
const result = await createTypeRamp(defs);
|
||||
return result;
|
||||
```
|
||||
|
||||
## Importing Library Text Styles
|
||||
|
||||
For text styles from **team libraries**, use `importStyleByKeyAsync`:
|
||||
|
||||
```javascript
|
||||
// Import a library text style by key
|
||||
const headingStyle = await figma.importStyleByKeyAsync("TEXT_STYLE_KEY");
|
||||
// Apply to a text node
|
||||
await textNode.setTextStyleIdAsync(headingStyle.id);
|
||||
```
|
||||
|
||||
`search_design_system` with `includeStyles: true` returns style keys you can import this way. Prefer importing library styles over creating new ones.
|
||||
|
||||
## Applying Text Styles to Nodes
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Applies a text style to all TEXT nodes on the current page that match a given name pattern.
|
||||
*
|
||||
* @param {string} styleId - The ID of a TextStyle.
|
||||
* @param {string} nodeNamePattern - Substring match against node names.
|
||||
* @returns {Promise<number>} - Number of nodes the style was applied to.
|
||||
*/
|
||||
async function applyTextStyleToMatchingNodes(styleId, nodeNamePattern) {
|
||||
const textNodes = figma.currentPage.findAllWithCriteria({ types: ['TEXT'] });
|
||||
let applied = 0;
|
||||
for (const node of textNodes) {
|
||||
if (node.name.includes(nodeNamePattern)) {
|
||||
await node.setTextStyleIdAsync(styleId);
|
||||
applied++;
|
||||
}
|
||||
}
|
||||
return applied;
|
||||
}
|
||||
```
|
||||
|
||||
Full runnable script:
|
||||
|
||||
```javascript
|
||||
const applied = await applyTextStyleToMatchingNodes('STYLE_ID', 'Heading');
|
||||
return { applied };
|
||||
```
|
||||
@@ -0,0 +1,82 @@
|
||||
# Validation Workflow & Error Recovery
|
||||
|
||||
> Part of the [use_figma skill](../SKILL.md). How to debug, validate, and recover from errors.
|
||||
|
||||
## Contents
|
||||
|
||||
- `get_metadata` vs `get_screenshot`
|
||||
- Error Recovery After Failed `use_figma`
|
||||
- Recommended Workflow
|
||||
|
||||
|
||||
## `get_metadata` vs `get_screenshot`
|
||||
|
||||
After each `use_figma` call, validate results using the right tool for the job. Do NOT reach for `get_screenshot` every time — it is expensive and should be reserved for visual checks.
|
||||
|
||||
### `get_metadata` — Use for intermediate validation (preferred)
|
||||
|
||||
`get_metadata` returns an XML tree of node IDs, types, names, positions, and sizes. Use it to confirm:
|
||||
|
||||
- **Structure & hierarchy**: correct parent-child relationships, component nesting, section contents
|
||||
- **Node counts**: expected number of variants created, children present
|
||||
- **Naming**: variant property names follow the `property=value` convention
|
||||
- **Positioning & alignment**: x/y coordinates, width/height values match expectations
|
||||
- **Layout properties**: auto-layout direction, sizing mode, padding, spacing
|
||||
- **Component set membership**: all expected variants are inside the ComponentSet
|
||||
|
||||
```
|
||||
Example: After creating a ComponentSet with 120 variants, call get_metadata on the
|
||||
ComponentSet node to verify all 120 children exist with correct names, sizes, and positions
|
||||
— without waiting for a full render.
|
||||
```
|
||||
|
||||
**When to use `get_metadata`:**
|
||||
- After creating/modifying nodes — to verify structure, counts, and names
|
||||
- After layout operations — to verify positions and dimensions
|
||||
- After combining variants — to confirm all components are in the ComponentSet
|
||||
- After binding variables — to verify node properties (use use_figma to read bound variables if needed)
|
||||
- Between multi-step workflows — to confirm step N succeeded before starting step N+1
|
||||
|
||||
### `get_screenshot` — Use after each major creation milestone
|
||||
|
||||
`get_screenshot` renders a pixel-accurate image. It is the only way to verify visual correctness (colors, typography rendering, effects, variable mode resolution). It is slower and produces large responses, so don't call it after every single `use_figma` — but do call it after each major milestone to catch visual problems early.
|
||||
|
||||
**When to use `get_screenshot`:**
|
||||
- **After creating a component set** — verify variants look correct, grid is readable, nothing is collapsed or overlapping
|
||||
- **After composing a layout** — verify overall structure and spacing
|
||||
- **After binding variables/modes** — verify colors and tokens resolved correctly
|
||||
- **After any fix or recovery** — verify the fix didn't introduce new visual issues
|
||||
- **Before reporting results to the user** — final visual proof
|
||||
|
||||
**What to look for in screenshots** — these are the most commonly missed issues:
|
||||
- **Cropped/clipped text** — line heights or frame sizing cutting off descenders, ascenders, or entire lines
|
||||
- **Overlapping content** — elements stacking on top of each other due to incorrect sizing or missing auto-layout
|
||||
- **Placeholder text** still showing ("Title", "Heading", "Button") instead of actual content
|
||||
|
||||
## Error Recovery After Failed `use_figma`
|
||||
|
||||
**`use_figma` is atomic — failed scripts do not execute.** If a script errors, no changes are made to the file. The file remains in exactly the same state as before the call. There are no partial nodes, no orphaned elements, and retrying after a fix is safe.
|
||||
|
||||
**Recovery steps when `use_figma` returns an error:**
|
||||
1. **STOP — do NOT immediately fix the code and retry.** Read the error message carefully first.
|
||||
2. **Understand the error.** Most errors are caused by wrong API usage, missing font loads, invalid property values, or referencing nodes that don't exist.
|
||||
3. **If the error is unclear**, call `get_metadata` or `get_screenshot` to understand the current file state and confirm nothing has changed.
|
||||
4. **Fix the script** based on the error message.
|
||||
5. **Retry** the corrected script.
|
||||
|
||||
## Recommended Workflow
|
||||
|
||||
```
|
||||
1. use_figma → Create/modify nodes
|
||||
2. get_metadata → Verify structure, counts, names, positions (fast, cheap)
|
||||
3. use_figma → Fix any structural issues found
|
||||
4. get_metadata → Re-verify fixes
|
||||
5. ... repeat as needed ...
|
||||
6. get_screenshot → Visual check after each major milestone
|
||||
|
||||
⚠️ ON ERROR at any step:
|
||||
a. Read the error message carefully
|
||||
b. get_metadata / get_screenshot → If the error is unclear, inspect file state
|
||||
c. Fix the script based on the error
|
||||
d. Retry the corrected script (safe — failed scripts don't modify the file)
|
||||
```
|
||||
@@ -0,0 +1,375 @@
|
||||
# Variable & Token API Patterns
|
||||
|
||||
> Part of the [use_figma skill](../SKILL.md). How to correctly create, bind, scope, and alias variables using the Plugin API.
|
||||
>
|
||||
> For design system context (aliasing strategy, mode decisions, code syntax philosophy, grouping conventions), see [wwds-variables](working-with-design-systems/wwds-variables.md).
|
||||
|
||||
## Contents
|
||||
|
||||
- Creating Variable Collections and Modes
|
||||
- Creating Variables (All Types)
|
||||
- Binding Variables to Node Properties
|
||||
- Variable Scopes: What They Are and How to Set Them
|
||||
- Variable Aliasing (VARIABLE_ALIAS)
|
||||
- Code Syntax (setVariableCodeSyntax)
|
||||
- Importing Library Variables
|
||||
- Discovering Existing Variables in the File
|
||||
- Effect Styles (For Shadows)
|
||||
|
||||
|
||||
## Creating Variable Collections and Modes
|
||||
|
||||
```javascript
|
||||
const collection = figma.variables.createVariableCollection("MyCollection");
|
||||
|
||||
// A new collection starts with 1 mode named "Mode 1" — always rename it
|
||||
collection.renameMode(collection.modes[0].modeId, "Light");
|
||||
|
||||
// Add additional modes (returns the new modeId)
|
||||
const darkModeId = collection.addMode("Dark");
|
||||
const lightModeId = collection.modes[0].modeId;
|
||||
```
|
||||
|
||||
**Mode limits are plan-dependent:** Free = 1 mode, Professional = up to 4, Organization/Enterprise = 40+. If you need many modes, split across multiple collections.
|
||||
|
||||
## Creating Variables (All Types)
|
||||
|
||||
`figma.variables.createVariable(name, collection, resolvedType)` — the second argument accepts a collection object or ID string (object preferred).
|
||||
|
||||
```javascript
|
||||
// COLOR — values use {r, g, b, a} (all 0–1 range, includes alpha)
|
||||
const colorVar = figma.variables.createVariable("my-color", collection, "COLOR");
|
||||
colorVar.setValueForMode(modeId, { r: 0.2, g: 0.36, b: 0.96, a: 1 });
|
||||
|
||||
// FLOAT — for spacing, radii, sizing, numeric values
|
||||
const floatVar = figma.variables.createVariable("my-spacing", collection, "FLOAT");
|
||||
floatVar.setValueForMode(modeId, 16);
|
||||
|
||||
// STRING — for font families, font style names, any text value
|
||||
const stringVar = figma.variables.createVariable("my-font", collection, "STRING");
|
||||
stringVar.setValueForMode(modeId, "Inter");
|
||||
|
||||
// BOOLEAN
|
||||
const boolVar = figma.variables.createVariable("my-flag", collection, "BOOLEAN");
|
||||
boolVar.setValueForMode(modeId, true);
|
||||
```
|
||||
|
||||
**Note:** Paint colors use `{r, g, b}` (no alpha), but COLOR variable values use `{r, g, b, a}` (with alpha). Don't mix them up.
|
||||
|
||||
## Binding Variables to Node Properties
|
||||
|
||||
### Color Bindings (Fills, Strokes)
|
||||
|
||||
`setBoundVariableForPaint` returns a **NEW paint** — you must capture the return value:
|
||||
|
||||
```javascript
|
||||
// Create a base paint, bind the variable, assign the result
|
||||
const basePaint = { type: 'SOLID', color: { r: 0, g: 0, b: 0 } };
|
||||
const boundPaint = figma.variables.setBoundVariableForPaint(basePaint, "color", colorVar);
|
||||
node.fills = [boundPaint];
|
||||
|
||||
// Only SOLID paints support color variable binding — gradients/images will throw
|
||||
```
|
||||
|
||||
### Numeric Bindings (Spacing, Radii, Sizing)
|
||||
|
||||
`setBoundVariable` binds FLOAT/STRING/BOOLEAN variables to node properties:
|
||||
|
||||
```javascript
|
||||
// Padding
|
||||
node.setBoundVariable("paddingTop", spacingVar);
|
||||
node.setBoundVariable("paddingBottom", spacingVar);
|
||||
node.setBoundVariable("paddingLeft", spacingVar);
|
||||
node.setBoundVariable("paddingRight", spacingVar);
|
||||
|
||||
// Gap
|
||||
node.setBoundVariable("itemSpacing", gapVar);
|
||||
node.setBoundVariable("counterAxisSpacing", gapVar);
|
||||
|
||||
// Corner radius — use individual corners, NOT cornerRadius
|
||||
node.setBoundVariable("topLeftRadius", radiusVar);
|
||||
node.setBoundVariable("topRightRadius", radiusVar);
|
||||
node.setBoundVariable("bottomLeftRadius", radiusVar);
|
||||
node.setBoundVariable("bottomRightRadius", radiusVar);
|
||||
|
||||
// Size
|
||||
node.setBoundVariable("width", sizeVar);
|
||||
node.setBoundVariable("height", sizeVar);
|
||||
node.setBoundVariable("minWidth", sizeVar);
|
||||
node.setBoundVariable("maxWidth", sizeVar);
|
||||
|
||||
// Other
|
||||
node.setBoundVariable("opacity", opacityVar);
|
||||
node.setBoundVariable("strokeWeight", strokeVar);
|
||||
```
|
||||
|
||||
**Not bindable via setBoundVariable:** `fontSize`, `fontWeight`, `lineHeight` — set these directly on text nodes.
|
||||
|
||||
### Effect Bindings
|
||||
|
||||
```javascript
|
||||
const effectCopy = JSON.parse(JSON.stringify(node.effects[0]));
|
||||
const newEffect = figma.variables.setBoundVariableForEffect(effectCopy, "color", colorVar);
|
||||
// ⚠️ Returns a NEW effect — must capture return value!
|
||||
node.effects = [newEffect];
|
||||
// Valid fields: "color" (COLOR), "radius" | "spread" | "offsetX" | "offsetY" (FLOAT)
|
||||
```
|
||||
|
||||
### Applying a Mode to a Frame
|
||||
|
||||
```javascript
|
||||
// All bound children of this frame will resolve to the specified mode's values
|
||||
frame.setExplicitVariableModeForCollection(collection, modeId);
|
||||
```
|
||||
|
||||
Without this, all nodes use the collection's default (first) mode.
|
||||
|
||||
## Variable Scopes: What They Are and How to Set Them
|
||||
|
||||
`variable.scopes` controls which Figma property pickers show the variable. The default is `["ALL_SCOPES"]` which shows it everywhere — this is almost never what you want.
|
||||
|
||||
```javascript
|
||||
variable.scopes = ["FRAME_FILL", "SHAPE_FILL"]; // only fill pickers
|
||||
variable.scopes = ["TEXT_FILL"]; // only text color picker
|
||||
variable.scopes = ["GAP"]; // only gap/spacing pickers
|
||||
variable.scopes = ["CORNER_RADIUS"]; // only radius pickers
|
||||
variable.scopes = []; // hidden from all pickers
|
||||
```
|
||||
|
||||
**All valid scope values:**
|
||||
`ALL_SCOPES`, `TEXT_CONTENT`, `CORNER_RADIUS`, `WIDTH_HEIGHT`, `GAP`, `ALL_FILLS`, `FRAME_FILL`, `SHAPE_FILL`, `TEXT_FILL`, `STROKE_COLOR`, `STROKE_FLOAT`, `EFFECT_FLOAT`, `EFFECT_COLOR`, `OPACITY`, `FONT_FAMILY`, `FONT_STYLE`, `FONT_WEIGHT`, `FONT_SIZE`, `LINE_HEIGHT`, `LETTER_SPACING`, `PARAGRAPH_SPACING`, `PARAGRAPH_INDENT`
|
||||
|
||||
**Always set scopes explicitly** — `ALL_SCOPES` is the default but almost never what you want. For a comprehensive scope-to-use-case mapping table, see [token-creation.md § Variable Scopes — Complete Reference Table](../../figma-generate-library/references/token-creation.md).
|
||||
|
||||
**Always check the existing file's scope patterns before creating variables** — match whatever convention is already in use. See "Discovering Existing Variables" below.
|
||||
|
||||
## Variable Aliasing (VARIABLE_ALIAS)
|
||||
|
||||
A variable's value can reference another variable via alias. This is how semantic tokens reference primitive tokens:
|
||||
|
||||
```javascript
|
||||
// Set a variable's value as an alias to another variable
|
||||
semanticVar.setValueForMode(modeId, {
|
||||
type: 'VARIABLE_ALIAS',
|
||||
id: primitiveVar.id
|
||||
});
|
||||
```
|
||||
|
||||
When the primitive changes, the semantic variable updates automatically across all modes.
|
||||
|
||||
## Code Syntax (setVariableCodeSyntax)
|
||||
|
||||
Links a Figma variable back to its code counterpart. Call once per platform:
|
||||
|
||||
```javascript
|
||||
variable.setVariableCodeSyntax('WEB', 'var(--color-bg-default)');
|
||||
variable.setVariableCodeSyntax('ANDROID', 'colorBgDefault');
|
||||
variable.setVariableCodeSyntax('iOS', 'Color.bgDefault');
|
||||
|
||||
// Read back: variable.codeSyntax → { WEB: '...', ANDROID: '...', iOS: '...' }
|
||||
```
|
||||
|
||||
**When deriving CSS names from Figma names**, replace both slashes AND spaces with hyphens:
|
||||
|
||||
```javascript
|
||||
// WRONG — leaves spaces in CSS variable name
|
||||
`var(--${figmaName.replace(/\//g, '-').toLowerCase()})`
|
||||
|
||||
// CORRECT — replace all whitespace and slashes
|
||||
`var(--${figmaName.replace(/[\s\/]+/g, '-').toLowerCase()})`
|
||||
|
||||
// BEST — use the original CSS variable name from the source, not a derived one
|
||||
`var(${token.cssVar})`
|
||||
```
|
||||
|
||||
## Importing Library Variables
|
||||
|
||||
For variables from **team libraries** (not the current file), use `importVariableByKeyAsync`:
|
||||
|
||||
```javascript
|
||||
// Import a single variable by its key
|
||||
const colorVar = await figma.variables.importVariableByKeyAsync("VARIABLE_KEY");
|
||||
// Now use it like any local variable
|
||||
const paint = figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', colorVar
|
||||
);
|
||||
node.fills = [paint];
|
||||
```
|
||||
|
||||
To discover available library variable collections and their variables:
|
||||
|
||||
```javascript
|
||||
// List all available library variable collections
|
||||
const libCollections = await figma.teamLibrary.getAvailableLibraryVariableCollectionsAsync();
|
||||
// Each has: name, key, libraryName
|
||||
|
||||
// Get variables in a specific library collection
|
||||
const libVars = await figma.teamLibrary.getVariablesInLibraryCollectionAsync(libCollections[0].key);
|
||||
// Each has: name, key, resolvedType
|
||||
// Import the ones you need:
|
||||
const imported = await figma.variables.importVariableByKeyAsync(libVars[0].key);
|
||||
```
|
||||
|
||||
**When to import vs. use local:** If `variable.remote === true`, it's from a library — you can reference it directly if already imported, or import by key. If `remote === false`, it's local to the file — use `getVariableByIdAsync` directly.
|
||||
|
||||
## Discovering Existing Variables in the File
|
||||
|
||||
**Always inspect the file's existing variables before creating new ones.** Different files use different naming conventions, scope patterns, and collection structures. Match what's already there.
|
||||
|
||||
### List collections with mode info
|
||||
|
||||
```javascript
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
const results = collections.map(c => ({
|
||||
name: c.name,
|
||||
id: c.id,
|
||||
varCount: c.variableIds.length,
|
||||
modes: c.modes.map(m => ({ name: m.name, id: m.modeId }))
|
||||
}));
|
||||
return results;
|
||||
```
|
||||
|
||||
### Inspect scope patterns used in existing variables
|
||||
|
||||
```javascript
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
const scopeGroups = {};
|
||||
for (const c of collections) {
|
||||
for (const id of c.variableIds) {
|
||||
const v = await figma.variables.getVariableByIdAsync(id);
|
||||
const key = JSON.stringify(v.scopes);
|
||||
if (!scopeGroups[key]) scopeGroups[key] = [];
|
||||
scopeGroups[key].push(v.name);
|
||||
}
|
||||
}
|
||||
return scopeGroups;
|
||||
```
|
||||
|
||||
### Build a name→variable lookup for reuse
|
||||
|
||||
```javascript
|
||||
const varByName = {};
|
||||
for (const v of await figma.variables.getLocalVariablesAsync()) {
|
||||
varByName[v.name] = v;
|
||||
}
|
||||
|
||||
// Bind to existing variable by name — no hex values needed
|
||||
function bindFill(node, varName) {
|
||||
const v = varByName[varName];
|
||||
if (!v) throw new Error(`Variable not found: ${varName}`);
|
||||
const paint = figma.variables.setBoundVariableForPaint(
|
||||
{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', v
|
||||
);
|
||||
node.fills = [paint];
|
||||
}
|
||||
```
|
||||
|
||||
**Only create new variables for tokens that have no match in the file.** After building the lookup, compare against the needed tokens and create variables only for the delta.
|
||||
|
||||
## Listing Collections with Full Variable Details
|
||||
|
||||
The async API returns richer data including code syntax and scopes per variable:
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Lists all local variable collections defined in the current Figma file,
|
||||
* including metadata for their modes and variables.
|
||||
*
|
||||
* @returns {Promise<Array<{
|
||||
* name: string,
|
||||
* id: string,
|
||||
* modes: Array<[name: string, modeId: string]>,
|
||||
* variables: Array<[name: string, id: string, codeSyntax: object, scopes: string[]]>
|
||||
* }>>}
|
||||
*/
|
||||
async function listVariableCollectionsAndVariables() {
|
||||
const collections = await figma.variables.getLocalVariableCollectionsAsync();
|
||||
const results = [];
|
||||
for (const collection of collections) {
|
||||
const vars = [];
|
||||
for (const id of collection.variableIds) {
|
||||
const v = await figma.variables.getVariableByIdAsync(id);
|
||||
vars.push([v.name, v.id, v.codeSyntax, v.scopes]);
|
||||
}
|
||||
results.push({
|
||||
name: collection.name,
|
||||
id: collection.id,
|
||||
modes: collection.modes.map(m => [m.name, m.modeId]),
|
||||
variables: vars
|
||||
});
|
||||
}
|
||||
return results;
|
||||
}
|
||||
```
|
||||
|
||||
Full runnable script:
|
||||
|
||||
```javascript
|
||||
const results = await listVariableCollectionsAndVariables();
|
||||
return results;
|
||||
```
|
||||
|
||||
## Setting and Removing Code Syntax
|
||||
|
||||
Must be executed in the file the variable is defined in:
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Set the code syntax for a variable for a specific platform.
|
||||
*
|
||||
* @param {string} variableId
|
||||
* @param {'WEB'|'ANDROID'|'iOS'} platform
|
||||
* @param {string} syntax
|
||||
*/
|
||||
async function setVariableCodeSyntax(variableId, platform, syntax) {
|
||||
const variable = await figma.variables.getVariableByIdAsync(variableId);
|
||||
variable.setVariableCodeSyntax(platform, syntax);
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove code syntax for a variable for one or more platforms.
|
||||
*
|
||||
* @param {string} variableId
|
||||
* @param {Array<'WEB'|'ANDROID'|'iOS'>} platforms — defaults to all three
|
||||
*/
|
||||
async function removeVariableCodeSyntax(variableId, platforms = ["WEB", "ANDROID", "iOS"]) {
|
||||
const variable = await figma.variables.getVariableByIdAsync(variableId);
|
||||
for (const platform of platforms) {
|
||||
variable.removeVariableCodeSyntax(platform);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Set a value for a variable in a specific mode.
|
||||
* For aliases, value must be: { type: 'VARIABLE_ALIAS', id: '<variableId>' }
|
||||
*
|
||||
* @param {string} variableId
|
||||
* @param {string} modeId
|
||||
* @param {string|number|boolean|RGB|RGBA|{type: 'VARIABLE_ALIAS', id: string}} value
|
||||
*/
|
||||
async function setVariableValueForMode(variableId, modeId, value) {
|
||||
const variable = await figma.variables.getVariableByIdAsync(variableId);
|
||||
variable.setValueForMode(modeId, value);
|
||||
}
|
||||
```
|
||||
|
||||
## Effect Styles (For Shadows)
|
||||
|
||||
Shadows can't be stored as variables. Use effect styles. For comprehensive patterns, see [effect-style-patterns.md](effect-style-patterns.md).
|
||||
|
||||
```javascript
|
||||
const shadow = figma.createEffectStyle();
|
||||
shadow.name = "Shadow/Subtle";
|
||||
shadow.effects = [{
|
||||
type: "DROP_SHADOW",
|
||||
color: { r: 0, g: 0, b: 0, a: 0.06 },
|
||||
offset: { x: 0, y: 2 },
|
||||
radius: 8,
|
||||
spread: 0,
|
||||
visible: true,
|
||||
blendMode: "NORMAL"
|
||||
}];
|
||||
|
||||
// Apply to a node
|
||||
frame.effectStyleId = shadow.id;
|
||||
```
|
||||
+17
@@ -0,0 +1,17 @@
|
||||
# Working with design systems: Creating Components
|
||||
|
||||
When creating Figma components, you need to start by understanding the source and its intent.
|
||||
|
||||
If the user is asking you to create a component based on a design or specification, you need to understand the property model before you build anything. What variants are needed? What text, boolean, or instance swap properties exist? Getting the structure right upfront matters because restructuring a component after instances exist is destructive.
|
||||
|
||||
If you are given a code component as reference (React props, tokens, etc.), your goal is to reflect the property surface as closely as makes sense in Figma's model. Not all code properties translate directly — hover and focus states are not props in web code, but they are variants in Figma. Understand those gaps and make deliberate decisions about how to represent them.
|
||||
|
||||
Variants are the most important thing to get right. Each combination of variant values creates a node on the canvas. Redundant combinations still exist as explicit nodes — there is no way to conditionally exclude them. Define only the axes you actually need.
|
||||
|
||||
Non-variant properties (text, boolean, instance swap) should be added after the variant structure is established. These are defined at the component/component set level and referenced by descendant nodes via `componentPropertyReferences`. Always connect them — a property that isn't wired to a descendant is invisible to users of the component.
|
||||
|
||||
If the user asks you to make architectural decisions, lean toward fewer variants and more boolean/text properties where possible. Variants multiply combinatorially; the other property types do not. An optional slot property in code might be a combination of instance swap and boolean visibility.
|
||||
|
||||
When naming properties, casing is less important since translation layers like Code Connect can do the mapping to represent the code form. Feel free to take a sentence or capitalized case approach for better readability in Figma.
|
||||
|
||||
Keep in mind that components often need to be published and connected to Code Connect for the full design-to-code workflow to work. Creating the component is only one part of the system.
|
||||
+17
@@ -0,0 +1,17 @@
|
||||
# Working with design systems: Using Components
|
||||
|
||||
When using Figma components, you need to start by understanding the state of the source and the state of Figma.
|
||||
|
||||
For the source, you need to know what component is being referenced. This could come from a component key, a node ID, a name, or a Code Connect mapping. If you have a component key from a design system library, prefer `importComponentByKeyAsync` over finding by name, since names are not unique. If you only have a name, search the page or use `search_design_system` to find the right match.
|
||||
|
||||
For Figma, you need to know whether the component is local or in a library. Local components can be accessed directly by node ID. Published library components must be imported first — `importComponentByKeyAsync` or `importComponentSetByKeyAsync` — before an instance can be created.
|
||||
|
||||
Before setting properties on an instance, read `componentPropertyDefinitions` from the main component first. Property names are not simple strings — TEXT, BOOLEAN, and INSTANCE_SWAP properties have a `#uid` suffix (e.g. `"Label#1234"`). Only VARIANT properties are plain names (e.g. `"Size"`). Using the wrong key in `setProperties` will silently do nothing.
|
||||
|
||||
A component might have multiple text properties, which are not possible to derive from text node layer names. Look to the properties to help you understand what values to set, rather than thinking of setting text node characters directly.
|
||||
|
||||
When you need to set a nested instance swap (e.g. an icon property), you need the component key of the swap target, not just its name. Import the target component and pass its node ID.
|
||||
|
||||
Be aware that instances inside other instances are nested and changes made to a nested instance may be treated as overrides. If the intent is to change the default appearance, you need to modify the main component, not the instance.
|
||||
|
||||
When selecting which variant to use, read the `componentProperties` on the instance to see the current state, and `componentPropertyDefinitions` on the main component to see all available options.
|
||||
+50
@@ -0,0 +1,50 @@
|
||||
# Components
|
||||
|
||||
Components overlap a lot with the idea of components in a codebase, but with some gaps and other Figma-specific use cases. Components in Figma can be reusable entities that do not have a comparable library pattern, or they can be published and distributed in a library that is aligned to a code forms.
|
||||
|
||||
Properties can vary from code in different ways, but alignment to code can still happen without a direct relationship. For example, an interactive pattern in code (like a button) can have many states. A lot of these states (active, focused etc) would be expressed in Figma as variants, which is a concept more closely aligned to properties in a code library. In the case of web this is confusing since hover is not a prop, it is a pseudo selector. At the same time, a color variant might be perfectly aligned between design and code (a property in both places). These discrepancies are accounted for in translation with Figma's Code Connect (deterministic context mapping), but in the case of these tools, must be understood to be properly used.
|
||||
|
||||
Figma has four property types, which can be inspected in the component definition's `componentPropertyDefinitions`. To fully understand the component, its descendants must be traversed. Property types include:
|
||||
|
||||
- Variant
|
||||
- This is reflected as permutations of the component in a Component Set on the canvas. Each variant is explicitly visualized, including an redundant permutations ("Small + Primary + Disabled" may look the same as "Small Secondary Sisabled"). These permutations create different variants implicitly in Figma and it is handled through layer naming (`Variant=Primary,Size=Small,State=Disabled`).
|
||||
- Text/String
|
||||
- Text properties are stored on the component parent, but can be mapped to Text node descendants.
|
||||
- `node.componentPropertyReferences.characters` on a descendant text node are how you determine where the text property is referenced (can be multiple, though unlikely).
|
||||
- Boolean
|
||||
- Boolean properties are stored on the component parent, but can be mapped to any node descendant that can have its visibility toggled.
|
||||
- `node.componentPropertyReferences.visible` on a descendant node are how you determine where the boolean property is referenced.
|
||||
- Instance Swap
|
||||
- Instance swap properties are stored on the component parent, but can be mapped to Instance node descendants.
|
||||
- `node.componentPropertyReferences.mainComponent` on a descendant instance node are how you determine where the instance property is referenced. A classic example of this is an icon property.
|
||||
|
||||
## Descriptions
|
||||
|
||||
Components, component sets, and instances all inherit `PublishableMixin`, which includes a writable `description` string. Setting a description is important for any component intended to be used by others — it appears in Figma's dev mode and component panel, and is surfaced in MCP context when reading component metadata.
|
||||
|
||||
Descriptions should explain the component's intent and any non-obvious usage constraints. They are not a substitute for Code Connect annotations, but they are always visible without any tooling setup.
|
||||
|
||||
```js
|
||||
component.description =
|
||||
"Primary action button. Use for the single most important action on a page.";
|
||||
```
|
||||
|
||||
Variant components (children of a component set) also have a `description` field, but in practice the component set description is what users see. Set it on the component set, not on individual variant nodes.
|
||||
|
||||
To read descriptions when auditing:
|
||||
|
||||
```js
|
||||
// Get all component sets and their descriptions
|
||||
figma.root
|
||||
.findAllWithCriteria({ types: ["COMPONENT_SET"] })
|
||||
.map((n) => ({ name: n.name, description: n.description }));
|
||||
```
|
||||
|
||||
## Usage guidelines
|
||||
|
||||
- [Creating components](wwds-components--creating.md): What you must consider when creating new components.
|
||||
- [Using components](wwds-components--using.md): What you must consider when trying to use the right components.
|
||||
|
||||
## Code patterns
|
||||
|
||||
For runnable code examples (creating, importing, discovering, inspecting components), see [component-patterns.md](../component-patterns.md).
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
# Working with design systems: Effect Styles
|
||||
|
||||
Effect styles in Figma are named, reusable definitions of one or more visual effects — drop shadows, inner shadows, and blurs. They are the closest equivalent to a shadow or elevation token in a design system.
|
||||
|
||||
Effect styles are distinct from variables. There is no single variable type that represents a shadow. However, individual numeric and color properties within an effect _can_ be bound to variables, allowing shadow values to participate in a token system.
|
||||
|
||||
## Model
|
||||
|
||||
An `EffectStyle` has one core writable property beyond the base style fields:
|
||||
|
||||
| Property | Type | Notes |
|
||||
| ------------- | ----------------------- | ----------------------------------------------------- |
|
||||
| `name` | `string` | Slash-delimited for grouping (e.g. `"Elevation/200"`) |
|
||||
| `effects` | `ReadonlyArray<Effect>` | **Read-only array** — clone, modify, reassign |
|
||||
| `description` | `string` | Inherited from `BaseStyleMixin` |
|
||||
|
||||
### Effect types
|
||||
|
||||
An `Effect` is a discriminated union. The most common types:
|
||||
|
||||
| `type` | Key properties |
|
||||
| ----------------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| `DROP_SHADOW` | `color: RGBA`, `offset: Vector`, `radius: number`, `spread: number`, `visible: boolean`, `blendMode` |
|
||||
| `INNER_SHADOW` | Same as `DROP_SHADOW` |
|
||||
| `LAYER_BLUR` | `radius: number`, `visible: boolean` |
|
||||
| `BACKGROUND_BLUR` | `radius: number`, `visible: boolean` |
|
||||
|
||||
All colors are in 0–1 range (`RGBA`), not 0–255.
|
||||
|
||||
### Variable bindings on effects
|
||||
|
||||
Effect properties that can be bound to variables (via `setBoundVariableForEffect(effect, field, variable)` on a node, or inline when constructing):
|
||||
|
||||
`color`, `radius`, `spread`, `offsetX`, `offsetY`
|
||||
|
||||
Note: `setBoundVariableForEffect` returns a **new** effect object — you must capture it and reassign the `effects` array.
|
||||
|
||||
### Applying an effect style to a node
|
||||
|
||||
Assign the style's `id` to the node's `effectStyleId`. The node's `effects` property will then reflect the style's values.
|
||||
|
||||
## Common gotchas
|
||||
|
||||
- **`effects` is read-only**: You cannot mutate the array in place. Clone it, modify the clone, then reassign: `style.effects = [...style.effects, newEffect]`.
|
||||
- **Effects stack in order**: The order of effects in the array matters visually. Drop shadows render bottom-to-top.
|
||||
- **Colors are RGBA 0–1**: `{ r: 0, g: 0, b: 0, a: 0.15 }` — not hex, not 0–255.
|
||||
- **`getLocalEffectStyles()` is deprecated**: Always use `getLocalEffectStylesAsync()`.
|
||||
- **Styles are not automatically applied**: Creating an `EffectStyle` has no effect on any node until you assign its ID to a node.
|
||||
|
||||
## Code patterns
|
||||
|
||||
For runnable code examples (listing, creating, applying effect styles), see [effect-style-patterns.md](../effect-style-patterns.md).
|
||||
+90
@@ -0,0 +1,90 @@
|
||||
# Working with design systems: Text Styles
|
||||
|
||||
Text styles in Figma are named, reusable typography definitions. They are the closest equivalent to a type ramp in a design token library. A text style bundles font family, size, weight, line height, letter spacing, and other typographic properties into a single named entity that can be applied to text nodes.
|
||||
|
||||
Text styles are distinct from variables. You cannot put typography into a single variable — there is no composite variable type. However, individual properties on a text style _can_ be bound to variables (e.g. binding `fontSize` to a size variable, or `fontFamily` to a string variable), which allows the style to participate in a token system.
|
||||
|
||||
## Model
|
||||
|
||||
A `TextStyle` has the following writable properties:
|
||||
|
||||
| Property | Type | Notes |
|
||||
| ------------------ | ---------------- | ---------------------------------------------------------------------------- |
|
||||
| `name` | `string` | Slash-delimited for grouping (e.g. `"Heading/XL"`) |
|
||||
| `fontSize` | `number` | In pixels |
|
||||
| `fontName` | `FontName` | `{ family: string, style: string }` — **font must be loaded before setting** |
|
||||
| `letterSpacing` | `LetterSpacing` | `{ value: number, unit: 'PIXELS' \| 'PERCENT' }` |
|
||||
| `lineHeight` | `LineHeight` | `{ value: number, unit: 'PIXELS' \| 'PERCENT' }` or `{ unit: 'AUTO' }` |
|
||||
| `textCase` | `TextCase` | `'ORIGINAL' \| 'UPPER' \| 'LOWER' \| 'TITLE' \| 'SMALL_CAPS'` |
|
||||
| `textDecoration` | `TextDecoration` | `'NONE' \| 'UNDERLINE' \| 'STRIKETHROUGH'` |
|
||||
| `paragraphSpacing` | `number` | |
|
||||
| `paragraphIndent` | `number` | |
|
||||
| `description` | `string` | Inherited from `BaseStyleMixin` |
|
||||
|
||||
### lineHeight and letterSpacing format
|
||||
|
||||
These properties must be objects — not bare numbers:
|
||||
|
||||
```js
|
||||
// WRONG — bare number throws
|
||||
style.lineHeight = 1.5;
|
||||
style.letterSpacing = 0;
|
||||
|
||||
// CORRECT
|
||||
style.lineHeight = { unit: "AUTO" }; // auto line height
|
||||
style.lineHeight = { value: 24, unit: "PIXELS" }; // fixed pixel height
|
||||
style.lineHeight = { value: 150, unit: "PERCENT" }; // 150% line height
|
||||
|
||||
style.letterSpacing = { value: 0, unit: "PIXELS" }; // zero tracking
|
||||
style.letterSpacing = { value: -2, unit: "PIXELS" }; // tight tracking
|
||||
style.letterSpacing = { value: 5, unit: "PERCENT" }; // percent-based tracking
|
||||
```
|
||||
|
||||
When reading a `lineHeight` back, always check `unit` first — `{ unit: 'AUTO' }` has no `value` key.
|
||||
|
||||
### Variable bindings on text styles
|
||||
|
||||
The following fields can be bound to variables via `style.setBoundVariable(field, variable)`:
|
||||
|
||||
`fontFamily`, `fontSize`, `fontStyle`, `fontWeight`, `letterSpacing`, `lineHeight`, `paragraphSpacing`, `paragraphIndent`
|
||||
|
||||
To unbind: `style.setBoundVariable(field, null)`
|
||||
|
||||
**Important: `setBoundVariable` is NOT available on `TextStyle` in headless `use_figma` mode.**
|
||||
|
||||
It is only available in interactive plugin context (UI plugins, Figma editor). When running through `use_figma` (MCP, assistant headless runtime), calling `ts.setBoundVariable(...)` will throw `"not a function"`. In this context, set raw values directly instead:
|
||||
|
||||
```js
|
||||
// In use_figma (headless) — variable binding not available
|
||||
const ts = figma.createTextStyle();
|
||||
ts.fontSize = 24; // set directly; cannot bind to a variable
|
||||
|
||||
// In a real interactive plugin — variable binding works
|
||||
const ts = figma.createTextStyle();
|
||||
ts.setBoundVariable("fontSize", fontSizeVariable);
|
||||
```
|
||||
|
||||
If live variable binding on text styles is required, the recommended approach is to:
|
||||
|
||||
1. Create the text styles with raw values via `use_figma`
|
||||
2. Open the file in Figma and bind variables interactively via the Styles panel, OR
|
||||
3. Use an interactive plugin that runs in the Figma editor (not headless)
|
||||
|
||||
### Applying a text style to a node
|
||||
|
||||
Once you have a `TextStyle`, apply it to a `TextNode` by assigning its `id` to the node's `textStyleId` property. You can also use the async setter `setTextStyleIdAsync(id)`. Setting `textStyleId` on a node does **not** require the font to be loaded — only editing the text content or font properties directly does.
|
||||
|
||||
## Common gotchas
|
||||
|
||||
- **Font must be loaded before setting `fontName`**: Call `await figma.loadFontAsync({ family, style })` before creating or modifying a text style's font.
|
||||
- **Font style names are file-dependent**: Font style names like `"SemiBold"` vs `"Semi Bold"` vary by font provider and Figma file. Always probe by calling `loadFontAsync` and catching errors to discover the correct style string rather than guessing.
|
||||
- **`setBoundVariable` not available headless**: `TextStyle.setBoundVariable()` throws `"not a function"` in `use_figma` / headless mode. Set raw values instead and bind interactively if needed.
|
||||
- **Styles are not automatically applied**: Creating a `TextStyle` has no effect on any node until you assign its ID to a text node.
|
||||
- **`getLocalTextStyles()` is deprecated**: Always use `getLocalTextStylesAsync()`.
|
||||
- **Names are not unique**: Two text styles can share the same name. Match by ID or `key` when looking up a known style, not by name alone.
|
||||
- **Slash grouping is visual only**: `"Heading/XL"` and `"HeadingXL"` are different names; the slash is just a UI affordance.
|
||||
- **`lineHeight` and `letterSpacing` must be objects**: `style.lineHeight = 1.5` throws. Always use `{ value, unit }` format or `{ unit: 'AUTO' }`.
|
||||
|
||||
## Code patterns
|
||||
|
||||
For runnable code examples (listing, creating, probing fonts, type ramps, applying styles), see [text-style-patterns.md](../text-style-patterns.md).
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
# Working with design systems: Creating Variables
|
||||
|
||||
When creating Figma variables, you need to start by understanding the state of the source data.
|
||||
|
||||
If the user is asking you to create variables based on values, they likely want you to indicate the structure. Whether or not you use semantic aliasing primitive will be based on the inputs you are given about the source data.
|
||||
|
||||
If you are given code inputs (JSON, CSS, etc) your goal should be to reflect the existing patterns as closely as possible, but also embrace the design context as distinct from code. For example, casing is less important since you have code syntax that can directly represent the code form. Feel free to take a sentence or capitalized case approach for better readability in Figma.
|
||||
|
||||
It is important to understand the underlying structure before you create anything. If there is an implied aliased setup, you want to get that right. You may also need to anticipate modes to know how to split things up. Sizes and Colors likely have different mode requirements in complex systems, so you want to consider that as you create the structure.
|
||||
|
||||
If someone asks you to just make a decision based on best practices, that answer will be relative to the complexity of the environment. A simple theme is great best practice for simple needs. Similarly, a complex extended collection setup for someone on an enterprise plan might also be best practice as well.
|
||||
|
||||
Keep in mind that systems might also require you to handle text and effect styles for some of the things specified in token libraries.
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
# Working with design systems: Using Variables
|
||||
|
||||
When using Figma variables, you need to start by understanding the state of the source and the state of Figma.
|
||||
|
||||
For the source, you need to know the breadth of variables code representation. CSS, JSON, theme providers etc will all be able to indicate what the user will expect you to cover in Figma. Some beginner users might not even know what does and doesn't exist in Figma, and if you cant discover that on your own, you will need their help making the right decision.
|
||||
|
||||
For Figma, you need to know what collections exist, what their modes are, and what values and names and code syntaxes are in them. This will help you make sure you are using the right things. For properties that "should" have variables but don't, you likely will need to ask the user what to do. Your understanding of Figma's current state should come first.
|
||||
|
||||
You can use code syntax and your understanding of the environment you are expected to be referencing to know which variable in Figma to use. You can also use Figma's variable scopes as indicators if they are specified. It is best to audit those up front.
|
||||
|
||||
When using variables you should also be aware of mode mismatches, the default mode in Figma may not be the mode referenced by the user in their expectations. Similarly, many collections may refer to values, but the most specific collection is what you should be using. For example, a semantic collection that aliases a primitive collection, the semantic collection would be what you reference. A component token collection (eg. button/background/primary) might alias a semantic collection, and it is the component collection you need to reference. In some other examples, there may be no aliasing and you're simply value matching.
|
||||
|
||||
Gap and padding values for frames are really important and often have to be interpreted semantically or based on layout component values.
|
||||
+64
@@ -0,0 +1,64 @@
|
||||
# Working with design systems: Variables
|
||||
|
||||
Variables overlap a lot with the idea of tokens in a codebase, but with some gaps and other Figma-specific use cases. Variables are single value, number, string, color, boolean.
|
||||
|
||||
In Figma you can do conditional logic and use variables to get basic prototyping functionality. String values can also be used as sophisticated placeholder setups that have different modes for different languages. Not everything you use a variable for in Figma would be used exactly the same way in code. However, for design systems, they are often synced to code in some way.
|
||||
|
||||
One gap is the lack of composite tokens. You can't put a box shadow behind a single variable. That is an [effect style](wwds-effect-styles.md), but style values can be bound to variables. Similarly for a type ramp, you have to use [Text Styles](wwds-text-styles.md).
|
||||
|
||||
## Model
|
||||
|
||||
### Collections
|
||||
|
||||
Collections can be thought of a groups in Figma. An example Collection would be "Colors" where there might be a light and dark "Mode." Each value would have two definitions.
|
||||
|
||||
### Extended Collections
|
||||
|
||||
Extended collections allow you to create a colleciton based on another collection and only override _some_ of the values. Just like inheritance and overrides in CSS. This aligns well for scenarios like branded color themes.
|
||||
|
||||
### Modes
|
||||
|
||||
Modes in Figma can be thought of like light and dark, but users can specify modes for anything, including sizes, languages (string variables exist in Figma too).
|
||||
|
||||
### Aliasing
|
||||
|
||||
Aliasing in Figma variables is simply when you point a variable to another variable. Common example is pointing a semantic variable to a primitive variable. Some teams also do component level tokens which adds a third component specific layer.
|
||||
|
||||
**Decision rule:** If the source data has two tiers (primitives + semantics), create all primitives first, then create semantic variables that alias into them. If the source data is a single flat tier, create flat variables with no aliases. When in doubt, ask.
|
||||
|
||||
### Code Syntax
|
||||
|
||||
Code syntax is a surface area in Figma for codebase translation context. You can set WEB, iOS, and ANDROID code syntax on any variable, and when that variable is referenced in other places (visually in Figma's dev mode, as design context via MCP), this codebase form will appear. These are best thought of as "instance" documentation, eg. `var(--the-thing)` instead of `--the-thing` in the case of CSS.
|
||||
|
||||
### Scope
|
||||
|
||||
`variable.scopes: VariableScope[]` specifies which properties in Figma the variable can be used for. This is important when you create and when you use variables. **Always set specific scopes rather than leaving the default `ALL_SCOPES`** — it pollutes every property picker with irrelevant tokens. The more specific the better. For the canonical scope-to-use-case mapping, see [token-creation.md § Variable Scopes — Complete Reference Table](../../figma-generate-library/references/token-creation.md).
|
||||
|
||||
Common scope values:
|
||||
|
||||
- `ALL_SCOPES` — unrestricted; **avoid this** — it is the default but almost never the right choice. Only acceptable for very simple files with a handful of variables where the overhead of precise scoping isn't justified
|
||||
- `FRAME_FILL`, `SHAPE_FILL`, `TEXT_FILL`, `STROKE_COLOR` — color bindings (use specific fill scopes; `ALL_FILLS` covers all three fill scopes together)
|
||||
- `TEXT_CONTENT` — string variables for text layers
|
||||
- `FONT_SIZE`, `FONT_WEIGHT`, `LINE_HEIGHT`, `LETTER_SPACING` — typography
|
||||
- `CORNER_RADIUS`, `WIDTH_HEIGHT`, `GAP` — layout/spacing
|
||||
- `OPACITY` — layer opacity
|
||||
|
||||
### Grouping
|
||||
|
||||
Variable names in Figma are slash delimited and each slash represents a group that is visualized in Figma. When you are doing matching, consider a part of a code prefix might be the name of the collection, not a top level group. Sometimes you will have prefixes in code that aren't in Figma, and that can be ok, just be sure to ask if it is unclear. You can always validate existing variables by referencing the code syntax.
|
||||
|
||||
## Common gotchas
|
||||
|
||||
- **`createVariableCollection` always creates a default mode** — you will need to rename it (or delete it and add your own) rather than creating from scratch.
|
||||
- **Duplicate variable names throw silently** — Figma does not error; it creates a second variable with the same name. Always check for existence before creating.
|
||||
- **Variable aliases require the target to be in the same file** — cross-file aliasing is not supported via the plugin API. If you need to alias to a library variable, import it first.
|
||||
- **`setValueForMode` with an alias requires the exact shape** — `{ type: 'VARIABLE_ALIAS', id: '<variableId>' }`. Any deviation will silently set the wrong value or throw.
|
||||
|
||||
## Usage guidelines
|
||||
|
||||
- [Creating variables](wwds-variables--creating.md): What you must consider when creating new variables.
|
||||
- [Using variables](wwds-variables--using.md): What you must consider when trying to use the right variables.
|
||||
|
||||
## Code patterns
|
||||
|
||||
For runnable code examples (creating collections, binding variables, scopes, aliasing, discovering existing variables), see [variable-patterns.md](../variable-patterns.md).
|
||||
+41
@@ -0,0 +1,41 @@
|
||||
# Working with design systems
|
||||
|
||||
When working with design systems in Figma, there can be many nuances when deciding how to do the right thing. Figma's model for patterns is form-agnostic, this is one of its strengths, allowing people to refer to a pattern in a spec that may take distinct forms in different codebases. However, this can result in complex procedures and nuances when translating something to Figma and back. Figma has components, tokens, and other reusable patterns (text and effect styles, prototyping actions, etc). The way that Figma's paradigms function can be difficult to translate one to one.
|
||||
|
||||
To make translation of patterns work between design and code forms, it is important that teams think about alignment while also embracing the function of representation (design) and implementation (production) forms independently as complementary pieces of a shared puzzle.
|
||||
|
||||
For the process of design, the desirable state of a system is something that is structured with experimentation in mind, something that is highly visual, easy to iterate, test, and confirm new ideas. Depending on the product and team, exploration might be mandatory to be done within the confines of an existing system, for other scenarios, exploration of new territory is the priority, a place for the system to grow into, or a new system to be made. Figma's platform allows for teams to validate, align, and collaborate on new ideas, then solidify them in product designs, which are ultimately specs. That work is supported by design libraries and that process can include code in prototypes and other less permanent forms as much as it does Figma's native paradigms.
|
||||
|
||||
For the process of implementation, the desirable state for production code is rigidity, efficiency, and related to secure data and functional layers. Developer experience implementing a design and the designer experience surfacing and committing to an idea are paths from distinct points of to the same shared outcome. Their optimization looks different, and that is reflected when you engage with Figma's APIs.
|
||||
|
||||
The key is not to avoid gaps, but to make sure they are definitively bridgable. Translation layers help agents and people go between representational and production forms.
|
||||
|
||||
The Figma paradigms you will need to understand when working with design systems. In each file below there will be further links to instructions for using and creating:
|
||||
|
||||
- [Components](wwds-components.md)
|
||||
- [Variables](wwds-variables.md)
|
||||
- [Effect Styles](wwds-effect-styles.md)
|
||||
- [Text Styles](wwds-text-styles.md)
|
||||
|
||||
Things you might be asked to do with respect to design systems:
|
||||
|
||||
- Create patterns in Figma that match patterns in code
|
||||
- Likely (but not exclusively) to get up to speed so that visual riffing can be done in Figma
|
||||
- Create variables based on a stylesheet, JSON format, some other theme definition
|
||||
- Create Figma text styles that match a type hierarchy defined somewhere
|
||||
- Create components based on existing code components
|
||||
- Sync between code and design forms
|
||||
- Making sure that Figma's concepts match a production form
|
||||
- Use an existing Figma design library to create something
|
||||
- This something could be matching an existing code form, an image, or just a prompt
|
||||
- Clean up a design to match some code pattern
|
||||
|
||||
## Things to remember
|
||||
|
||||
Many people will use these tools to try out ideas, and not everything you get asked to do will feel realistic for the environment you are running in. It is important to contextualize that, but then also know when you are definitively working in a production environment and there is a very real task you need to perform consistently.
|
||||
|
||||
Not everyone asking you to do something knows what they should be doing. You must figure out if the request is to generically perform design systems actions, uphold existing the rules that are codified in Figma or in a codebase, demonstrate an idea, enforce existing guidelines, etc.
|
||||
|
||||
Not every environment you are working in has the same degree of expertise and maturity. Some systems will be very complex and the priority and have a lot of things to parse through to get to the right outcome. Some scenarios will be very immature and even starting from scratch. Something as simple as creating a component could be very elementary or very sophisticated depending on the environment. The instructions you find here are attempting to be unbiased.
|
||||
|
||||
For example, how you reflect the "hover" state of a button could be left entirely up to you to make a reasonable decision for a user that is playing around with getting a decent example scaffolded using best practices, but it could also be something that exists definitively in the codebase and you need to go match it. That codebase definition could be refering to design tokens that do not yet exist in code that change dark and light mode values. In this second example you are now needing to do a bunch of variables work just to add a hover state to a component with proper dark and light mode support, where in the first scenario, you can kinda just do whatever is easiest. This is the line you will be walking, and making good judgement here is about doing whatever is the smartest thing in the environment you are in.
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
name: add-mcp-server
|
||||
description: Use this skill when helping users add MCP servers to their Warp configuration.
|
||||
---
|
||||
|
||||
# Adding MCP Servers to Warp
|
||||
|
||||
Warp supports MCP servers via native config files. Follow these steps when helping a user add an MCP server.
|
||||
|
||||
## Step 1: Determine Scope
|
||||
|
||||
If the user hasn't specified, ask whether they want to configure the server **globally** (for all projects) or **project-scoped** (for a specific repository only).
|
||||
|
||||
Config file paths:
|
||||
- **Global (user-scoped):** `~/.warp/.mcp.json`
|
||||
- **Project-scoped:** `{repo_root}/.warp/.mcp.json`
|
||||
|
||||
## Step 2: Gather Server Details
|
||||
|
||||
If the user hasn't provided the server's connection details, use WebSearch to find the correct configuration for the named server.
|
||||
|
||||
If it's unclear whether the server should be run as a local CLI process (stdio transport) or connected to via URL (HTTP/SSE streaming transport), ask the user which they prefer.
|
||||
|
||||
## Step 3: Check and Prepare the Config File
|
||||
|
||||
Check whether the target config file exists.
|
||||
|
||||
- **If it does not exist**, create it with `mkdir -p` for the directory and initialize it with an empty `mcpServers` wrapper key:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {}
|
||||
}
|
||||
```
|
||||
|
||||
- **If it exists**, read it to determine which top-level wrapper key is already in use. Recognized wrapper keys (in order of preference):
|
||||
- `mcpServers` *(preferred)*
|
||||
- `mcp_servers`
|
||||
- `servers`
|
||||
- `mcp.servers` (nested under a `mcp` key)
|
||||
- Flat map (each top-level key is a server name)
|
||||
|
||||
Preserve the existing wrapper key when writing. If the existing key is unrecognized or incompatible, switch to `mcpServers`.
|
||||
|
||||
**Never remove existing server entries** — only add or update the new server.
|
||||
|
||||
## Step 4: Write the Server Configuration
|
||||
|
||||
### Command-based server (stdio transport)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"server-name": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@scope/package-name"],
|
||||
"env": {
|
||||
"API_KEY": "${API_KEY}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### URL-based server (HTTP/SSE streaming transport)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"server-name": {
|
||||
"url": "https://example.com/mcp",
|
||||
"env": {
|
||||
"API_KEY": "${API_KEY}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For environment variables containing secrets, use `${VAR_NAME}` syntax — Warp will substitute the value from the user's environment at runtime.
|
||||
|
||||
## Notes
|
||||
|
||||
- Warp auto-detects changes to `.mcp.json` files on save — no restart required.
|
||||
- Configured servers appear in Warp's Settings under MCP, labeled **"Detected from Warp"**.
|
||||
- Global config applies across all sessions; project config only applies when working inside that repository.
|
||||
@@ -0,0 +1,202 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright 2026 Anthropic, PBC.
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
@@ -0,0 +1,324 @@
|
||||
---
|
||||
name: claude-api
|
||||
description: "Build, debug, and optimize Claude API / Anthropic SDK apps. Apps built with this skill should include prompt caching. Also handles migrating existing Claude API code between Claude model versions (4.5 → 4.6, 4.6 → 4.7, retired-model replacements). TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`; user asks for the Claude API, Anthropic SDK, or Managed Agents; user adds/modifies/tunes a Claude feature (caching, thinking, compaction, tool use, batch, files, citations, memory) or model (Opus/Sonnet/Haiku) in a file; questions about prompt caching / cache hit rate in an Anthropic SDK project. SKIP: file imports `openai`/other-provider SDK, filename like `*-openai.py`/`*-generic.py`, provider-neutral code, general programming/ML."
|
||||
license: Complete terms in LICENSE.txt
|
||||
---
|
||||
|
||||
# Building LLM-Powered Applications with Claude
|
||||
|
||||
This skill helps you build LLM-powered applications with Claude. Choose the right surface based on your needs, detect the project language, then read the relevant language-specific documentation.
|
||||
|
||||
## Before You Start
|
||||
|
||||
Scan the target file (or, if no target file, the prompt and project) for non-Anthropic provider markers — `import openai`, `from openai`, `langchain_openai`, `OpenAI(`, `gpt-4`, `gpt-5`, file names like `agent-openai.py` or `*-generic.py`, or any explicit instruction to keep the code provider-neutral. If you find any, stop and tell the user that this skill produces Claude/Anthropic SDK code; ask whether they want to switch the file to Claude or want a non-Claude implementation. Do not edit a non-Anthropic file with Anthropic SDK calls.
|
||||
|
||||
## Output Requirement
|
||||
|
||||
When the user asks you to add, modify, or implement a Claude feature, your code must call Claude through one of:
|
||||
|
||||
1. **The official Anthropic SDK** for the project's language (`anthropic`, `@anthropic-ai/sdk`, `com.anthropic.*`, etc.). This is the default whenever a supported SDK exists for the project.
|
||||
2. **Raw HTTP** (`curl`, `requests`, `fetch`, `httpx`, etc.) — only when the user explicitly asks for cURL/REST/raw HTTP, the project is a shell/cURL project, or the language has no official SDK.
|
||||
|
||||
Never mix the two — don't reach for `requests`/`fetch` in a Python or TypeScript project just because it feels lighter. Never fall back to OpenAI-compatible shims.
|
||||
|
||||
**Never guess SDK usage.** Function names, class names, namespaces, method signatures, and import paths must come from explicit documentation — either the `{lang}/` files in this skill or the official SDK repositories or documentation links listed in `shared/live-sources.md`. If the binding you need is not explicitly documented in the skill files, WebFetch the relevant SDK repo from `shared/live-sources.md` before writing code. Do not infer Ruby/Java/Go/PHP/C# APIs from cURL shapes or from another language's SDK.
|
||||
|
||||
## Defaults
|
||||
|
||||
Unless the user requests otherwise:
|
||||
|
||||
For the Claude model version, please use Claude Opus 4.7, which you can access via the exact model string `claude-opus-4-7`. Please default to using adaptive thinking (`thinking: {type: "adaptive"}`) for anything remotely complicated. And finally, please default to streaming for any request that may involve long input, long output, or high `max_tokens` — it prevents hitting request timeouts. Use the SDK's `.get_final_message()` / `.finalMessage()` helper to get the complete response if you don't need to handle individual stream events
|
||||
|
||||
---
|
||||
|
||||
## Subcommands
|
||||
|
||||
If the User Request at the bottom of this prompt is a bare subcommand string (no prose), search every **Subcommands** table in this document — including any in sections appended below — and follow the matching Action column directly. This lets users invoke specific flows via `/claude-api <subcommand>`. If no table in the document matches, treat the request as normal prose.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Language Detection
|
||||
|
||||
Before reading code examples, determine which language the user is working in:
|
||||
|
||||
1. **Look at project files** to infer the language:
|
||||
|
||||
- `*.py`, `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` → **Python** — read from `python/`
|
||||
- `*.ts`, `*.tsx`, `package.json`, `tsconfig.json` → **TypeScript** — read from `typescript/`
|
||||
- `*.js`, `*.jsx` (no `.ts` files present) → **TypeScript** — JS uses the same SDK, read from `typescript/`
|
||||
- `*.java`, `pom.xml`, `build.gradle` → **Java** — read from `java/`
|
||||
- `*.kt`, `*.kts`, `build.gradle.kts` → **Java** — Kotlin uses the Java SDK, read from `java/`
|
||||
- `*.scala`, `build.sbt` → **Java** — Scala uses the Java SDK, read from `java/`
|
||||
- `*.go`, `go.mod` → **Go** — read from `go/`
|
||||
- `*.rb`, `Gemfile` → **Ruby** — read from `ruby/`
|
||||
- `*.cs`, `*.csproj` → **C#** — read from `csharp/`
|
||||
- `*.php`, `composer.json` → **PHP** — read from `php/`
|
||||
|
||||
2. **If multiple languages detected** (e.g., both Python and TypeScript files):
|
||||
|
||||
- Check which language the user's current file or question relates to
|
||||
- If still ambiguous, ask: "I detected both Python and TypeScript files. Which language are you using for the Claude API integration?"
|
||||
|
||||
3. **If language can't be inferred** (empty project, no source files, or unsupported language):
|
||||
|
||||
- Use AskUserQuestion with options: Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP
|
||||
- If AskUserQuestion is unavailable, default to Python examples and note: "Showing Python examples. Let me know if you need a different language."
|
||||
|
||||
4. **If unsupported language detected** (Rust, Swift, C++, Elixir, etc.):
|
||||
|
||||
- Suggest cURL/raw HTTP examples from `curl/` and note that community SDKs may exist
|
||||
- Offer to show Python or TypeScript examples as reference implementations
|
||||
|
||||
5. **If user needs cURL/raw HTTP examples**, read from `curl/`.
|
||||
|
||||
### Language-Specific Feature Support
|
||||
|
||||
| Language | Tool Runner | Managed Agents | Notes |
|
||||
| ---------- | ----------- | -------------- | ------------------------------------- |
|
||||
| Python | Yes (beta) | Yes (beta) | Full support — `@beta_tool` decorator |
|
||||
| TypeScript | Yes (beta) | Yes (beta) | Full support — `betaZodTool` + Zod |
|
||||
| Java | Yes (beta) | Yes (beta) | Beta tool use with annotated classes |
|
||||
| Go | Yes (beta) | Yes (beta) | `BetaToolRunner` in `toolrunner` pkg |
|
||||
| Ruby | Yes (beta) | Yes (beta) | `BaseTool` + `tool_runner` in beta |
|
||||
| C# | No | No | Official SDK |
|
||||
| PHP | Yes (beta) | Yes (beta) | `BetaRunnableTool` + `toolRunner()` |
|
||||
| cURL | N/A | Yes (beta) | Raw HTTP, no SDK features |
|
||||
|
||||
> **Managed Agents code examples**: dedicated language-specific READMEs are provided for Python, TypeScript, Go, Ruby, PHP, Java, and cURL (`{lang}/managed-agents/README.md`, `curl/managed-agents.md`). Read your language's README plus the language-agnostic `shared/managed-agents-*.md` concept files. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. If a binding you need isn't shown in the README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# does not currently have Managed Agents support; use cURL-style raw HTTP requests against the API.
|
||||
|
||||
---
|
||||
|
||||
## Which Surface Should I Use?
|
||||
|
||||
> **Start simple.** Default to the simplest tier that meets your needs. Single API calls and workflows handle most use cases — only reach for agents when the task genuinely requires open-ended, model-driven exploration.
|
||||
|
||||
| Use Case | Tier | Recommended Surface | Why |
|
||||
| ----------------------------------------------- | --------------- | ------------------------- | ------------------------------------------------------------ |
|
||||
| Classification, summarization, extraction, Q&A | Single LLM call | **Claude API** | One request, one response |
|
||||
| Batch processing or embeddings | Single LLM call | **Claude API** | Specialized endpoints |
|
||||
| Multi-step pipelines with code-controlled logic | Workflow | **Claude API + tool use** | You orchestrate the loop |
|
||||
| Custom agent with your own tools | Agent | **Claude API + tool use** | Maximum flexibility |
|
||||
| Server-managed stateful agent with workspace | Agent | **Managed Agents** | Anthropic runs the loop and hosts the tool-execution sandbox |
|
||||
| Persisted, versioned agent configs | Agent | **Managed Agents** | Agents are stored objects; sessions pin to a version |
|
||||
| Long-running multi-turn agent with file mounts | Agent | **Managed Agents** | Per-session containers, SSE event stream, Skills + MCP |
|
||||
|
||||
> **Note:** Managed Agents is the right choice when you want Anthropic to run the agent loop *and* host the container where tools execute — file ops, bash, code execution all run in the per-session workspace. If you want to host the compute yourself or run your own custom tool runtime, Claude API + tool use is the right choice — use the tool runner for automatic loop handling, or the manual loop for fine-grained control (approval gates, custom logging, conditional execution).
|
||||
|
||||
> **Third-party providers (Amazon Bedrock, Google Vertex AI, Microsoft Foundry):** Managed Agents is **not available** on Bedrock, Vertex, or Foundry. If you are deploying through any third-party provider, use **Claude API + tool use** for all use cases — including ones where Managed Agents would otherwise be the recommended surface.
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```
|
||||
What does your application need?
|
||||
|
||||
0. Are you deploying through Amazon Bedrock, Google Vertex AI, or Microsoft Foundry?
|
||||
└── Yes → Claude API (+ tool use for agents) — Managed Agents is 1P only.
|
||||
No → continue.
|
||||
|
||||
1. Single LLM call (classification, summarization, extraction, Q&A)
|
||||
└── Claude API — one request, one response
|
||||
|
||||
2. Do you want Anthropic to run the agent loop and host a per-session
|
||||
container where Claude executes tools (bash, file ops, code)?
|
||||
└── Yes → Managed Agents — server-managed sessions, persisted agent configs,
|
||||
SSE event stream, Skills + MCP, file mounts.
|
||||
Examples: "stateful coding agent with a workspace per task",
|
||||
"long-running research agent that streams events to a UI",
|
||||
"agent with persisted, versioned config used across many sessions"
|
||||
|
||||
3. Workflow (multi-step, code-orchestrated, with your own tools)
|
||||
└── Claude API with tool use — you control the loop
|
||||
|
||||
4. Open-ended agent (model decides its own trajectory, your own tools, you host the compute)
|
||||
└── Claude API agentic loop (maximum flexibility)
|
||||
```
|
||||
|
||||
### Should I Build an Agent?
|
||||
|
||||
Before choosing the agent tier, check all four criteria:
|
||||
|
||||
- **Complexity** — Is the task multi-step and hard to fully specify in advance? (e.g., "turn this design doc into a PR" vs. "extract the title from this PDF")
|
||||
- **Value** — Does the outcome justify higher cost and latency?
|
||||
- **Viability** — Is Claude capable at this task type?
|
||||
- **Cost of error** — Can errors be caught and recovered from? (tests, review, rollback)
|
||||
|
||||
If the answer is "no" to any of these, stay at a simpler tier (single call or workflow).
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
Everything goes through `POST /v1/messages`. Tools and output constraints are features of this single endpoint — not separate APIs.
|
||||
|
||||
**User-defined tools** — You define tools (via decorators, Zod schemas, or raw JSON), and the SDK's tool runner handles calling the API, executing your functions, and looping until Claude is done. For full control, you can write the loop manually.
|
||||
|
||||
**Server-side tools** — Anthropic-hosted tools that run on Anthropic's infrastructure. Code execution is fully server-side (declare it in `tools`, Claude runs code automatically). Computer use can be server-hosted or self-hosted.
|
||||
|
||||
**Structured outputs** — Constrains the Messages API response format (`output_config.format`) and/or tool parameter validation (`strict: true`). The recommended approach is `client.messages.parse()` which validates responses against your schema automatically. Note: the old `output_format` parameter is deprecated; use `output_config: {format: {...}}` on `messages.create()`.
|
||||
|
||||
**Supporting endpoints** — Batches (`POST /v1/messages/batches`), Files (`POST /v1/files`), Token Counting, and Models (`GET /v1/models`, `GET /v1/models/{id}` — live capability/context-window discovery) feed into or support Messages API requests.
|
||||
|
||||
---
|
||||
|
||||
## Current Models (cached: 2026-04-15)
|
||||
|
||||
| Model | Model ID | Context | Input $/1M | Output $/1M |
|
||||
| ----------------- | ------------------- | -------------- | ---------- | ----------- |
|
||||
| Claude Opus 4.7 | `claude-opus-4-7` | 1M | $5.00 | $25.00 |
|
||||
| Claude Opus 4.6 | `claude-opus-4-6` | 1M | $5.00 | $25.00 |
|
||||
| Claude Sonnet 4.6 | `claude-sonnet-4-6` | 1M | $3.00 | $15.00 |
|
||||
| Claude Haiku 4.5 | `claude-haiku-4-5` | 200K | $1.00 | $5.00 |
|
||||
|
||||
**ALWAYS use `claude-opus-4-7` unless the user explicitly names a different model.** This is non-negotiable. Do not use `claude-sonnet-4-6`, `claude-sonnet-4-5`, or any other model unless the user literally says "use sonnet" or "use haiku". Never downgrade for cost — that's the user's decision, not yours.
|
||||
|
||||
**CRITICAL: Use only the exact model ID strings from the table above — they are complete as-is. Do not append date suffixes.** For example, use `claude-sonnet-4-5`, never `claude-sonnet-4-5-20250514` or any other date-suffixed variant you might recall from training data. If the user requests an older model not in the table (e.g., "opus 4.5", "sonnet 3.7"), read `shared/models.md` for the exact ID — do not construct one yourself.
|
||||
|
||||
A note: if any of the model strings above look unfamiliar to you, that's to be expected — that just means they were released after your training data cutoff. Rest assured they are real models; we wouldn't mess with you like that.
|
||||
|
||||
**Live capability lookup:** The table above is cached. When the user asks "what's the context window for X", "does X support vision/thinking/effort", or "which models support Y", query the Models API (`client.models.retrieve(id)` / `client.models.list()`) — see `shared/models.md` for the field reference and capability-filter examples.
|
||||
|
||||
---
|
||||
|
||||
## Thinking & Effort (Quick Reference)
|
||||
|
||||
**Opus 4.7 — Adaptive thinking only:** Use `thinking: {type: "adaptive"}`. `thinking: {type: "enabled", budget_tokens: N}` returns a 400 on Opus 4.7 — adaptive is the only on-mode. `{type: "disabled"}` and omitting `thinking` both work. Sampling parameters (`temperature`, `top_p`, `top_k`) are also removed and will 400. See `shared/model-migration.md` → Migrating to Opus 4.7 for the full breaking-change list.
|
||||
**Opus 4.6 — Adaptive thinking (recommended):** Use `thinking: {type: "adaptive"}`. Claude dynamically decides when and how much to think. No `budget_tokens` needed — `budget_tokens` is deprecated on Opus 4.6 and Sonnet 4.6 and should not be used for new code. Adaptive thinking also automatically enables interleaved thinking (no beta header needed). **When the user asks for "extended thinking", a "thinking budget", or `budget_tokens`: always use Opus 4.7 or 4.6 with `thinking: {type: "adaptive"}`. The concept of a fixed token budget for thinking is deprecated — adaptive thinking replaces it. Do NOT use `budget_tokens` for new 4.6/4.7 code and do NOT switch to an older model.** *Gradual-migration carve-out:* `budget_tokens` is still functional on Opus 4.6 and Sonnet 4.6 as a transitional escape hatch — if you're migrating existing code and need a hard token ceiling before you've tuned `effort`, see `shared/model-migration.md` → Transitional escape hatch. Note: this carve-out does **not** apply to Opus 4.7 — `budget_tokens` is fully removed there.
|
||||
**Effort parameter (GA, no beta header):** Controls thinking depth and overall token spend via `output_config: {effort: "low"|"medium"|"high"|"max"}` (inside `output_config`, not top-level). Default is `high` (equivalent to omitting it). `max` is Opus-tier only (Opus 4.6 and later — not Sonnet or Haiku). Opus 4.7 adds `"xhigh"` (between `high` and `max`) — the best setting for most coding and agentic use cases on 4.7, and the default in Claude Code; use a minimum of `high` for most intelligence-sensitive work. Works on Opus 4.5, Opus 4.6, Opus 4.7, and Sonnet 4.6. Will error on Sonnet 4.5 / Haiku 4.5. On Opus 4.7, effort matters more than on any prior Opus — re-tune it when migrating. Combine with adaptive thinking for the best cost-quality tradeoffs. Lower effort means fewer and more-consolidated tool calls, less preamble, and terser confirmations — `high` is often the sweet spot balancing quality and token efficiency; use `max` when correctness matters more than cost; use `low` for subagents or simple tasks.
|
||||
|
||||
**Opus 4.7 — thinking content omitted by default:** `thinking` blocks still stream but their text is empty unless you opt in with `thinking: {type: "adaptive", display: "summarized"}` (default is `"omitted"`). Silent change — no error. If you stream reasoning to users, the default looks like a long pause before output; set `"summarized"` to restore visible progress.
|
||||
|
||||
**Task Budgets (beta, Opus 4.7):** `output_config: {task_budget: {type: "tokens", total: N}}` tells the model how many tokens it has for a full agentic loop — it sees a running countdown and self-moderates (minimum 20,000; beta header `task-budgets-2026-03-13`). Distinct from `max_tokens`, which is an enforced per-response ceiling the model is not aware of. See `shared/model-migration.md` → Task Budgets.
|
||||
|
||||
**Sonnet 4.6:** Supports adaptive thinking (`thinking: {type: "adaptive"}`). `budget_tokens` is deprecated on Sonnet 4.6 — use adaptive thinking instead.
|
||||
|
||||
**Older models (only if explicitly requested):** If the user specifically asks for Sonnet 4.5 or another older model, use `thinking: {type: "enabled", budget_tokens: N}`. `budget_tokens` must be less than `max_tokens` (minimum 1024). Never choose an older model just because the user mentions `budget_tokens` — use Opus 4.7 with adaptive thinking instead.
|
||||
|
||||
---
|
||||
|
||||
## Compaction (Quick Reference)
|
||||
|
||||
**Beta, Opus 4.7, Opus 4.6, and Sonnet 4.6.** For long-running conversations that may exceed the 1M context window, enable server-side compaction. The API automatically summarizes earlier context when it approaches the trigger threshold (default: 150K tokens). Requires beta header `compact-2026-01-12`.
|
||||
|
||||
**Critical:** Append `response.content` (not just the text) back to your messages on every turn. Compaction blocks in the response must be preserved — the API uses them to replace the compacted history on the next request. Extracting only the text string and appending that will silently lose the compaction state.
|
||||
|
||||
See `{lang}/claude-api/README.md` (Compaction section) for code examples. Full docs via WebFetch in `shared/live-sources.md`.
|
||||
|
||||
---
|
||||
|
||||
## Prompt Caching (Quick Reference)
|
||||
|
||||
**Prefix match.** Any byte change anywhere in the prefix invalidates everything after it. Render order is `tools` → `system` → `messages`. Keep stable content first (frozen system prompt, deterministic tool list), put volatile content (timestamps, per-request IDs, varying questions) after the last `cache_control` breakpoint.
|
||||
|
||||
**Top-level auto-caching** (`cache_control: {type: "ephemeral"}` on `messages.create()`) is the simplest option when you don't need fine-grained placement. Max 4 breakpoints per request. Minimum cacheable prefix is ~1024 tokens — shorter prefixes silently won't cache.
|
||||
|
||||
**Verify with `usage.cache_read_input_tokens`** — if it's zero across repeated requests, a silent invalidator is at work (`datetime.now()` in system prompt, unsorted JSON, varying tool set).
|
||||
|
||||
For placement patterns, architectural guidance, and the silent-invalidator audit checklist: read `shared/prompt-caching.md`. Language-specific syntax: `{lang}/claude-api/README.md` (Prompt Caching section).
|
||||
|
||||
---
|
||||
|
||||
## Managed Agents (Beta)
|
||||
|
||||
**Managed Agents** is a third surface: server-managed stateful agents with Anthropic-hosted tool execution. You create a persisted, versioned Agent config (`POST /v1/agents`), then start Sessions that reference it. Each session provisions a container as the agent's workspace — bash, file ops, and code execution run there; the agent loop itself runs on Anthropic's orchestration layer and acts on the container via tools. The session streams events; you send messages and tool results back.
|
||||
|
||||
**Managed Agents is first-party only.** It is not available on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. For agents on third-party providers, use Claude API + tool use.
|
||||
|
||||
**Mandatory flow:** Agent (once) → Session (every run). `model`/`system`/`tools` live on the agent, never the session. See `shared/managed-agents-overview.md` for the full reading guide, beta headers, and pitfalls.
|
||||
|
||||
**Beta headers:** `managed-agents-2026-04-01` — the SDK sets this automatically for all `client.beta.{agents,environments,sessions,vaults}.*` calls. Skills API uses `skills-2025-10-02` and Files API uses `files-api-2025-04-14`, but you don't need to explicitly pass those in for endpoints other than `/v1/skills` and `/v1/files`.
|
||||
|
||||
**Subcommands** — invoke directly with `/claude-api <subcommand>`:
|
||||
|
||||
| Subcommand | Action |
|
||||
|---|---|
|
||||
| `managed-agents-onboard` | Walk the user through setting up a Managed Agent from scratch. **Read `shared/managed-agents-onboarding.md` immediately** and follow its interview script: mental model → know-or-explore branch → template config → session setup → emit code. Do not summarize — run the interview. |
|
||||
|
||||
**Reading guide:** Start with `shared/managed-agents-overview.md`, then the topical `shared/managed-agents-*.md` files (core, environments, tools, events, client-patterns, onboarding, api-reference). For Python, TypeScript, Go, Ruby, PHP, and Java, read `{lang}/managed-agents/README.md` for code examples. For cURL, read `curl/managed-agents.md`. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML (URL in `shared/live-sources.md`). If a binding you need isn't shown in the language README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# does not currently have Managed Agents support; use raw HTTP from `curl/managed-agents.md` as a reference.
|
||||
|
||||
**When the user wants to set up a Managed Agent from scratch** (e.g. "how do I get started", "walk me through creating one", "set up a new agent"): read `shared/managed-agents-onboarding.md` and run its interview — same flow as the `managed-agents-onboard` subcommand.
|
||||
|
||||
**When the user asks "how do I write the client code for X":** reach for `shared/managed-agents-client-patterns.md` — covers lossless stream reconnect, `processed_at` queued/processed gate, interrupt, `tool_confirmation` round-trip, the correct idle/terminated break gate, post-idle status race, stream-first ordering, file-mount gotchas, keeping credentials host-side via custom tools, etc.
|
||||
|
||||
---
|
||||
|
||||
## Reading Guide
|
||||
|
||||
After detecting the language, read the relevant files based on what the user needs:
|
||||
|
||||
### Quick Task Reference
|
||||
|
||||
**Single text classification/summarization/extraction/Q&A:**
|
||||
→ Read only `{lang}/claude-api/README.md`
|
||||
|
||||
**Chat UI or real-time response display:**
|
||||
→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/streaming.md`
|
||||
|
||||
**Long-running conversations (may exceed context window):**
|
||||
→ Read `{lang}/claude-api/README.md` — see Compaction section
|
||||
**Migrating to a newer model (Opus 4.7 / Opus 4.6 / Sonnet 4.6) or replacing a retired model:**
|
||||
→ Read `shared/model-migration.md`
|
||||
**Prompt caching / optimize caching / "why is my cache hit rate low":**
|
||||
→ Read `shared/prompt-caching.md` + `{lang}/claude-api/README.md` (Prompt Caching section)
|
||||
|
||||
**Function calling / tool use / agents:**
|
||||
→ Read `{lang}/claude-api/README.md` + `shared/tool-use-concepts.md` + `{lang}/claude-api/tool-use.md`
|
||||
|
||||
**Agent design (tool surface, context management, caching strategy):**
|
||||
→ Read `shared/agent-design.md`
|
||||
|
||||
**Batch processing (non-latency-sensitive):**
|
||||
→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/batches.md`
|
||||
|
||||
**File uploads across multiple requests:**
|
||||
→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/files-api.md`
|
||||
|
||||
**Managed Agents (server-managed stateful agents with workspace):**
|
||||
→ Read `shared/managed-agents-overview.md` + the rest of the `shared/managed-agents-*.md` files. For Python, TypeScript, Go, Ruby, PHP, and Java, read `{lang}/managed-agents/README.md` for code examples. For cURL, read `curl/managed-agents.md`. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML (URL in `shared/live-sources.md`). If a binding you need isn't shown in the language README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# does not currently support Managed Agents — use raw HTTP from `curl/managed-agents.md` as a reference.
|
||||
|
||||
### Claude API (Full File Reference)
|
||||
|
||||
Read the **language-specific Claude API folder** (`{language}/claude-api/`):
|
||||
|
||||
1. **`{language}/claude-api/README.md`** — **Read this first.** Installation, quick start, common patterns, error handling.
|
||||
2. **`shared/tool-use-concepts.md`** — Read when the user needs function calling, code execution, memory, or structured outputs. Covers conceptual foundations.
|
||||
3. **`shared/agent-design.md`** — Read when designing an agent: bash vs. dedicated tools, programmatic tool calling, tool search/skills, context editing vs. compaction vs. memory, caching principles.
|
||||
4. **`{language}/claude-api/tool-use.md`** — Read for language-specific tool use code examples (tool runner, manual loop, code execution, memory, structured outputs).
|
||||
5. **`{language}/claude-api/streaming.md`** — Read when building chat UIs or interfaces that display responses incrementally.
|
||||
6. **`{language}/claude-api/batches.md`** — Read when processing many requests offline (not latency-sensitive). Runs asynchronously at 50% cost.
|
||||
7. **`{language}/claude-api/files-api.md`** — Read when sending the same file across multiple requests without re-uploading.
|
||||
8. **`shared/prompt-caching.md`** — Read when adding or optimizing prompt caching. Covers prefix-stability design, breakpoint placement, and anti-patterns that silently invalidate cache.
|
||||
9. **`shared/error-codes.md`** — Read when debugging HTTP errors or implementing error handling.
|
||||
10. **`shared/model-migration.md`** — Read when upgrading to newer models, replacing retired models, or translating `budget_tokens` / prefill patterns to the current API.
|
||||
11. **`shared/live-sources.md`** — WebFetch URLs for fetching the latest official documentation.
|
||||
|
||||
> **Note:** For Java, Go, Ruby, C#, PHP, and cURL — these have a single file each covering all basics. Read that file plus `shared/tool-use-concepts.md` and `shared/error-codes.md` as needed.
|
||||
|
||||
> **Note:** For the Managed Agents file reference, see the `## Managed Agents (Beta)` section above — it lists every `shared/managed-agents-*.md` file and the language-specific READMEs.
|
||||
|
||||
---
|
||||
|
||||
## When to Use WebFetch
|
||||
|
||||
Use WebFetch to get the latest documentation when:
|
||||
|
||||
- User asks for "latest" or "current" information
|
||||
- Cached data seems incorrect
|
||||
- User asks about features not covered here
|
||||
|
||||
Live documentation URLs are in `shared/live-sources.md`.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- Don't truncate inputs when passing files or content to the API. If the content is too long to fit in the context window, notify the user and discuss options (chunking, summarization, etc.) rather than silently truncating.
|
||||
- **Opus 4.7 thinking:** Adaptive only. `thinking: {type: "enabled", budget_tokens: N}` returns 400 on Opus 4.7 — `budget_tokens` is fully removed there (along with `temperature`, `top_p`, `top_k`). Use `thinking: {type: "adaptive"}`.
|
||||
- **Opus 4.6 / Sonnet 4.6 thinking:** Use `thinking: {type: "adaptive"}` — do NOT use `budget_tokens` for new 4.6 code (deprecated on both Opus 4.6 and Sonnet 4.6; for gradual migration of existing code, see the transitional escape hatch in `shared/model-migration.md` — note this carve-out does not apply to Opus 4.7). For older models, `budget_tokens` must be less than `max_tokens` (minimum 1024). This will throw an error if you get it wrong.
|
||||
- **4.6/4.7 family prefill removed:** Assistant message prefills (last-assistant-turn prefills) return a 400 error on Opus 4.6, Opus 4.7, and Sonnet 4.6. Use structured outputs (`output_config.format`) or system prompt instructions to control response format instead.
|
||||
- **Confirm migration scope before editing:** When a user asks to migrate code to a newer Claude model without naming a specific file, directory, or file list, **ask which scope to apply first** — the entire working directory, a specific subdirectory, or a specific set of files. Do not start editing until the user confirms. Imperative phrasings like "migrate my codebase", "move my project to X", "upgrade to Sonnet 4.6", or bare "migrate to Opus 4.7" are **still ambiguous** — they tell you what to do but not where, so ask. Proceed without asking only when the prompt names an exact file, a specific directory, or an explicit file list ("migrate `app.py`", "migrate everything under `services/`", "update `a.py` and `b.py`"). See `shared/model-migration.md` Step 0.
|
||||
- **`max_tokens` defaults:** Don't lowball `max_tokens` — hitting the cap truncates output mid-thought and requires a retry. For non-streaming requests, default to `~16000` (keeps responses under SDK HTTP timeouts). For streaming requests, default to `~64000` (timeouts aren't a concern, so give the model room). Only go lower when you have a hard reason: classification (`~256`), cost caps, or deliberately short outputs.
|
||||
- **128K output tokens:** Opus 4.6 and Opus 4.7 support up to 128K `max_tokens`, but the SDKs require streaming for values that large to avoid HTTP timeouts. Use `.stream()` with `.get_final_message()` / `.finalMessage()`.
|
||||
- **Tool call JSON parsing (4.6/4.7 family):** Opus 4.6, Opus 4.7, and Sonnet 4.6 may produce different JSON string escaping in tool call `input` fields (e.g., Unicode or forward-slash escaping). Always parse tool inputs with `json.loads()` / `JSON.parse()` — never do raw string matching on the serialized input.
|
||||
- **Structured outputs (all models):** Use `output_config: {format: {...}}` instead of the deprecated `output_format` parameter on `messages.create()`. This is a general API change, not 4.6-specific.
|
||||
- **Don't reimplement SDK functionality:** The SDK provides high-level helpers — use them instead of building from scratch. Specifically: use `stream.finalMessage()` instead of wrapping `.on()` events in `new Promise()`; use typed exception classes (`Anthropic.RateLimitError`, etc.) instead of string-matching error messages; use SDK types (`Anthropic.MessageParam`, `Anthropic.Tool`, `Anthropic.Message`, etc.) instead of redefining equivalent interfaces.
|
||||
- **Don't define custom types for SDK data structures:** The SDK exports types for all API objects. Use `Anthropic.MessageParam` for messages, `Anthropic.Tool` for tool definitions, `Anthropic.ToolUseBlock` / `Anthropic.ToolResultBlockParam` for tool results, `Anthropic.Message` for responses. Defining your own `interface ChatMessage { role: string; content: unknown }` duplicates what the SDK already provides and loses type safety.
|
||||
- **Report and document output:** For tasks that produce reports, documents, or visualizations, the code execution sandbox has `python-docx`, `python-pptx`, `matplotlib`, `pillow`, and `pypdf` pre-installed. Claude can generate formatted files (DOCX, PDF, charts) and return them via the Files API — consider this for "report" or "document" type requests instead of plain stdout text.
|
||||
@@ -0,0 +1,402 @@
|
||||
# Claude API — C#
|
||||
|
||||
> **Note:** The C# SDK is the official Anthropic SDK for C#. Tool use is supported via the Messages API. A class-annotation-based tool runner is not available; use raw tool definitions with JSON schema. The SDK also supports Microsoft.Extensions.AI IChatClient integration with function invocation.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
dotnet add package Anthropic
|
||||
```
|
||||
|
||||
## Client Initialization
|
||||
|
||||
```csharp
|
||||
using Anthropic;
|
||||
|
||||
// Default (uses ANTHROPIC_API_KEY env var)
|
||||
AnthropicClient client = new();
|
||||
|
||||
// Explicit API key (use environment variables — never hardcode keys)
|
||||
AnthropicClient client = new() {
|
||||
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Basic Message Request
|
||||
|
||||
```csharp
|
||||
using Anthropic.Models.Messages;
|
||||
|
||||
var parameters = new MessageCreateParams
|
||||
{
|
||||
Model = Model.ClaudeOpus4_6,
|
||||
MaxTokens = 16000,
|
||||
Messages = [new() { Role = Role.User, Content = "What is the capital of France?" }]
|
||||
};
|
||||
var response = await client.Messages.Create(parameters);
|
||||
|
||||
// ContentBlock is a union wrapper. .Value unwraps to the variant object,
|
||||
// then OfType<T> filters to the type you want. Or use the TryPick* idiom
|
||||
// shown in the Thinking section below.
|
||||
foreach (var text in response.Content.Select(b => b.Value).OfType<TextBlock>())
|
||||
{
|
||||
Console.WriteLine(text.Text);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Streaming
|
||||
|
||||
```csharp
|
||||
using Anthropic.Models.Messages;
|
||||
|
||||
var parameters = new MessageCreateParams
|
||||
{
|
||||
Model = Model.ClaudeOpus4_6,
|
||||
MaxTokens = 64000,
|
||||
Messages = [new() { Role = Role.User, Content = "Write a haiku" }]
|
||||
};
|
||||
|
||||
await foreach (RawMessageStreamEvent streamEvent in client.Messages.CreateStreaming(parameters))
|
||||
{
|
||||
if (streamEvent.TryPickContentBlockDelta(out var delta) &&
|
||||
delta.Delta.TryPickText(out var text))
|
||||
{
|
||||
Console.Write(text.Text);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**`RawMessageStreamEvent` TryPick methods** (naming drops the `Message`/`Raw` prefix): `TryPickStart`, `TryPickDelta`, `TryPickStop`, `TryPickContentBlockStart`, `TryPickContentBlockDelta`, `TryPickContentBlockStop`. There is no `TryPickMessageStop` — use `TryPickStop`.
|
||||
|
||||
---
|
||||
|
||||
## Thinking
|
||||
|
||||
**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think.
|
||||
|
||||
```csharp
|
||||
using Anthropic.Models.Messages;
|
||||
|
||||
var response = await client.Messages.Create(new MessageCreateParams
|
||||
{
|
||||
Model = Model.ClaudeOpus4_6,
|
||||
MaxTokens = 16000,
|
||||
// ThinkingConfigParam? implicitly converts from the concrete variant classes —
|
||||
// no wrapper needed.
|
||||
Thinking = new ThinkingConfigAdaptive(),
|
||||
Messages =
|
||||
[
|
||||
new() { Role = Role.User, Content = "Solve: 27 * 453" },
|
||||
],
|
||||
});
|
||||
|
||||
// ThinkingBlock(s) precede TextBlock in Content. TryPick* narrows the union.
|
||||
foreach (var block in response.Content)
|
||||
{
|
||||
if (block.TryPickThinking(out ThinkingBlock? t))
|
||||
{
|
||||
Console.WriteLine($"[thinking] {t.Thinking}");
|
||||
}
|
||||
else if (block.TryPickText(out TextBlock? text))
|
||||
{
|
||||
Console.WriteLine(text.Text);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Deprecated:** `new ThinkingConfigEnabled { BudgetTokens = N }` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
|
||||
|
||||
Alternative to `TryPick*`: `.Select(b => b.Value).OfType<ThinkingBlock>()` (same LINQ pattern as the Basic Message example).
|
||||
|
||||
---
|
||||
|
||||
## Tool Use
|
||||
|
||||
### Defining a tool
|
||||
|
||||
`Tool` (NOT `ToolParam`) with an `InputSchema` record. `InputSchema.Type` is auto-set to `"object"` by the constructor — don't set it. `ToolUnion` has an implicit conversion from `Tool`, triggered by the collection expression `[...]`.
|
||||
|
||||
```csharp
|
||||
using System.Text.Json;
|
||||
using Anthropic.Models.Messages;
|
||||
|
||||
var parameters = new MessageCreateParams
|
||||
{
|
||||
Model = Model.ClaudeSonnet4_6,
|
||||
MaxTokens = 16000,
|
||||
Tools = [
|
||||
new Tool {
|
||||
Name = "get_weather",
|
||||
Description = "Get the current weather in a given location",
|
||||
InputSchema = new() {
|
||||
Properties = new Dictionary<string, JsonElement> {
|
||||
["location"] = JsonSerializer.SerializeToElement(
|
||||
new { type = "string", description = "City name" }),
|
||||
},
|
||||
Required = ["location"],
|
||||
},
|
||||
},
|
||||
],
|
||||
Messages = [new() { Role = Role.User, Content = "Weather in Paris?" }],
|
||||
};
|
||||
```
|
||||
|
||||
Derived from `anthropic-sdk-csharp/src/Anthropic/Models/Messages/Tool.cs` and `ToolUnion.cs:799` (implicit conversion).
|
||||
|
||||
See [shared tool use concepts](../shared/tool-use-concepts.md) for the loop pattern.
|
||||
### Converting response content to the follow-up assistant message
|
||||
|
||||
When echoing Claude's response back in the assistant turn, **there is no `.ToParam()` helper** — manually reconstruct each `ContentBlock` variant as its `*Param` counterpart. Do NOT use `new ContentBlockParam(block.Json)`: it compiles and serializes, but `.Value` stays `null` so `TryPick*`/`Validate()` fail (degraded JSON pass-through, not the typed path).
|
||||
|
||||
```csharp
|
||||
using Anthropic.Models.Messages;
|
||||
|
||||
Message response = await client.Messages.Create(parameters);
|
||||
|
||||
// No .ToParam() — reconstruct per variant. Implicit conversions from each
|
||||
// *Param type to ContentBlockParam mean no explicit wrapper.
|
||||
List<ContentBlockParam> assistantContent = [];
|
||||
List<ContentBlockParam> toolResults = [];
|
||||
foreach (ContentBlock block in response.Content)
|
||||
{
|
||||
if (block.TryPickText(out TextBlock? text))
|
||||
{
|
||||
assistantContent.Add(new TextBlockParam { Text = text.Text });
|
||||
}
|
||||
else if (block.TryPickThinking(out ThinkingBlock? thinking))
|
||||
{
|
||||
// Signature MUST be preserved — the API rejects tampering
|
||||
assistantContent.Add(new ThinkingBlockParam
|
||||
{
|
||||
Thinking = thinking.Thinking,
|
||||
Signature = thinking.Signature,
|
||||
});
|
||||
}
|
||||
else if (block.TryPickRedactedThinking(out RedactedThinkingBlock? redacted))
|
||||
{
|
||||
assistantContent.Add(new RedactedThinkingBlockParam { Data = redacted.Data });
|
||||
}
|
||||
else if (block.TryPickToolUse(out ToolUseBlock? toolUse))
|
||||
{
|
||||
// ToolUseBlock has required Caller; ToolUseBlockParam.Caller is optional — don't copy it
|
||||
assistantContent.Add(new ToolUseBlockParam
|
||||
{
|
||||
ID = toolUse.ID,
|
||||
Name = toolUse.Name,
|
||||
Input = toolUse.Input,
|
||||
});
|
||||
// Execute the tool; collect ONE result per tool_use block — the API
|
||||
// rejects the follow-up if any tool_use ID lacks a matching tool_result.
|
||||
string result = ExecuteYourTool(toolUse.Name, toolUse.Input);
|
||||
toolResults.Add(new ToolResultBlockParam
|
||||
{
|
||||
ToolUseID = toolUse.ID,
|
||||
Content = result,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Follow-up: prior messages + assistant echo + user tool_result(s)
|
||||
List<MessageParam> followUpMessages =
|
||||
[
|
||||
.. parameters.Messages,
|
||||
new() { Role = Role.Assistant, Content = assistantContent },
|
||||
new() { Role = Role.User, Content = toolResults },
|
||||
];
|
||||
```
|
||||
|
||||
`ToolResultBlockParam` has no tuple constructor — use the object initializer. `Content` is a string-or-list union; a plain `string` implicitly converts.
|
||||
|
||||
---
|
||||
|
||||
## Context Editing / Compaction (Beta)
|
||||
|
||||
**Beta-namespace prefix is inconsistent** (source-verified against `src/Anthropic/Models/Beta/Messages/*.cs` @ 12.9.0). No prefix: `MessageCreateParams`, `MessageCountTokensParams`, `Role`. **Everything else has the `Beta` prefix**: `BetaMessageParam`, `BetaMessage`, `BetaContentBlock`, `BetaToolUseBlock`, all block param types. The unprefixed `Role` WILL collide with `Anthropic.Models.Messages.Role` if you import both namespaces (CS0104). Safest: import only Beta; if mixing, alias the beta `Role`:
|
||||
|
||||
```csharp
|
||||
using Anthropic.Models.Beta.Messages;
|
||||
using NonBeta = Anthropic.Models.Messages; // only if you also need non-beta types
|
||||
// Now: MessageCreateParams, BetaMessageParam, Role (beta's), NonBeta.Role (if needed)
|
||||
```
|
||||
|
||||
|
||||
`BetaMessage.Content` is `IReadOnlyList<BetaContentBlock>` — a 15-variant discriminated union. Narrow with `TryPick*`. **Response `BetaContentBlock` is NOT assignable to param `BetaContentBlockParam`** — there's no `.ToParam()` in C#. Round-trip by converting each block:
|
||||
|
||||
```csharp
|
||||
using Anthropic.Models.Beta.Messages;
|
||||
|
||||
var betaParams = new MessageCreateParams // no Beta prefix — one of only 2 unprefixed
|
||||
{
|
||||
Model = Model.ClaudeOpus4_6,
|
||||
MaxTokens = 16000,
|
||||
Betas = ["compact-2026-01-12"],
|
||||
ContextManagement = new BetaContextManagementConfig
|
||||
{
|
||||
Edits = [new BetaCompact20260112Edit()],
|
||||
},
|
||||
Messages = messages,
|
||||
};
|
||||
BetaMessage resp = await client.Beta.Messages.Create(betaParams);
|
||||
|
||||
foreach (BetaContentBlock block in resp.Content)
|
||||
{
|
||||
if (block.TryPickCompaction(out BetaCompactionBlock? compaction))
|
||||
{
|
||||
// Content is nullable — compaction can fail server-side
|
||||
Console.WriteLine($"compaction summary: {compaction.Content}");
|
||||
}
|
||||
}
|
||||
|
||||
// Context-edit metadata lives on a separate nullable field
|
||||
if (resp.ContextManagement is { } ctx)
|
||||
{
|
||||
foreach (var edit in ctx.AppliedEdits)
|
||||
Console.WriteLine($"cleared {edit.ClearedInputTokens} tokens");
|
||||
}
|
||||
|
||||
// ROUND-TRIP: BetaMessageParam.Content is BetaMessageParamContent (a string|list
|
||||
// union). It implicit-converts from List<BetaContentBlockParam>, NOT from the
|
||||
// response's IReadOnlyList<BetaContentBlock>. Convert each block:
|
||||
List<BetaContentBlockParam> paramBlocks = [];
|
||||
foreach (var b in resp.Content)
|
||||
{
|
||||
if (b.TryPickText(out var t)) paramBlocks.Add(new BetaTextBlockParam { Text = t.Text });
|
||||
else if (b.TryPickCompaction(out var c)) paramBlocks.Add(new BetaCompactionBlockParam { Content = c.Content });
|
||||
// ... other variants as needed
|
||||
}
|
||||
messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = paramBlocks });
|
||||
```
|
||||
|
||||
All 15 `BetaContentBlock.TryPick*` variants: `Text`, `Thinking`, `RedactedThinking`, `ToolUse`, `ServerToolUse`, `WebSearchToolResult`, `WebFetchToolResult`, `CodeExecutionToolResult`, `BashCodeExecutionToolResult`, `TextEditorCodeExecutionToolResult`, `ToolSearchToolResult`, `McpToolUse`, `McpToolResult`, `ContainerUpload`, `Compaction`.
|
||||
|
||||
**`BetaToolUseBlock.Input` is `IReadOnlyDictionary<string, JsonElement>`** — index by key then call the `JsonElement` extractor:
|
||||
|
||||
```csharp
|
||||
if (block.TryPickToolUse(out BetaToolUseBlock? tu))
|
||||
{
|
||||
int a = tu.Input["a"].GetInt32();
|
||||
string s = tu.Input["name"].GetString()!;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Effort Parameter
|
||||
|
||||
Effort is nested under `OutputConfig`, NOT a top-level property. `ApiEnum<string, Effort>` has an implicit conversion from the enum, so assign `Effort.High` directly.
|
||||
|
||||
```csharp
|
||||
OutputConfig = new OutputConfig { Effort = Effort.High },
|
||||
```
|
||||
|
||||
Values: `Effort.Low`, `Effort.Medium`, `Effort.High`, `Effort.Max`. Combine with `Thinking = new ThinkingConfigAdaptive()` for cost-quality control.
|
||||
|
||||
---
|
||||
|
||||
## Prompt Caching
|
||||
|
||||
`System` takes `MessageCreateParamsSystem?` — a union of `string` or `List<TextBlockParam>`. There is no `SystemTextBlockParam`; use plain `TextBlockParam`. The implicit conversion needs the concrete `List<TextBlockParam>` type (array literals won't convert). For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
|
||||
|
||||
```csharp
|
||||
System = new List<TextBlockParam> {
|
||||
new() {
|
||||
Text = longSystemPrompt,
|
||||
CacheControl = new CacheControlEphemeral(), // auto-sets Type = "ephemeral"
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
Optional `Ttl` on `CacheControlEphemeral`: `new() { Ttl = Ttl.Ttl1h }` or `Ttl.Ttl5m`. `CacheControl` also exists on `Tool.CacheControl` and top-level `MessageCreateParams.CacheControl`.
|
||||
|
||||
Verify hits via `response.Usage.CacheCreationInputTokens` / `response.Usage.CacheReadInputTokens`.
|
||||
|
||||
---
|
||||
|
||||
## Token Counting
|
||||
|
||||
```csharp
|
||||
MessageTokensCount result = await client.Messages.CountTokens(new MessageCountTokensParams {
|
||||
Model = Model.ClaudeOpus4_6,
|
||||
Messages = [new() { Role = Role.User, Content = "Hello" }],
|
||||
});
|
||||
long tokens = result.InputTokens;
|
||||
```
|
||||
|
||||
`MessageCountTokensParams.Tools` uses a different union type (`MessageCountTokensTool`) than `MessageCreateParams.Tools` (`ToolUnion`) — if you're passing tools, the compiler will tell you when it matters.
|
||||
|
||||
---
|
||||
|
||||
## Structured Output
|
||||
|
||||
```csharp
|
||||
OutputConfig = new OutputConfig {
|
||||
Format = new JsonOutputFormat {
|
||||
Schema = new Dictionary<string, JsonElement> {
|
||||
["type"] = JsonSerializer.SerializeToElement("object"),
|
||||
["properties"] = JsonSerializer.SerializeToElement(
|
||||
new { name = new { type = "string" } }),
|
||||
["required"] = JsonSerializer.SerializeToElement(new[] { "name" }),
|
||||
},
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
`JsonOutputFormat.Type` is auto-set to `"json_schema"` by the constructor. `Schema` is `required`.
|
||||
|
||||
---
|
||||
|
||||
## PDF / Document Input
|
||||
|
||||
`DocumentBlockParam` takes a `DocumentBlockParamSource` union: `Base64PdfSource` / `UrlPdfSource` / `PlainTextSource` / `ContentBlockSource`. `Base64PdfSource` auto-sets `MediaType = "application/pdf"` and `Type = "base64"`.
|
||||
|
||||
```csharp
|
||||
new MessageParam {
|
||||
Role = Role.User,
|
||||
Content = new List<ContentBlockParam> {
|
||||
new DocumentBlockParam { Source = new Base64PdfSource { Data = base64String } },
|
||||
new TextBlockParam { Text = "Summarize this PDF" },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Tools
|
||||
|
||||
Web search, bash, text editor, and code execution are built-in server tools. Type names are version-suffixed; constructors auto-set `name`/`type`. All implicit-convert to `ToolUnion`.
|
||||
|
||||
```csharp
|
||||
Tools = [
|
||||
new WebSearchTool20260209(),
|
||||
new ToolBash20250124(),
|
||||
new ToolTextEditor20250728(),
|
||||
new CodeExecutionTool20260120(),
|
||||
],
|
||||
```
|
||||
|
||||
Also available: `WebFetchTool20260209`, `MemoryTool20250818`. `WebSearchTool20260209` optionals: `AllowedDomains`, `BlockedDomains`, `MaxUses`, `UserLocation`.
|
||||
|
||||
---
|
||||
|
||||
## Files API (Beta)
|
||||
|
||||
Files live under `client.Beta.Files` (namespace `Anthropic.Models.Beta.Files`). `BinaryContent` implicit-converts from `Stream` and `byte[]`.
|
||||
|
||||
```csharp
|
||||
using Anthropic.Models.Beta.Files;
|
||||
using Anthropic.Models.Beta.Messages;
|
||||
|
||||
FileMetadata meta = await client.Beta.Files.Upload(
|
||||
new FileUploadParams { File = File.OpenRead("doc.pdf") });
|
||||
|
||||
// Referencing the uploaded file requires Beta message types:
|
||||
new BetaRequestDocumentBlock {
|
||||
Source = new BetaFileDocumentSource { FileID = meta.ID },
|
||||
}
|
||||
```
|
||||
|
||||
The non-beta `DocumentBlockParamSource` union has no file-ID variant — file references need `client.Beta.Messages.Create()`.
|
||||
@@ -0,0 +1,216 @@
|
||||
# Claude API — cURL / Raw HTTP
|
||||
|
||||
Use these examples when the user needs raw HTTP requests or is working in a language without an official SDK.
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="your-api-key"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Basic Message Request
|
||||
|
||||
```bash
|
||||
curl https://api.anthropic.com/v1/messages \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-d '{
|
||||
"model": "claude-opus-4-7",
|
||||
"max_tokens": 16000,
|
||||
"messages": [
|
||||
{"role": "user", "content": "What is the capital of France?"}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
### Parsing the response
|
||||
|
||||
Use `jq` to extract fields from the JSON response. Do not use `grep`/`sed` —
|
||||
JSON strings can contain any character and regex parsing will break on quotes,
|
||||
escapes, or multi-line content.
|
||||
|
||||
```bash
|
||||
# Capture the response, then extract fields
|
||||
response=$(curl -s https://api.anthropic.com/v1/messages \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-d '{"model":"claude-opus-4-7","max_tokens":16000,"messages":[{"role":"user","content":"Hello"}]}')
|
||||
|
||||
# Print the first text block (-r strips the JSON quotes)
|
||||
echo "$response" | jq -r '.content[0].text'
|
||||
|
||||
# Read usage fields
|
||||
input_tokens=$(echo "$response" | jq -r '.usage.input_tokens')
|
||||
output_tokens=$(echo "$response" | jq -r '.usage.output_tokens')
|
||||
|
||||
# Read stop reason (for tool-use loops)
|
||||
stop_reason=$(echo "$response" | jq -r '.stop_reason')
|
||||
|
||||
# Extract all text blocks (content is an array; filter to type=="text")
|
||||
echo "$response" | jq -r '.content[] | select(.type == "text") | .text'
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Streaming (SSE)
|
||||
|
||||
```bash
|
||||
curl https://api.anthropic.com/v1/messages \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-d '{
|
||||
"model": "claude-opus-4-7",
|
||||
"max_tokens": 64000,
|
||||
"stream": true,
|
||||
"messages": [{"role": "user", "content": "Write a haiku"}]
|
||||
}'
|
||||
```
|
||||
|
||||
The response is a stream of Server-Sent Events:
|
||||
|
||||
```
|
||||
event: message_start
|
||||
data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}}
|
||||
|
||||
event: content_block_start
|
||||
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
|
||||
|
||||
event: content_block_delta
|
||||
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
|
||||
|
||||
event: content_block_stop
|
||||
data: {"type":"content_block_stop","index":0}
|
||||
|
||||
event: message_delta
|
||||
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}
|
||||
|
||||
event: message_stop
|
||||
data: {"type":"message_stop"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tool Use
|
||||
|
||||
```bash
|
||||
curl https://api.anthropic.com/v1/messages \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-d '{
|
||||
"model": "claude-opus-4-7",
|
||||
"max_tokens": 16000,
|
||||
"tools": [{
|
||||
"name": "get_weather",
|
||||
"description": "Get current weather for a location",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"location": {"type": "string", "description": "City name"}
|
||||
},
|
||||
"required": ["location"]
|
||||
}
|
||||
}],
|
||||
"messages": [{"role": "user", "content": "What is the weather in Paris?"}]
|
||||
}'
|
||||
```
|
||||
|
||||
When Claude responds with a `tool_use` block, send the result back:
|
||||
|
||||
```bash
|
||||
curl https://api.anthropic.com/v1/messages \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-d '{
|
||||
"model": "claude-opus-4-7",
|
||||
"max_tokens": 16000,
|
||||
"tools": [{
|
||||
"name": "get_weather",
|
||||
"description": "Get current weather for a location",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"location": {"type": "string", "description": "City name"}
|
||||
},
|
||||
"required": ["location"]
|
||||
}
|
||||
}],
|
||||
"messages": [
|
||||
{"role": "user", "content": "What is the weather in Paris?"},
|
||||
{"role": "assistant", "content": [
|
||||
{"type": "text", "text": "Let me check the weather."},
|
||||
{"type": "tool_use", "id": "toolu_abc123", "name": "get_weather", "input": {"location": "Paris"}}
|
||||
]},
|
||||
{"role": "user", "content": [
|
||||
{"type": "tool_result", "tool_use_id": "toolu_abc123", "content": "72°F and sunny"}
|
||||
]}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompt Caching
|
||||
|
||||
Put `cache_control` on the last block of the stable prefix. See `shared/prompt-caching.md` for placement patterns and the silent-invalidator audit checklist.
|
||||
|
||||
```bash
|
||||
curl https://api.anthropic.com/v1/messages \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-d '{
|
||||
"model": "claude-opus-4-7",
|
||||
"max_tokens": 16000,
|
||||
"system": [
|
||||
{"type": "text", "text": "<large shared prompt...>", "cache_control": {"type": "ephemeral"}}
|
||||
],
|
||||
"messages": [{"role": "user", "content": "Summarize the key points"}]
|
||||
}'
|
||||
```
|
||||
|
||||
For 1-hour TTL: `"cache_control": {"type": "ephemeral", "ttl": "1h"}`. Top-level `"cache_control"` on the request body auto-places on the last cacheable block. Verify hits via the response `usage.cache_creation_input_tokens` / `usage.cache_read_input_tokens` fields.
|
||||
|
||||
---
|
||||
|
||||
## Extended Thinking
|
||||
|
||||
> **Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Opus 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
|
||||
> **Older models:** Use `"type": "enabled"` with `"budget_tokens": N` (must be < `max_tokens`, min 1024).
|
||||
|
||||
```bash
|
||||
# Opus 4.7 / 4.6: adaptive thinking (recommended)
|
||||
curl https://api.anthropic.com/v1/messages \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-d '{
|
||||
"model": "claude-opus-4-7",
|
||||
"max_tokens": 16000,
|
||||
"thinking": {
|
||||
"type": "adaptive"
|
||||
},
|
||||
"output_config": {
|
||||
"effort": "high"
|
||||
},
|
||||
"messages": [{"role": "user", "content": "Solve this step by step..."}]
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Required Headers
|
||||
|
||||
| Header | Value | Description |
|
||||
| ------------------- | ------------------ | -------------------------- |
|
||||
| `Content-Type` | `application/json` | Required |
|
||||
| `x-api-key` | Your API key | Authentication |
|
||||
| `anthropic-version` | `2023-06-01` | API version |
|
||||
| `anthropic-beta` | Beta feature IDs | Required for beta features |
|
||||
@@ -0,0 +1,337 @@
|
||||
# Managed Agents — cURL / Raw HTTP
|
||||
|
||||
Use these examples when the user needs raw HTTP requests or is working without an SDK.
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="your-api-key"
|
||||
|
||||
# Common headers
|
||||
HEADERS=(
|
||||
-H "Content-Type: application/json"
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY"
|
||||
-H "anthropic-version: 2023-06-01"
|
||||
-H "anthropic-beta: managed-agents-2026-04-01"
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create an Environment
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.anthropic.com/v1/environments \
|
||||
"${HEADERS[@]}" \
|
||||
-d '{
|
||||
"name": "my-dev-env",
|
||||
"config": {
|
||||
"type": "cloud",
|
||||
"networking": { "type": "unrestricted" }
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### With restricted networking
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.anthropic.com/v1/environments \
|
||||
"${HEADERS[@]}" \
|
||||
-d '{
|
||||
"name": "restricted-env",
|
||||
"config": {
|
||||
"type": "cloud",
|
||||
"networking": {
|
||||
"type": "package_managers_and_custom",
|
||||
"allowed_hosts": ["api.example.com"]
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create an Agent (required first step)
|
||||
|
||||
> ⚠️ **There is no inline agent config.** Under `managed-agents-2026-04-01`, `model`/`system`/`tools` are top-level fields on `POST /v1/agents`, not on the session. Always create the agent first — the session only takes `"agent": {"type": "agent", "id": "..."}`.
|
||||
|
||||
### Minimal
|
||||
|
||||
```bash
|
||||
# 1. Create the agent
|
||||
curl -X POST https://api.anthropic.com/v1/agents \
|
||||
"${HEADERS[@]}" \
|
||||
-d '{
|
||||
"name": "Coding Assistant",
|
||||
"model": "claude-opus-4-7",
|
||||
"tools": [{ "type": "agent_toolset_20260401" }]
|
||||
}'
|
||||
# → { "id": "agent_abc123", ... }
|
||||
|
||||
# 2. Start a session
|
||||
curl -X POST https://api.anthropic.com/v1/sessions \
|
||||
"${HEADERS[@]}" \
|
||||
-d '{
|
||||
"agent": { "type": "agent", "id": "agent_abc123", "version": "1772585501101368014" },
|
||||
"environment_id": "env_abc123"
|
||||
}'
|
||||
```
|
||||
|
||||
### With system prompt, custom tools, and GitHub repo
|
||||
|
||||
```bash
|
||||
# 1. Create the agent
|
||||
curl -X POST https://api.anthropic.com/v1/agents \
|
||||
"${HEADERS[@]}" \
|
||||
-d '{
|
||||
"name": "Code Reviewer",
|
||||
"model": "claude-opus-4-7",
|
||||
"system": "You are a senior code reviewer. Be thorough and constructive.",
|
||||
"tools": [
|
||||
{ "type": "agent_toolset_20260401" },
|
||||
{
|
||||
"type": "custom",
|
||||
"name": "run_linter",
|
||||
"description": "Run the project linter on a file",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"file_path": { "type": "string", "description": "Path to lint" }
|
||||
},
|
||||
"required": ["file_path"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}'
|
||||
|
||||
# 2. Start a session with the repo mounted
|
||||
curl -X POST https://api.anthropic.com/v1/sessions \
|
||||
"${HEADERS[@]}" \
|
||||
-d '{
|
||||
"agent": { "type": "agent", "id": "agent_abc123", "version": "1772585501101368014" },
|
||||
"environment_id": "env_abc123",
|
||||
"title": "Code review session",
|
||||
"resources": [
|
||||
{
|
||||
"type": "github_repository",
|
||||
"url": "https://github.com/owner/repo",
|
||||
"mount_path": "/workspace/repo",
|
||||
"authorization_token": "ghp_...",
|
||||
"branch": "feature-branch"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Send a User Message
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
|
||||
"${HEADERS[@]}" \
|
||||
-d '{
|
||||
"events": [
|
||||
{
|
||||
"type": "user.message",
|
||||
"content": [{ "type": "text", "text": "Review the auth module for security issues" }]
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stream Events (SSE)
|
||||
|
||||
```bash
|
||||
curl -N https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream \
|
||||
"${HEADERS[@]}"
|
||||
```
|
||||
|
||||
Response format:
|
||||
|
||||
```
|
||||
event: session.status_running
|
||||
data: {"type":"session.status_running","id":"sevt_...","processed_at":"..."}
|
||||
|
||||
event: agent.message
|
||||
data: {"type":"agent.message","id":"sevt_...","content":[{"type":"text","text":"I'll review..."}],"processed_at":"..."}
|
||||
|
||||
event: session.status_idle
|
||||
data: {"type":"session.status_idle","id":"sevt_...","processed_at":"..."}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Poll Events
|
||||
|
||||
```bash
|
||||
# Get all events
|
||||
curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
|
||||
"${HEADERS[@]}"
|
||||
|
||||
# Paginated — get next page of events
|
||||
curl "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?page=page_abc123" \
|
||||
"${HEADERS[@]}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Provide Custom Tool Result
|
||||
|
||||
When the agent calls a custom tool, send the result back:
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
|
||||
"${HEADERS[@]}" \
|
||||
-d '{
|
||||
"events": [
|
||||
{
|
||||
"type": "user.custom_tool_result",
|
||||
"custom_tool_use_id": "sevt_abc123",
|
||||
"content": [{ "type": "text", "text": "No linting errors found." }]
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Interrupt a Running Session
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
|
||||
"${HEADERS[@]}" \
|
||||
-d '{
|
||||
"events": [
|
||||
{
|
||||
"type": "interrupt"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Get Session Details
|
||||
|
||||
```bash
|
||||
curl https://api.anthropic.com/v1/sessions/$SESSION_ID \
|
||||
"${HEADERS[@]}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## List Sessions
|
||||
|
||||
```bash
|
||||
curl https://api.anthropic.com/v1/sessions \
|
||||
"${HEADERS[@]}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Delete a Session
|
||||
|
||||
```bash
|
||||
curl -X DELETE https://api.anthropic.com/v1/sessions/$SESSION_ID \
|
||||
"${HEADERS[@]}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Upload a File
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.anthropic.com/v1/files \
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-H "anthropic-beta: files-api-2025-04-14" \
|
||||
-F "file=@path/to/file.txt" \
|
||||
-F "purpose=agent"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## List and Download Session Files
|
||||
|
||||
List files the agent wrote to `/mnt/session/outputs/` during a session, then download them.
|
||||
|
||||
```bash
|
||||
# List files associated with a session
|
||||
curl "https://api.anthropic.com/v1/files?scope_id=$SESSION_ID" \
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-H "anthropic-beta: files-api-2025-04-14,managed-agents-2026-04-01"
|
||||
|
||||
# Download a specific file
|
||||
curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-H "anthropic-beta: files-api-2025-04-14,managed-agents-2026-04-01" \
|
||||
-o downloaded_file.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## List Agents
|
||||
|
||||
```bash
|
||||
curl https://api.anthropic.com/v1/agents \
|
||||
"${HEADERS[@]}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Integration
|
||||
|
||||
```bash
|
||||
# 1. Agent declares MCP server (no auth here — auth goes in a vault)
|
||||
curl -X POST https://api.anthropic.com/v1/agents \
|
||||
"${HEADERS[@]}" \
|
||||
-d '{
|
||||
"name": "MCP Agent",
|
||||
"model": "claude-opus-4-7",
|
||||
"mcp_servers": [
|
||||
{ "type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse" }
|
||||
],
|
||||
"tools": [
|
||||
{ "type": "agent_toolset_20260401" },
|
||||
{ "type": "mcp_toolset", "mcp_server_name": "my-tools" }
|
||||
]
|
||||
}'
|
||||
|
||||
# 2. Session attaches vault containing credentials for that MCP server URL
|
||||
curl -X POST https://api.anthropic.com/v1/sessions \
|
||||
"${HEADERS[@]}" \
|
||||
-d '{
|
||||
"agent": "agent_abc123",
|
||||
"environment_id": "env_abc123",
|
||||
"vault_ids": ["vlt_abc123"]
|
||||
}'
|
||||
```
|
||||
|
||||
See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials.
|
||||
|
||||
---
|
||||
|
||||
## Tool Configuration
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.anthropic.com/v1/agents \
|
||||
"${HEADERS[@]}" \
|
||||
-d '{
|
||||
"name": "Restricted Agent",
|
||||
"model": "claude-opus-4-7",
|
||||
"tools": [
|
||||
{
|
||||
"type": "agent_toolset_20260401",
|
||||
"default_config": { "enabled": true },
|
||||
"configs": [
|
||||
{ "name": "bash", "enabled": false }
|
||||
]
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
@@ -0,0 +1,421 @@
|
||||
# Claude API — Go
|
||||
|
||||
> **Note:** The Go SDK supports the Claude API and beta tool use with `BetaToolRunner`. Agent SDK is not yet available for Go.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
go get github.com/anthropics/anthropic-sdk-go
|
||||
```
|
||||
|
||||
## Client Initialization
|
||||
|
||||
```go
|
||||
import (
|
||||
"github.com/anthropics/anthropic-sdk-go"
|
||||
"github.com/anthropics/anthropic-sdk-go/option"
|
||||
)
|
||||
|
||||
// Default (uses ANTHROPIC_API_KEY env var)
|
||||
client := anthropic.NewClient()
|
||||
|
||||
// Explicit API key
|
||||
client := anthropic.NewClient(
|
||||
option.WithAPIKey("your-api-key"),
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Basic Message Request
|
||||
|
||||
```go
|
||||
response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
|
||||
Model: anthropic.ModelClaudeOpus4_6,
|
||||
MaxTokens: 16000,
|
||||
Messages: []anthropic.MessageParam{
|
||||
anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France?")),
|
||||
},
|
||||
})
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
for _, block := range response.Content {
|
||||
switch variant := block.AsAny().(type) {
|
||||
case anthropic.TextBlock:
|
||||
fmt.Println(variant.Text)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Streaming
|
||||
|
||||
```go
|
||||
stream := client.Messages.NewStreaming(context.Background(), anthropic.MessageNewParams{
|
||||
Model: anthropic.ModelClaudeOpus4_6,
|
||||
MaxTokens: 64000,
|
||||
Messages: []anthropic.MessageParam{
|
||||
anthropic.NewUserMessage(anthropic.NewTextBlock("Write a haiku")),
|
||||
},
|
||||
})
|
||||
|
||||
for stream.Next() {
|
||||
event := stream.Current()
|
||||
switch eventVariant := event.AsAny().(type) {
|
||||
case anthropic.ContentBlockDeltaEvent:
|
||||
switch deltaVariant := eventVariant.Delta.AsAny().(type) {
|
||||
case anthropic.TextDelta:
|
||||
fmt.Print(deltaVariant.Text)
|
||||
}
|
||||
}
|
||||
}
|
||||
if err := stream.Err(); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
```
|
||||
|
||||
**Accumulating the final message** (there is no `GetFinalMessage()` on the stream):
|
||||
|
||||
```go
|
||||
stream := client.Messages.NewStreaming(ctx, params)
|
||||
message := anthropic.Message{}
|
||||
for stream.Next() {
|
||||
message.Accumulate(stream.Current())
|
||||
}
|
||||
if err := stream.Err(); err != nil { log.Fatal(err) }
|
||||
// message.Content now has the complete response
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Tool Use
|
||||
|
||||
### Tool Runner (Beta — Recommended)
|
||||
|
||||
**Beta:** The Go SDK provides `BetaToolRunner` for automatic tool use loops via the `toolrunner` package.
|
||||
|
||||
```go
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"log"
|
||||
|
||||
"github.com/anthropics/anthropic-sdk-go"
|
||||
"github.com/anthropics/anthropic-sdk-go/toolrunner"
|
||||
)
|
||||
|
||||
// Define tool input with jsonschema tags for automatic schema generation
|
||||
type GetWeatherInput struct {
|
||||
City string `json:"city" jsonschema:"required,description=The city name"`
|
||||
}
|
||||
|
||||
// Create a tool with automatic schema generation from struct tags
|
||||
weatherTool, err := toolrunner.NewBetaToolFromJSONSchema(
|
||||
"get_weather",
|
||||
"Get current weather for a city",
|
||||
func(ctx context.Context, input GetWeatherInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
|
||||
return anthropic.BetaToolResultBlockParamContentUnion{
|
||||
OfText: &anthropic.BetaTextBlockParam{
|
||||
Text: fmt.Sprintf("The weather in %s is sunny, 72°F", input.City),
|
||||
},
|
||||
}, nil
|
||||
},
|
||||
)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// Create a tool runner that handles the conversation loop automatically
|
||||
runner := client.Beta.Messages.NewToolRunner(
|
||||
[]anthropic.BetaTool{weatherTool},
|
||||
anthropic.BetaToolRunnerParams{
|
||||
BetaMessageNewParams: anthropic.BetaMessageNewParams{
|
||||
Model: anthropic.ModelClaudeOpus4_6,
|
||||
MaxTokens: 16000,
|
||||
Messages: []anthropic.BetaMessageParam{
|
||||
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's the weather in Paris?")),
|
||||
},
|
||||
},
|
||||
MaxIterations: 5,
|
||||
},
|
||||
)
|
||||
|
||||
// Run until Claude produces a final response
|
||||
message, err := runner.RunToCompletion(context.Background())
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// RunToCompletion returns *BetaMessage; content is []BetaContentBlockUnion.
|
||||
// Narrow via AsAny() switch — note the Beta-namespace types (BetaTextBlock,
|
||||
// not TextBlock):
|
||||
for _, block := range message.Content {
|
||||
switch block := block.AsAny().(type) {
|
||||
case anthropic.BetaTextBlock:
|
||||
fmt.Println(block.Text)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key features of the Go tool runner:**
|
||||
|
||||
- Automatic schema generation from Go structs via `jsonschema` tags
|
||||
- `RunToCompletion()` for simple one-shot usage
|
||||
- `All()` iterator for processing each message in the conversation
|
||||
- `NextMessage()` for step-by-step iteration
|
||||
- Streaming variant via `NewToolRunnerStreaming()` with `AllStreaming()`
|
||||
|
||||
### Manual Loop
|
||||
|
||||
For fine-grained control over the agentic loop, define tools with `ToolParam`, check `StopReason`, execute tools yourself, and feed `tool_result` blocks back. This is the pattern when you need to intercept, validate, or log tool calls.
|
||||
|
||||
Derived from `anthropic-sdk-go/examples/tools/main.go`.
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"log"
|
||||
|
||||
"github.com/anthropics/anthropic-sdk-go"
|
||||
)
|
||||
|
||||
func main() {
|
||||
client := anthropic.NewClient()
|
||||
|
||||
// 1. Define tools. ToolParam.InputSchema uses a map, no struct tags needed.
|
||||
addTool := anthropic.ToolParam{
|
||||
Name: "add",
|
||||
Description: anthropic.String("Add two integers"),
|
||||
InputSchema: anthropic.ToolInputSchemaParam{
|
||||
Properties: map[string]any{
|
||||
"a": map[string]any{"type": "integer"},
|
||||
"b": map[string]any{"type": "integer"},
|
||||
},
|
||||
},
|
||||
}
|
||||
// ToolParam must be wrapped in ToolUnionParam for the Tools slice
|
||||
tools := []anthropic.ToolUnionParam{{OfTool: &addTool}}
|
||||
|
||||
messages := []anthropic.MessageParam{
|
||||
anthropic.NewUserMessage(anthropic.NewTextBlock("What is 2 + 3?")),
|
||||
}
|
||||
|
||||
for {
|
||||
resp, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
|
||||
Model: anthropic.ModelClaudeSonnet4_6,
|
||||
MaxTokens: 16000,
|
||||
Messages: messages,
|
||||
Tools: tools,
|
||||
})
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// 2. Append the assistant response to history BEFORE processing tool calls.
|
||||
// resp.ToParam() converts Message → MessageParam in one call.
|
||||
messages = append(messages, resp.ToParam())
|
||||
|
||||
// 3. Walk content blocks. ContentBlockUnion is a flattened struct;
|
||||
// use block.AsAny().(type) to switch on the actual variant.
|
||||
toolResults := []anthropic.ContentBlockParamUnion{}
|
||||
for _, block := range resp.Content {
|
||||
switch variant := block.AsAny().(type) {
|
||||
case anthropic.TextBlock:
|
||||
fmt.Println(variant.Text)
|
||||
case anthropic.ToolUseBlock:
|
||||
// 4. Parse the tool input. Use variant.JSON.Input.Raw() to get the
|
||||
// raw JSON — block.Input is json.RawMessage, not the parsed value.
|
||||
var in struct {
|
||||
A int `json:"a"`
|
||||
B int `json:"b"`
|
||||
}
|
||||
if err := json.Unmarshal([]byte(variant.JSON.Input.Raw()), &in); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
result := fmt.Sprintf("%d", in.A+in.B)
|
||||
// 5. NewToolResultBlock(toolUseID, content, isError) builds the
|
||||
// ContentBlockParamUnion for you. block.ID is the tool_use_id.
|
||||
toolResults = append(toolResults,
|
||||
anthropic.NewToolResultBlock(block.ID, result, false))
|
||||
}
|
||||
}
|
||||
|
||||
// 6. Exit when Claude stops asking for tools
|
||||
if resp.StopReason != anthropic.StopReasonToolUse {
|
||||
break
|
||||
}
|
||||
|
||||
// 7. Tool results go in a user message (variadic: all results in one turn)
|
||||
messages = append(messages, anthropic.NewUserMessage(toolResults...))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key API surface:**
|
||||
|
||||
| Symbol | Purpose |
|
||||
|---|---|
|
||||
| `resp.ToParam()` | Convert `Message` response → `MessageParam` for history |
|
||||
| `block.AsAny().(type)` | Type-switch on `ContentBlockUnion` variants |
|
||||
| `variant.JSON.Input.Raw()` | Raw JSON string of tool input (for `json.Unmarshal`) |
|
||||
| `anthropic.NewToolResultBlock(id, content, isError)` | Build `tool_result` block |
|
||||
| `anthropic.NewUserMessage(blocks...)` | Wrap tool results as a user turn |
|
||||
| `anthropic.StopReasonToolUse` | `StopReason` constant to check loop termination |
|
||||
| `anthropic.ToolUnionParam{OfTool: &t}` | Wrap `ToolParam` in the union for `Tools:` |
|
||||
|
||||
---
|
||||
|
||||
## Thinking
|
||||
|
||||
Enable Claude's internal reasoning by setting `Thinking` in `MessageNewParams`. The response will contain `ThinkingBlock` content before the final `TextBlock`.
|
||||
|
||||
**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. Combine with the `effort` parameter for cost-quality control.
|
||||
|
||||
Derived from `anthropic-sdk-go/message.go` (`ThinkingConfigParamUnion`, `NewThinkingConfigAdaptiveParam`).
|
||||
|
||||
```go
|
||||
// There is no ThinkingConfigParamOfAdaptive helper — construct the union
|
||||
// struct-literal directly and take the address of the variant.
|
||||
adaptive := anthropic.NewThinkingConfigAdaptiveParam()
|
||||
params := anthropic.MessageNewParams{
|
||||
Model: anthropic.ModelClaudeSonnet4_6,
|
||||
MaxTokens: 16000,
|
||||
Thinking: anthropic.ThinkingConfigParamUnion{OfAdaptive: &adaptive},
|
||||
Messages: []anthropic.MessageParam{
|
||||
anthropic.NewUserMessage(anthropic.NewTextBlock("How many r's in strawberry?")),
|
||||
},
|
||||
}
|
||||
|
||||
resp, err := client.Messages.New(context.Background(), params)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// ThinkingBlock(s) precede TextBlock in content
|
||||
for _, block := range resp.Content {
|
||||
switch b := block.AsAny().(type) {
|
||||
case anthropic.ThinkingBlock:
|
||||
fmt.Println("[thinking]", b.Thinking)
|
||||
case anthropic.TextBlock:
|
||||
fmt.Println(b.Text)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Deprecated:** `ThinkingConfigParamOfEnabled(budgetTokens)` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
|
||||
|
||||
To disable: `anthropic.ThinkingConfigParamUnion{OfDisabled: &anthropic.ThinkingConfigDisabledParam{}}`.
|
||||
|
||||
---
|
||||
|
||||
## Prompt Caching
|
||||
|
||||
`System` is `[]TextBlockParam`; set `CacheControl` on the last block to cache tools + system together. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
|
||||
|
||||
```go
|
||||
System: []anthropic.TextBlockParam{{
|
||||
Text: longSystemPrompt,
|
||||
CacheControl: anthropic.NewCacheControlEphemeralParam(), // default 5m TTL
|
||||
}},
|
||||
```
|
||||
|
||||
For 1-hour TTL: `anthropic.CacheControlEphemeralParam{TTL: anthropic.CacheControlEphemeralTTLTTL1h}`. There's also a top-level `CacheControl` on `MessageNewParams` that auto-places on the last cacheable block.
|
||||
|
||||
Verify hits via `resp.Usage.CacheCreationInputTokens` / `resp.Usage.CacheReadInputTokens`.
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Tools
|
||||
|
||||
Version-suffixed struct names with `Param` suffix. `Name`/`Type` are `constant.*` types — zero value marshals correctly, so `{}` works. Wrap in `ToolUnionParam` with the matching `Of*` field.
|
||||
|
||||
```go
|
||||
Tools: []anthropic.ToolUnionParam{
|
||||
{OfWebSearchTool20260209: &anthropic.WebSearchTool20260209Param{}},
|
||||
{OfBashTool20250124: &anthropic.ToolBash20250124Param{}},
|
||||
{OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
|
||||
{OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}},
|
||||
},
|
||||
```
|
||||
|
||||
Also available: `WebFetchTool20260209Param`, `MemoryTool20250818Param`, `ToolSearchToolBm25_20251119Param`, `ToolSearchToolRegex20251119Param`.
|
||||
|
||||
---
|
||||
|
||||
## PDF / Document Input
|
||||
|
||||
`NewDocumentBlock` generic helper accepts any source type. `MediaType`/`Type` are auto-set.
|
||||
|
||||
```go
|
||||
b64 := base64.StdEncoding.EncodeToString(pdfBytes)
|
||||
|
||||
msg := anthropic.NewUserMessage(
|
||||
anthropic.NewDocumentBlock(anthropic.Base64PDFSourceParam{Data: b64}),
|
||||
anthropic.NewTextBlock("Summarize this document"),
|
||||
)
|
||||
```
|
||||
|
||||
Other sources: `URLPDFSourceParam{URL: "https://..."}`, `PlainTextSourceParam{Data: "..."}`.
|
||||
|
||||
---
|
||||
|
||||
## Files API (Beta)
|
||||
|
||||
Under `client.Beta.Files`. Method is **`Upload`** (NOT `New`/`Create`), params struct is `BetaFileUploadParams`. The `File` field takes an `io.Reader`; use `anthropic.File()` to attach a filename + content-type for the multipart encoding.
|
||||
|
||||
```go
|
||||
f, _ := os.Open("./upload_me.txt")
|
||||
defer f.Close()
|
||||
|
||||
meta, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{
|
||||
File: anthropic.File(f, "upload_me.txt", "text/plain"),
|
||||
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14},
|
||||
})
|
||||
// meta.ID is the file_id to reference in subsequent message requests
|
||||
```
|
||||
|
||||
Other `Beta.Files` methods: `List`, `Delete`, `Download`, `GetMetadata`.
|
||||
|
||||
---
|
||||
|
||||
## Context Editing / Compaction (Beta)
|
||||
|
||||
Use `Beta.Messages.New` with `ContextManagement` on `BetaMessageNewParams`. There is no `NewBetaAssistantMessage` — use `.ToParam()` for the round-trip.
|
||||
|
||||
```go
|
||||
params := anthropic.BetaMessageNewParams{
|
||||
Model: anthropic.ModelClaudeOpus4_6, // also supported: ModelClaudeSonnet4_6
|
||||
MaxTokens: 16000,
|
||||
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
|
||||
ContextManagement: anthropic.BetaContextManagementConfigParam{
|
||||
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
|
||||
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
|
||||
},
|
||||
},
|
||||
Messages: []anthropic.BetaMessageParam{ /* ... */ },
|
||||
}
|
||||
|
||||
resp, err := client.Beta.Messages.New(ctx, params)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// Round-trip: append response to history via .ToParam()
|
||||
params.Messages = append(params.Messages, resp.ToParam())
|
||||
|
||||
// Read compaction blocks from the response
|
||||
for _, block := range resp.Content {
|
||||
if c, ok := block.AsAny().(anthropic.BetaCompactionBlock); ok {
|
||||
fmt.Println("compaction summary:", c.Content)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Other edit types: `BetaClearToolUses20250919EditParam`, `BetaClearThinking20251015EditParam`.
|
||||
@@ -0,0 +1,561 @@
|
||||
# Managed Agents — Go
|
||||
|
||||
> **Bindings not shown here:** This README covers the most common managed-agents flows for Go. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Go SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
|
||||
|
||||
> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.New` and pass it to every subsequent `sessions.New`; do not call `agents.New` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
go get github.com/anthropics/anthropic-sdk-go
|
||||
```
|
||||
|
||||
## Client Initialization
|
||||
|
||||
```go
|
||||
import (
|
||||
"context"
|
||||
|
||||
"github.com/anthropics/anthropic-sdk-go"
|
||||
"github.com/anthropics/anthropic-sdk-go/option"
|
||||
)
|
||||
|
||||
// Default (uses ANTHROPIC_API_KEY env var)
|
||||
client := anthropic.NewClient()
|
||||
|
||||
// Explicit API key
|
||||
client := anthropic.NewClient(
|
||||
option.WithAPIKey("your-api-key"),
|
||||
)
|
||||
|
||||
ctx := context.Background()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create an Environment
|
||||
|
||||
```go
|
||||
environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
|
||||
Name: "my-dev-env",
|
||||
Config: anthropic.BetaCloudConfigParams{
|
||||
Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
|
||||
OfUnrestricted: &anthropic.UnrestrictedNetworkParam{},
|
||||
},
|
||||
},
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
fmt.Println(environment.ID) // env_...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create an Agent (required first step)
|
||||
|
||||
> ⚠️ **There is no inline agent config.** `Model`/`System`/`Tools` live on the agent object, not the session. Always start with `Beta.Agents.New()` — the session only takes `Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)}` (or the typed `OfBetaManagedAgentsAgents` variant when you need a specific version).
|
||||
|
||||
### Minimal
|
||||
|
||||
```go
|
||||
// 1. Create the agent (reusable, versioned)
|
||||
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
|
||||
Name: "Coding Assistant",
|
||||
Model: anthropic.BetaManagedAgentsModelConfigParams{
|
||||
ID: "claude-opus-4-7",
|
||||
Type: anthropic.BetaManagedAgentsModelConfigParamsTypeModelConfig,
|
||||
},
|
||||
System: anthropic.String("You are a helpful coding assistant."),
|
||||
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
|
||||
OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
|
||||
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
|
||||
},
|
||||
}},
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// 2. Start a session
|
||||
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
|
||||
Agent: anthropic.BetaSessionNewParamsAgentUnion{
|
||||
OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
|
||||
Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent,
|
||||
ID: agent.ID,
|
||||
Version: anthropic.Int(agent.Version),
|
||||
},
|
||||
},
|
||||
EnvironmentID: environment.ID,
|
||||
Title: anthropic.String("Quickstart session"),
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
fmt.Printf("Session ID: %s, status: %s\n", session.ID, session.Status)
|
||||
```
|
||||
|
||||
### Updating an Agent
|
||||
|
||||
Updates create new versions; the agent object is immutable per version.
|
||||
|
||||
```go
|
||||
updatedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
|
||||
Version: agent.Version,
|
||||
System: anthropic.String("You are a helpful coding agent. Always write tests."),
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
fmt.Printf("New version: %d\n", updatedAgent.Version)
|
||||
|
||||
// List all versions
|
||||
iter := client.Beta.Agents.Versions.ListAutoPaging(ctx, agent.ID, anthropic.BetaAgentVersionListParams{})
|
||||
for iter.Next() {
|
||||
version := iter.Current()
|
||||
fmt.Printf("Version %d: %s\n", version.Version, version.UpdatedAt.Format(time.RFC3339))
|
||||
}
|
||||
if err := iter.Err(); err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// Archive the agent
|
||||
_, err = client.Beta.Agents.Archive(ctx, agent.ID, anthropic.BetaAgentArchiveParams{})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Send a User Message
|
||||
|
||||
```go
|
||||
_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
|
||||
Events: []anthropic.SendEventsParamsUnion{{
|
||||
OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
|
||||
Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
|
||||
Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
|
||||
OfText: &anthropic.BetaManagedAgentsTextBlockParam{
|
||||
Type: anthropic.BetaManagedAgentsTextBlockTypeText,
|
||||
Text: "Review the auth module",
|
||||
},
|
||||
}},
|
||||
},
|
||||
}},
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns).
|
||||
|
||||
---
|
||||
|
||||
## Stream Events (SSE)
|
||||
|
||||
```go
|
||||
// Open the stream first, then send the user message
|
||||
stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
|
||||
defer stream.Close()
|
||||
|
||||
if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
|
||||
Events: []anthropic.SendEventsParamsUnion{{
|
||||
OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
|
||||
Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
|
||||
Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
|
||||
OfText: &anthropic.BetaManagedAgentsTextBlockParam{
|
||||
Type: anthropic.BetaManagedAgentsTextBlockTypeText,
|
||||
Text: "Summarize the repo README",
|
||||
},
|
||||
}},
|
||||
},
|
||||
}},
|
||||
}); err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
events:
|
||||
for stream.Next() {
|
||||
switch event := stream.Current().AsAny().(type) {
|
||||
case anthropic.BetaManagedAgentsAgentMessageEvent:
|
||||
for _, block := range event.Content {
|
||||
fmt.Print(block.Text)
|
||||
}
|
||||
case anthropic.BetaManagedAgentsAgentToolUseEvent:
|
||||
fmt.Printf("\n[Using tool: %s]\n", event.Name)
|
||||
case anthropic.BetaManagedAgentsSessionStatusIdleEvent:
|
||||
break events
|
||||
case anthropic.BetaManagedAgentsSessionErrorEvent:
|
||||
fmt.Printf("\n[Error: %s]\n", event.Error.Message)
|
||||
break events
|
||||
}
|
||||
}
|
||||
if err := stream.Err(); err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
### Reconnecting and Tailing
|
||||
|
||||
When reconnecting mid-session, list past events first to dedupe, then tail live events:
|
||||
|
||||
```go
|
||||
stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
|
||||
defer stream.Close()
|
||||
|
||||
// Stream is open and buffering. List history before tailing live.
|
||||
seenEventIDs := map[string]struct{}{}
|
||||
history := client.Beta.Sessions.Events.ListAutoPaging(ctx, session.ID, anthropic.BetaSessionEventListParams{})
|
||||
for history.Next() {
|
||||
seenEventIDs[history.Current().ID] = struct{}{}
|
||||
}
|
||||
if err := history.Err(); err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// Tail live events, skipping anything already seen
|
||||
tail:
|
||||
for stream.Next() {
|
||||
event := stream.Current()
|
||||
if _, seen := seenEventIDs[event.ID]; seen {
|
||||
continue
|
||||
}
|
||||
seenEventIDs[event.ID] = struct{}{}
|
||||
switch event := event.AsAny().(type) {
|
||||
case anthropic.BetaManagedAgentsAgentMessageEvent:
|
||||
for _, block := range event.Content {
|
||||
fmt.Print(block.Text)
|
||||
}
|
||||
case anthropic.BetaManagedAgentsSessionStatusIdleEvent:
|
||||
break tail
|
||||
}
|
||||
}
|
||||
if err := stream.Err(); err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Provide Custom Tool Result
|
||||
|
||||
> ℹ️ The Go managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `github.com/anthropics/anthropic-sdk-go` repository for the corresponding Go params types.
|
||||
|
||||
---
|
||||
|
||||
## Poll Events
|
||||
|
||||
```go
|
||||
// Auto-paginating iterator
|
||||
iter := client.Beta.Sessions.Events.ListAutoPaging(ctx, session.ID, anthropic.BetaSessionEventListParams{})
|
||||
for iter.Next() {
|
||||
event := iter.Current()
|
||||
fmt.Printf("%s: %s\n", event.Type, event.ID)
|
||||
}
|
||||
if err := iter.Err(); err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Upload a File
|
||||
|
||||
```go
|
||||
csvFile, err := os.Open("data.csv")
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
defer csvFile.Close()
|
||||
|
||||
file, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{
|
||||
File: csvFile,
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
fmt.Printf("File ID: %s\n", file.ID)
|
||||
|
||||
// Mount in a session
|
||||
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
|
||||
Agent: anthropic.BetaSessionNewParamsAgentUnion{
|
||||
OfString: anthropic.String(agent.ID),
|
||||
},
|
||||
EnvironmentID: environment.ID,
|
||||
Resources: []anthropic.BetaSessionNewParamsResourceUnion{{
|
||||
OfFile: &anthropic.BetaManagedAgentsFileResourceParams{
|
||||
Type: anthropic.BetaManagedAgentsFileResourceParamsTypeFile,
|
||||
FileID: file.ID,
|
||||
MountPath: anthropic.String("/workspace/data.csv"),
|
||||
},
|
||||
}},
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
### Add and Manage Resources on an Existing Session
|
||||
|
||||
```go
|
||||
// Attach an additional file to an open session
|
||||
resource, err := client.Beta.Sessions.Resources.Add(ctx, session.ID, anthropic.BetaSessionResourceAddParams{
|
||||
BetaManagedAgentsFileResourceParams: anthropic.BetaManagedAgentsFileResourceParams{
|
||||
Type: anthropic.BetaManagedAgentsFileResourceParamsTypeFile,
|
||||
FileID: file.ID,
|
||||
},
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
fmt.Println(resource.ID) // "sesrsc_01ABC..."
|
||||
|
||||
// List resources on the session
|
||||
listed, err := client.Beta.Sessions.Resources.List(ctx, session.ID, anthropic.BetaSessionResourceListParams{})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
for _, entry := range listed.Data {
|
||||
fmt.Println(entry.ID, entry.Type)
|
||||
}
|
||||
|
||||
// Detach a resource
|
||||
if _, err := client.Beta.Sessions.Resources.Delete(ctx, resource.ID, anthropic.BetaSessionResourceDeleteParams{
|
||||
SessionID: session.ID,
|
||||
}); err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## List and Download Session Files
|
||||
|
||||
> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for Go in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `github.com/anthropics/anthropic-sdk-go` repository for the `Beta.Files.List` and `Beta.Files.Download` Go params types.
|
||||
|
||||
---
|
||||
|
||||
## Session Management
|
||||
|
||||
```go
|
||||
// List environments
|
||||
environments, err := client.Beta.Environments.List(ctx, anthropic.BetaEnvironmentListParams{})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// Retrieve a specific environment
|
||||
env, err := client.Beta.Environments.Get(ctx, environment.ID, anthropic.BetaEnvironmentGetParams{})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// Archive an environment (read-only, existing sessions continue)
|
||||
_, err = client.Beta.Environments.Archive(ctx, environment.ID, anthropic.BetaEnvironmentArchiveParams{})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// Delete an environment (only if no sessions reference it)
|
||||
_, err = client.Beta.Environments.Delete(ctx, environment.ID, anthropic.BetaEnvironmentDeleteParams{})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// Delete a session
|
||||
_, err = client.Beta.Sessions.Delete(ctx, session.ID, anthropic.BetaSessionDeleteParams{})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Integration
|
||||
|
||||
```go
|
||||
// Agent declares MCP server (no auth here — auth goes in a vault)
|
||||
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
|
||||
Name: "GitHub Assistant",
|
||||
Model: anthropic.BetaManagedAgentsModelConfigParams{
|
||||
ID: "claude-opus-4-7",
|
||||
Type: anthropic.BetaManagedAgentsModelConfigParamsTypeModelConfig,
|
||||
},
|
||||
MCPServers: []anthropic.BetaManagedAgentsUrlmcpServerParams{{
|
||||
Type: anthropic.BetaManagedAgentsUrlmcpServerParamsTypeURL,
|
||||
Name: "github",
|
||||
URL: "https://api.githubcopilot.com/mcp/",
|
||||
}},
|
||||
Tools: []anthropic.BetaAgentNewParamsToolUnion{
|
||||
{
|
||||
OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
|
||||
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
|
||||
},
|
||||
},
|
||||
{
|
||||
OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{
|
||||
Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset,
|
||||
MCPServerName: "github",
|
||||
},
|
||||
},
|
||||
},
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// Session attaches vault(s) containing credentials for those MCP server URLs
|
||||
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
|
||||
Agent: anthropic.BetaSessionNewParamsAgentUnion{
|
||||
OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
|
||||
Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent,
|
||||
ID: agent.ID,
|
||||
Version: anthropic.Int(agent.Version),
|
||||
},
|
||||
},
|
||||
EnvironmentID: environment.ID,
|
||||
VaultIDs: []string{vault.ID},
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials.
|
||||
|
||||
---
|
||||
|
||||
## Vaults
|
||||
|
||||
```go
|
||||
// Create a vault
|
||||
vault, err := client.Beta.Vaults.New(ctx, anthropic.BetaVaultNewParams{
|
||||
DisplayName: "Alice",
|
||||
Metadata: map[string]string{"external_user_id": "usr_abc123"},
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// Add an OAuth credential
|
||||
credential, err := client.Beta.Vaults.Credentials.New(ctx, vault.ID, anthropic.BetaVaultCredentialNewParams{
|
||||
DisplayName: anthropic.String("Alice's Slack"),
|
||||
Auth: anthropic.BetaVaultCredentialNewParamsAuthUnion{
|
||||
OfMCPOAuth: &anthropic.BetaManagedAgentsMCPOAuthCreateParams{
|
||||
Type: anthropic.BetaManagedAgentsMCPOAuthCreateParamsTypeMCPOAuth,
|
||||
MCPServerURL: "https://mcp.slack.com/mcp",
|
||||
AccessToken: "xoxp-...",
|
||||
ExpiresAt: anthropic.Time(time.Date(2026, time.April, 15, 0, 0, 0, 0, time.UTC)),
|
||||
Refresh: anthropic.BetaManagedAgentsMCPOAuthRefreshParams{
|
||||
TokenEndpoint: "https://slack.com/api/oauth.v2.access",
|
||||
ClientID: "1234567890.0987654321",
|
||||
Scope: anthropic.String("channels:read chat:write"),
|
||||
RefreshToken: "xoxe-1-...",
|
||||
TokenEndpointAuth: anthropic.BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnion{
|
||||
OfClientSecretPost: &anthropic.BetaManagedAgentsTokenEndpointAuthPostParam{
|
||||
Type: anthropic.BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost,
|
||||
ClientSecret: "abc123...",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// Rotate the credential (e.g., after a token refresh)
|
||||
_, err = client.Beta.Vaults.Credentials.Update(ctx, credential.ID, anthropic.BetaVaultCredentialUpdateParams{
|
||||
VaultID: vault.ID,
|
||||
Auth: anthropic.BetaVaultCredentialUpdateParamsAuthUnion{
|
||||
OfMCPOAuth: &anthropic.BetaManagedAgentsMCPOAuthUpdateParams{
|
||||
Type: anthropic.BetaManagedAgentsMCPOAuthUpdateParamsTypeMCPOAuth,
|
||||
AccessToken: anthropic.String("xoxp-new-..."),
|
||||
ExpiresAt: anthropic.Time(time.Date(2026, time.May, 15, 0, 0, 0, 0, time.UTC)),
|
||||
Refresh: anthropic.BetaManagedAgentsMCPOAuthRefreshUpdateParams{
|
||||
RefreshToken: anthropic.String("xoxe-1-new-..."),
|
||||
},
|
||||
},
|
||||
},
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// Archive a vault
|
||||
_, err = client.Beta.Vaults.Archive(ctx, vault.ID, anthropic.BetaVaultArchiveParams{})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GitHub Repository Integration
|
||||
|
||||
Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential):
|
||||
|
||||
```go
|
||||
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
|
||||
Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
|
||||
EnvironmentID: environment.ID,
|
||||
VaultIDs: []string{vault.ID},
|
||||
Resources: []anthropic.BetaSessionNewParamsResourceUnion{
|
||||
{
|
||||
OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{
|
||||
Type: anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository,
|
||||
URL: "https://github.com/org/repo",
|
||||
MountPath: anthropic.String("/workspace/repo"),
|
||||
AuthorizationToken: "ghp_your_github_token",
|
||||
},
|
||||
},
|
||||
},
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
Multiple repositories on the same session:
|
||||
|
||||
```go
|
||||
resources := []anthropic.BetaSessionNewParamsResourceUnion{
|
||||
{
|
||||
OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{
|
||||
Type: anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository,
|
||||
URL: "https://github.com/org/frontend",
|
||||
MountPath: anthropic.String("/workspace/frontend"),
|
||||
AuthorizationToken: "ghp_your_github_token",
|
||||
},
|
||||
},
|
||||
{
|
||||
OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{
|
||||
Type: anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository,
|
||||
URL: "https://github.com/org/backend",
|
||||
MountPath: anthropic.String("/workspace/backend"),
|
||||
AuthorizationToken: "ghp_your_github_token",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Rotating a repository's authorization token:
|
||||
|
||||
```go
|
||||
listed, err := client.Beta.Sessions.Resources.List(ctx, session.ID, anthropic.BetaSessionResourceListParams{})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
repoResourceID := listed.Data[0].ID
|
||||
|
||||
_, err = client.Beta.Sessions.Resources.Update(ctx, repoResourceID, anthropic.BetaSessionResourceUpdateParams{
|
||||
SessionID: session.ID,
|
||||
AuthorizationToken: "ghp_your_new_github_token",
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,432 @@
|
||||
# Claude API — Java
|
||||
|
||||
> **Note:** The Java SDK supports the Claude API and beta tool use with annotated classes. Agent SDK is not yet available for Java.
|
||||
|
||||
## Installation
|
||||
|
||||
Maven:
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.anthropic</groupId>
|
||||
<artifactId>anthropic-java</artifactId>
|
||||
<version>2.17.0</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
Gradle:
|
||||
|
||||
```groovy
|
||||
implementation("com.anthropic:anthropic-java:2.17.0")
|
||||
```
|
||||
|
||||
## Client Initialization
|
||||
|
||||
```java
|
||||
import com.anthropic.client.AnthropicClient;
|
||||
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
|
||||
|
||||
// Default (reads ANTHROPIC_API_KEY from environment)
|
||||
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
|
||||
|
||||
// Explicit API key
|
||||
AnthropicClient client = AnthropicOkHttpClient.builder()
|
||||
.apiKey("your-api-key")
|
||||
.build();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Basic Message Request
|
||||
|
||||
```java
|
||||
import com.anthropic.models.messages.MessageCreateParams;
|
||||
import com.anthropic.models.messages.Message;
|
||||
import com.anthropic.models.messages.Model;
|
||||
|
||||
MessageCreateParams params = MessageCreateParams.builder()
|
||||
.model(Model.CLAUDE_OPUS_4_6)
|
||||
.maxTokens(16000L)
|
||||
.addUserMessage("What is the capital of France?")
|
||||
.build();
|
||||
|
||||
Message response = client.messages().create(params);
|
||||
response.content().stream()
|
||||
.flatMap(block -> block.text().stream())
|
||||
.forEach(textBlock -> System.out.println(textBlock.text()));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Streaming
|
||||
|
||||
```java
|
||||
import com.anthropic.core.http.StreamResponse;
|
||||
import com.anthropic.models.messages.RawMessageStreamEvent;
|
||||
|
||||
MessageCreateParams params = MessageCreateParams.builder()
|
||||
.model(Model.CLAUDE_OPUS_4_6)
|
||||
.maxTokens(64000L)
|
||||
.addUserMessage("Write a haiku")
|
||||
.build();
|
||||
|
||||
try (StreamResponse<RawMessageStreamEvent> streamResponse = client.messages().createStreaming(params)) {
|
||||
streamResponse.stream()
|
||||
.flatMap(event -> event.contentBlockDelta().stream())
|
||||
.flatMap(deltaEvent -> deltaEvent.delta().text().stream())
|
||||
.forEach(textDelta -> System.out.print(textDelta.text()));
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Thinking
|
||||
|
||||
**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. The builder has a direct `.thinking(ThinkingConfigAdaptive)` overload — no manual union wrapping.
|
||||
|
||||
```java
|
||||
import com.anthropic.models.messages.ContentBlock;
|
||||
import com.anthropic.models.messages.MessageCreateParams;
|
||||
import com.anthropic.models.messages.Model;
|
||||
import com.anthropic.models.messages.ThinkingConfigAdaptive;
|
||||
|
||||
MessageCreateParams params = MessageCreateParams.builder()
|
||||
.model(Model.CLAUDE_SONNET_4_6)
|
||||
.maxTokens(16000L)
|
||||
.thinking(ThinkingConfigAdaptive.builder().build())
|
||||
.addUserMessage("Solve this step by step: 27 * 453")
|
||||
.build();
|
||||
|
||||
for (ContentBlock block : client.messages().create(params).content()) {
|
||||
block.thinking().ifPresent(t -> System.out.println("[thinking] " + t.thinking()));
|
||||
block.text().ifPresent(t -> System.out.println(t.text()));
|
||||
}
|
||||
```
|
||||
|
||||
> **Deprecated:** `ThinkingConfigEnabled.builder().budgetTokens(N)` (and the `.enabledThinking(N)` shortcut) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
|
||||
|
||||
`ContentBlock` narrowing: `.thinking()` / `.text()` return `Optional<T>` — use `.ifPresent(...)` or `.stream().flatMap(...)`. Alternative: `isThinking()` / `asThinking()` boolean+unwrap pairs (throws on wrong variant).
|
||||
|
||||
---
|
||||
|
||||
## Tool Use (Beta)
|
||||
|
||||
The Java SDK supports beta tool use with annotated classes. Tool classes implement `Supplier<String>` for automatic execution via `BetaToolRunner`.
|
||||
|
||||
### Tool Runner (automatic loop)
|
||||
|
||||
```java
|
||||
import com.anthropic.models.beta.messages.MessageCreateParams;
|
||||
import com.anthropic.models.beta.messages.BetaMessage;
|
||||
import com.anthropic.helpers.BetaToolRunner;
|
||||
import com.fasterxml.jackson.annotation.JsonClassDescription;
|
||||
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
|
||||
import java.util.function.Supplier;
|
||||
|
||||
@JsonClassDescription("Get the weather in a given location")
|
||||
static class GetWeather implements Supplier<String> {
|
||||
@JsonPropertyDescription("The city and state, e.g. San Francisco, CA")
|
||||
public String location;
|
||||
|
||||
@Override
|
||||
public String get() {
|
||||
return "The weather in " + location + " is sunny and 72°F";
|
||||
}
|
||||
}
|
||||
|
||||
BetaToolRunner toolRunner = client.beta().messages().toolRunner(
|
||||
MessageCreateParams.builder()
|
||||
.model("claude-opus-4-7")
|
||||
.maxTokens(16000L)
|
||||
.putAdditionalHeader("anthropic-beta", "structured-outputs-2025-11-13")
|
||||
.addTool(GetWeather.class)
|
||||
.addUserMessage("What's the weather in San Francisco?")
|
||||
.build());
|
||||
|
||||
for (BetaMessage message : toolRunner) {
|
||||
System.out.println(message);
|
||||
}
|
||||
```
|
||||
|
||||
### Memory Tool
|
||||
|
||||
The Java SDK provides `BetaMemoryToolHandler` for implementing the memory tool backend. You supply a handler that manages file storage, and the `BetaToolRunner` handles memory tool calls automatically.
|
||||
|
||||
```java
|
||||
import com.anthropic.helpers.BetaMemoryToolHandler;
|
||||
import com.anthropic.helpers.BetaToolRunner;
|
||||
import com.anthropic.models.beta.messages.BetaMemoryTool20250818;
|
||||
import com.anthropic.models.beta.messages.BetaMessage;
|
||||
import com.anthropic.models.beta.messages.MessageCreateParams;
|
||||
import com.anthropic.models.beta.messages.ToolRunnerCreateParams;
|
||||
|
||||
// Implement BetaMemoryToolHandler with your storage backend (e.g., filesystem)
|
||||
BetaMemoryToolHandler memoryHandler = new FileSystemMemoryToolHandler(sandboxRoot);
|
||||
|
||||
MessageCreateParams createParams = MessageCreateParams.builder()
|
||||
.model("claude-opus-4-7")
|
||||
.maxTokens(4096L)
|
||||
.addTool(BetaMemoryTool20250818.builder().build())
|
||||
.addUserMessage("Remember that my favorite color is blue")
|
||||
.build();
|
||||
|
||||
BetaToolRunner toolRunner = client.beta().messages().toolRunner(
|
||||
ToolRunnerCreateParams.builder()
|
||||
.betaMemoryToolHandler(memoryHandler)
|
||||
.initialMessageParams(createParams)
|
||||
.build());
|
||||
|
||||
for (BetaMessage message : toolRunner) {
|
||||
System.out.println(message);
|
||||
}
|
||||
```
|
||||
|
||||
See the [shared memory tool concepts](../shared/tool-use-concepts.md) for more details on the memory tool.
|
||||
|
||||
### Non-Beta Tool Declaration (manual JSON schema)
|
||||
|
||||
`Tool.InputSchema.Properties` is a freeform `Map<String, JsonValue>` wrapper — build property schemas via `putAdditionalProperty`. `type: "object"` is the default. The builder has a direct `.addTool(Tool)` overload that wraps in `ToolUnion` automatically.
|
||||
|
||||
```java
|
||||
import com.anthropic.core.JsonValue;
|
||||
import com.anthropic.models.messages.Tool;
|
||||
|
||||
Tool tool = Tool.builder()
|
||||
.name("get_weather")
|
||||
.description("Get the current weather in a given location")
|
||||
.inputSchema(Tool.InputSchema.builder()
|
||||
.properties(Tool.InputSchema.Properties.builder()
|
||||
.putAdditionalProperty("location", JsonValue.from(Map.of("type", "string")))
|
||||
.build())
|
||||
.required(List.of("location"))
|
||||
.build())
|
||||
.build();
|
||||
|
||||
MessageCreateParams params = MessageCreateParams.builder()
|
||||
.model(Model.CLAUDE_SONNET_4_6)
|
||||
.maxTokens(16000L)
|
||||
.addTool(tool)
|
||||
.addUserMessage("Weather in Paris?")
|
||||
.build();
|
||||
```
|
||||
|
||||
For manual tool loops, handle `tool_use` blocks in the response, send `tool_result` back, loop until `stop_reason` is `"end_turn"`. See [shared tool use concepts](../shared/tool-use-concepts.md).
|
||||
|
||||
### Building `MessageParam` with Content Blocks (Tool Result Round-Trip)
|
||||
|
||||
`MessageParam.Content` is an inner union class (string | list). Use the builder's `.contentOfBlockParams(List<ContentBlockParam>)` alias — there is NO separate `MessageParamContent` class with a static `ofBlockParams`:
|
||||
|
||||
```java
|
||||
import com.anthropic.models.messages.MessageParam;
|
||||
import com.anthropic.models.messages.ContentBlockParam;
|
||||
import com.anthropic.models.messages.ToolResultBlockParam;
|
||||
|
||||
List<ContentBlockParam> results = List.of(
|
||||
ContentBlockParam.ofToolResult(ToolResultBlockParam.builder()
|
||||
.toolUseId(toolUseBlock.id())
|
||||
.content(yourResultString)
|
||||
.build())
|
||||
);
|
||||
|
||||
MessageParam toolResultMsg = MessageParam.builder()
|
||||
.role(MessageParam.Role.USER)
|
||||
.contentOfBlockParams(results) // builder alias for Content.ofBlockParams(...)
|
||||
.build();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Effort Parameter
|
||||
|
||||
Effort is nested inside `OutputConfig` — there is NO `.effort()` directly on `MessageCreateParams.Builder`.
|
||||
|
||||
```java
|
||||
import com.anthropic.models.messages.OutputConfig;
|
||||
|
||||
.outputConfig(OutputConfig.builder()
|
||||
.effort(OutputConfig.Effort.HIGH) // or LOW, MEDIUM, MAX
|
||||
.build())
|
||||
```
|
||||
|
||||
Combine with `Thinking = ThinkingConfigAdaptive` for cost-quality control.
|
||||
|
||||
---
|
||||
|
||||
## Prompt Caching
|
||||
|
||||
System message as a list of `TextBlockParam` with `CacheControlEphemeral`. Use `.systemOfTextBlockParams(...)` — the plain `.system(String)` overload can't carry cache control. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
|
||||
|
||||
```java
|
||||
import com.anthropic.models.messages.TextBlockParam;
|
||||
import com.anthropic.models.messages.CacheControlEphemeral;
|
||||
|
||||
.systemOfTextBlockParams(List.of(
|
||||
TextBlockParam.builder()
|
||||
.text(longSystemPrompt)
|
||||
.cacheControl(CacheControlEphemeral.builder()
|
||||
.ttl(CacheControlEphemeral.Ttl.TTL_1H) // optional; also TTL_5M
|
||||
.build())
|
||||
.build()))
|
||||
```
|
||||
|
||||
There's also a top-level `.cacheControl(CacheControlEphemeral)` on `MessageCreateParams.Builder` and on `Tool.builder()`.
|
||||
|
||||
Verify hits via `response.usage().cacheCreationInputTokens()` / `response.usage().cacheReadInputTokens()`.
|
||||
|
||||
---
|
||||
|
||||
## Token Counting
|
||||
|
||||
```java
|
||||
import com.anthropic.models.messages.MessageCountTokensParams;
|
||||
|
||||
long tokens = client.messages().countTokens(
|
||||
MessageCountTokensParams.builder()
|
||||
.model(Model.CLAUDE_SONNET_4_6)
|
||||
.addUserMessage("Hello")
|
||||
.build()
|
||||
).inputTokens();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Structured Output
|
||||
|
||||
The class-based overload auto-derives the JSON schema from your POJO and gives you a typed `.text()` return — no manual schema, no manual parsing.
|
||||
|
||||
```java
|
||||
import com.anthropic.models.messages.StructuredMessageCreateParams;
|
||||
|
||||
record Book(String title, String author) {}
|
||||
record BookList(List<Book> books) {}
|
||||
|
||||
StructuredMessageCreateParams<BookList> params = MessageCreateParams.builder()
|
||||
.model(Model.CLAUDE_SONNET_4_6)
|
||||
.maxTokens(16000L)
|
||||
.outputConfig(BookList.class) // returns a typed builder
|
||||
.addUserMessage("List 3 classic novels")
|
||||
.build();
|
||||
|
||||
client.messages().create(params).content().stream()
|
||||
.flatMap(cb -> cb.text().stream())
|
||||
.forEach(typed -> {
|
||||
// typed.text() returns BookList, not String
|
||||
for (Book b : typed.text().books()) System.out.println(b.title());
|
||||
});
|
||||
```
|
||||
|
||||
Supports Jackson annotations: `@JsonPropertyDescription`, `@JsonIgnore`, `@ArraySchema(minItems=...)`. Manual schema path: `OutputConfig.builder().format(JsonOutputFormat.builder().schema(...).build())`.
|
||||
|
||||
---
|
||||
|
||||
## PDF / Document Input
|
||||
|
||||
`DocumentBlockParam` builder has source shortcuts. Wrap in `ContentBlockParam.ofDocument()` and pass via `.addUserMessageOfBlockParams()`.
|
||||
|
||||
```java
|
||||
import com.anthropic.models.messages.DocumentBlockParam;
|
||||
import com.anthropic.models.messages.ContentBlockParam;
|
||||
import com.anthropic.models.messages.TextBlockParam;
|
||||
|
||||
DocumentBlockParam doc = DocumentBlockParam.builder()
|
||||
.base64Source(base64String) // or .urlSource("https://...") or .textSource("...")
|
||||
.title("My Document") // optional
|
||||
.build();
|
||||
|
||||
.addUserMessageOfBlockParams(List.of(
|
||||
ContentBlockParam.ofDocument(doc),
|
||||
ContentBlockParam.ofText(TextBlockParam.builder().text("Summarize this").build())))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Tools
|
||||
|
||||
Version-suffixed types; `name`/`type` auto-set by builder. Direct `.addTool()` overloads exist for every type — no manual `ToolUnion` wrapping.
|
||||
|
||||
```java
|
||||
import com.anthropic.models.messages.WebSearchTool20260209;
|
||||
import com.anthropic.models.messages.ToolBash20250124;
|
||||
import com.anthropic.models.messages.ToolTextEditor20250728;
|
||||
import com.anthropic.models.messages.CodeExecutionTool20260120;
|
||||
|
||||
.addTool(WebSearchTool20260209.builder()
|
||||
.maxUses(5L) // optional
|
||||
.allowedDomains(List.of("example.com")) // optional
|
||||
.build())
|
||||
.addTool(ToolBash20250124.builder().build())
|
||||
.addTool(ToolTextEditor20250728.builder().build())
|
||||
.addTool(CodeExecutionTool20260120.builder().build())
|
||||
```
|
||||
|
||||
Also available: `WebFetchTool20260209`, `MemoryTool20250818`, `ToolSearchToolBm25_20251119`.
|
||||
|
||||
### Beta namespace (MCP, compaction)
|
||||
|
||||
For beta-only features use `com.anthropic.models.beta.messages.*` — class names have a `Beta` prefix AND live in the beta package. The beta `MessageCreateParams.Builder` has direct `.addTool(BetaToolBash20250124)` overloads AND `.addMcpServer()`:
|
||||
|
||||
```java
|
||||
import com.anthropic.models.beta.messages.MessageCreateParams;
|
||||
import com.anthropic.models.beta.messages.BetaToolBash20250124;
|
||||
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20260120;
|
||||
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
|
||||
|
||||
MessageCreateParams params = MessageCreateParams.builder()
|
||||
.model(Model.CLAUDE_OPUS_4_6)
|
||||
.maxTokens(16000L)
|
||||
.addBeta("mcp-client-2025-11-20")
|
||||
.addTool(BetaToolBash20250124.builder().build())
|
||||
.addTool(BetaCodeExecutionTool20260120.builder().build())
|
||||
.addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
|
||||
.name("my-server")
|
||||
.url("https://example.com/mcp")
|
||||
.build())
|
||||
.addUserMessage("...")
|
||||
.build();
|
||||
|
||||
client.beta().messages().create(params);
|
||||
```
|
||||
|
||||
`BetaTool*` types are NOT interchangeable with non-beta `Tool*` — pick one namespace per request.
|
||||
|
||||
**Reading server-tool blocks in the response:** `ServerToolUseBlock` has `.id()`, `.name()` (enum), and `._input()` returning raw `JsonValue` — there is NO typed `.input()`. For code execution results, unwrap two levels:
|
||||
|
||||
```java
|
||||
for (ContentBlock block : response.content()) {
|
||||
block.serverToolUse().ifPresent(stu -> {
|
||||
System.out.println("tool: " + stu.name() + " input: " + stu._input());
|
||||
});
|
||||
block.codeExecutionToolResult().ifPresent(r -> {
|
||||
r.content().resultBlock().ifPresent(result -> {
|
||||
System.out.println("stdout: " + result.stdout());
|
||||
System.out.println("stderr: " + result.stderr());
|
||||
System.out.println("exit: " + result.returnCode());
|
||||
});
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Files API (Beta)
|
||||
|
||||
Under `client.beta().files()`. File references in messages need the beta message types (non-beta `DocumentBlockParam.Source` has no file-ID variant).
|
||||
|
||||
```java
|
||||
import com.anthropic.models.beta.files.FileUploadParams;
|
||||
import com.anthropic.models.beta.files.FileMetadata;
|
||||
import com.anthropic.models.beta.messages.BetaRequestDocumentBlock;
|
||||
import java.nio.file.Paths;
|
||||
|
||||
FileMetadata meta = client.beta().files().upload(
|
||||
FileUploadParams.builder()
|
||||
.file(Paths.get("/path/to/doc.pdf")) // or .file(InputStream) or .file(byte[])
|
||||
.build());
|
||||
|
||||
// Reference in a beta message:
|
||||
BetaRequestDocumentBlock doc = BetaRequestDocumentBlock.builder()
|
||||
.fileSource(meta.id())
|
||||
.build();
|
||||
```
|
||||
|
||||
Other methods: `.list()`, `.delete(String fileId)`, `.download(String fileId)`, `.retrieveMetadata(String fileId)`.
|
||||
@@ -0,0 +1,442 @@
|
||||
# Managed Agents — Java
|
||||
|
||||
> **Bindings not shown here:** This README covers the most common managed-agents flows for Java. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Java SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
|
||||
|
||||
> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `client.beta().agents().create` and pass it to every subsequent `client.beta().sessions().create`; do not call `agents().create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
|
||||
|
||||
## Installation
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.anthropic</groupId>
|
||||
<artifactId>anthropic-java</artifactId>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
## Client Initialization
|
||||
|
||||
```java
|
||||
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
|
||||
|
||||
// Default (uses ANTHROPIC_API_KEY env var)
|
||||
var client = AnthropicOkHttpClient.fromEnv();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create an Environment
|
||||
|
||||
```java
|
||||
import com.anthropic.models.beta.environments.BetaCloudConfigParams;
|
||||
import com.anthropic.models.beta.environments.EnvironmentCreateParams;
|
||||
import com.anthropic.models.beta.environments.UnrestrictedNetwork;
|
||||
|
||||
var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
|
||||
.name("my-dev-env")
|
||||
.config(BetaCloudConfigParams.builder()
|
||||
.networking(UnrestrictedNetwork.builder().build())
|
||||
.build())
|
||||
.build());
|
||||
System.out.println("Environment ID: " + environment.id()); // env_...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create an Agent (required first step)
|
||||
|
||||
> ⚠️ **There is no inline agent config.** Model, system, and tools live on the agent object, not the session. Always start with `client.beta().agents().create()` — the session takes either `.agent(agent.id())` or the typed `BetaManagedAgentsAgentParams.builder()...build()`.
|
||||
|
||||
### Minimal
|
||||
|
||||
```java
|
||||
import com.anthropic.models.beta.agents.AgentCreateParams;
|
||||
import com.anthropic.models.beta.agents.BetaManagedAgentsAgentToolset20260401Params;
|
||||
import com.anthropic.models.beta.sessions.BetaManagedAgentsAgentParams;
|
||||
import com.anthropic.models.beta.sessions.SessionCreateParams;
|
||||
|
||||
// 1. Create the agent (reusable, versioned)
|
||||
var agent = client.beta().agents().create(AgentCreateParams.builder()
|
||||
.name("Coding Assistant")
|
||||
.model("claude-opus-4-7")
|
||||
.system("You are a helpful coding assistant.")
|
||||
.addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
|
||||
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
|
||||
.build())
|
||||
.build());
|
||||
|
||||
// 2. Start a session
|
||||
var session = client.beta().sessions().create(SessionCreateParams.builder()
|
||||
.agent(BetaManagedAgentsAgentParams.builder()
|
||||
.type(BetaManagedAgentsAgentParams.Type.AGENT)
|
||||
.id(agent.id())
|
||||
.version(agent.version())
|
||||
.build())
|
||||
.environmentId(environment.id())
|
||||
.title("Quickstart session")
|
||||
.build());
|
||||
System.out.println("Session ID: " + session.id());
|
||||
```
|
||||
|
||||
### Updating an Agent
|
||||
|
||||
Updates create new versions; the agent object is immutable per version.
|
||||
|
||||
```java
|
||||
import com.anthropic.models.beta.agents.AgentUpdateParams;
|
||||
|
||||
var updatedAgent = client.beta().agents().update(agent.id(), AgentUpdateParams.builder()
|
||||
.version(agent.version())
|
||||
.system("You are a helpful coding agent. Always write tests.")
|
||||
.build());
|
||||
System.out.println("New version: " + updatedAgent.version());
|
||||
|
||||
// List all versions
|
||||
for (var version : client.beta().agents().versions().list(agent.id()).autoPager()) {
|
||||
System.out.println("Version " + version.version() + ": " + version.updatedAt());
|
||||
}
|
||||
|
||||
// Archive the agent
|
||||
var archived = client.beta().agents().archive(agent.id());
|
||||
System.out.println("Archived at: " + archived.archivedAt().orElseThrow());
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Send a User Message
|
||||
|
||||
```java
|
||||
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserMessageEventParams;
|
||||
import com.anthropic.models.beta.sessions.events.EventSendParams;
|
||||
|
||||
client.beta().sessions().events().send(session.id(), EventSendParams.builder()
|
||||
.addEvent(BetaManagedAgentsUserMessageEventParams.builder()
|
||||
.type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
|
||||
.addTextContent("Review the auth module")
|
||||
.build())
|
||||
.build());
|
||||
```
|
||||
|
||||
> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns).
|
||||
|
||||
---
|
||||
|
||||
## Stream Events (SSE)
|
||||
|
||||
```java
|
||||
import com.anthropic.models.beta.sessions.events.StreamEvents;
|
||||
|
||||
// Open the stream first, then send the user message
|
||||
try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
|
||||
client.beta().sessions().events().send(session.id(), EventSendParams.builder()
|
||||
.addEvent(BetaManagedAgentsUserMessageEventParams.builder()
|
||||
.type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
|
||||
.addTextContent("Summarize the repo README")
|
||||
.build())
|
||||
.build());
|
||||
|
||||
for (var event : (Iterable<StreamEvents>) stream.stream()::iterator) {
|
||||
if (event.isAgentMessage()) {
|
||||
event.asAgentMessage().content().forEach(block -> System.out.print(block.text()));
|
||||
} else if (event.isAgentToolUse()) {
|
||||
System.out.println("\n[Using tool: " + event.asAgentToolUse().name() + "]");
|
||||
} else if (event.isSessionStatusIdle()) {
|
||||
break;
|
||||
} else if (event.isSessionError()) {
|
||||
System.out.println("\n[Error]");
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Reconnecting and Tailing
|
||||
|
||||
When reconnecting mid-session, list past events first to dedupe, then tail live events. The cross-variant `id` field is read from the raw `_json()` value:
|
||||
|
||||
```java
|
||||
import com.anthropic.core.JsonValue;
|
||||
import java.util.HashSet;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
|
||||
try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
|
||||
// Stream is open and buffering. List history before tailing live.
|
||||
var seenEventIds = new HashSet<String>();
|
||||
for (var past : client.beta().sessions().events().list(session.id()).autoPager()) {
|
||||
Optional<Map<String, JsonValue>> obj = past._json().orElseThrow().asObject();
|
||||
seenEventIds.add(obj.orElseThrow().get("id").asStringOrThrow());
|
||||
}
|
||||
|
||||
// Tail live events, skipping anything already seen
|
||||
for (var event : (Iterable<StreamEvents>) stream.stream()::iterator) {
|
||||
Optional<Map<String, JsonValue>> obj = event._json().orElseThrow().asObject();
|
||||
if (!seenEventIds.add(obj.orElseThrow().get("id").asStringOrThrow())) continue;
|
||||
if (event.isAgentMessage()) {
|
||||
event.asAgentMessage().content().forEach(block -> System.out.print(block.text()));
|
||||
} else if (event.isSessionStatusIdle()) {
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Provide Custom Tool Result
|
||||
|
||||
> ℹ️ The Java managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `anthropic-java` repository for the corresponding params types.
|
||||
|
||||
---
|
||||
|
||||
## Poll Events
|
||||
|
||||
```java
|
||||
for (var event : client.beta().sessions().events().list(session.id()).autoPager()) {
|
||||
System.out.println(event.type() + ": " + event);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Upload a File
|
||||
|
||||
```java
|
||||
import com.anthropic.models.beta.files.FileUploadParams;
|
||||
import com.anthropic.models.beta.sessions.BetaManagedAgentsFileResourceParams;
|
||||
import java.nio.file.Path;
|
||||
|
||||
var dataCsv = Path.of("data.csv");
|
||||
|
||||
var file = client.beta().files().upload(FileUploadParams.builder()
|
||||
.file(dataCsv)
|
||||
.build());
|
||||
System.out.println("File ID: " + file.id());
|
||||
|
||||
// Mount in a session
|
||||
var session = client.beta().sessions().create(SessionCreateParams.builder()
|
||||
.agent(agent.id())
|
||||
.environmentId(environment.id())
|
||||
.addResource(BetaManagedAgentsFileResourceParams.builder()
|
||||
.type(BetaManagedAgentsFileResourceParams.Type.FILE)
|
||||
.fileId(file.id())
|
||||
.mountPath("/workspace/data.csv")
|
||||
.build())
|
||||
.build());
|
||||
```
|
||||
|
||||
### Add and Manage Resources on an Existing Session
|
||||
|
||||
```java
|
||||
import com.anthropic.models.beta.sessions.resources.ResourceAddParams;
|
||||
import com.anthropic.models.beta.sessions.resources.ResourceDeleteParams;
|
||||
|
||||
// Attach an additional file to an open session
|
||||
var resource = client.beta().sessions().resources().add(session.id(), ResourceAddParams.builder()
|
||||
.betaManagedAgentsFileResourceParams(BetaManagedAgentsFileResourceParams.builder()
|
||||
.type(BetaManagedAgentsFileResourceParams.Type.FILE)
|
||||
.fileId(file.id())
|
||||
.build())
|
||||
.build());
|
||||
System.out.println(resource.id()); // "sesrsc_01ABC..."
|
||||
|
||||
// List resources on the session — entries are a discriminated union
|
||||
var listed = client.beta().sessions().resources().list(session.id());
|
||||
for (var entry : listed.data()) {
|
||||
if (entry.isFile()) {
|
||||
var fileResource = entry.asFile();
|
||||
System.out.println(fileResource.id() + " " + fileResource.type());
|
||||
} else if (entry.isGitHubRepository()) {
|
||||
var repoResource = entry.asGitHubRepository();
|
||||
System.out.println(repoResource.id() + " " + repoResource.type());
|
||||
}
|
||||
}
|
||||
|
||||
// Detach a resource
|
||||
client.beta().sessions().resources().delete(resource.id(), ResourceDeleteParams.builder()
|
||||
.sessionId(session.id())
|
||||
.build());
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## List and Download Session Files
|
||||
|
||||
> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for Java in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `anthropic-java` repository for the file list/download bindings.
|
||||
|
||||
---
|
||||
|
||||
## Session Management
|
||||
|
||||
```java
|
||||
// List environments
|
||||
var environments = client.beta().environments().list();
|
||||
|
||||
// Retrieve a specific environment
|
||||
var env = client.beta().environments().retrieve(environment.id());
|
||||
|
||||
// Archive an environment (read-only, existing sessions continue)
|
||||
client.beta().environments().archive(environment.id());
|
||||
|
||||
// Delete an environment (only if no sessions reference it)
|
||||
client.beta().environments().delete(environment.id());
|
||||
|
||||
// Delete a session
|
||||
client.beta().sessions().delete(session.id());
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Integration
|
||||
|
||||
```java
|
||||
import com.anthropic.models.beta.agents.BetaManagedAgentsMcpToolsetParams;
|
||||
import com.anthropic.models.beta.agents.BetaManagedAgentsUrlmcpServerParams;
|
||||
|
||||
// Agent declares MCP server (no auth here — auth goes in a vault)
|
||||
var agent = client.beta().agents().create(AgentCreateParams.builder()
|
||||
.name("GitHub Assistant")
|
||||
.model("claude-opus-4-7")
|
||||
.addMcpServer(BetaManagedAgentsUrlmcpServerParams.builder()
|
||||
.type(BetaManagedAgentsUrlmcpServerParams.Type.URL)
|
||||
.name("github")
|
||||
.url("https://api.githubcopilot.com/mcp/")
|
||||
.build())
|
||||
.addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
|
||||
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
|
||||
.build())
|
||||
.addTool(BetaManagedAgentsMcpToolsetParams.builder()
|
||||
.type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET)
|
||||
.mcpServerName("github")
|
||||
.build())
|
||||
.build());
|
||||
|
||||
// Session attaches vault(s) containing credentials for those MCP server URLs
|
||||
var session = client.beta().sessions().create(SessionCreateParams.builder()
|
||||
.agent(BetaManagedAgentsAgentParams.builder()
|
||||
.type(BetaManagedAgentsAgentParams.Type.AGENT)
|
||||
.id(agent.id())
|
||||
.version(agent.version())
|
||||
.build())
|
||||
.environmentId(environment.id())
|
||||
.addVaultId(vault.id())
|
||||
.build());
|
||||
```
|
||||
|
||||
See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials.
|
||||
|
||||
---
|
||||
|
||||
## Vaults
|
||||
|
||||
```java
|
||||
import com.anthropic.core.JsonValue;
|
||||
import com.anthropic.models.beta.vaults.VaultCreateParams;
|
||||
import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthCreateParams;
|
||||
import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthRefreshParams;
|
||||
import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthRefreshUpdateParams;
|
||||
import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthUpdateParams;
|
||||
import com.anthropic.models.beta.vaults.credentials.CredentialCreateParams;
|
||||
import com.anthropic.models.beta.vaults.credentials.CredentialUpdateParams;
|
||||
import java.time.OffsetDateTime;
|
||||
|
||||
// Create a vault
|
||||
var vault = client.beta().vaults().create(VaultCreateParams.builder()
|
||||
.displayName("Alice")
|
||||
.metadata(VaultCreateParams.Metadata.builder()
|
||||
.putAdditionalProperty("external_user_id", JsonValue.from("usr_abc123"))
|
||||
.build())
|
||||
.build());
|
||||
System.out.println(vault.id()); // "vlt_01ABC..."
|
||||
|
||||
// Add an OAuth credential
|
||||
var credential = client.beta().vaults().credentials().create(vault.id(),
|
||||
CredentialCreateParams.builder()
|
||||
.displayName("Alice's Slack")
|
||||
.auth(BetaManagedAgentsMcpOAuthCreateParams.builder()
|
||||
.type(BetaManagedAgentsMcpOAuthCreateParams.Type.MCP_OAUTH)
|
||||
.mcpServerUrl("https://mcp.slack.com/mcp")
|
||||
.accessToken("xoxp-...")
|
||||
.expiresAt(OffsetDateTime.parse("2026-04-15T00:00:00Z"))
|
||||
.refresh(BetaManagedAgentsMcpOAuthRefreshParams.builder()
|
||||
.tokenEndpoint("https://slack.com/api/oauth.v2.access")
|
||||
.clientId("1234567890.0987654321")
|
||||
.scope("channels:read chat:write")
|
||||
.refreshToken("xoxe-1-...")
|
||||
.clientSecretPostTokenEndpointAuth("abc123...")
|
||||
.build())
|
||||
.build())
|
||||
.build());
|
||||
|
||||
// Rotate the credential (e.g., after a token refresh)
|
||||
client.beta().vaults().credentials().update(credential.id(),
|
||||
CredentialUpdateParams.builder()
|
||||
.vaultId(vault.id())
|
||||
.auth(BetaManagedAgentsMcpOAuthUpdateParams.builder()
|
||||
.type(BetaManagedAgentsMcpOAuthUpdateParams.Type.MCP_OAUTH)
|
||||
.accessToken("xoxp-new-...")
|
||||
.expiresAt(OffsetDateTime.parse("2026-05-15T00:00:00Z"))
|
||||
.refresh(BetaManagedAgentsMcpOAuthRefreshUpdateParams.builder()
|
||||
.refreshToken("xoxe-1-new-...")
|
||||
.build())
|
||||
.build())
|
||||
.build());
|
||||
|
||||
// Archive a vault
|
||||
client.beta().vaults().archive(vault.id());
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GitHub Repository Integration
|
||||
|
||||
Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential):
|
||||
|
||||
```java
|
||||
import com.anthropic.models.beta.sessions.BetaManagedAgentsGitHubRepositoryResourceParams;
|
||||
|
||||
var session = client.beta().sessions().create(SessionCreateParams.builder()
|
||||
.agent(agent.id())
|
||||
.environmentId(environment.id())
|
||||
.addVaultId(vault.id())
|
||||
.addResource(BetaManagedAgentsGitHubRepositoryResourceParams.builder()
|
||||
.type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY)
|
||||
.url("https://github.com/org/repo")
|
||||
.mountPath("/workspace/repo")
|
||||
.authorizationToken("ghp_your_github_token")
|
||||
.build())
|
||||
.build());
|
||||
```
|
||||
|
||||
Multiple repositories on the same session:
|
||||
|
||||
```java
|
||||
import java.util.List;
|
||||
|
||||
var resources = List.of(
|
||||
BetaManagedAgentsGitHubRepositoryResourceParams.builder()
|
||||
.type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY)
|
||||
.url("https://github.com/org/frontend")
|
||||
.mountPath("/workspace/frontend")
|
||||
.authorizationToken("ghp_your_github_token")
|
||||
.build(),
|
||||
BetaManagedAgentsGitHubRepositoryResourceParams.builder()
|
||||
.type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY)
|
||||
.url("https://github.com/org/backend")
|
||||
.mountPath("/workspace/backend")
|
||||
.authorizationToken("ghp_your_github_token")
|
||||
.build());
|
||||
```
|
||||
|
||||
Rotating a repository's authorization token:
|
||||
|
||||
```java
|
||||
import com.anthropic.models.beta.sessions.resources.ResourceUpdateParams;
|
||||
|
||||
var listed = client.beta().sessions().resources().list(session.id());
|
||||
var repoResourceId = listed.data().get(0).asGitHubRepository().id();
|
||||
|
||||
client.beta().sessions().resources().update(repoResourceId, ResourceUpdateParams.builder()
|
||||
.sessionId(session.id())
|
||||
.authorizationToken("ghp_your_new_github_token")
|
||||
.build());
|
||||
```
|
||||
@@ -0,0 +1,375 @@
|
||||
# Claude API — PHP
|
||||
|
||||
> **Note:** The PHP SDK is the official Anthropic SDK for PHP. A beta tool runner is available via `$client->beta->messages->toolRunner()`. Structured output helpers are supported via `StructuredOutputModel` classes. Agent SDK is not available. Bedrock, Vertex AI, and Foundry clients are supported.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
composer require "anthropic-ai/sdk"
|
||||
```
|
||||
|
||||
## Client Initialization
|
||||
|
||||
```php
|
||||
use Anthropic\Client;
|
||||
|
||||
// Using API key from environment variable
|
||||
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
|
||||
```
|
||||
|
||||
### Amazon Bedrock
|
||||
|
||||
```php
|
||||
use Anthropic\Bedrock;
|
||||
|
||||
// Constructor is private — use the static factory. Reads AWS credentials from env.
|
||||
$client = Bedrock\Client::fromEnvironment(region: 'us-east-1');
|
||||
```
|
||||
|
||||
### Google Vertex AI
|
||||
|
||||
```php
|
||||
use Anthropic\Vertex;
|
||||
|
||||
// Constructor is private. Parameter is `location`, not `region`.
|
||||
$client = Vertex\Client::fromEnvironment(
|
||||
location: 'us-east5',
|
||||
projectId: 'my-project-id',
|
||||
);
|
||||
```
|
||||
|
||||
### Anthropic Foundry
|
||||
|
||||
```php
|
||||
use Anthropic\Foundry;
|
||||
|
||||
// Constructor is private. baseUrl or resource is required.
|
||||
$client = Foundry\Client::withCredentials(
|
||||
authToken: getenv('ANTHROPIC_FOUNDRY_AUTH_TOKEN'),
|
||||
baseUrl: 'https://<resource>.services.ai.azure.com/anthropic',
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Basic Message Request
|
||||
|
||||
```php
|
||||
$message = $client->messages->create(
|
||||
model: 'claude-opus-4-7',
|
||||
maxTokens: 16000,
|
||||
messages: [
|
||||
['role' => 'user', 'content' => 'What is the capital of France?'],
|
||||
],
|
||||
);
|
||||
|
||||
// content is an array of polymorphic blocks (TextBlock, ToolUseBlock,
|
||||
// ThinkingBlock). Accessing ->text on content[0] without checking the block
|
||||
// type will throw if the first block is not a TextBlock (e.g., when extended
|
||||
// thinking is enabled and a ThinkingBlock comes first). Always guard:
|
||||
foreach ($message->content as $block) {
|
||||
if ($block->type === 'text') {
|
||||
echo $block->text;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you only want the first text block:
|
||||
|
||||
```php
|
||||
foreach ($message->content as $block) {
|
||||
if ($block->type === 'text') {
|
||||
echo $block->text;
|
||||
break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Streaming
|
||||
|
||||
> **Requires SDK v0.5.0+.** v0.4.0 and earlier used a single `$params` array; calling with named parameters throws `Unknown named parameter $model`. Upgrade: `composer require "anthropic-ai/sdk:^0.7"`
|
||||
|
||||
```php
|
||||
use Anthropic\Messages\RawContentBlockDeltaEvent;
|
||||
use Anthropic\Messages\TextDelta;
|
||||
|
||||
$stream = $client->messages->createStream(
|
||||
model: 'claude-opus-4-7',
|
||||
maxTokens: 64000,
|
||||
messages: [
|
||||
['role' => 'user', 'content' => 'Write a haiku'],
|
||||
],
|
||||
);
|
||||
|
||||
foreach ($stream as $event) {
|
||||
if ($event instanceof RawContentBlockDeltaEvent && $event->delta instanceof TextDelta) {
|
||||
echo $event->delta->text;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tool Use
|
||||
|
||||
### Tool Runner (Beta)
|
||||
|
||||
**Beta:** The PHP SDK provides a tool runner via `$client->beta->messages->toolRunner()`. Define tools with `BetaRunnableTool` — a definition array plus a `run` closure:
|
||||
|
||||
```php
|
||||
use Anthropic\Lib\Tools\BetaRunnableTool;
|
||||
|
||||
$weatherTool = new BetaRunnableTool(
|
||||
definition: [
|
||||
'name' => 'get_weather',
|
||||
'description' => 'Get the current weather for a location.',
|
||||
'input_schema' => [
|
||||
'type' => 'object',
|
||||
'properties' => [
|
||||
'location' => ['type' => 'string', 'description' => 'City and state'],
|
||||
],
|
||||
'required' => ['location'],
|
||||
],
|
||||
],
|
||||
run: function (array $input): string {
|
||||
return "The weather in {$input['location']} is sunny and 72°F.";
|
||||
},
|
||||
);
|
||||
|
||||
$runner = $client->beta->messages->toolRunner(
|
||||
maxTokens: 16000,
|
||||
messages: [['role' => 'user', 'content' => 'What is the weather in Paris?']],
|
||||
model: 'claude-opus-4-7',
|
||||
tools: [$weatherTool],
|
||||
);
|
||||
|
||||
foreach ($runner as $message) {
|
||||
foreach ($message->content as $block) {
|
||||
if ($block->type === 'text') {
|
||||
echo $block->text;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Manual Loop
|
||||
|
||||
Tools are passed as arrays. **The SDK uses camelCase keys** (`inputSchema`, `toolUseID`, `stopReason`) and auto-maps to the API's snake_case on the wire — since v0.5.0. See [shared tool use concepts](../shared/tool-use-concepts.md) for the loop pattern.
|
||||
|
||||
```php
|
||||
use Anthropic\Messages\ToolUseBlock;
|
||||
|
||||
$tools = [
|
||||
[
|
||||
'name' => 'get_weather',
|
||||
'description' => 'Get the current weather in a given location',
|
||||
'inputSchema' => [ // camelCase, not input_schema
|
||||
'type' => 'object',
|
||||
'properties' => [
|
||||
'location' => ['type' => 'string', 'description' => 'City and state'],
|
||||
],
|
||||
'required' => ['location'],
|
||||
],
|
||||
],
|
||||
];
|
||||
|
||||
$messages = [['role' => 'user', 'content' => 'What is the weather in SF?']];
|
||||
|
||||
$response = $client->messages->create(
|
||||
model: 'claude-opus-4-7',
|
||||
maxTokens: 16000,
|
||||
tools: $tools,
|
||||
messages: $messages,
|
||||
);
|
||||
|
||||
while ($response->stopReason === 'tool_use') { // camelCase property
|
||||
$toolResults = [];
|
||||
foreach ($response->content as $block) {
|
||||
if ($block instanceof ToolUseBlock) {
|
||||
// $block->name : string — tool name to dispatch on
|
||||
// $block->input : array<string,mixed> — parsed JSON input
|
||||
// $block->id : string — pass back as toolUseID
|
||||
$result = executeYourTool($block->name, $block->input);
|
||||
$toolResults[] = [
|
||||
'type' => 'tool_result',
|
||||
'toolUseID' => $block->id, // camelCase, not tool_use_id
|
||||
'content' => $result,
|
||||
];
|
||||
}
|
||||
}
|
||||
|
||||
// Append assistant turn + user turn with tool results
|
||||
$messages[] = ['role' => 'assistant', 'content' => $response->content];
|
||||
$messages[] = ['role' => 'user', 'content' => $toolResults];
|
||||
|
||||
$response = $client->messages->create(
|
||||
model: 'claude-opus-4-7',
|
||||
maxTokens: 16000,
|
||||
tools: $tools,
|
||||
messages: $messages,
|
||||
);
|
||||
}
|
||||
|
||||
// Final text response
|
||||
foreach ($response->content as $block) {
|
||||
if ($block->type === 'text') {
|
||||
echo $block->text;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`$block->type === 'tool_use'` also works; `instanceof ToolUseBlock` narrows for PHPStan.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Extended Thinking
|
||||
|
||||
**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think.
|
||||
|
||||
```php
|
||||
use Anthropic\Messages\ThinkingBlock;
|
||||
|
||||
$message = $client->messages->create(
|
||||
model: 'claude-opus-4-7',
|
||||
maxTokens: 16000,
|
||||
thinking: ['type' => 'adaptive'],
|
||||
messages: [
|
||||
['role' => 'user', 'content' => 'Solve: 27 * 453'],
|
||||
],
|
||||
);
|
||||
|
||||
// ThinkingBlock(s) precede TextBlock in content
|
||||
foreach ($message->content as $block) {
|
||||
if ($block instanceof ThinkingBlock) {
|
||||
echo "Thinking:\n{$block->thinking}\n\n";
|
||||
// $block->signature is an opaque string — preserve verbatim if
|
||||
// passing thinking blocks back in multi-turn conversations
|
||||
} elseif ($block->type === 'text') {
|
||||
echo "Answer: {$block->text}\n";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Deprecated:** `['type' => 'enabled', 'budgetTokens' => N]` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
|
||||
|
||||
`$block->type === 'thinking'` also works for the check; `instanceof` narrows for PHPStan.
|
||||
|
||||
---
|
||||
|
||||
## Prompt Caching
|
||||
|
||||
`system:` takes an array of text blocks; set `cacheControl` on the last block. Array-shape syntax (camelCase keys) is idiomatic. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
|
||||
|
||||
```php
|
||||
$message = $client->messages->create(
|
||||
model: 'claude-opus-4-7',
|
||||
maxTokens: 16000,
|
||||
system: [
|
||||
['type' => 'text', 'text' => $longSystemPrompt, 'cacheControl' => ['type' => 'ephemeral']],
|
||||
],
|
||||
messages: [['role' => 'user', 'content' => 'Summarize the key points']],
|
||||
);
|
||||
```
|
||||
|
||||
For 1-hour TTL: `'cacheControl' => ['type' => 'ephemeral', 'ttl' => '1h']`. There's also a top-level `cacheControl:` on `messages->create(...)` that auto-places on the last cacheable block.
|
||||
|
||||
Verify hits via `$message->usage->cacheCreationInputTokens` / `$message->usage->cacheReadInputTokens`.
|
||||
|
||||
---
|
||||
|
||||
## Structured Outputs
|
||||
|
||||
### Using StructuredOutputModel (Recommended)
|
||||
|
||||
Define a PHP class implementing `StructuredOutputModel` and pass it as `outputConfig`:
|
||||
|
||||
```php
|
||||
use Anthropic\Lib\Contracts\StructuredOutputModel;
|
||||
use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
|
||||
use Anthropic\Lib\Attributes\Constrained;
|
||||
|
||||
class Person implements StructuredOutputModel
|
||||
{
|
||||
use StructuredOutputModelTrait;
|
||||
|
||||
#[Constrained(description: 'Full name')]
|
||||
public string $name;
|
||||
|
||||
public int $age;
|
||||
|
||||
public ?string $email = null; // nullable = optional field
|
||||
}
|
||||
|
||||
$message = $client->messages->create(
|
||||
model: 'claude-opus-4-7',
|
||||
maxTokens: 16000,
|
||||
messages: [['role' => 'user', 'content' => 'Generate a profile for Alice, age 30']],
|
||||
outputConfig: ['format' => Person::class],
|
||||
);
|
||||
|
||||
$person = $message->parsedOutput(); // Person instance
|
||||
echo $person->name;
|
||||
```
|
||||
|
||||
Types are inferred from PHP type hints. Use `#[Constrained(description: '...')]` to add descriptions. Nullable properties (`?string`) become optional fields.
|
||||
|
||||
### Raw Schema
|
||||
|
||||
```php
|
||||
$message = $client->messages->create(
|
||||
model: 'claude-opus-4-7',
|
||||
maxTokens: 16000,
|
||||
messages: [['role' => 'user', 'content' => 'Extract: John (john@co.com), Enterprise plan']],
|
||||
outputConfig: [
|
||||
'format' => [
|
||||
'type' => 'json_schema',
|
||||
'schema' => [
|
||||
'type' => 'object',
|
||||
'properties' => [
|
||||
'name' => ['type' => 'string'],
|
||||
'email' => ['type' => 'string'],
|
||||
'plan' => ['type' => 'string'],
|
||||
],
|
||||
'required' => ['name', 'email', 'plan'],
|
||||
'additionalProperties' => false,
|
||||
],
|
||||
],
|
||||
],
|
||||
);
|
||||
|
||||
// First text block contains valid JSON
|
||||
foreach ($message->content as $block) {
|
||||
if ($block->type === 'text') {
|
||||
$data = json_decode($block->text, true);
|
||||
break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Beta Features & Server-Side Tools
|
||||
|
||||
**`betas:` is NOT a param on `$client->messages->create()`** — it only exists on the beta namespace. Use it for features that need an explicit opt-in header:
|
||||
|
||||
```php
|
||||
use Anthropic\Beta\Messages\BetaRequestMCPServerURLDefinition;
|
||||
|
||||
$response = $client->beta->messages->create(
|
||||
model: 'claude-opus-4-7',
|
||||
maxTokens: 16000,
|
||||
mcpServers: [
|
||||
BetaRequestMCPServerURLDefinition::with(
|
||||
name: 'my-server',
|
||||
url: 'https://example.com/mcp',
|
||||
),
|
||||
],
|
||||
betas: ['mcp-client-2025-11-20'], // only valid on ->beta->messages
|
||||
messages: [['role' => 'user', 'content' => 'Use the MCP tools']],
|
||||
);
|
||||
```
|
||||
|
||||
**Server-side tools** (bash, web_search, text_editor, code_execution) are GA and work on both paths — `Anthropic\Messages\ToolBash20250124` / `WebSearchTool20260209` / `ToolTextEditor20250728` / `CodeExecutionTool20260120` for non-beta, `Anthropic\Beta\Messages\BetaToolBash20250124` / `BetaWebSearchTool20260209` / `BetaToolTextEditor20250728` / `BetaCodeExecutionTool20260120` for beta. No `betas:` header needed for these.
|
||||
@@ -0,0 +1,435 @@
|
||||
# Managed Agents — PHP
|
||||
|
||||
> **Bindings not shown here:** This README covers the most common managed-agents flows for PHP. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the PHP SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
|
||||
|
||||
> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `$client->beta->agents->create` and pass it to every subsequent `->sessions->create`; do not call `agents->create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
composer require "anthropic-ai/sdk"
|
||||
```
|
||||
|
||||
## Client Initialization
|
||||
|
||||
```php
|
||||
use Anthropic\Client;
|
||||
|
||||
// Default (uses ANTHROPIC_API_KEY env var)
|
||||
$client = new Client();
|
||||
|
||||
// Explicit API key
|
||||
$client = new Client(apiKey: 'your-api-key');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create an Environment
|
||||
|
||||
```php
|
||||
$environment = $client->beta->environments->create(
|
||||
name: 'my-dev-env',
|
||||
config: ['type' => 'cloud', 'networking' => ['type' => 'unrestricted']],
|
||||
);
|
||||
echo "Environment ID: {$environment->id}\n"; // env_...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create an Agent (required first step)
|
||||
|
||||
> ⚠️ **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `$client->beta->agents->create()` — the session takes either `agent: $agent->id` or the typed `BetaManagedAgentsAgentParams::with(type: 'agent', id: $agent->id, version: $agent->version)`.
|
||||
|
||||
### Minimal
|
||||
|
||||
```php
|
||||
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
|
||||
|
||||
// 1. Create the agent (reusable, versioned)
|
||||
$agent = $client->beta->agents->create(
|
||||
name: 'Coding Assistant',
|
||||
model: 'claude-opus-4-7',
|
||||
system: 'You are a helpful coding assistant.',
|
||||
tools: [
|
||||
BetaManagedAgentsAgentToolset20260401Params::with(
|
||||
type: 'agent_toolset_20260401',
|
||||
),
|
||||
],
|
||||
);
|
||||
|
||||
// 2. Start a session
|
||||
$session = $client->beta->sessions->create(
|
||||
agent: ['type' => 'agent', 'id' => $agent->id, 'version' => $agent->version],
|
||||
environmentID: $environment->id,
|
||||
title: 'Quickstart session',
|
||||
);
|
||||
echo "Session ID: {$session->id}\n";
|
||||
```
|
||||
|
||||
### Updating an Agent
|
||||
|
||||
Updates create new versions; the agent object is immutable per version.
|
||||
|
||||
```php
|
||||
$updatedAgent = $client->beta->agents->update(
|
||||
$agent->id,
|
||||
version: $agent->version,
|
||||
system: 'You are a helpful coding agent. Always write tests.',
|
||||
);
|
||||
echo "New version: {$updatedAgent->version}\n";
|
||||
|
||||
// List all versions
|
||||
foreach ($client->beta->agents->versions->list($agent->id)->pagingEachItem() as $version) {
|
||||
echo "Version {$version->version}: {$version->updatedAt->format(DateTimeInterface::ATOM)}\n";
|
||||
}
|
||||
|
||||
// Archive the agent
|
||||
$archived = $client->beta->agents->archive($agent->id);
|
||||
echo "Archived at: {$archived->archivedAt->format(DateTimeInterface::ATOM)}\n";
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Send a User Message
|
||||
|
||||
```php
|
||||
$client->beta->sessions->events->send(
|
||||
$session->id,
|
||||
events: [
|
||||
[
|
||||
'type' => 'user.message',
|
||||
'content' => [['type' => 'text', 'text' => 'Review the auth module']],
|
||||
],
|
||||
],
|
||||
);
|
||||
```
|
||||
|
||||
> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns).
|
||||
|
||||
---
|
||||
|
||||
## Stream Events (SSE)
|
||||
|
||||
> ℹ️ **Streaming transporter:** PHP's default buffered PSR-18 client never returns for the open-ended session event stream. Use a streaming Guzzle transporter for `streamStream()` calls — other calls keep the default client.
|
||||
|
||||
```php
|
||||
$streamingClient = new GuzzleHttp\Client(['stream' => true]);
|
||||
|
||||
// Open the stream first, then send the user message
|
||||
$stream = $client->beta->sessions->events->streamStream(
|
||||
$session->id,
|
||||
requestOptions: ['transporter' => $streamingClient],
|
||||
);
|
||||
$client->beta->sessions->events->send(
|
||||
$session->id,
|
||||
events: [
|
||||
[
|
||||
'type' => 'user.message',
|
||||
'content' => [['type' => 'text', 'text' => 'Summarize the repo README']],
|
||||
],
|
||||
],
|
||||
);
|
||||
|
||||
foreach ($stream as $event) {
|
||||
match ($event->type) {
|
||||
'agent.message' => array_walk(
|
||||
$event->content,
|
||||
static fn($block) => $block->type === 'text' ? print($block->text) : null,
|
||||
),
|
||||
'agent.tool_use' => print("\n[Using tool: {$event->name}]\n"),
|
||||
'session.error' => printf("\n[Error: %s]", $event->error?->message ?? 'unknown'),
|
||||
default => null,
|
||||
};
|
||||
if ($event->type === 'session.status_idle' || $event->type === 'session.error') {
|
||||
break;
|
||||
}
|
||||
}
|
||||
$stream->close();
|
||||
```
|
||||
|
||||
### Reconnecting and Tailing
|
||||
|
||||
When reconnecting mid-session, list past events first to dedupe, then tail live events:
|
||||
|
||||
```php
|
||||
$stream = $client->beta->sessions->events->streamStream(
|
||||
$session->id,
|
||||
requestOptions: ['transporter' => $streamingClient],
|
||||
);
|
||||
|
||||
// Stream is open and buffering. List history before tailing live.
|
||||
$seenEventIds = [];
|
||||
foreach ($client->beta->sessions->events->list($session->id)->pagingEachItem() as $event) {
|
||||
$seenEventIds[$event->id] = true;
|
||||
}
|
||||
|
||||
// Tail live events, skipping anything already seen
|
||||
foreach ($stream as $event) {
|
||||
if (isset($seenEventIds[$event->id])) {
|
||||
continue;
|
||||
}
|
||||
$seenEventIds[$event->id] = true;
|
||||
match ($event->type) {
|
||||
'agent.message' => array_walk(
|
||||
$event->content,
|
||||
static fn($block) => $block->type === 'text' ? print($block->text) : null,
|
||||
),
|
||||
default => null,
|
||||
};
|
||||
if ($event->type === 'session.status_idle') {
|
||||
break;
|
||||
}
|
||||
}
|
||||
$stream->close();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Provide Custom Tool Result
|
||||
|
||||
> ℹ️ The PHP managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `anthropic-ai/sdk` PHP repository for the corresponding params.
|
||||
|
||||
---
|
||||
|
||||
## Poll Events
|
||||
|
||||
```php
|
||||
foreach ($client->beta->sessions->events->list($session->id)->pagingEachItem() as $event) {
|
||||
echo "{$event->type}: {$event->id}\n";
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Upload a File
|
||||
|
||||
> ℹ️ **PHP file upload:** The PHP SDK's beta managed-agents file upload binding is not shown in the apps source examples; the canonical PHP example uses raw cURL against `POST /v1/files`. If your codebase prefers the SDK, WebFetch the `anthropic-ai/sdk` PHP repository for the latest binding before writing code.
|
||||
|
||||
```php
|
||||
use Anthropic\Beta\Sessions\BetaManagedAgentsFileResourceParams;
|
||||
|
||||
// Raw cURL upload (canonical example from the apps source)
|
||||
$csvPath = 'data.csv';
|
||||
$ch = curl_init('https://api.anthropic.com/v1/files');
|
||||
curl_setopt_array($ch, [
|
||||
CURLOPT_RETURNTRANSFER => true,
|
||||
CURLOPT_POST => true,
|
||||
CURLOPT_HTTPHEADER => [
|
||||
'x-api-key: ' . getenv('ANTHROPIC_API_KEY'),
|
||||
'anthropic-version: 2023-06-01',
|
||||
'anthropic-beta: files-api-2025-04-14',
|
||||
],
|
||||
CURLOPT_POSTFIELDS => ['file' => new CURLFile($csvPath, 'text/csv', 'data.csv')],
|
||||
]);
|
||||
$file = json_decode(curl_exec($ch));
|
||||
echo "File ID: {$file->id}\n";
|
||||
|
||||
// Mount in a session
|
||||
$session = $client->beta->sessions->create(
|
||||
agent: $agent->id,
|
||||
environmentID: $environment->id,
|
||||
resources: [
|
||||
BetaManagedAgentsFileResourceParams::with(
|
||||
type: 'file',
|
||||
fileID: $file->id,
|
||||
mountPath: '/workspace/data.csv',
|
||||
),
|
||||
],
|
||||
);
|
||||
```
|
||||
|
||||
### Add and Manage Resources on an Existing Session
|
||||
|
||||
```php
|
||||
// Attach an additional file to an open session
|
||||
$resource = $client->beta->sessions->resources->add(
|
||||
$session->id,
|
||||
type: 'file',
|
||||
fileID: $file->id,
|
||||
);
|
||||
echo "{$resource->id}\n"; // "sesrsc_01ABC..."
|
||||
|
||||
// List resources on the session
|
||||
$listed = $client->beta->sessions->resources->list($session->id);
|
||||
foreach ($listed->data as $entry) {
|
||||
echo "{$entry->id} {$entry->type}\n";
|
||||
}
|
||||
|
||||
// Detach a resource
|
||||
$client->beta->sessions->resources->delete($resource->id, sessionID: $session->id);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## List and Download Session Files
|
||||
|
||||
> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for PHP in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `anthropic-ai/sdk` PHP repository for the file list/download bindings.
|
||||
|
||||
---
|
||||
|
||||
## Session Management
|
||||
|
||||
```php
|
||||
// List environments
|
||||
$environments = $client->beta->environments->list();
|
||||
|
||||
// Retrieve a specific environment
|
||||
$env = $client->beta->environments->retrieve($environment->id);
|
||||
|
||||
// Archive an environment (read-only, existing sessions continue)
|
||||
$client->beta->environments->archive($environment->id);
|
||||
|
||||
// Delete an environment (only if no sessions reference it)
|
||||
$client->beta->environments->delete($environment->id);
|
||||
|
||||
// Delete a session
|
||||
$client->beta->sessions->delete($session->id);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Integration
|
||||
|
||||
```php
|
||||
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
|
||||
use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetParams;
|
||||
use Anthropic\Beta\Agents\BetaManagedAgentsUrlmcpServerParams;
|
||||
use Anthropic\Beta\Sessions\BetaManagedAgentsAgentParams;
|
||||
|
||||
// Agent declares MCP server (no auth here — auth goes in a vault)
|
||||
$agent = $client->beta->agents->create(
|
||||
name: 'GitHub Assistant',
|
||||
model: 'claude-opus-4-7',
|
||||
mcpServers: [
|
||||
BetaManagedAgentsUrlmcpServerParams::with(
|
||||
type: 'url',
|
||||
name: 'github',
|
||||
url: 'https://api.githubcopilot.com/mcp/',
|
||||
),
|
||||
],
|
||||
tools: [
|
||||
BetaManagedAgentsAgentToolset20260401Params::with(type: 'agent_toolset_20260401'),
|
||||
BetaManagedAgentsMCPToolsetParams::with(
|
||||
type: 'mcp_toolset',
|
||||
mcpServerName: 'github',
|
||||
),
|
||||
],
|
||||
);
|
||||
|
||||
// Session attaches vault(s) containing credentials for those MCP server URLs
|
||||
$session = $client->beta->sessions->create(
|
||||
agent: BetaManagedAgentsAgentParams::with(
|
||||
type: 'agent',
|
||||
id: $agent->id,
|
||||
version: $agent->version,
|
||||
),
|
||||
environmentID: $environment->id,
|
||||
vaultIDs: [$vault->id],
|
||||
);
|
||||
```
|
||||
|
||||
See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials.
|
||||
|
||||
---
|
||||
|
||||
## Vaults
|
||||
|
||||
```php
|
||||
// Create a vault
|
||||
$vault = $client->beta->vaults->create(
|
||||
displayName: 'Alice',
|
||||
metadata: ['external_user_id' => 'usr_abc123'],
|
||||
);
|
||||
echo $vault->id . "\n"; // "vlt_01ABC..."
|
||||
|
||||
// Add an OAuth credential
|
||||
$credential = $client->beta->vaults->credentials->create(
|
||||
vaultID: $vault->id,
|
||||
displayName: "Alice's Slack",
|
||||
auth: [
|
||||
'type' => 'mcp_oauth',
|
||||
'mcp_server_url' => 'https://mcp.slack.com/mcp',
|
||||
'access_token' => 'xoxp-...',
|
||||
'expires_at' => '2026-04-15T00:00:00Z',
|
||||
'refresh' => [
|
||||
'token_endpoint' => 'https://slack.com/api/oauth.v2.access',
|
||||
'client_id' => '1234567890.0987654321',
|
||||
'scope' => 'channels:read chat:write',
|
||||
'refresh_token' => 'xoxe-1-...',
|
||||
'token_endpoint_auth' => [
|
||||
'type' => 'client_secret_post',
|
||||
'client_secret' => 'abc123...',
|
||||
],
|
||||
],
|
||||
],
|
||||
);
|
||||
|
||||
// Rotate the credential (e.g., after a token refresh)
|
||||
$client->beta->vaults->credentials->update(
|
||||
$credential->id,
|
||||
vaultID: $vault->id,
|
||||
auth: [
|
||||
'type' => 'mcp_oauth',
|
||||
'access_token' => 'xoxp-new-...',
|
||||
'expires_at' => '2026-05-15T00:00:00Z',
|
||||
'refresh' => ['refresh_token' => 'xoxe-1-new-...'],
|
||||
],
|
||||
);
|
||||
|
||||
// Archive a vault
|
||||
$client->beta->vaults->archive($vault->id);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GitHub Repository Integration
|
||||
|
||||
Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential):
|
||||
|
||||
```php
|
||||
$session = $client->beta->sessions->create(
|
||||
agent: $agent->id,
|
||||
environmentID: $environment->id,
|
||||
vaultIDs: [$vault->id],
|
||||
resources: [
|
||||
[
|
||||
'type' => 'github_repository',
|
||||
'url' => 'https://github.com/org/repo',
|
||||
'mountPath' => '/workspace/repo',
|
||||
'authorizationToken' => 'ghp_your_github_token',
|
||||
],
|
||||
],
|
||||
);
|
||||
```
|
||||
|
||||
Multiple repositories on the same session:
|
||||
|
||||
```php
|
||||
$resources = [
|
||||
[
|
||||
'type' => 'github_repository',
|
||||
'url' => 'https://github.com/org/frontend',
|
||||
'mountPath' => '/workspace/frontend',
|
||||
'authorizationToken' => 'ghp_your_github_token',
|
||||
],
|
||||
[
|
||||
'type' => 'github_repository',
|
||||
'url' => 'https://github.com/org/backend',
|
||||
'mountPath' => '/workspace/backend',
|
||||
'authorizationToken' => 'ghp_your_github_token',
|
||||
],
|
||||
];
|
||||
```
|
||||
|
||||
Rotating a repository's authorization token:
|
||||
|
||||
```php
|
||||
$listed = $client->beta->sessions->resources->list($session->id);
|
||||
$repoResourceId = $listed->data[0]->id;
|
||||
|
||||
$client->beta->sessions->resources->update(
|
||||
$repoResourceId,
|
||||
sessionID: $session->id,
|
||||
authorizationToken: 'ghp_your_new_github_token',
|
||||
);
|
||||
```
|
||||
@@ -0,0 +1,420 @@
|
||||
# Claude API — Python
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install anthropic
|
||||
```
|
||||
|
||||
## Client Initialization
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
|
||||
# Default (uses ANTHROPIC_API_KEY env var)
|
||||
client = anthropic.Anthropic()
|
||||
|
||||
# Explicit API key
|
||||
client = anthropic.Anthropic(api_key="your-api-key")
|
||||
|
||||
# Async client
|
||||
async_client = anthropic.AsyncAnthropic()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Basic Message Request
|
||||
|
||||
```python
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[
|
||||
{"role": "user", "content": "What is the capital of France?"}
|
||||
]
|
||||
)
|
||||
# response.content is a list of content block objects (TextBlock, ThinkingBlock,
|
||||
# ToolUseBlock, ...). Check .type before accessing .text.
|
||||
for block in response.content:
|
||||
if block.type == "text":
|
||||
print(block.text)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## System Prompts
|
||||
|
||||
```python
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
system="You are a helpful coding assistant. Always provide examples in Python.",
|
||||
messages=[{"role": "user", "content": "How do I read a JSON file?"}]
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Vision (Images)
|
||||
|
||||
### Base64
|
||||
|
||||
```python
|
||||
import base64
|
||||
|
||||
with open("image.png", "rb") as f:
|
||||
image_data = base64.standard_b64encode(f.read()).decode("utf-8")
|
||||
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{
|
||||
"type": "image",
|
||||
"source": {
|
||||
"type": "base64",
|
||||
"media_type": "image/png",
|
||||
"data": image_data
|
||||
}
|
||||
},
|
||||
{"type": "text", "text": "What's in this image?"}
|
||||
]
|
||||
}]
|
||||
)
|
||||
```
|
||||
|
||||
### URL
|
||||
|
||||
```python
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{
|
||||
"type": "image",
|
||||
"source": {
|
||||
"type": "url",
|
||||
"url": "https://example.com/image.png"
|
||||
}
|
||||
},
|
||||
{"type": "text", "text": "Describe this image"}
|
||||
]
|
||||
}]
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompt Caching
|
||||
|
||||
Cache large context to reduce costs (up to 90% savings). **Caching is a prefix match** — any byte change anywhere in the prefix invalidates everything after it. For placement patterns, architectural guidance (frozen system prompt, deterministic tool order, where to put volatile content), and the silent-invalidator audit checklist, read `shared/prompt-caching.md`.
|
||||
|
||||
### Automatic Caching (Recommended)
|
||||
|
||||
Use top-level `cache_control` to automatically cache the last cacheable block in the request — no need to annotate individual content blocks:
|
||||
|
||||
```python
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
cache_control={"type": "ephemeral"}, # auto-caches the last cacheable block
|
||||
system="You are an expert on this large document...",
|
||||
messages=[{"role": "user", "content": "Summarize the key points"}]
|
||||
)
|
||||
```
|
||||
|
||||
### Manual Cache Control
|
||||
|
||||
For fine-grained control, add `cache_control` to specific content blocks:
|
||||
|
||||
```python
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
system=[{
|
||||
"type": "text",
|
||||
"text": "You are an expert on this large document...",
|
||||
"cache_control": {"type": "ephemeral"} # default TTL is 5 minutes
|
||||
}],
|
||||
messages=[{"role": "user", "content": "Summarize the key points"}]
|
||||
)
|
||||
|
||||
# With explicit TTL (time-to-live)
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
system=[{
|
||||
"type": "text",
|
||||
"text": "You are an expert on this large document...",
|
||||
"cache_control": {"type": "ephemeral", "ttl": "1h"} # 1 hour TTL
|
||||
}],
|
||||
messages=[{"role": "user", "content": "Summarize the key points"}]
|
||||
)
|
||||
```
|
||||
|
||||
### Verifying Cache Hits
|
||||
|
||||
```python
|
||||
print(response.usage.cache_creation_input_tokens) # tokens written to cache (~1.25x cost)
|
||||
print(response.usage.cache_read_input_tokens) # tokens served from cache (~0.1x cost)
|
||||
print(response.usage.input_tokens) # uncached tokens (full cost)
|
||||
```
|
||||
|
||||
If `cache_read_input_tokens` is zero across repeated identical-prefix requests, a silent invalidator is at work — `datetime.now()` or a UUID in the system prompt, unsorted `json.dumps()`, or a varying tool set. See `shared/prompt-caching.md` for the full audit table.
|
||||
|
||||
---
|
||||
|
||||
## Extended Thinking
|
||||
|
||||
> **Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Opus 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
|
||||
> **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024).
|
||||
|
||||
```python
|
||||
# Opus 4.7 / 4.6: adaptive thinking (recommended)
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
thinking={"type": "adaptive"},
|
||||
output_config={"effort": "high"}, # low | medium | high | max
|
||||
messages=[{"role": "user", "content": "Solve this step by step..."}]
|
||||
)
|
||||
|
||||
# Access thinking and response
|
||||
for block in response.content:
|
||||
if block.type == "thinking":
|
||||
print(f"Thinking: {block.thinking}")
|
||||
elif block.type == "text":
|
||||
print(f"Response: {block.text}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
|
||||
try:
|
||||
response = client.messages.create(...)
|
||||
except anthropic.BadRequestError as e:
|
||||
print(f"Bad request: {e.message}")
|
||||
except anthropic.AuthenticationError:
|
||||
print("Invalid API key")
|
||||
except anthropic.PermissionDeniedError:
|
||||
print("API key lacks required permissions")
|
||||
except anthropic.NotFoundError:
|
||||
print("Invalid model or endpoint")
|
||||
except anthropic.RateLimitError as e:
|
||||
retry_after = int(e.response.headers.get("retry-after", "60"))
|
||||
print(f"Rate limited. Retry after {retry_after}s.")
|
||||
except anthropic.APIStatusError as e:
|
||||
if e.status_code >= 500:
|
||||
print(f"Server error ({e.status_code}). Retry later.")
|
||||
else:
|
||||
print(f"API error: {e.message}")
|
||||
except anthropic.APIConnectionError:
|
||||
print("Network error. Check internet connection.")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multi-Turn Conversations
|
||||
|
||||
The API is stateless — send the full conversation history each time.
|
||||
|
||||
```python
|
||||
class ConversationManager:
|
||||
"""Manage multi-turn conversations with the Claude API."""
|
||||
|
||||
def __init__(self, client: anthropic.Anthropic, model: str, system: str = None):
|
||||
self.client = client
|
||||
self.model = model
|
||||
self.system = system
|
||||
self.messages = []
|
||||
|
||||
def send(self, user_message: str, **kwargs) -> str:
|
||||
"""Send a message and get a response."""
|
||||
self.messages.append({"role": "user", "content": user_message})
|
||||
|
||||
response = self.client.messages.create(
|
||||
model=self.model,
|
||||
max_tokens=kwargs.get("max_tokens", 16000),
|
||||
system=self.system,
|
||||
messages=self.messages,
|
||||
**kwargs
|
||||
)
|
||||
|
||||
assistant_message = next(
|
||||
(b.text for b in response.content if b.type == "text"), ""
|
||||
)
|
||||
self.messages.append({"role": "assistant", "content": assistant_message})
|
||||
|
||||
return assistant_message
|
||||
|
||||
# Usage
|
||||
conversation = ConversationManager(
|
||||
client=anthropic.Anthropic(),
|
||||
model="claude-opus-4-7",
|
||||
system="You are a helpful assistant."
|
||||
)
|
||||
|
||||
response1 = conversation.send("My name is Alice.")
|
||||
response2 = conversation.send("What's my name?") # Claude remembers "Alice"
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Messages must alternate between `user` and `assistant`
|
||||
- First message must be `user`
|
||||
|
||||
---
|
||||
|
||||
### Compaction (long conversations)
|
||||
|
||||
> **Beta, Opus 4.7, Opus 4.6, and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text.
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
|
||||
client = anthropic.Anthropic()
|
||||
messages = []
|
||||
|
||||
def chat(user_message: str) -> str:
|
||||
messages.append({"role": "user", "content": user_message})
|
||||
|
||||
response = client.beta.messages.create(
|
||||
betas=["compact-2026-01-12"],
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=messages,
|
||||
context_management={
|
||||
"edits": [{"type": "compact_20260112"}]
|
||||
}
|
||||
)
|
||||
|
||||
# Append full content — compaction blocks must be preserved
|
||||
messages.append({"role": "assistant", "content": response.content})
|
||||
|
||||
return next(block.text for block in response.content if block.type == "text")
|
||||
|
||||
# Compaction triggers automatically when context grows large
|
||||
print(chat("Help me build a Python web scraper"))
|
||||
print(chat("Add support for JavaScript-rendered pages"))
|
||||
print(chat("Now add rate limiting and error handling"))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stop Reasons
|
||||
|
||||
The `stop_reason` field in the response indicates why the model stopped generating:
|
||||
|
||||
| Value | Meaning |
|
||||
|-------|---------|
|
||||
| `end_turn` | Claude finished its response naturally |
|
||||
| `max_tokens` | Hit the `max_tokens` limit — increase it or use streaming |
|
||||
| `stop_sequence` | Hit a custom stop sequence |
|
||||
| `tool_use` | Claude wants to call a tool — execute it and continue |
|
||||
| `pause_turn` | Model paused and can be resumed (agentic flows) |
|
||||
| `refusal` | Claude refused for safety reasons — output may not match your schema |
|
||||
|
||||
---
|
||||
|
||||
## Cost Optimization Strategies
|
||||
|
||||
### 1. Use Prompt Caching for Repeated Context
|
||||
|
||||
```python
|
||||
# Automatic caching (simplest — caches the last cacheable block)
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
cache_control={"type": "ephemeral"},
|
||||
system=large_document_text, # e.g., 50KB of context
|
||||
messages=[{"role": "user", "content": "Summarize the key points"}]
|
||||
)
|
||||
|
||||
# First request: full cost
|
||||
# Subsequent requests: ~90% cheaper for cached portion
|
||||
```
|
||||
|
||||
### 2. Choose the Right Model
|
||||
|
||||
```python
|
||||
# Default to Opus for most tasks
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7", # $5.00/$25.00 per 1M tokens
|
||||
max_tokens=16000,
|
||||
messages=[{"role": "user", "content": "Explain quantum computing"}]
|
||||
)
|
||||
|
||||
# Use Sonnet for high-volume production workloads
|
||||
standard_response = client.messages.create(
|
||||
model="claude-sonnet-4-6", # $3.00/$15.00 per 1M tokens
|
||||
max_tokens=16000,
|
||||
messages=[{"role": "user", "content": "Summarize this document"}]
|
||||
)
|
||||
|
||||
# Use Haiku only for simple, speed-critical tasks
|
||||
simple_response = client.messages.create(
|
||||
model="claude-haiku-4-5", # $1.00/$5.00 per 1M tokens
|
||||
max_tokens=256,
|
||||
messages=[{"role": "user", "content": "Classify this as positive or negative"}]
|
||||
)
|
||||
```
|
||||
|
||||
### 3. Use Token Counting Before Requests
|
||||
|
||||
```python
|
||||
count_response = client.messages.count_tokens(
|
||||
model="claude-opus-4-7",
|
||||
messages=messages,
|
||||
system=system
|
||||
)
|
||||
|
||||
estimated_input_cost = count_response.input_tokens * 0.000005 # $5/1M tokens
|
||||
print(f"Estimated input cost: ${estimated_input_cost:.4f}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Retry with Exponential Backoff
|
||||
|
||||
> **Note:** The Anthropic SDK automatically retries rate limit (429) and server errors (5xx) with exponential backoff. You can configure this with `max_retries` (default: 2). Only implement custom retry logic if you need behavior beyond what the SDK provides.
|
||||
|
||||
```python
|
||||
import time
|
||||
import random
|
||||
import anthropic
|
||||
|
||||
def call_with_retry(
|
||||
client: anthropic.Anthropic,
|
||||
max_retries: int = 5,
|
||||
base_delay: float = 1.0,
|
||||
max_delay: float = 60.0,
|
||||
**kwargs
|
||||
):
|
||||
"""Call the API with exponential backoff retry."""
|
||||
last_exception = None
|
||||
|
||||
for attempt in range(max_retries):
|
||||
try:
|
||||
return client.messages.create(**kwargs)
|
||||
except anthropic.RateLimitError as e:
|
||||
last_exception = e
|
||||
except anthropic.APIStatusError as e:
|
||||
if e.status_code >= 500:
|
||||
last_exception = e
|
||||
else:
|
||||
raise # Client errors (4xx except 429) should not be retried
|
||||
|
||||
delay = min(base_delay * (2 ** attempt) + random.uniform(0, 1), max_delay)
|
||||
print(f"Retry {attempt + 1}/{max_retries} after {delay:.1f}s")
|
||||
time.sleep(delay)
|
||||
|
||||
raise last_exception
|
||||
```
|
||||
@@ -0,0 +1,185 @@
|
||||
# Message Batches API — Python
|
||||
|
||||
The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices.
|
||||
|
||||
## Key Facts
|
||||
|
||||
- Up to 100,000 requests or 256 MB per batch
|
||||
- Most batches complete within 1 hour; maximum 24 hours
|
||||
- Results available for 29 days after creation
|
||||
- 50% cost reduction on all token usage
|
||||
- All Messages API features supported (vision, tools, caching, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Create a Batch
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
|
||||
from anthropic.types.messages.batch_create_params import Request
|
||||
|
||||
client = anthropic.Anthropic()
|
||||
|
||||
message_batch = client.messages.batches.create(
|
||||
requests=[
|
||||
Request(
|
||||
custom_id="request-1",
|
||||
params=MessageCreateParamsNonStreaming(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{"role": "user", "content": "Summarize climate change impacts"}]
|
||||
)
|
||||
),
|
||||
Request(
|
||||
custom_id="request-2",
|
||||
params=MessageCreateParamsNonStreaming(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{"role": "user", "content": "Explain quantum computing basics"}]
|
||||
)
|
||||
),
|
||||
]
|
||||
)
|
||||
|
||||
print(f"Batch ID: {message_batch.id}")
|
||||
print(f"Status: {message_batch.processing_status}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Poll for Completion
|
||||
|
||||
```python
|
||||
import time
|
||||
|
||||
while True:
|
||||
batch = client.messages.batches.retrieve(message_batch.id)
|
||||
if batch.processing_status == "ended":
|
||||
break
|
||||
print(f"Status: {batch.processing_status}, processing: {batch.request_counts.processing}")
|
||||
time.sleep(60)
|
||||
|
||||
print("Batch complete!")
|
||||
print(f"Succeeded: {batch.request_counts.succeeded}")
|
||||
print(f"Errored: {batch.request_counts.errored}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Retrieve Results
|
||||
|
||||
> **Note:** Examples below use `match/case` syntax, requiring Python 3.10+. For earlier versions, use `if/elif` chains instead.
|
||||
|
||||
```python
|
||||
for result in client.messages.batches.results(message_batch.id):
|
||||
match result.result.type:
|
||||
case "succeeded":
|
||||
msg = result.result.message
|
||||
text = next((b.text for b in msg.content if b.type == "text"), "")
|
||||
print(f"[{result.custom_id}] {text[:100]}")
|
||||
case "errored":
|
||||
if result.result.error.type == "invalid_request":
|
||||
print(f"[{result.custom_id}] Validation error - fix request and retry")
|
||||
else:
|
||||
print(f"[{result.custom_id}] Server error - safe to retry")
|
||||
case "canceled":
|
||||
print(f"[{result.custom_id}] Canceled")
|
||||
case "expired":
|
||||
print(f"[{result.custom_id}] Expired - resubmit")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cancel a Batch
|
||||
|
||||
```python
|
||||
cancelled = client.messages.batches.cancel(message_batch.id)
|
||||
print(f"Status: {cancelled.processing_status}") # "canceling"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Batch with Prompt Caching
|
||||
|
||||
```python
|
||||
shared_system = [
|
||||
{"type": "text", "text": "You are a literary analyst."},
|
||||
{
|
||||
"type": "text",
|
||||
"text": large_document_text, # Shared across all requests
|
||||
"cache_control": {"type": "ephemeral"}
|
||||
}
|
||||
]
|
||||
|
||||
message_batch = client.messages.batches.create(
|
||||
requests=[
|
||||
Request(
|
||||
custom_id=f"analysis-{i}",
|
||||
params=MessageCreateParamsNonStreaming(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
system=shared_system,
|
||||
messages=[{"role": "user", "content": question}]
|
||||
)
|
||||
)
|
||||
for i, question in enumerate(questions)
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Full End-to-End Example
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
import time
|
||||
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
|
||||
from anthropic.types.messages.batch_create_params import Request
|
||||
|
||||
client = anthropic.Anthropic()
|
||||
|
||||
# 1. Prepare requests
|
||||
items_to_classify = [
|
||||
"The product quality is excellent!",
|
||||
"Terrible customer service, never again.",
|
||||
"It's okay, nothing special.",
|
||||
]
|
||||
|
||||
requests = [
|
||||
Request(
|
||||
custom_id=f"classify-{i}",
|
||||
params=MessageCreateParamsNonStreaming(
|
||||
model="claude-haiku-4-5",
|
||||
max_tokens=50,
|
||||
messages=[{
|
||||
"role": "user",
|
||||
"content": f"Classify as positive/negative/neutral (one word): {text}"
|
||||
}]
|
||||
)
|
||||
)
|
||||
for i, text in enumerate(items_to_classify)
|
||||
]
|
||||
|
||||
# 2. Create batch
|
||||
batch = client.messages.batches.create(requests=requests)
|
||||
print(f"Created batch: {batch.id}")
|
||||
|
||||
# 3. Wait for completion
|
||||
while True:
|
||||
batch = client.messages.batches.retrieve(batch.id)
|
||||
if batch.processing_status == "ended":
|
||||
break
|
||||
time.sleep(10)
|
||||
|
||||
# 4. Collect results
|
||||
results = {}
|
||||
for result in client.messages.batches.results(batch.id):
|
||||
if result.result.type == "succeeded":
|
||||
msg = result.result.message
|
||||
results[result.custom_id] = next((b.text for b in msg.content if b.type == "text"), "")
|
||||
|
||||
for custom_id, classification in sorted(results.items()):
|
||||
print(f"{custom_id}: {classification}")
|
||||
```
|
||||
@@ -0,0 +1,165 @@
|
||||
# Files API — Python
|
||||
|
||||
The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls.
|
||||
|
||||
**Beta:** Pass `betas=["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically).
|
||||
|
||||
## Key Facts
|
||||
|
||||
- Maximum file size: 500 MB
|
||||
- Total storage: 100 GB per organization
|
||||
- Files persist until deleted
|
||||
- File operations (upload, list, delete) are free; content used in messages is billed as input tokens
|
||||
- Not available on Amazon Bedrock or Google Vertex AI
|
||||
|
||||
---
|
||||
|
||||
## Upload a File
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
|
||||
client = anthropic.Anthropic()
|
||||
|
||||
uploaded = client.beta.files.upload(
|
||||
file=("report.pdf", open("report.pdf", "rb"), "application/pdf"),
|
||||
)
|
||||
print(f"File ID: {uploaded.id}")
|
||||
print(f"Size: {uploaded.size_bytes} bytes")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Use a File in Messages
|
||||
|
||||
### PDF / Text Document
|
||||
|
||||
```python
|
||||
response = client.beta.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{"type": "text", "text": "Summarize the key findings in this report."},
|
||||
{
|
||||
"type": "document",
|
||||
"source": {"type": "file", "file_id": uploaded.id},
|
||||
"title": "Q4 Report", # optional
|
||||
"citations": {"enabled": True} # optional, enables citations
|
||||
}
|
||||
]
|
||||
}],
|
||||
betas=["files-api-2025-04-14"],
|
||||
)
|
||||
for block in response.content:
|
||||
if block.type == "text":
|
||||
print(block.text)
|
||||
```
|
||||
|
||||
### Image
|
||||
|
||||
```python
|
||||
image_file = client.beta.files.upload(
|
||||
file=("photo.png", open("photo.png", "rb"), "image/png"),
|
||||
)
|
||||
|
||||
response = client.beta.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{"type": "text", "text": "What's in this image?"},
|
||||
{
|
||||
"type": "image",
|
||||
"source": {"type": "file", "file_id": image_file.id}
|
||||
}
|
||||
]
|
||||
}],
|
||||
betas=["files-api-2025-04-14"],
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Manage Files
|
||||
|
||||
### List Files
|
||||
|
||||
```python
|
||||
files = client.beta.files.list()
|
||||
for f in files.data:
|
||||
print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)")
|
||||
```
|
||||
|
||||
### Get File Metadata
|
||||
|
||||
```python
|
||||
file_info = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w")
|
||||
print(f"Filename: {file_info.filename}")
|
||||
print(f"MIME type: {file_info.mime_type}")
|
||||
```
|
||||
|
||||
### Delete a File
|
||||
|
||||
```python
|
||||
client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w")
|
||||
```
|
||||
|
||||
### Download a File
|
||||
|
||||
Only files created by the code execution tool or skills can be downloaded (not user-uploaded files).
|
||||
|
||||
```python
|
||||
file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w")
|
||||
file_content.write_to_file("output.txt")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Full End-to-End Example
|
||||
|
||||
Upload a document once, ask multiple questions about it:
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
|
||||
client = anthropic.Anthropic()
|
||||
|
||||
# 1. Upload once
|
||||
uploaded = client.beta.files.upload(
|
||||
file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"),
|
||||
)
|
||||
print(f"Uploaded: {uploaded.id}")
|
||||
|
||||
# 2. Ask multiple questions using the same file_id
|
||||
questions = [
|
||||
"What are the key terms and conditions?",
|
||||
"What is the termination clause?",
|
||||
"Summarize the payment schedule.",
|
||||
]
|
||||
|
||||
for question in questions:
|
||||
response = client.beta.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{"type": "text", "text": question},
|
||||
{
|
||||
"type": "document",
|
||||
"source": {"type": "file", "file_id": uploaded.id}
|
||||
}
|
||||
]
|
||||
}],
|
||||
betas=["files-api-2025-04-14"],
|
||||
)
|
||||
print(f"\nQ: {question}")
|
||||
text = next((b.text for b in response.content if b.type == "text"), "")
|
||||
print(f"A: {text[:200]}")
|
||||
|
||||
# 3. Clean up when done
|
||||
client.beta.files.delete(uploaded.id)
|
||||
```
|
||||
@@ -0,0 +1,162 @@
|
||||
# Streaming — Python
|
||||
|
||||
## Quick Start
|
||||
|
||||
```python
|
||||
with client.messages.stream(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=64000,
|
||||
messages=[{"role": "user", "content": "Write a story"}]
|
||||
) as stream:
|
||||
for text in stream.text_stream:
|
||||
print(text, end="", flush=True)
|
||||
```
|
||||
|
||||
### Async
|
||||
|
||||
```python
|
||||
async with async_client.messages.stream(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=64000,
|
||||
messages=[{"role": "user", "content": "Write a story"}]
|
||||
) as stream:
|
||||
async for text in stream.text_stream:
|
||||
print(text, end="", flush=True)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Handling Different Content Types
|
||||
|
||||
Claude may return text, thinking blocks, or tool use. Handle each appropriately:
|
||||
|
||||
> **Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead.
|
||||
|
||||
```python
|
||||
with client.messages.stream(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=64000,
|
||||
thinking={"type": "adaptive"},
|
||||
messages=[{"role": "user", "content": "Analyze this problem"}]
|
||||
) as stream:
|
||||
for event in stream:
|
||||
if event.type == "content_block_start":
|
||||
if event.content_block.type == "thinking":
|
||||
print("\n[Thinking...]")
|
||||
elif event.content_block.type == "text":
|
||||
print("\n[Response:]")
|
||||
|
||||
elif event.type == "content_block_delta":
|
||||
if event.delta.type == "thinking_delta":
|
||||
print(event.delta.thinking, end="", flush=True)
|
||||
elif event.delta.type == "text_delta":
|
||||
print(event.delta.text, end="", flush=True)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Streaming with Tool Use
|
||||
|
||||
The Python tool runner currently returns complete messages. Use streaming for individual API calls within a manual loop if you need per-token streaming with tools:
|
||||
|
||||
```python
|
||||
with client.messages.stream(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=64000,
|
||||
tools=tools,
|
||||
messages=messages
|
||||
) as stream:
|
||||
for text in stream.text_stream:
|
||||
print(text, end="", flush=True)
|
||||
|
||||
response = stream.get_final_message()
|
||||
# Continue with tool execution if response.stop_reason == "tool_use"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting the Final Message
|
||||
|
||||
```python
|
||||
with client.messages.stream(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=64000,
|
||||
messages=[{"role": "user", "content": "Hello"}]
|
||||
) as stream:
|
||||
for text in stream.text_stream:
|
||||
print(text, end="", flush=True)
|
||||
|
||||
# Get full message after streaming
|
||||
final_message = stream.get_final_message()
|
||||
print(f"\n\nTokens used: {final_message.usage.output_tokens}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Streaming with Progress Updates
|
||||
|
||||
```python
|
||||
def stream_with_progress(client, **kwargs):
|
||||
"""Stream a response with progress updates."""
|
||||
total_tokens = 0
|
||||
content_parts = []
|
||||
|
||||
with client.messages.stream(**kwargs) as stream:
|
||||
for event in stream:
|
||||
if event.type == "content_block_delta":
|
||||
if event.delta.type == "text_delta":
|
||||
text = event.delta.text
|
||||
content_parts.append(text)
|
||||
print(text, end="", flush=True)
|
||||
|
||||
elif event.type == "message_delta":
|
||||
if event.usage and event.usage.output_tokens is not None:
|
||||
total_tokens = event.usage.output_tokens
|
||||
|
||||
final_message = stream.get_final_message()
|
||||
|
||||
print(f"\n\n[Tokens used: {total_tokens}]")
|
||||
return "".join(content_parts)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling in Streams
|
||||
|
||||
```python
|
||||
try:
|
||||
with client.messages.stream(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=64000,
|
||||
messages=[{"role": "user", "content": "Write a story"}]
|
||||
) as stream:
|
||||
for text in stream.text_stream:
|
||||
print(text, end="", flush=True)
|
||||
except anthropic.APIConnectionError:
|
||||
print("\nConnection lost. Please retry.")
|
||||
except anthropic.RateLimitError:
|
||||
print("\nRate limited. Please wait and retry.")
|
||||
except anthropic.APIStatusError as e:
|
||||
print(f"\nAPI error: {e.status_code}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stream Event Types
|
||||
|
||||
| Event Type | Description | When it fires |
|
||||
| --------------------- | --------------------------- | --------------------------------- |
|
||||
| `message_start` | Contains message metadata | Once at the beginning |
|
||||
| `content_block_start` | New content block beginning | When a text/tool_use block starts |
|
||||
| `content_block_delta` | Incremental content update | For each token/chunk |
|
||||
| `content_block_stop` | Content block complete | When a block finishes |
|
||||
| `message_delta` | Message-level updates | Contains `stop_reason`, usage |
|
||||
| `message_stop` | Message complete | Once at the end |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always flush output** — Use `flush=True` to show tokens immediately
|
||||
2. **Handle partial responses** — If the stream is interrupted, you may have incomplete content
|
||||
3. **Track token usage** — The `message_delta` event contains usage information
|
||||
4. **Use timeouts** — Set appropriate timeouts for your application
|
||||
5. **Default to streaming** — Use `.get_final_message()` to get the complete response even when streaming, giving you timeout protection without needing to handle individual events
|
||||
@@ -0,0 +1,590 @@
|
||||
# Tool Use — Python
|
||||
|
||||
For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md).
|
||||
|
||||
## Tool Runner (Recommended)
|
||||
|
||||
**Beta:** The tool runner is in beta in the Python SDK.
|
||||
|
||||
Use the `@beta_tool` decorator to define tools as typed functions, then pass them to `client.beta.messages.tool_runner()`:
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
from anthropic import beta_tool
|
||||
|
||||
client = anthropic.Anthropic()
|
||||
|
||||
@beta_tool
|
||||
def get_weather(location: str, unit: str = "celsius") -> str:
|
||||
"""Get current weather for a location.
|
||||
|
||||
Args:
|
||||
location: City and state, e.g., San Francisco, CA.
|
||||
unit: Temperature unit, either "celsius" or "fahrenheit".
|
||||
"""
|
||||
# Your implementation here
|
||||
return f"72°F and sunny in {location}"
|
||||
|
||||
# The tool runner handles the agentic loop automatically
|
||||
runner = client.beta.messages.tool_runner(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
tools=[get_weather],
|
||||
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
|
||||
)
|
||||
|
||||
# Each iteration yields a BetaMessage; iteration stops when Claude is done
|
||||
for message in runner:
|
||||
print(message)
|
||||
```
|
||||
|
||||
For async usage, use `@beta_async_tool` with `async def` functions.
|
||||
|
||||
**Key benefits of the tool runner:**
|
||||
|
||||
- No manual loop — the SDK handles calling tools and feeding results back
|
||||
- Type-safe tool inputs via decorators
|
||||
- Tool schemas are generated automatically from function signatures
|
||||
- Iteration stops automatically when Claude has no more tool calls
|
||||
|
||||
---
|
||||
|
||||
## MCP Tool Conversion Helpers
|
||||
|
||||
**Beta.** Convert [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) tools, prompts, and resources to Anthropic API types for use with the tool runner. Requires `pip install anthropic[mcp]` (Python 3.10+).
|
||||
|
||||
> **Note:** The Claude API also supports an `mcp_servers` parameter that lets Claude connect directly to remote MCP servers. Use these helpers instead when you need local MCP servers, prompts, resources, or more control over the MCP connection.
|
||||
|
||||
### MCP Tools with Tool Runner
|
||||
|
||||
```python
|
||||
from anthropic import AsyncAnthropic
|
||||
from anthropic.lib.tools.mcp import async_mcp_tool
|
||||
from mcp import ClientSession
|
||||
from mcp.client.stdio import stdio_client, StdioServerParameters
|
||||
|
||||
client = AsyncAnthropic()
|
||||
|
||||
async with stdio_client(StdioServerParameters(command="mcp-server")) as (read, write):
|
||||
async with ClientSession(read, write) as mcp_client:
|
||||
await mcp_client.initialize()
|
||||
|
||||
tools_result = await mcp_client.list_tools()
|
||||
# tool_runner is sync — returns the runner, not a coroutine
|
||||
runner = client.beta.messages.tool_runner(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{"role": "user", "content": "Use the available tools"}],
|
||||
tools=[async_mcp_tool(t, mcp_client) for t in tools_result.tools],
|
||||
)
|
||||
async for message in runner:
|
||||
print(message)
|
||||
```
|
||||
|
||||
For sync usage, use `mcp_tool` instead of `async_mcp_tool`.
|
||||
|
||||
### MCP Prompts
|
||||
|
||||
```python
|
||||
from anthropic.lib.tools.mcp import mcp_message
|
||||
|
||||
prompt = await mcp_client.get_prompt(name="my-prompt")
|
||||
response = await client.beta.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[mcp_message(m) for m in prompt.messages],
|
||||
)
|
||||
```
|
||||
|
||||
### MCP Resources as Content
|
||||
|
||||
```python
|
||||
from anthropic.lib.tools.mcp import mcp_resource_to_content
|
||||
|
||||
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
|
||||
response = await client.beta.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{
|
||||
"role": "user",
|
||||
"content": [
|
||||
mcp_resource_to_content(resource),
|
||||
{"type": "text", "text": "Summarize this document"},
|
||||
],
|
||||
}],
|
||||
)
|
||||
```
|
||||
|
||||
### Upload MCP Resources as Files
|
||||
|
||||
```python
|
||||
from anthropic.lib.tools.mcp import mcp_resource_to_file
|
||||
|
||||
resource = await mcp_client.read_resource(uri="file:///path/to/data.json")
|
||||
uploaded = await client.beta.files.upload(file=mcp_resource_to_file(resource))
|
||||
```
|
||||
|
||||
Conversion functions raise `UnsupportedMCPValueError` if an MCP value cannot be converted (e.g., unsupported content types like audio, unsupported MIME types).
|
||||
|
||||
---
|
||||
|
||||
## Manual Agentic Loop
|
||||
|
||||
Use this when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval):
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
|
||||
client = anthropic.Anthropic()
|
||||
tools = [...] # Your tool definitions
|
||||
messages = [{"role": "user", "content": user_input}]
|
||||
|
||||
# Agentic loop: keep going until Claude stops calling tools
|
||||
while True:
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
tools=tools,
|
||||
messages=messages
|
||||
)
|
||||
|
||||
# If Claude is done (no more tool calls), break
|
||||
if response.stop_reason == "end_turn":
|
||||
break
|
||||
|
||||
# Server-side tool hit iteration limit; re-send to continue
|
||||
if response.stop_reason == "pause_turn":
|
||||
messages = [
|
||||
{"role": "user", "content": user_input},
|
||||
{"role": "assistant", "content": response.content},
|
||||
]
|
||||
continue
|
||||
|
||||
# Extract tool use blocks from the response
|
||||
tool_use_blocks = [b for b in response.content if b.type == "tool_use"]
|
||||
|
||||
# Append assistant's response (including tool_use blocks)
|
||||
messages.append({"role": "assistant", "content": response.content})
|
||||
|
||||
# Execute each tool and collect results
|
||||
tool_results = []
|
||||
for tool in tool_use_blocks:
|
||||
result = execute_tool(tool.name, tool.input) # Your implementation
|
||||
tool_results.append({
|
||||
"type": "tool_result",
|
||||
"tool_use_id": tool.id, # Must match the tool_use block's id
|
||||
"content": result
|
||||
})
|
||||
|
||||
# Append tool results as a user message
|
||||
messages.append({"role": "user", "content": tool_results})
|
||||
|
||||
# Final response text
|
||||
final_text = next(b.text for b in response.content if b.type == "text")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Handling Tool Results
|
||||
|
||||
```python
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
tools=tools,
|
||||
messages=[{"role": "user", "content": "What's the weather in Paris?"}]
|
||||
)
|
||||
|
||||
for block in response.content:
|
||||
if block.type == "tool_use":
|
||||
tool_name = block.name
|
||||
tool_input = block.input
|
||||
tool_use_id = block.id
|
||||
|
||||
result = execute_tool(tool_name, tool_input)
|
||||
|
||||
followup = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
tools=tools,
|
||||
messages=[
|
||||
{"role": "user", "content": "What's the weather in Paris?"},
|
||||
{"role": "assistant", "content": response.content},
|
||||
{
|
||||
"role": "user",
|
||||
"content": [{
|
||||
"type": "tool_result",
|
||||
"tool_use_id": tool_use_id,
|
||||
"content": result
|
||||
}]
|
||||
}
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multiple Tool Calls
|
||||
|
||||
```python
|
||||
tool_results = []
|
||||
|
||||
for block in response.content:
|
||||
if block.type == "tool_use":
|
||||
result = execute_tool(block.name, block.input)
|
||||
tool_results.append({
|
||||
"type": "tool_result",
|
||||
"tool_use_id": block.id,
|
||||
"content": result
|
||||
})
|
||||
|
||||
# Send all results back at once
|
||||
if tool_results:
|
||||
followup = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
tools=tools,
|
||||
messages=[
|
||||
*previous_messages,
|
||||
{"role": "assistant", "content": response.content},
|
||||
{"role": "user", "content": tool_results}
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling in Tool Results
|
||||
|
||||
```python
|
||||
tool_result = {
|
||||
"type": "tool_result",
|
||||
"tool_use_id": tool_use_id,
|
||||
"content": "Error: Location 'xyz' not found. Please provide a valid city name.",
|
||||
"is_error": True
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tool Choice
|
||||
|
||||
```python
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
tools=tools,
|
||||
tool_choice={"type": "tool", "name": "get_weather"}, # Force specific tool
|
||||
messages=[{"role": "user", "content": "What's the weather in Paris?"}]
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Code Execution
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
|
||||
client = anthropic.Anthropic()
|
||||
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{
|
||||
"role": "user",
|
||||
"content": "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
|
||||
}],
|
||||
tools=[{
|
||||
"type": "code_execution_20260120",
|
||||
"name": "code_execution"
|
||||
}]
|
||||
)
|
||||
|
||||
for block in response.content:
|
||||
if block.type == "text":
|
||||
print(block.text)
|
||||
elif block.type == "bash_code_execution_tool_result":
|
||||
print(f"stdout: {block.content.stdout}")
|
||||
```
|
||||
|
||||
### Upload Files for Analysis
|
||||
|
||||
```python
|
||||
# 1. Upload a file
|
||||
uploaded = client.beta.files.upload(file=open("sales_data.csv", "rb"))
|
||||
|
||||
# 2. Pass to code execution via container_upload block
|
||||
# Code execution is GA; Files API is still beta (pass via extra_headers)
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
extra_headers={"anthropic-beta": "files-api-2025-04-14"},
|
||||
messages=[{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{"type": "text", "text": "Analyze this sales data. Show trends and create a visualization."},
|
||||
{"type": "container_upload", "file_id": uploaded.id}
|
||||
]
|
||||
}],
|
||||
tools=[{"type": "code_execution_20260120", "name": "code_execution"}]
|
||||
)
|
||||
```
|
||||
|
||||
### Retrieve Generated Files
|
||||
|
||||
```python
|
||||
import os
|
||||
|
||||
OUTPUT_DIR = "./claude_outputs"
|
||||
os.makedirs(OUTPUT_DIR, exist_ok=True)
|
||||
|
||||
for block in response.content:
|
||||
if block.type == "bash_code_execution_tool_result":
|
||||
result = block.content
|
||||
if result.type == "bash_code_execution_result" and result.content:
|
||||
for file_ref in result.content:
|
||||
if file_ref.type == "bash_code_execution_output":
|
||||
metadata = client.beta.files.retrieve_metadata(file_ref.file_id)
|
||||
file_content = client.beta.files.download(file_ref.file_id)
|
||||
# Use basename to prevent path traversal; validate result
|
||||
safe_name = os.path.basename(metadata.filename)
|
||||
if not safe_name or safe_name in (".", ".."):
|
||||
print(f"Skipping invalid filename: {metadata.filename}")
|
||||
continue
|
||||
output_path = os.path.join(OUTPUT_DIR, safe_name)
|
||||
file_content.write_to_file(output_path)
|
||||
print(f"Saved: {output_path}")
|
||||
```
|
||||
|
||||
### Container Reuse
|
||||
|
||||
```python
|
||||
# First request: set up environment
|
||||
response1 = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{"role": "user", "content": "Install tabulate and create data.json with sample data"}],
|
||||
tools=[{"type": "code_execution_20260120", "name": "code_execution"}]
|
||||
)
|
||||
|
||||
# Get container ID from response
|
||||
container_id = response1.container.id
|
||||
|
||||
# Second request: reuse the same container
|
||||
response2 = client.messages.create(
|
||||
container=container_id,
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{"role": "user", "content": "Read data.json and display as a formatted table"}],
|
||||
tools=[{"type": "code_execution_20260120", "name": "code_execution"}]
|
||||
)
|
||||
```
|
||||
|
||||
### Response Structure
|
||||
|
||||
```python
|
||||
for block in response.content:
|
||||
if block.type == "text":
|
||||
print(block.text) # Claude's explanation
|
||||
elif block.type == "server_tool_use":
|
||||
print(f"Running: {block.name} - {block.input}") # What Claude is doing
|
||||
elif block.type == "bash_code_execution_tool_result":
|
||||
result = block.content
|
||||
if result.type == "bash_code_execution_result":
|
||||
if result.return_code == 0:
|
||||
print(f"Output: {result.stdout}")
|
||||
else:
|
||||
print(f"Error: {result.stderr}")
|
||||
else:
|
||||
print(f"Tool error: {result.error_code}")
|
||||
elif block.type == "text_editor_code_execution_tool_result":
|
||||
print(f"File operation: {block.content}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Memory Tool
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
|
||||
client = anthropic.Anthropic()
|
||||
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{"role": "user", "content": "Remember that my preferred language is Python."}],
|
||||
tools=[{"type": "memory_20250818", "name": "memory"}],
|
||||
)
|
||||
```
|
||||
|
||||
### SDK Memory Helper
|
||||
|
||||
Subclass `BetaAbstractMemoryTool`:
|
||||
|
||||
```python
|
||||
from anthropic.lib.tools import BetaAbstractMemoryTool
|
||||
|
||||
class MyMemoryTool(BetaAbstractMemoryTool):
|
||||
def view(self, command): ...
|
||||
def create(self, command): ...
|
||||
def str_replace(self, command): ...
|
||||
def insert(self, command): ...
|
||||
def delete(self, command): ...
|
||||
def rename(self, command): ...
|
||||
|
||||
memory = MyMemoryTool()
|
||||
|
||||
# Use with tool runner
|
||||
runner = client.beta.messages.tool_runner(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
tools=[memory],
|
||||
messages=[{"role": "user", "content": "Remember my preferences"}],
|
||||
)
|
||||
|
||||
for message in runner:
|
||||
print(message)
|
||||
```
|
||||
|
||||
For full implementation examples, use WebFetch:
|
||||
|
||||
- `https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py`
|
||||
|
||||
---
|
||||
|
||||
## Structured Outputs
|
||||
|
||||
### JSON Outputs (Pydantic — Recommended)
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
from typing import List
|
||||
import anthropic
|
||||
|
||||
class ContactInfo(BaseModel):
|
||||
name: str
|
||||
email: str
|
||||
plan: str
|
||||
interests: List[str]
|
||||
demo_requested: bool
|
||||
|
||||
client = anthropic.Anthropic()
|
||||
|
||||
response = client.messages.parse(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{
|
||||
"role": "user",
|
||||
"content": "Extract: Jane Doe (jane@co.com) wants Enterprise, interested in API and SDKs, wants a demo."
|
||||
}],
|
||||
output_format=ContactInfo,
|
||||
)
|
||||
|
||||
# response.parsed_output is a validated ContactInfo instance
|
||||
contact = response.parsed_output
|
||||
print(contact.name) # "Jane Doe"
|
||||
print(contact.interests) # ["API", "SDKs"]
|
||||
```
|
||||
|
||||
### Raw Schema
|
||||
|
||||
```python
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{
|
||||
"role": "user",
|
||||
"content": "Extract info: John Smith (john@example.com) wants the Enterprise plan."
|
||||
}],
|
||||
output_config={
|
||||
"format": {
|
||||
"type": "json_schema",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": {"type": "string"},
|
||||
"email": {"type": "string"},
|
||||
"plan": {"type": "string"},
|
||||
"demo_requested": {"type": "boolean"}
|
||||
},
|
||||
"required": ["name", "email", "plan", "demo_requested"],
|
||||
"additionalProperties": False
|
||||
}
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
import json
|
||||
# output_config.format guarantees the first block is text with valid JSON
|
||||
text = next(b.text for b in response.content if b.type == "text")
|
||||
data = json.loads(text)
|
||||
```
|
||||
|
||||
### Strict Tool Use
|
||||
|
||||
```python
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{"role": "user", "content": "Book a flight to Tokyo for 2 passengers on March 15"}],
|
||||
tools=[{
|
||||
"name": "book_flight",
|
||||
"description": "Book a flight to a destination",
|
||||
"strict": True,
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"destination": {"type": "string"},
|
||||
"date": {"type": "string", "format": "date"},
|
||||
"passengers": {"type": "integer", "enum": [1, 2, 3, 4, 5, 6, 7, 8]}
|
||||
},
|
||||
"required": ["destination", "date", "passengers"],
|
||||
"additionalProperties": False
|
||||
}
|
||||
}]
|
||||
)
|
||||
```
|
||||
|
||||
### Using Both Together
|
||||
|
||||
```python
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=16000,
|
||||
messages=[{"role": "user", "content": "Plan a trip to Paris next month"}],
|
||||
output_config={
|
||||
"format": {
|
||||
"type": "json_schema",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"summary": {"type": "string"},
|
||||
"next_steps": {"type": "array", "items": {"type": "string"}}
|
||||
},
|
||||
"required": ["summary", "next_steps"],
|
||||
"additionalProperties": False
|
||||
}
|
||||
}
|
||||
},
|
||||
tools=[{
|
||||
"name": "search_flights",
|
||||
"description": "Search for available flights",
|
||||
"strict": True,
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"destination": {"type": "string"},
|
||||
"date": {"type": "string", "format": "date"}
|
||||
},
|
||||
"required": ["destination", "date"],
|
||||
"additionalProperties": False
|
||||
}
|
||||
}]
|
||||
)
|
||||
```
|
||||
@@ -0,0 +1,332 @@
|
||||
# Managed Agents — Python
|
||||
|
||||
> **Bindings not shown here:** This README covers the most common managed-agents flows for Python. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Python SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
|
||||
|
||||
> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install anthropic
|
||||
```
|
||||
|
||||
## Client Initialization
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
|
||||
# Default (uses ANTHROPIC_API_KEY env var)
|
||||
client = anthropic.Anthropic()
|
||||
|
||||
# Explicit API key
|
||||
client = anthropic.Anthropic(api_key="your-api-key")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create an Environment
|
||||
|
||||
```python
|
||||
environment = client.beta.environments.create(
|
||||
name="my-dev-env",
|
||||
config={
|
||||
"type": "cloud",
|
||||
"networking": {"type": "unrestricted"},
|
||||
},
|
||||
)
|
||||
print(environment.id) # env_...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create an Agent (required first step)
|
||||
|
||||
> ⚠️ **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `agents.create()` — the session only takes `agent={"type": "agent", "id": agent.id}`.
|
||||
|
||||
### Minimal
|
||||
|
||||
```python
|
||||
# 1. Create the agent (reusable, versioned)
|
||||
agent = client.beta.agents.create(
|
||||
name="Coding Assistant",
|
||||
model="claude-opus-4-7",
|
||||
tools=[{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}],
|
||||
)
|
||||
|
||||
# 2. Start a session
|
||||
session = client.beta.sessions.create(
|
||||
agent={"type": "agent", "id": agent.id, "version": agent.version},
|
||||
environment_id=environment.id,
|
||||
)
|
||||
print(session.id, session.status)
|
||||
```
|
||||
|
||||
### With system prompt and custom tools
|
||||
|
||||
```python
|
||||
import os
|
||||
|
||||
agent = client.beta.agents.create(
|
||||
name="Code Reviewer",
|
||||
model="claude-opus-4-7",
|
||||
system="You are a senior code reviewer.",
|
||||
tools=[
|
||||
{"type": "agent_toolset_20260401"},
|
||||
{
|
||||
"type": "custom",
|
||||
"name": "run_tests",
|
||||
"description": "Run the test suite",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"test_path": {"type": "string", "description": "Path to test file"}
|
||||
},
|
||||
"required": ["test_path"],
|
||||
},
|
||||
},
|
||||
],
|
||||
)
|
||||
|
||||
session = client.beta.sessions.create(
|
||||
agent={"type": "agent", "id": agent.id, "version": agent.version},
|
||||
environment_id=environment.id,
|
||||
title="Code review session",
|
||||
resources=[
|
||||
{
|
||||
"type": "github_repository",
|
||||
"url": "https://github.com/owner/repo",
|
||||
"mount_path": "/workspace/repo",
|
||||
"authorization_token": os.environ["GITHUB_TOKEN"],
|
||||
"branch": "main",
|
||||
}
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Send a User Message
|
||||
|
||||
```python
|
||||
client.beta.sessions.events.send(
|
||||
session_id=session.id,
|
||||
events=[
|
||||
{
|
||||
"type": "user.message",
|
||||
"content": [{"type": "text", "text": "Review the auth module"}],
|
||||
}
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns).
|
||||
|
||||
---
|
||||
|
||||
## Stream Events (SSE)
|
||||
|
||||
```python
|
||||
import json
|
||||
|
||||
# Stream-first: open stream, then send while stream is live
|
||||
with client.beta.sessions.stream(
|
||||
session_id=session.id,
|
||||
) as stream:
|
||||
client.beta.sessions.events.send(
|
||||
session_id=session.id,
|
||||
events=[{"type": "user.message", "content": [{"type": "text", "text": "..."}]}],
|
||||
)
|
||||
for event in stream:
|
||||
... # process events
|
||||
|
||||
# Standalone stream iteration:
|
||||
with client.beta.sessions.stream(
|
||||
session_id=session.id,
|
||||
) as stream:
|
||||
for event in stream:
|
||||
if event.type == "agent.message":
|
||||
for block in event.content:
|
||||
if block.type == "text":
|
||||
print(block.text, end="", flush=True)
|
||||
elif event.type == "agent.custom_tool_use":
|
||||
# Custom tool invocation — session is now idle
|
||||
print(f"\nCustom tool call: {event.tool_name}")
|
||||
print(f"Input: {json.dumps(event.input)}")
|
||||
# Send result back (see below)
|
||||
elif event.type == "session.status_idle":
|
||||
print("\n--- Agent idle ---")
|
||||
elif event.type == "session.status_terminated":
|
||||
print("\n--- Session terminated ---")
|
||||
break
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Provide Custom Tool Result
|
||||
|
||||
```python
|
||||
client.beta.sessions.events.send(
|
||||
session_id=session.id,
|
||||
events=[
|
||||
{
|
||||
"type": "user.custom_tool_result",
|
||||
"custom_tool_use_id": "sevt_abc123",
|
||||
"content": [{"type": "text", "text": "All 42 tests passed."}],
|
||||
}
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Poll Events
|
||||
|
||||
```python
|
||||
events = client.beta.sessions.events.list(
|
||||
session_id=session.id,
|
||||
)
|
||||
for event in events.data:
|
||||
print(f"{event.type}: {event.id}")
|
||||
```
|
||||
|
||||
> ⚠️ **Prefer the SDK over raw `requests`/`httpx`.** If you hand-roll a poll loop, don't assume `timeout=(5, 60)` or `httpx.Timeout(120)` caps total call duration — both are **per-chunk** read timeouts (reset on every byte), so a trickling response can block forever. For a hard wall-clock deadline, track `time.monotonic()` at the loop level and bail explicitly, or wrap with `asyncio.wait_for()`. See [Receiving Events](../../shared/managed-agents-events.md#receiving-events).
|
||||
|
||||
---
|
||||
|
||||
## Full Streaming Loop with Custom Tools
|
||||
|
||||
```python
|
||||
import json
|
||||
|
||||
|
||||
def run_custom_tool(tool_name: str, tool_input: dict) -> str:
|
||||
"""Execute a custom tool and return the result."""
|
||||
if tool_name == "run_tests":
|
||||
# Your tool implementation here
|
||||
return "All tests passed."
|
||||
return f"Unknown tool: {tool_name}"
|
||||
|
||||
|
||||
def run_session(client, session_id: str):
|
||||
"""Stream events and handle custom tool calls."""
|
||||
while True:
|
||||
with client.beta.sessions.stream(
|
||||
session_id=session_id,
|
||||
) as stream:
|
||||
tool_calls = []
|
||||
for event in stream:
|
||||
if event.type == "agent.message":
|
||||
for block in event.content:
|
||||
if block.type == "text":
|
||||
print(block.text, end="", flush=True)
|
||||
elif event.type == "agent.custom_tool_use":
|
||||
tool_calls.append(event)
|
||||
elif event.type == "session.status_idle":
|
||||
break
|
||||
elif event.type == "session.status_terminated":
|
||||
return
|
||||
|
||||
if not tool_calls:
|
||||
break
|
||||
|
||||
# Process custom tool calls
|
||||
results = []
|
||||
for call in tool_calls:
|
||||
result = run_custom_tool(call.tool_name, call.input)
|
||||
results.append({
|
||||
"type": "user.custom_tool_result",
|
||||
"custom_tool_use_id": call.id,
|
||||
"content": [{"type": "text", "text": result}],
|
||||
})
|
||||
|
||||
client.beta.sessions.events.send(
|
||||
session_id=session_id,
|
||||
events=results,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Upload a File
|
||||
|
||||
```python
|
||||
with open("data.csv", "rb") as f:
|
||||
file = client.beta.files.upload(
|
||||
file=f,
|
||||
)
|
||||
|
||||
# Use in a session
|
||||
session = client.beta.sessions.create(
|
||||
agent={"type": "agent", "id": agent.id, "version": agent.version},
|
||||
environment_id=environment.id,
|
||||
resources=[{"type": "file", "file_id": file.id, "mount_path": "/workspace/data.csv"}],
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## List and Download Session Files
|
||||
|
||||
List files the agent wrote to `/mnt/session/outputs/` during a session, then download them.
|
||||
|
||||
```python
|
||||
# List files associated with a session
|
||||
files = client.beta.files.list(
|
||||
scope_id=session.id,
|
||||
betas=["managed-agents-2026-04-01"],
|
||||
)
|
||||
for f in files.data:
|
||||
print(f.filename, f.size_bytes)
|
||||
# Download each file and save to disk
|
||||
file_content = client.beta.files.download(f.id)
|
||||
file_content.write_to_file(f.filename)
|
||||
```
|
||||
|
||||
> 💡 There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if the list is empty.
|
||||
|
||||
---
|
||||
|
||||
## Session Management
|
||||
|
||||
```python
|
||||
# Get session details
|
||||
session = client.beta.sessions.retrieve(session_id="sesn_011CZxAbc123Def456")
|
||||
print(session.status, session.usage)
|
||||
|
||||
# List sessions
|
||||
sessions = client.beta.sessions.list()
|
||||
|
||||
# Delete a session
|
||||
client.beta.sessions.delete(session_id="sesn_011CZxAbc123Def456")
|
||||
|
||||
# Archive a session
|
||||
client.beta.sessions.archive(session_id="sesn_011CZxAbc123Def456")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Integration
|
||||
|
||||
```python
|
||||
# Agent declares MCP server (no auth here — auth goes in a vault)
|
||||
agent = client.beta.agents.create(
|
||||
name="MCP Agent",
|
||||
model="claude-opus-4-7",
|
||||
mcp_servers=[
|
||||
{"type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse"},
|
||||
],
|
||||
tools=[
|
||||
{"type": "agent_toolset_20260401", "default_config": {"enabled": True}},
|
||||
{"type": "mcp_toolset", "mcp_server_name": "my-tools"},
|
||||
],
|
||||
)
|
||||
|
||||
# Session attaches vault(s) containing credentials for those MCP server URLs
|
||||
session = client.beta.sessions.create(
|
||||
agent=agent.id,
|
||||
environment_id=environment.id,
|
||||
vault_ids=[vault.id],
|
||||
)
|
||||
```
|
||||
|
||||
See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials.
|
||||
@@ -0,0 +1,113 @@
|
||||
# Claude API — Ruby
|
||||
|
||||
> **Note:** The Ruby SDK supports the Claude API. A tool runner is available in beta via `client.beta.messages.tool_runner()`. Agent SDK is not yet available for Ruby.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
gem install anthropic
|
||||
```
|
||||
|
||||
## Client Initialization
|
||||
|
||||
```ruby
|
||||
require "anthropic"
|
||||
|
||||
# Default (uses ANTHROPIC_API_KEY env var)
|
||||
client = Anthropic::Client.new
|
||||
|
||||
# Explicit API key
|
||||
client = Anthropic::Client.new(api_key: "your-api-key")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Basic Message Request
|
||||
|
||||
```ruby
|
||||
message = client.messages.create(
|
||||
model: :"claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: [
|
||||
{ role: "user", content: "What is the capital of France?" }
|
||||
]
|
||||
)
|
||||
# content is an array of polymorphic block objects (TextBlock, ThinkingBlock,
|
||||
# ToolUseBlock, ...). .type is a Symbol — compare with :text, not "text".
|
||||
# .text raises NoMethodError on non-TextBlock entries.
|
||||
message.content.each do |block|
|
||||
puts block.text if block.type == :text
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Streaming
|
||||
|
||||
```ruby
|
||||
stream = client.messages.stream(
|
||||
model: :"claude-opus-4-7",
|
||||
max_tokens: 64000,
|
||||
messages: [{ role: "user", content: "Write a haiku" }]
|
||||
)
|
||||
|
||||
stream.text.each { |text| print(text) }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tool Use
|
||||
|
||||
The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution.
|
||||
|
||||
### Tool Runner (Beta)
|
||||
|
||||
```ruby
|
||||
class GetWeatherInput < Anthropic::BaseModel
|
||||
required :location, String, doc: "City and state, e.g. San Francisco, CA"
|
||||
end
|
||||
|
||||
class GetWeather < Anthropic::BaseTool
|
||||
doc "Get the current weather for a location"
|
||||
|
||||
input_schema GetWeatherInput
|
||||
|
||||
def call(input)
|
||||
"The weather in #{input.location} is sunny and 72°F."
|
||||
end
|
||||
end
|
||||
|
||||
client.beta.messages.tool_runner(
|
||||
model: :"claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
tools: [GetWeather.new],
|
||||
messages: [{ role: "user", content: "What's the weather in San Francisco?" }]
|
||||
).each_message do |message|
|
||||
puts message.content
|
||||
end
|
||||
```
|
||||
|
||||
### Manual Loop
|
||||
|
||||
See the [shared tool use concepts](../shared/tool-use-concepts.md) for the tool definition format and agentic loop pattern.
|
||||
|
||||
---
|
||||
|
||||
## Prompt Caching
|
||||
|
||||
`system_:` (trailing underscore — avoids shadowing `Kernel#system`) takes an array of text blocks; set `cache_control` on the last block. Plain hashes work via the `OrHash` type alias. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
|
||||
|
||||
```ruby
|
||||
message = client.messages.create(
|
||||
model: :"claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
system_: [
|
||||
{ type: "text", text: long_system_prompt, cache_control: { type: "ephemeral" } }
|
||||
],
|
||||
messages: [{ role: "user", content: "Summarize the key points" }]
|
||||
)
|
||||
```
|
||||
|
||||
For 1-hour TTL: `cache_control: { type: "ephemeral", ttl: "1h" }`. There's also a top-level `cache_control:` on `messages.create` that auto-places on the last cacheable block.
|
||||
|
||||
Verify hits via `message.usage.cache_creation_input_tokens` / `message.usage.cache_read_input_tokens`.
|
||||
@@ -0,0 +1,389 @@
|
||||
# Managed Agents — Ruby
|
||||
|
||||
> **Bindings not shown here:** This README covers the most common managed-agents flows for Ruby. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Ruby SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
|
||||
|
||||
> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `client.beta.agents.create` and pass it to every subsequent `client.beta.sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
gem install anthropic
|
||||
```
|
||||
|
||||
## Client Initialization
|
||||
|
||||
```ruby
|
||||
require "anthropic"
|
||||
|
||||
# Default (uses ANTHROPIC_API_KEY env var)
|
||||
client = Anthropic::Client.new
|
||||
|
||||
# Explicit API key
|
||||
client = Anthropic::Client.new(api_key: "your-api-key")
|
||||
```
|
||||
|
||||
> ⚠️ **Trailing underscores:** The Ruby SDK uses `system_:` and `send_(` (trailing underscore) to avoid shadowing `Kernel#system` and `Kernel#send`. Use these forms throughout managed-agents code.
|
||||
|
||||
---
|
||||
|
||||
## Create an Environment
|
||||
|
||||
```ruby
|
||||
environment = client.beta.environments.create(
|
||||
name: "my-dev-env",
|
||||
config: {
|
||||
type: "cloud",
|
||||
networking: {type: "unrestricted"}
|
||||
}
|
||||
)
|
||||
puts "Environment ID: #{environment.id}" # env_...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create an Agent (required first step)
|
||||
|
||||
> ⚠️ **There is no inline agent config.** `model`/`system_`/`tools` live on the agent object, not the session. Always start with `client.beta.agents.create()` — the session takes either `agent: agent.id` or the typed hash form `agent: {type: "agent", id: agent.id, version: agent.version}`.
|
||||
|
||||
### Minimal
|
||||
|
||||
```ruby
|
||||
# 1. Create the agent (reusable, versioned)
|
||||
agent = client.beta.agents.create(
|
||||
name: "Coding Assistant",
|
||||
model: :"claude-opus-4-7",
|
||||
system_: "You are a helpful coding assistant.",
|
||||
tools: [{type: "agent_toolset_20260401"}]
|
||||
)
|
||||
|
||||
# 2. Start a session
|
||||
session = client.beta.sessions.create(
|
||||
agent: {type: "agent", id: agent.id, version: agent.version},
|
||||
environment_id: environment.id,
|
||||
title: "Quickstart session"
|
||||
)
|
||||
puts "Session ID: #{session.id}"
|
||||
```
|
||||
|
||||
### Updating an Agent
|
||||
|
||||
Updates create new versions; the agent object is immutable per version.
|
||||
|
||||
```ruby
|
||||
updated_agent = client.beta.agents.update(
|
||||
agent.id,
|
||||
version: agent.version,
|
||||
system_: "You are a helpful coding agent. Always write tests."
|
||||
)
|
||||
puts "New version: #{updated_agent.version}"
|
||||
|
||||
# List all versions
|
||||
client.beta.agents.versions.list(agent.id).auto_paging_each do |version|
|
||||
puts "Version #{version.version}: #{version.updated_at.iso8601}"
|
||||
end
|
||||
|
||||
# Archive the agent
|
||||
archived = client.beta.agents.archive(agent.id)
|
||||
puts "Archived at: #{archived.archived_at.iso8601}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Send a User Message
|
||||
|
||||
```ruby
|
||||
client.beta.sessions.events.send_(
|
||||
session.id,
|
||||
events: [{
|
||||
type: "user.message",
|
||||
content: [{type: "text", text: "Review the auth module"}]
|
||||
}]
|
||||
)
|
||||
```
|
||||
|
||||
> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns).
|
||||
|
||||
---
|
||||
|
||||
## Stream Events (SSE)
|
||||
|
||||
```ruby
|
||||
# Open the stream first, then send the user message
|
||||
stream = client.beta.sessions.events.stream_events(session.id)
|
||||
|
||||
client.beta.sessions.events.send_(
|
||||
session.id,
|
||||
events: [{
|
||||
type: "user.message",
|
||||
content: [{type: "text", text: "Summarize the repo README"}]
|
||||
}]
|
||||
)
|
||||
|
||||
stream.each do |event|
|
||||
case event.type
|
||||
in :"agent.message"
|
||||
event.content.each { |block| print block.text }
|
||||
in :"agent.tool_use"
|
||||
puts "\n[Using tool: #{event.name}]"
|
||||
in :"session.status_idle"
|
||||
break
|
||||
in :"session.error"
|
||||
puts "\n[Error: #{event.error&.message || "unknown"}]"
|
||||
break
|
||||
else
|
||||
# ignore other event types
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
> ℹ️ Event `.type` is a Symbol (compare with `:"agent.message"`, not `"agent.message"`).
|
||||
|
||||
### Reconnecting and Tailing
|
||||
|
||||
When reconnecting mid-session, list past events first to dedupe, then tail live events:
|
||||
|
||||
```ruby
|
||||
require "set"
|
||||
|
||||
stream = client.beta.sessions.events.stream_events(session.id)
|
||||
|
||||
# Stream is open and buffering. List history before tailing live.
|
||||
seen_event_ids = Set.new
|
||||
client.beta.sessions.events.list(session.id).auto_paging_each { |past| seen_event_ids << past.id }
|
||||
|
||||
# Tail live events, skipping anything already seen
|
||||
stream.each do |event|
|
||||
next if seen_event_ids.include?(event.id)
|
||||
seen_event_ids << event.id
|
||||
case event.type
|
||||
in :"agent.message"
|
||||
event.content.each { |block| print block.text }
|
||||
in :"session.status_idle"
|
||||
break
|
||||
else
|
||||
# ignore other event types
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Provide Custom Tool Result
|
||||
|
||||
> ℹ️ The Ruby managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `anthropic` Ruby gem repository for the corresponding params.
|
||||
|
||||
---
|
||||
|
||||
## Poll Events
|
||||
|
||||
```ruby
|
||||
client.beta.sessions.events.list(session.id).auto_paging_each do |event|
|
||||
puts "#{event.type}: #{event.id}"
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Upload a File
|
||||
|
||||
```ruby
|
||||
require "pathname"
|
||||
|
||||
file = client.beta.files.upload(file: Pathname("data.csv"))
|
||||
puts "File ID: #{file.id}"
|
||||
|
||||
# Mount in a session
|
||||
session = client.beta.sessions.create(
|
||||
agent: agent.id,
|
||||
environment_id: environment.id,
|
||||
resources: [
|
||||
{
|
||||
type: "file",
|
||||
file_id: file.id,
|
||||
mount_path: "/workspace/data.csv"
|
||||
}
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
### Add and Manage Resources on an Existing Session
|
||||
|
||||
```ruby
|
||||
# Attach an additional file to an open session
|
||||
resource = client.beta.sessions.resources.add(
|
||||
session.id,
|
||||
type: "file",
|
||||
file_id: file.id
|
||||
)
|
||||
puts resource.id # "sesrsc_01ABC..."
|
||||
|
||||
# List resources on the session
|
||||
listed = client.beta.sessions.resources.list(session.id)
|
||||
listed.data.each { |entry| puts "#{entry.id} #{entry.type}" }
|
||||
|
||||
# Detach a resource
|
||||
client.beta.sessions.resources.delete(resource.id, session_id: session.id)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## List and Download Session Files
|
||||
|
||||
> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for Ruby in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `anthropic` Ruby gem repository for the file list/download bindings.
|
||||
|
||||
---
|
||||
|
||||
## Session Management
|
||||
|
||||
```ruby
|
||||
# List environments
|
||||
environments = client.beta.environments.list
|
||||
|
||||
# Retrieve a specific environment
|
||||
env = client.beta.environments.retrieve(environment.id)
|
||||
|
||||
# Archive an environment (read-only, existing sessions continue)
|
||||
client.beta.environments.archive(environment.id)
|
||||
|
||||
# Delete an environment (only if no sessions reference it)
|
||||
client.beta.environments.delete(environment.id)
|
||||
|
||||
# Delete a session
|
||||
client.beta.sessions.delete(session.id)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Integration
|
||||
|
||||
```ruby
|
||||
# Agent declares MCP server (no auth here — auth goes in a vault)
|
||||
agent = client.beta.agents.create(
|
||||
name: "GitHub Assistant",
|
||||
model: :"claude-opus-4-7",
|
||||
mcp_servers: [
|
||||
{
|
||||
type: "url",
|
||||
name: "github",
|
||||
url: "https://api.githubcopilot.com/mcp/"
|
||||
}
|
||||
],
|
||||
tools: [
|
||||
{type: "agent_toolset_20260401"},
|
||||
{type: "mcp_toolset", mcp_server_name: "github"}
|
||||
]
|
||||
)
|
||||
|
||||
# Session attaches vault(s) containing credentials for those MCP server URLs
|
||||
session = client.beta.sessions.create(
|
||||
agent: {type: "agent", id: agent.id, version: agent.version},
|
||||
environment_id: environment.id,
|
||||
vault_ids: [vault.id]
|
||||
)
|
||||
```
|
||||
|
||||
See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials.
|
||||
|
||||
---
|
||||
|
||||
## Vaults
|
||||
|
||||
```ruby
|
||||
# Create a vault
|
||||
vault = client.beta.vaults.create(
|
||||
display_name: "Alice",
|
||||
metadata: {external_user_id: "usr_abc123"}
|
||||
)
|
||||
puts vault.id # "vlt_01ABC..."
|
||||
|
||||
# Add an OAuth credential
|
||||
credential = client.beta.vaults.credentials.create(
|
||||
vault.id,
|
||||
display_name: "Alice's Slack",
|
||||
auth: {
|
||||
type: "mcp_oauth",
|
||||
mcp_server_url: "https://mcp.slack.com/mcp",
|
||||
access_token: "xoxp-...",
|
||||
expires_at: "2026-04-15T00:00:00Z",
|
||||
refresh: {
|
||||
token_endpoint: "https://slack.com/api/oauth.v2.access",
|
||||
client_id: "1234567890.0987654321",
|
||||
scope: "channels:read chat:write",
|
||||
refresh_token: "xoxe-1-...",
|
||||
token_endpoint_auth: {
|
||||
type: "client_secret_post",
|
||||
client_secret: "abc123..."
|
||||
}
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
# Rotate the credential (e.g., after a token refresh)
|
||||
client.beta.vaults.credentials.update(
|
||||
credential.id,
|
||||
vault_id: vault.id,
|
||||
auth: {
|
||||
type: "mcp_oauth",
|
||||
access_token: "xoxp-new-...",
|
||||
expires_at: "2026-05-15T00:00:00Z",
|
||||
refresh: {refresh_token: "xoxe-1-new-..."}
|
||||
}
|
||||
)
|
||||
|
||||
# Archive a vault
|
||||
client.beta.vaults.archive(vault.id)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GitHub Repository Integration
|
||||
|
||||
Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential):
|
||||
|
||||
```ruby
|
||||
session = client.beta.sessions.create(
|
||||
agent: agent.id,
|
||||
environment_id: environment.id,
|
||||
vault_ids: [vault.id],
|
||||
resources: [
|
||||
{
|
||||
type: "github_repository",
|
||||
url: "https://github.com/org/repo",
|
||||
mount_path: "/workspace/repo",
|
||||
authorization_token: "ghp_your_github_token"
|
||||
}
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
Multiple repositories on the same session:
|
||||
|
||||
```ruby
|
||||
resources = [
|
||||
{
|
||||
type: "github_repository",
|
||||
url: "https://github.com/org/frontend",
|
||||
mount_path: "/workspace/frontend",
|
||||
authorization_token: "ghp_your_github_token"
|
||||
},
|
||||
{
|
||||
type: "github_repository",
|
||||
url: "https://github.com/org/backend",
|
||||
mount_path: "/workspace/backend",
|
||||
authorization_token: "ghp_your_github_token"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Rotating a repository's authorization token:
|
||||
|
||||
```ruby
|
||||
listed = client.beta.sessions.resources.list(session.id)
|
||||
repo_resource_id = listed.data.first.id
|
||||
|
||||
client.beta.sessions.resources.update(
|
||||
repo_resource_id,
|
||||
session_id: session.id,
|
||||
authorization_token: "ghp_your_new_github_token"
|
||||
)
|
||||
```
|
||||
@@ -0,0 +1,101 @@
|
||||
# Agent Design Patterns
|
||||
|
||||
This file covers decision heuristics for building agents on the Claude API: which primitives to reach for, how to design your tool surface, and how to manage context and cost over long runs. For per-tool mechanics and code examples, see `tool-use-concepts.md` and the language-specific folders.
|
||||
|
||||
---
|
||||
|
||||
## Model Parameters
|
||||
|
||||
| Parameter | When to use it | What to expect |
|
||||
| --- | --- | --- |
|
||||
| **Adaptive thinking** (`thinking: {type: "adaptive"}`) | When you want Claude to control when and how much to think. | Claude determines thinking depth per request and automatically interleaves thinking between tool calls. No token budget to tune. |
|
||||
| **Effort** (`output_config: {effort: ...}`) | When adjusting the tradeoff between thoroughness and token efficiency. | Lower effort → fewer and more-consolidated tool calls, less preamble, terser confirmations. `medium` is often a favorable balance. Use `max` when correctness matters more than cost. |
|
||||
|
||||
See `SKILL.md` §Thinking & Effort for model support and parameter details.
|
||||
|
||||
---
|
||||
|
||||
## Designing Your Tool Surface
|
||||
|
||||
### Bash vs. dedicated tools
|
||||
|
||||
Claude doesn't know your application's security boundary, approval policy, or UX surface. Claude emits tool calls; your harness handles them. The shape of those tool calls determines what the harness can do.
|
||||
|
||||
A **bash tool** gives Claude broad programmatic leverage — it can perform almost any action. But it gives the harness only an opaque command string, the same shape for every action. Promoting an action to a **dedicated tool** gives the harness an action-specific hook with typed arguments it can intercept, gate, render, or audit.
|
||||
|
||||
**When to promote an action to a dedicated tool:**
|
||||
|
||||
- **Security boundary.** Actions that require gating are natural candidates. Reversibility is a useful criterion: hard-to-reverse actions (external API calls, sending messages, deleting data) can be gated behind user confirmation. A `send_email` tool is easy to gate; `bash -c "curl -X POST ..."` is not.
|
||||
- **Staleness checks.** A dedicated `edit` tool can reject writes if the file changed since Claude last read it. Bash can't enforce that invariant.
|
||||
- **Rendering.** Some actions benefit from custom UI. Claude Code promotes question-asking to a tool so it can render as a modal, present options, and block the agent loop until answered.
|
||||
- **Scheduling.** Read-only tools like `glob` and `grep` can be marked parallel-safe. When the same actions run through bash, the harness can't tell a parallel-safe `grep` from a parallel-unsafe `git push`, so it must serialize.
|
||||
|
||||
**Rule of thumb:** Start with bash for breadth. Promote to dedicated tools when you need to gate, render, audit, or parallelize the action.
|
||||
|
||||
---
|
||||
|
||||
## Anthropic-Provided Tools
|
||||
|
||||
| Tool | Side | When to use it | What to expect |
|
||||
| --- | --- | --- | --- |
|
||||
| **Bash** | Client | Claude needs to execute shell commands. | Claude emits commands; your harness executes them. Reference implementation provided. |
|
||||
| **Text editor** | Client | Claude needs to read or edit files. | Claude views, creates, and edits files via your implementation. Reference implementation provided. |
|
||||
| **Computer use** | Client or Server | Claude needs to interact with GUIs, web apps, or visual interfaces. | Claude takes screenshots and issues mouse/keyboard commands. Can be self-hosted (you run the environment) or Anthropic-hosted. |
|
||||
| **Code execution** | Server | Claude needs to run code in a sandbox you don't want to manage. | Anthropic-hosted container with built-in file and bash sub-tools. No client-side execution. |
|
||||
| **Web search / fetch** | Server | Claude needs information past its training cutoff (news, current events, recent docs) or the content of a specific URL. | Claude issues a query or URL; Anthropic executes it and returns results with citations. |
|
||||
| **Memory** | Client | Claude needs to save context across sessions. | Claude reads/writes a `/memories` directory. You implement the storage backend. |
|
||||
|
||||
**Client-side** tools are defined by Anthropic (name, schema, Claude's usage pattern) but executed by your harness. Anthropic provides reference implementations. **Server-side** tools run entirely on Anthropic infrastructure — declare them in `tools` and Claude handles the rest.
|
||||
|
||||
---
|
||||
|
||||
## Composing Tool Calls: Programmatic Tool Calling
|
||||
|
||||
With standard tool use, each tool call is a round trip: Claude calls the tool, the result lands in Claude's context, Claude reasons about it, then calls the next tool. Three sequential actions (read profile → look up orders → check inventory) means three round trips. Each adds latency and tokens, and most of the intermediate data is never needed again.
|
||||
|
||||
**Programmatic tool calling (PTC)** lets Claude compose those calls into a script instead. The script runs in the code execution container. When the script calls a tool, the container pauses, the call is executed (client-side or server-side), and the result returns to the running code — not to Claude's context. The script processes it with normal control flow (loops, filters, branches). Only the script's final output returns to Claude.
|
||||
|
||||
| When to use it | What to expect |
|
||||
| --- | --- |
|
||||
| Many sequential tool calls, or large intermediate results you want filtered before they hit the context window. | Claude writes code that invokes tools as functions. Runs in the code execution container. Token cost scales with final output, not intermediate results. |
|
||||
|
||||
---
|
||||
|
||||
## Scaling the Tool and Instruction Set
|
||||
|
||||
| Feature | When to use it | What to expect |
|
||||
| --- | --- | --- |
|
||||
| **Tool search** | Many tools available, but only a few relevant per request. Don't want all schemas in context upfront. | Claude searches the tool set and loads only relevant schemas. Tool definitions are appended, not swapped — preserves cache (see Caching below). |
|
||||
| **Skills** | Task-specific instructions Claude should load only when relevant. | Each skill is a folder with a `SKILL.md`. The skill's description sits in context by default; Claude reads the full file when the task calls for it. |
|
||||
|
||||
Both patterns keep the fixed context small and load detail on demand.
|
||||
|
||||
---
|
||||
|
||||
## Long-Running Agents: Managing Context
|
||||
|
||||
| Pattern | When to use it | What to expect |
|
||||
| --- | --- | --- |
|
||||
| **Context editing** | Context grows stale over many turns (old tool results, completed thinking). | Tool results and thinking blocks are cleared based on configurable thresholds. Keeps the transcript lean without summarizing. |
|
||||
| **Compaction** | Conversation likely to reach or exceed the context window limit. | Earlier context is summarized into a compaction block server-side. See `SKILL.md` §Compaction for the critical `response.content` handling. |
|
||||
| **Memory** | State must persist across sessions (not just within one conversation). | Claude reads/writes files in a memory directory. Survives process restarts. |
|
||||
|
||||
**Choosing between them:** Context editing and compaction operate within a session — editing prunes stale turns, compaction summarizes when you're near the limit. Memory is for cross-session persistence. Many long-running agents use all three.
|
||||
|
||||
---
|
||||
|
||||
## Caching for Agents
|
||||
|
||||
**Read `prompt-caching.md` first.** It covers the prefix-match invariant, breakpoint placement, the silent-invalidator audit, and why changing tools or models mid-session breaks the cache. This section covers only the agent-specific workarounds for those constraints.
|
||||
|
||||
| Constraint (from `prompt-caching.md`) | Agent-specific workaround |
|
||||
| --- | --- |
|
||||
| Editing the system prompt mid-session invalidates the cache. | Append a `<system-reminder>` block in the `messages` array instead. The cached prefix stays intact. Claude Code uses this for time updates and mode transitions. |
|
||||
| Switching models mid-session invalidates the cache. | Spawn a **subagent** with the cheaper model for the sub-task; keep the main loop on one model. Claude Code's Explore subagents use Haiku this way. |
|
||||
| Adding/removing tools mid-session invalidates the cache. | Use **tool search** for dynamic discovery — it appends tool schemas rather than swapping them, so the existing prefix is preserved. |
|
||||
|
||||
For multi-turn breakpoint placement, use top-level auto-caching — see `prompt-caching.md` §Placement patterns.
|
||||
|
||||
---
|
||||
|
||||
For live documentation on any of these features, see `live-sources.md`.
|
||||
@@ -0,0 +1,213 @@
|
||||
# HTTP Error Codes Reference
|
||||
|
||||
This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the `python/` or `typescript/` folders.
|
||||
|
||||
## Error Code Summary
|
||||
|
||||
| Code | Error Type | Retryable | Common Cause |
|
||||
| ---- | ----------------------- | --------- | ------------------------------------ |
|
||||
| 400 | `invalid_request_error` | No | Invalid request format or parameters |
|
||||
| 401 | `authentication_error` | No | Invalid or missing API key |
|
||||
| 403 | `permission_error` | No | API key lacks permission |
|
||||
| 404 | `not_found_error` | No | Invalid endpoint or model ID |
|
||||
| 413 | `request_too_large` | No | Request exceeds size limits |
|
||||
| 429 | `rate_limit_error` | Yes | Too many requests |
|
||||
| 500 | `api_error` | Yes | Anthropic service issue |
|
||||
| 529 | `overloaded_error` | Yes | API is temporarily overloaded |
|
||||
|
||||
## Detailed Error Information
|
||||
|
||||
### 400 Bad Request
|
||||
|
||||
**Causes:**
|
||||
|
||||
- Malformed JSON in request body
|
||||
- Missing required parameters (`model`, `max_tokens`, `messages`)
|
||||
- Invalid parameter types (e.g., string where integer expected)
|
||||
- Empty messages array
|
||||
- Messages not alternating user/assistant
|
||||
|
||||
**Example error:**
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "error",
|
||||
"error": {
|
||||
"type": "invalid_request_error",
|
||||
"message": "messages: roles must alternate between \"user\" and \"assistant\""
|
||||
},
|
||||
"request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
|
||||
}
|
||||
```
|
||||
|
||||
**Fix:** Validate request structure before sending. Check that:
|
||||
|
||||
- `model` is a valid model ID
|
||||
- `max_tokens` is a positive integer
|
||||
- `messages` array is non-empty and alternates correctly
|
||||
|
||||
---
|
||||
|
||||
### 401 Unauthorized
|
||||
|
||||
**Causes:**
|
||||
|
||||
- Missing `x-api-key` header or `Authorization` header
|
||||
- Invalid API key format
|
||||
- Revoked or deleted API key
|
||||
|
||||
**Fix:** Ensure `ANTHROPIC_API_KEY` environment variable is set correctly.
|
||||
|
||||
---
|
||||
|
||||
### 403 Forbidden
|
||||
|
||||
**Causes:**
|
||||
|
||||
- API key doesn't have access to the requested model
|
||||
- Organization-level restrictions
|
||||
- Attempting to access beta features without beta access
|
||||
|
||||
**Fix:** Check your API key permissions in the Console. You may need a different API key or to request access to specific features.
|
||||
|
||||
---
|
||||
|
||||
### 404 Not Found
|
||||
|
||||
**Causes:**
|
||||
|
||||
- Typo in model ID (e.g., `claude-sonnet-4.6` instead of `claude-sonnet-4-6`)
|
||||
- Using deprecated model ID
|
||||
- Invalid API endpoint
|
||||
|
||||
**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., `claude-opus-4-7`).
|
||||
|
||||
---
|
||||
|
||||
### 413 Request Too Large
|
||||
|
||||
**Causes:**
|
||||
|
||||
- Request body exceeds maximum size
|
||||
- Too many tokens in input
|
||||
- Image data too large
|
||||
|
||||
**Fix:** Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks.
|
||||
|
||||
---
|
||||
|
||||
### 400 Validation Errors
|
||||
|
||||
Some 400 errors are specifically related to parameter validation:
|
||||
|
||||
- `max_tokens` exceeds model's limit
|
||||
- Invalid `temperature` value (must be 0.0-1.0)
|
||||
- `budget_tokens` >= `max_tokens` in extended thinking
|
||||
- Invalid tool definition schema
|
||||
|
||||
**Model-specific 400s on Opus 4.7:**
|
||||
|
||||
- `temperature`, `top_p`, `top_k` are removed — sending any of them returns 400. Delete the parameter; see `shared/model-migration.md` → Per-SDK Syntax Reference.
|
||||
- `thinking: {type: "enabled", budget_tokens: N}` is removed — sending it returns 400. Use `thinking: {type: "adaptive"}` instead.
|
||||
|
||||
**Common mistake with extended thinking on older models (Opus 4.6 and earlier):**
|
||||
|
||||
```
|
||||
# Wrong: budget_tokens must be < max_tokens
|
||||
thinking: budget_tokens=10000, max_tokens=1000 → Error!
|
||||
|
||||
# Correct
|
||||
thinking: budget_tokens=10000, max_tokens=16000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 429 Rate Limited
|
||||
|
||||
**Causes:**
|
||||
|
||||
- Exceeded requests per minute (RPM)
|
||||
- Exceeded tokens per minute (TPM)
|
||||
- Exceeded tokens per day (TPD)
|
||||
|
||||
**Headers to check:**
|
||||
|
||||
- `retry-after`: Seconds to wait before retrying
|
||||
- `x-ratelimit-limit-*`: Your limits
|
||||
- `x-ratelimit-remaining-*`: Remaining quota
|
||||
|
||||
**Fix:** The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: `max_retries=2`). For custom retry behavior, see the language-specific error handling examples.
|
||||
|
||||
---
|
||||
|
||||
### 500 Internal Server Error
|
||||
|
||||
**Causes:**
|
||||
|
||||
- Temporary Anthropic service issue
|
||||
- Bug in API processing
|
||||
|
||||
**Fix:** Retry with exponential backoff. If persistent, check [status.anthropic.com](https://status.anthropic.com).
|
||||
|
||||
---
|
||||
|
||||
### 529 Overloaded
|
||||
|
||||
**Causes:**
|
||||
|
||||
- High API demand
|
||||
- Service capacity reached
|
||||
|
||||
**Fix:** Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing.
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes and Fixes
|
||||
|
||||
| Mistake | Error | Fix |
|
||||
| ------------------------------- | ---------------- | ------------------------------------------------------- |
|
||||
| `temperature`/`top_p`/`top_k` on Opus 4.7 | 400 | Remove the parameter (see `shared/model-migration.md`) |
|
||||
| `budget_tokens` on Opus 4.7 | 400 | Use `thinking: {type: "adaptive"}` |
|
||||
| `budget_tokens` >= `max_tokens` (older models) | 400 | Ensure `budget_tokens` < `max_tokens` |
|
||||
| Typo in model ID | 404 | Use valid model ID like `claude-opus-4-7` |
|
||||
| First message is `assistant` | 400 | First message must be `user` |
|
||||
| Consecutive same-role messages | 400 | Alternate `user` and `assistant` |
|
||||
| API key in code | 401 (leaked key) | Use environment variable |
|
||||
| Custom retry needs | 429/5xx | SDK retries automatically; customize with `max_retries` |
|
||||
|
||||
## Typed Exceptions in SDKs
|
||||
|
||||
**Always use the SDK's typed exception classes** instead of checking error messages with string matching. Each HTTP error code maps to a specific exception class:
|
||||
|
||||
| HTTP Code | TypeScript Class | Python Class |
|
||||
| --------- | --------------------------------- | --------------------------------- |
|
||||
| 400 | `Anthropic.BadRequestError` | `anthropic.BadRequestError` |
|
||||
| 401 | `Anthropic.AuthenticationError` | `anthropic.AuthenticationError` |
|
||||
| 403 | `Anthropic.PermissionDeniedError` | `anthropic.PermissionDeniedError` |
|
||||
| 404 | `Anthropic.NotFoundError` | `anthropic.NotFoundError` |
|
||||
| 429 | `Anthropic.RateLimitError` | `anthropic.RateLimitError` |
|
||||
| 500+ | `Anthropic.InternalServerError` | `anthropic.InternalServerError` |
|
||||
| Any | `Anthropic.APIError` | `anthropic.APIError` |
|
||||
|
||||
```typescript
|
||||
// ✅ Correct: use typed exceptions
|
||||
try {
|
||||
const response = await client.messages.create({...});
|
||||
} catch (error) {
|
||||
if (error instanceof Anthropic.RateLimitError) {
|
||||
// Handle rate limiting
|
||||
} else if (error instanceof Anthropic.APIError) {
|
||||
console.error(`API error ${error.status}:`, error.message);
|
||||
}
|
||||
}
|
||||
|
||||
// ❌ Wrong: don't check error messages with string matching
|
||||
try {
|
||||
const response = await client.messages.create({...});
|
||||
} catch (error) {
|
||||
const msg = error instanceof Error ? error.message : String(error);
|
||||
if (msg.includes("429") || msg.includes("rate_limit")) { ... }
|
||||
}
|
||||
```
|
||||
|
||||
All exception classes extend `Anthropic.APIError`, which has a `status` property. Use `instanceof` checks from most specific to least specific (e.g., check `RateLimitError` before `APIError`).
|
||||
@@ -0,0 +1,132 @@
|
||||
# Live Documentation Sources
|
||||
|
||||
This file contains WebFetch URLs for fetching current information from platform.claude.com and Agent SDK repositories. Use these when users need the latest data that may have changed since the cached content was last updated.
|
||||
|
||||
## When to Use WebFetch
|
||||
|
||||
- User explicitly asks for "latest" or "current" information
|
||||
- Cached data seems incorrect
|
||||
- User asks about features not covered in cached content
|
||||
- User needs specific API details or examples
|
||||
|
||||
## Claude API Documentation URLs
|
||||
|
||||
### Models & Pricing
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| --------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
|
||||
| Models Overview | `https://platform.claude.com/docs/en/about-claude/models/overview.md` | "Extract current model IDs, context windows, and pricing for all Claude models" |
|
||||
| Migration Guide | `https://platform.claude.com/docs/en/about-claude/models/migration-guide.md` | "Extract breaking changes, deprecated parameters, and per-model migration steps when moving to a newer Claude model" |
|
||||
| Pricing | `https://platform.claude.com/docs/en/pricing.md` | "Extract current pricing per million tokens for input and output" |
|
||||
|
||||
### Core Features
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| ----------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
||||
| Extended Thinking | `https://platform.claude.com/docs/en/build-with-claude/extended-thinking.md` | "Extract extended thinking parameters, budget_tokens requirements, and usage examples" |
|
||||
| Adaptive Thinking | `https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking.md` | "Extract adaptive thinking setup, effort levels, and Claude Opus 4.7 usage examples" |
|
||||
| Effort Parameter | `https://platform.claude.com/docs/en/build-with-claude/effort.md` | "Extract effort levels, cost-quality tradeoffs, and interaction with thinking" |
|
||||
| Tool Use | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview.md` | "Extract tool definition schema, tool_choice options, and handling tool results" |
|
||||
| Streaming | `https://platform.claude.com/docs/en/build-with-claude/streaming.md` | "Extract streaming event types, SDK examples, and best practices" |
|
||||
| Prompt Caching | `https://platform.claude.com/docs/en/build-with-claude/prompt-caching.md` | "Extract cache_control usage, pricing benefits, and implementation examples" |
|
||||
|
||||
### Media & Files
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| ----------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| Vision | `https://platform.claude.com/docs/en/build-with-claude/vision.md` | "Extract supported image formats, size limits, and code examples" |
|
||||
| PDF Support | `https://platform.claude.com/docs/en/build-with-claude/pdf-support.md` | "Extract PDF handling capabilities, limits, and examples" |
|
||||
|
||||
### API Operations
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| Batch Processing | `https://platform.claude.com/docs/en/build-with-claude/batch-processing.md` | "Extract batch API endpoints, request format, and polling for results" |
|
||||
| Files API | `https://platform.claude.com/docs/en/build-with-claude/files.md` | "Extract file upload, download, and referencing in messages, including supported types and beta header" |
|
||||
| Token Counting | `https://platform.claude.com/docs/en/build-with-claude/token-counting.md` | "Extract token counting API usage and examples" |
|
||||
| Rate Limits | `https://platform.claude.com/docs/en/api/rate-limits.md` | "Extract current rate limits by tier and model" |
|
||||
| Errors | `https://platform.claude.com/docs/en/api/errors.md` | "Extract HTTP error codes, meanings, and retry guidance" |
|
||||
|
||||
### Tools
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| -------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| Code Execution | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool.md` | "Extract code execution tool setup, file upload, container reuse, and response handling" |
|
||||
| Computer Use | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use.md` | "Extract computer use tool setup, capabilities, and implementation examples" |
|
||||
| Bash Tool | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool.md` | "Extract bash tool schema, reference implementation, and security considerations" |
|
||||
| Text Editor | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool.md` | "Extract text editor tool commands, schema, and reference implementation" |
|
||||
| Memory Tool | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md` | "Extract memory tool commands, directory structure, and implementation patterns" |
|
||||
| Tool Search | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool.md` | "Extract tool search setup, when to use, and cache interaction" |
|
||||
| Programmatic Tool Calling | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling.md` | "Extract PTC setup, script execution model, and tool invocation from code" |
|
||||
| Skills | `https://platform.claude.com/docs/en/agents-and-tools/skills.md` | "Extract skill folder structure, SKILL.md format, and loading behavior" |
|
||||
|
||||
### Advanced Features
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| ------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------- |
|
||||
| Structured Outputs | `https://platform.claude.com/docs/en/build-with-claude/structured-outputs.md` | "Extract output_config.format usage and schema enforcement" |
|
||||
| Compaction | `https://platform.claude.com/docs/en/build-with-claude/compaction.md` | "Extract compaction setup, trigger config, and streaming with compaction" |
|
||||
| Context Editing | `https://platform.claude.com/docs/en/build-with-claude/context-editing.md` | "Extract context editing thresholds, what gets cleared, and configuration" |
|
||||
| Citations | `https://platform.claude.com/docs/en/build-with-claude/citations.md` | "Extract citation format and implementation" |
|
||||
| Context Windows | `https://platform.claude.com/docs/en/build-with-claude/context-windows.md` | "Extract context window sizes and token management" |
|
||||
|
||||
### Managed Agents
|
||||
|
||||
Use these when a managed-agents binding, behavior, or wire-level detail isn't covered in the cached `shared/managed-agents-*.md` concept files or in `{lang}/managed-agents/README.md`.
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| --------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
||||
| Overview | `https://platform.claude.com/docs/en/managed-agents/overview.md` | "Extract the high-level architecture and how agents/sessions/environments/vaults fit together" |
|
||||
| Quickstart | `https://platform.claude.com/docs/en/managed-agents/quickstart.md` | "Extract the minimal end-to-end agent → environment → session → stream code path" |
|
||||
| Agent Setup | `https://platform.claude.com/docs/en/managed-agents/agent-setup.md` | "Extract agent create/update/list-versions/archive lifecycle and parameters" |
|
||||
| Define Outcomes | `https://platform.claude.com/docs/en/managed-agents/define-outcomes.md` | "Extract outcome definitions, evaluation hooks, and success criteria configuration" |
|
||||
| Sessions | `https://platform.claude.com/docs/en/managed-agents/sessions.md` | "Extract session lifecycle, status transitions, idle/terminated semantics, and resume rules" |
|
||||
| Environments | `https://platform.claude.com/docs/en/managed-agents/environments.md` | "Extract environment config (cloud/networking), management endpoints, and reuse model" |
|
||||
| Events and Streaming | `https://platform.claude.com/docs/en/managed-agents/events-and-streaming.md` | "Extract event stream types, stream-first ordering, reconnect/dedupe, and steering patterns" |
|
||||
| Tools | `https://platform.claude.com/docs/en/managed-agents/tools.md` | "Extract built-in toolset, custom tool definitions, and tool result wire format" |
|
||||
| Files | `https://platform.claude.com/docs/en/managed-agents/files.md` | "Extract file upload, mount paths, session resources, and listing/downloading session outputs" |
|
||||
| Permission Policies | `https://platform.claude.com/docs/en/managed-agents/permission-policies.md` | "Extract permission policy types (allow/deny/confirm) and per-tool config" |
|
||||
| Multi-Agent | `https://platform.claude.com/docs/en/managed-agents/multi-agent.md` | "Extract multi-agent composition patterns, sub-agent invocation, and result handoff" |
|
||||
| Observability | `https://platform.claude.com/docs/en/managed-agents/observability.md` | "Extract logging, tracing, and usage telemetry exposed by managed agents" |
|
||||
| GitHub | `https://platform.claude.com/docs/en/managed-agents/github.md` | "Extract github_repository resource shape, multi-repo mounting, and token rotation" |
|
||||
| MCP Connector | `https://platform.claude.com/docs/en/managed-agents/mcp-connector.md` | "Extract MCP server declaration on agents and vault-based credential injection at session" |
|
||||
| Vaults | `https://platform.claude.com/docs/en/managed-agents/vaults.md` | "Extract vault create, credential add/rotate, OAuth refresh shape, and archive" |
|
||||
| Skills | `https://platform.claude.com/docs/en/managed-agents/skills.md` | "Extract skill packaging and loading model for managed agents" |
|
||||
| Memory | `https://platform.claude.com/docs/en/managed-agents/memory.md` | "Extract memory resource shape, scoping, and lifecycle" |
|
||||
| Onboarding | `https://platform.claude.com/docs/en/managed-agents/onboarding.md` | "Extract first-run setup, prerequisites, and account/region requirements" |
|
||||
| Cloud Containers | `https://platform.claude.com/docs/en/managed-agents/cloud-containers.md` | "Extract cloud container runtime, image config, and network/storage knobs" |
|
||||
| Migration | `https://platform.claude.com/docs/en/managed-agents/migration.md` | "Extract migration paths from earlier APIs/preview shapes to GA managed agents" |
|
||||
|
||||
### Anthropic CLI
|
||||
|
||||
The `ant` CLI provides terminal access to the Claude API. Every API resource is exposed as a subcommand. It is one convenient way to create agents, environments, sessions, and other resources from version-controlled YAML, and to inspect responses interactively.
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| ------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
||||
| Anthropic CLI | `https://platform.claude.com/docs/en/api/sdks/cli.md` | "Extract CLI install, authentication, command structure, and the beta:agents/environments/sessions commands" |
|
||||
|
||||
---
|
||||
|
||||
## Claude API SDK Repositories
|
||||
|
||||
WebFetch these when a binding (class, method, namespace, field) isn't covered in the cached `{lang}/` skill files or in the managed-agents docs above. The SDKs include beta managed-agents support for `/v1/agents`, `/v1/sessions`, `/v1/environments`, and related resources — search the repo for `BetaManagedAgents`, `beta.agents`, `beta.sessions`, or the equivalent namespace for that language.
|
||||
|
||||
| SDK | URL | Extraction Prompt |
|
||||
| ---------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
||||
| Python | `https://github.com/anthropics/anthropic-sdk-python` | "Extract beta managed-agents namespaces, classes, and method signatures (`client.beta.agents`, `client.beta.sessions`)" |
|
||||
| TypeScript | `https://github.com/anthropics/anthropic-sdk-typescript` | "Extract beta managed-agents namespaces, classes, and method signatures (`client.beta.agents`, `client.beta.sessions`)" |
|
||||
| Java | `https://github.com/anthropics/anthropic-sdk-java` | "Extract beta managed-agents classes, builders, and method signatures (`client.beta().agents()`, `BetaManagedAgents*`)" |
|
||||
| Go | `https://github.com/anthropics/anthropic-sdk-go` | "Extract beta managed-agents types and method signatures (`client.Beta.Agents`, `BetaManagedAgents*` event types)" |
|
||||
| Ruby | `https://github.com/anthropics/anthropic-sdk-ruby` | "Extract beta managed-agents methods and parameter shapes (`client.beta.agents`, `client.beta.sessions`)" |
|
||||
| C# | `https://github.com/anthropics/anthropic-sdk-csharp` | "Extract beta managed-agents classes and method signatures (NuGet package, `BetaManagedAgents*` types)" |
|
||||
| PHP | `https://github.com/anthropics/anthropic-sdk-php` | "Extract beta managed-agents classes and method signatures (`$client->beta->agents`, `BetaManagedAgents*` params)" |
|
||||
|
||||
---
|
||||
|
||||
## Fallback Strategy
|
||||
|
||||
If WebFetch fails (network issues, URL changed):
|
||||
|
||||
1. Use cached content from the language-specific files (note the cache date)
|
||||
2. Inform user the data may be outdated
|
||||
3. Suggest they check platform.claude.com or the GitHub repos directly
|
||||
@@ -0,0 +1,299 @@
|
||||
# Managed Agents — Endpoint Reference
|
||||
|
||||
All endpoints require `x-api-key` and `anthropic-version: 2023-06-01` headers. Managed Agents endpoints additionally require the `anthropic-beta` header.
|
||||
|
||||
## Beta Headers
|
||||
|
||||
```
|
||||
anthropic-beta: managed-agents-2026-04-01
|
||||
```
|
||||
|
||||
The SDK adds this header automatically for all `client.beta.{agents,environments,sessions,vaults}.*` calls. Skills endpoints use `skills-2025-10-02`; Files endpoints use `files-api-2025-04-14`.
|
||||
|
||||
---
|
||||
|
||||
## SDK Method Reference
|
||||
|
||||
All resources are under the `beta` namespace. Python and TypeScript share identical method names.
|
||||
|
||||
| Resource | Python / TypeScript (`client.beta.*`) | Go (`client.Beta.*`) |
|
||||
| --- | --- | --- |
|
||||
| Agents | `agents.create` / `retrieve` / `update` / `list` / `archive` | `Agents.New` / `Get` / `Update` / `List` / `Archive` |
|
||||
| Agent Versions | `agents.versions.list` | `Agents.Versions.List` |
|
||||
| Environments | `environments.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Environments.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
|
||||
| Sessions | `sessions.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Sessions.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
|
||||
| Session Events | `sessions.events.list` / `send` / `stream` | `Sessions.Events.List` / `Send` / `StreamEvents` |
|
||||
| Session Resources | `sessions.resources.add` / `retrieve` / `update` / `list` / `delete` | `Sessions.Resources.Add` / `Get` / `Update` / `List` / `Delete` |
|
||||
| Vaults | `vaults.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Vaults.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
|
||||
| Credentials | `vaults.credentials.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Vaults.Credentials.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
|
||||
|
||||
**Naming quirks to watch for:**
|
||||
- Agents have **no delete** — only `archive`. Archive is **permanent**: the agent becomes read-only, new sessions cannot reference it, and there is no unarchive. Confirm with the user before archiving a production agent. Environments, Sessions, Vaults, and Credentials have both `delete` and `archive`; Session Resources, Files, and Skills are `delete`-only.
|
||||
- Session resources use `add` (not `create`).
|
||||
- Go's event stream is `StreamEvents` (not `Stream`).
|
||||
|
||||
**Agent shorthand:** `agent` on session create accepts either a bare string (`agent="agent_abc123"` — uses latest version) or the full reference object (`{type: "agent", id: "agent_abc123", version: 123}`).
|
||||
|
||||
**Model shorthand:** `model` on agent create accepts either a bare string (`model="claude-opus-4-7"` — uses `standard` speed) or the full config object (`{type: "model_config", id: "claude-opus-4-6", speed: "fast"}`). Note: `speed: "fast"` is only supported on Opus 4.6.
|
||||
|
||||
---
|
||||
|
||||
## Agents
|
||||
|
||||
**Step one of every flow.** Sessions require a pre-created agent — there is no inline agent config under `managed-agents-2026-04-01`.
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
|
||||
| `GET` | `/v1/agents` | ListAgents | List agents |
|
||||
| `POST` | `/v1/agents` | CreateAgent | Create a saved agent configuration |
|
||||
| `GET` | `/v1/agents/{agent_id}` | GetAgent | Get agent details |
|
||||
| `POST` | `/v1/agents/{agent_id}` | UpdateAgent | Update agent configuration |
|
||||
| `POST` | `/v1/agents/{agent_id}/archive` | ArchiveAgent | Archive an agent. Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state. |
|
||||
| `GET` | `/v1/agents/{agent_id}/versions` | ListAgentVersions | List agent versions |
|
||||
|
||||
## Sessions
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
|
||||
| `GET` | `/v1/sessions` | ListSessions | List sessions (paginated) |
|
||||
| `POST` | `/v1/sessions` | CreateSession | Create a new session |
|
||||
| `GET` | `/v1/sessions/{session_id}` | GetSession | Get session details |
|
||||
| `POST` | `/v1/sessions/{session_id}` | UpdateSession | Update session metadata/title |
|
||||
| `DELETE` | `/v1/sessions/{session_id}` | DeleteSession | Delete a session |
|
||||
| `POST` | `/v1/sessions/{session_id}/archive` | ArchiveSession | Archive a session |
|
||||
|
||||
## Events
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
|
||||
| `GET` | `/v1/sessions/{session_id}/events` | ListEvents | List events (polling, paginated) |
|
||||
| `POST` | `/v1/sessions/{session_id}/events` | SendEvents | Send events (user message, tool result) |
|
||||
| `GET` | `/v1/sessions/{session_id}/events/stream` | StreamEvents | Stream events via SSE |
|
||||
|
||||
## Session Resources
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------------- | ---------------- | ---------------------------------------- |
|
||||
| `GET` | `/v1/sessions/{session_id}/resources` | ListResources | List resources attached to session |
|
||||
| `POST` | `/v1/sessions/{session_id}/resources` | AddResource | Attach file or github_repository mount (SDK method: `add`, not `create`) |
|
||||
| `GET` | `/v1/sessions/{session_id}/resources/{resource_id}` | GetResource | Get a single resource |
|
||||
| `POST` | `/v1/sessions/{session_id}/resources/{resource_id}` | UpdateResource | Update resource |
|
||||
| `DELETE` | `/v1/sessions/{session_id}/resources/{resource_id}` | DeleteResource | Remove resource from session |
|
||||
|
||||
## Environments
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ---------------------------------------------------------------- | -------------------- | ----------------------------------- |
|
||||
| `POST` | `/v1/environments` | CreateEnvironment | Create environment |
|
||||
| `GET` | `/v1/environments` | ListEnvironments | List environments |
|
||||
| `GET` | `/v1/environments/{environment_id}` | GetEnvironment | Get environment details |
|
||||
| `POST` | `/v1/environments/{environment_id}` | UpdateEnvironment | Update environment |
|
||||
| `DELETE` | `/v1/environments/{environment_id}` | DeleteEnvironment | Delete environment. Returns 204. |
|
||||
| `POST` | `/v1/environments/{environment_id}/archive` | ArchiveEnvironment | Archive environment. Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state. |
|
||||
|
||||
## Vaults
|
||||
|
||||
Vaults store MCP credentials that Anthropic manages on your behalf — OAuth credentials with auto-refresh, or static bearer tokens. Attach to sessions via `vault_ids`. See `managed-agents-tools.md` §Vaults for the conceptual guide and credential shapes.
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
|
||||
| `POST` | `/v1/vaults` | CreateVault | Create a vault |
|
||||
| `GET` | `/v1/vaults` | ListVaults | List vaults |
|
||||
| `GET` | `/v1/vaults/{vault_id}` | GetVault | Get vault details |
|
||||
| `POST` | `/v1/vaults/{vault_id}` | UpdateVault | Update vault |
|
||||
| `DELETE` | `/v1/vaults/{vault_id}` | DeleteVault | Delete vault |
|
||||
| `POST` | `/v1/vaults/{vault_id}/archive` | ArchiveVault | Archive vault |
|
||||
|
||||
## Credentials
|
||||
|
||||
Credentials are individual secrets stored inside a vault.
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ----------------------------------------------------------------- | ------------------ | ---------------------------- |
|
||||
| `POST` | `/v1/vaults/{vault_id}/credentials` | CreateCredential | Create a credential |
|
||||
| `GET` | `/v1/vaults/{vault_id}/credentials` | ListCredentials | List credentials in vault |
|
||||
| `GET` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | GetCredential | Get credential metadata |
|
||||
| `POST` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | UpdateCredential | Update credential |
|
||||
| `DELETE` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | DeleteCredential | Delete credential |
|
||||
| `POST` | `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` | ArchiveCredential | Archive credential |
|
||||
|
||||
## Files
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
|
||||
| `POST` | `/v1/files` | UploadFile | Upload a file |
|
||||
| `GET` | `/v1/files` | ListFiles | List files |
|
||||
| `GET` | `/v1/files/{file_id}` | GetFile | Get file metadata (SDK method: `retrieve_metadata`) |
|
||||
| `GET` | `/v1/files/{file_id}/content` | DownloadFile | Download file content |
|
||||
| `DELETE` | `/v1/files/{file_id}` | DeleteFile | Delete a file |
|
||||
|
||||
## Skills
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | --------------------------------------------------------------- | ------------------ | ---------------------------- |
|
||||
| `POST` | `/v1/skills` | CreateSkill | Create a skill |
|
||||
| `GET` | `/v1/skills` | ListSkills | List skills |
|
||||
| `GET` | `/v1/skills/{skill_id}` | GetSkill | Get skill details |
|
||||
| `DELETE` | `/v1/skills/{skill_id}` | DeleteSkill | Delete a skill |
|
||||
| `POST` | `/v1/skills/{skill_id}/versions` | CreateVersion | Create skill version |
|
||||
| `GET` | `/v1/skills/{skill_id}/versions` | ListVersions | List skill versions |
|
||||
| `GET` | `/v1/skills/{skill_id}/versions/{version}` | GetVersion | Get skill version |
|
||||
| `DELETE` | `/v1/skills/{skill_id}/versions/{version}` | DeleteVersion | Delete skill version |
|
||||
|
||||
---
|
||||
|
||||
## Request/Response Schema Quick Reference
|
||||
|
||||
### CreateAgent Request Body
|
||||
|
||||
**Always start here.** `model`, `system`, `tools`, `mcp_servers`, `skills` are top-level fields on this object — they do NOT go on the session.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string (required, 1-256 chars)",
|
||||
"model": "claude-opus-4-7 (required — bare string, or {id, speed} object)",
|
||||
"description": "string (optional, up to 2048 chars)",
|
||||
"system": "string (optional, up to 100,000 chars)",
|
||||
"tools": [
|
||||
{ "type": "agent_toolset_20260401" }
|
||||
],
|
||||
"skills": [
|
||||
{ "type": "anthropic", "skill_id": "xlsx" },
|
||||
{ "type": "custom", "skill_id": "skill_abc123", "version": "1" }
|
||||
],
|
||||
"mcp_servers": [
|
||||
{
|
||||
"type": "url",
|
||||
"name": "github",
|
||||
"url": "https://api.githubcopilot.com/mcp/"
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"key": "value (max 16 pairs, keys ≤64 chars, values ≤512 chars)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> Limits: `tools` max 50, `skills` max 64, `mcp_servers` max 20 (unique names).
|
||||
|
||||
### CreateSession Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": "agent_abc123 (required — string shorthand for latest version, or {type: \"agent\", id, version} object)",
|
||||
"environment_id": "env_abc123 (required)",
|
||||
"title": "string (optional)",
|
||||
"resources": [
|
||||
{
|
||||
"type": "github_repository",
|
||||
"url": "https://github.com/owner/repo (required)",
|
||||
"authorization_token": "ghp_... (required)",
|
||||
"mount_path": "/workspace/repo (optional — defaults to /workspace/<repo-name>)",
|
||||
"checkout": { "type": "branch", "name": "main" }
|
||||
}
|
||||
],
|
||||
"vault_ids": ["vlt_abc123 (optional — MCP credentials with auto-refresh)"],
|
||||
"metadata": {
|
||||
"key": "value"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> The `agent` field accepts only a string ID or `{type: "agent", id, version}` — `model`/`system`/`tools` live on the agent, not here.
|
||||
>
|
||||
> **`checkout`** accepts `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Omit for the repo's default branch.
|
||||
|
||||
### CreateEnvironment Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string (required)",
|
||||
"description": "string (optional)",
|
||||
"config": {
|
||||
"type": "cloud",
|
||||
"networking": {
|
||||
"type": "unrestricted | limited (union — see SDK types)"
|
||||
},
|
||||
"packages": { }
|
||||
},
|
||||
"metadata": { "key": "value" }
|
||||
}
|
||||
```
|
||||
|
||||
### SendEvents Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"events": [
|
||||
{
|
||||
"type": "user.message",
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Hello"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Tool Result Event
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "user.custom_tool_result",
|
||||
"custom_tool_use_id": "sevt_abc123",
|
||||
"content": [{ "type": "text", "text": "Result data" }],
|
||||
"is_error": false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
Managed Agents endpoints use the standard Anthropic API error format. Errors are returned with an HTTP status code and a JSON body containing `type`, `error`, and `request_id`:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "error",
|
||||
"error": {
|
||||
"type": "invalid_request_error",
|
||||
"message": "Description of what went wrong"
|
||||
},
|
||||
"request_id": "req_011CRv1W3XQ8XpFikNYG7RnE"
|
||||
}
|
||||
```
|
||||
|
||||
Include the `request_id` when reporting issues to Anthropic — it lets us trace the request end-to-end. The inner `error.type` is one of the following:
|
||||
|
||||
| Status | Error type | Description |
|
||||
|---|---|---|
|
||||
| 400 | `invalid_request_error` | The request was malformed or missing required parameters |
|
||||
| 401 | `authentication_error` | Invalid or missing API key |
|
||||
| 403 | `permission_error` | The API key doesn't have permission for this operation |
|
||||
| 404 | `not_found_error` | The requested resource doesn't exist |
|
||||
| 409 | `invalid_request_error` | The request conflicts with the resource's current state (e.g., sending to an archived session) |
|
||||
| 413 | `request_too_large` | The request body exceeds the maximum allowed size |
|
||||
| 429 | `rate_limit_error` | Too many requests — check rate limit headers for retry timing |
|
||||
| 500 | `api_error` | An internal server error occurred |
|
||||
| 529 | `overloaded_error` | The service is temporarily overloaded — retry with backoff |
|
||||
|
||||
Note that `409 Conflict` carries `error.type: "invalid_request_error"` (there is no separate `conflict_error` type); inspect both the HTTP status and the `message` to distinguish conflicts from other invalid requests.
|
||||
|
||||
---
|
||||
|
||||
## Rate Limits
|
||||
|
||||
Managed Agents endpoints have per-organization request-per-minute (RPM) limits, separate from your [Messages API token limits](https://platform.claude.com/docs/en/api/rate-limits). Model inference inside a session still draws from your organization's standard ITPM/OTPM limits.
|
||||
|
||||
| Endpoint group | Scope | RPM | Max concurrent |
|
||||
|---|---|---|---|
|
||||
| Create operations (Agents, Sessions, Vaults) | organization | 60 | — |
|
||||
| All other operations (Agents, Sessions, Vaults) | organization | 600 | — |
|
||||
| All operations (Environments) | organization | 60 | 5 |
|
||||
|
||||
Files and Skills endpoints use the standard tier-based [rate limits](https://platform.claude.com/docs/en/api/rate-limits).
|
||||
|
||||
When a limit is exceeded the API returns `429` with a `rate_limit_error` (see [Error Handling](#error-handling) for the response envelope) and a `retry-after` header indicating how many seconds to wait before retrying. The Anthropic SDK reads this header and retries automatically.
|
||||
@@ -0,0 +1,209 @@
|
||||
# Managed Agents — Common Client Patterns
|
||||
|
||||
Patterns you'll write on the client side when driving a Managed Agent session, grounded in working SDK examples.
|
||||
|
||||
Code samples are TypeScript — Python and cURL follow the same shape; see `python/managed-agents/README.md` and `curl/managed-agents.md` for equivalents.
|
||||
|
||||
---
|
||||
|
||||
## 1. Lossless stream reconnect
|
||||
|
||||
**Problem:** SSE has no replay. If the connection drops mid-session, a naive reconnect re-opens the stream from "now" and you silently miss every event emitted in between.
|
||||
|
||||
**Solution:** on reconnect, fetch the full event history via `events.list()` *before* consuming the live stream, and dedupe on event ID as the live stream catches up.
|
||||
|
||||
```ts
|
||||
const seenEventIds = new Set<string>()
|
||||
const stream = await client.beta.sessions.events.stream(session.id)
|
||||
|
||||
// Stream is now open and buffering server-side. Read history first.
|
||||
for await (const event of client.beta.sessions.events.list(session.id)) {
|
||||
seenEventIds.add(event.id)
|
||||
handle(event)
|
||||
}
|
||||
|
||||
// Tail the live stream. Dedupe only gates handle() — terminal checks must run
|
||||
// even for already-seen events, or a terminal event that was in the history
|
||||
// response gets skipped by `continue` and the loop never exits.
|
||||
for await (const event of stream) {
|
||||
if (!seenEventIds.has(event.id)) {
|
||||
seenEventIds.add(event.id)
|
||||
handle(event)
|
||||
}
|
||||
if (event.type === 'session.status_terminated') break
|
||||
if (event.type === 'session.status_idle' && event.stop_reason.type !== 'requires_action') break
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. `processed_at` — queued vs processed
|
||||
|
||||
Every event on the stream carries `processed_at` (ISO 8601). For client-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`) it's `null` when the event has been queued but not yet picked up by the agent, and populated once the agent processes it. The same event appears on the stream twice — once with `processed_at: null`, once with a timestamp.
|
||||
|
||||
```ts
|
||||
for await (const event of stream) {
|
||||
if (event.type === 'user.message') {
|
||||
if (event.processed_at == null) onQueued(event.id)
|
||||
else onProcessed(event.id, event.processed_at)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use this to drive pending → acknowledged UI state for anything you send. How you map a locally-rendered optimistic message to the server-assigned `event.id` is application-specific (typically via the return value of `events.send()` or FIFO ordering).
|
||||
|
||||
---
|
||||
|
||||
## 3. Interrupt a running session
|
||||
|
||||
Send `user.interrupt` as a normal event. The session keeps running until it reaches a safe boundary, then goes idle.
|
||||
|
||||
```ts
|
||||
await client.beta.sessions.events.send(session.id, {
|
||||
events: [{ type: 'user.interrupt' }],
|
||||
})
|
||||
|
||||
// Drain until the session is truly done — see Pattern 5 for the full gate.
|
||||
for await (const event of stream) {
|
||||
if (event.type === 'session.status_terminated') break
|
||||
if (
|
||||
event.type === 'session.status_idle' &&
|
||||
event.stop_reason.type !== 'requires_action'
|
||||
) break
|
||||
}
|
||||
```
|
||||
|
||||
Reference: `interrupt.ts` — sends the interrupt the moment it sees `span.model_request_start`, drains to idle, then verifies via `sessions.retrieve()`.
|
||||
|
||||
---
|
||||
|
||||
## 4. `tool_confirmation` round-trip
|
||||
|
||||
When the agent has `permission_policy: { type: 'always_ask' }`, any call to that tool fires an `agent.tool_use` event with `evaluated_permission === 'ask'` and the session goes idle waiting for a decision. Respond with `user.tool_confirmation`.
|
||||
|
||||
```ts
|
||||
for await (const event of stream) {
|
||||
if (event.type === 'agent.tool_use' && event.evaluated_permission === 'ask') {
|
||||
await client.beta.sessions.events.send(session.id, {
|
||||
events: [{
|
||||
type: 'user.tool_confirmation',
|
||||
tool_use_id: event.id, // not a toolu_ id — use event.id
|
||||
result: 'allow', // or 'deny'
|
||||
// deny_message: '...', // optional, only with result: 'deny'
|
||||
}],
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Key points:
|
||||
- `tool_use_id` is `event.id` (typically `sevt_...`), **not** a `toolu_...` ID.
|
||||
- `result` is `'allow' | 'deny'`. Use `deny_message` to tell the model *why* you denied — it gets surfaced back to the agent.
|
||||
- Multiple pending tools: respond once per `agent.tool_use` event with `evaluated_permission === 'ask'`.
|
||||
|
||||
Reference: `tool-permissions.ts`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Correct idle-break gate
|
||||
|
||||
Do not break on `session.status_idle` alone. The session goes idle transiently — e.g. between parallel tool executions, while waiting for a `user.tool_confirmation`, or while awaiting a `user.custom_tool_result`. Break when idle with a terminal `stop_reason`, or on `session.status_terminated`.
|
||||
|
||||
```ts
|
||||
for await (const event of stream) {
|
||||
handle(event)
|
||||
if (event.type === 'session.status_terminated') break
|
||||
if (event.type === 'session.status_idle') {
|
||||
if (event.stop_reason.type === 'requires_action') continue // waiting on you — handle it
|
||||
break // end_turn or retries_exhausted — both terminal
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`stop_reason.type` values on `session.status_idle`:
|
||||
- `requires_action` — agent is waiting on a client-side event (tool confirmation, custom tool result). Handle it, don't break.
|
||||
- `retries_exhausted` — terminal failure. Break, then check `sessions.retrieve()` for the error state.
|
||||
- `end_turn` — normal completion.
|
||||
|
||||
---
|
||||
|
||||
## 6. Post-idle status-write race
|
||||
|
||||
The SSE stream emits `session.status_idle` slightly before the session's queryable status reflects it. Clients that break on idle and immediately call `sessions.delete()` or `sessions.archive()` will intermittently 400 with "cannot delete/archive while running."
|
||||
|
||||
Poll before cleanup:
|
||||
|
||||
```ts
|
||||
let s
|
||||
for (let i = 0; i < 10; i++) {
|
||||
s = await client.beta.sessions.retrieve(session.id)
|
||||
if (s.status !== 'running') break
|
||||
await new Promise(r => setTimeout(r, 200))
|
||||
}
|
||||
if (s?.status !== 'running') {
|
||||
await client.beta.sessions.archive(session.id)
|
||||
} // else: still running after 2s — don't archive, let it settle or escalate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Stream-first, then send
|
||||
|
||||
Always open the stream **before** sending the kickoff event. Otherwise the agent may process the event and emit the first events before your consumer is attached, and you'll miss them.
|
||||
|
||||
```ts
|
||||
const stream = await client.beta.sessions.events.stream(session.id)
|
||||
await client.beta.sessions.events.send(session.id, {
|
||||
events: [{ type: 'user.message', content: [{ type: 'text', text: 'Hello' }] }],
|
||||
})
|
||||
for await (const event of stream) { /* ... */ }
|
||||
```
|
||||
|
||||
The `Promise.all([stream, send])` shape works too, but stream-first is simpler and has the same effect — the stream starts buffering the moment it's opened.
|
||||
|
||||
---
|
||||
|
||||
## 8. File-mount gotchas
|
||||
|
||||
**The mounted resource has a different `file_id` than the file you uploaded.** Session creation makes a session-scoped copy.
|
||||
|
||||
```ts
|
||||
const uploaded = await client.beta.files.upload({ file, purpose: 'agent_resource' })
|
||||
// uploaded.id → the original file
|
||||
const session = await client.beta.sessions.create({
|
||||
/* ... */
|
||||
resources: [{ type: 'file', file_id: uploaded.id, mount_path: '/workspace/data.csv' }],
|
||||
})
|
||||
// session.resources[0].file_id !== uploaded.id ← different IDs
|
||||
```
|
||||
|
||||
Delete the original via `files.delete(uploaded.id)`; the session-scoped copy is garbage-collected with the session. `mount_path` must be absolute — see `shared/managed-agents-environments.md`.
|
||||
|
||||
---
|
||||
|
||||
## 9. Secrets for non-MCP APIs and CLIs — keep them host-side via custom tools
|
||||
|
||||
**Problem:** you want the agent to call a third-party API or run a CLI that needs a secret (API key, token, service-account credential), but there is currently no way to set environment variables inside the session container, and vaults currently hold MCP credentials only — they are not exposed to the container's shell. So `curl`, installed CLIs, or SDK clients running via the `bash` tool have no first-class place to read a secret from.
|
||||
|
||||
**Solution:** move the authenticated call to your side. Declare a custom tool on the agent; when the agent emits `agent.custom_tool_use`, your orchestrator (the process reading the SSE stream) executes the call with its own credentials and responds with `user.custom_tool_result`. The container never sees the key.
|
||||
|
||||
```ts
|
||||
// Agent template: declare the tool, no credentials
|
||||
tools: [{ type: 'custom', name: 'linear_graphql', input_schema: { /* query, vars */ } }]
|
||||
|
||||
// Orchestrator: handle the call with host-side creds
|
||||
for await (const event of stream) {
|
||||
if (event.type === 'agent.custom_tool_use' && event.name === 'linear_graphql') {
|
||||
const result = await linear.request(event.input.query, event.input.vars) // host's key
|
||||
await client.beta.sessions.events.send(session.id, {
|
||||
events: [{ type: 'user.custom_tool_result', tool_use_id: event.id, result }],
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Same shape works for `gh` CLI, local eval scripts, or anything else that needs host-side auth or binaries.
|
||||
|
||||
**Security note:** this does not expose a public endpoint. `agent.custom_tool_use` arrives on the SSE stream your orchestrator already holds open with your Anthropic API key, and `user.custom_tool_result` goes back via `events.send()` under the same key. Your orchestrator is a client, not a server — nothing unauthenticated is listening.
|
||||
|
||||
**Do not embed API keys in the system prompt or user messages as a workaround.** Prompts and messages are stored in the session's event history, returned by `events.list()`, and included in compaction summaries — a secret placed there is durably persisted and readable via the API for the life of the session.
|
||||
@@ -0,0 +1,218 @@
|
||||
# Managed Agents — Core Concepts
|
||||
|
||||
## Architecture
|
||||
|
||||
Managed Agents is built around four core concepts:
|
||||
|
||||
| Concept | Endpoint | What it is |
|
||||
|---|---|---|
|
||||
| **Agent** | `/v1/agents` | A persisted, versioned object defining the agent's capabilities and persona: model, system prompt, tools, MCP servers, skills. **Must be created before starting a session.** See the Agents section below. |
|
||||
| **Session** | `/v1/sessions` | A stateful interaction with an agent. References a pre-created agent by ID + an environment + initial instructions. Produces an event stream. |
|
||||
| **Environment** | `/v1/environments` | A template defining the configuration for container provisioning. |
|
||||
| **Container** | N/A | An isolated compute instance where the agent's **tools** execute (bash, file ops, code). The agent loop does not run here — it runs on Anthropic's orchestration layer and acts on the container via tool calls. |
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Anthropic orchestration layer │
|
||||
Agent (config) ───────▶│ (agent loop: Claude + tool calls) │
|
||||
└──────────────┬──────────────────────┘
|
||||
│ tool calls
|
||||
▼
|
||||
Environment (template) ──▶ Container (tool execution workspace)
|
||||
│
|
||||
Session ─┤
|
||||
├── Resources (files, repos — mounted at startup)
|
||||
├── Vault IDs (MCP credential references)
|
||||
└── Conversation (event stream in/out)
|
||||
```
|
||||
|
||||
> **Agent creation is a prerequisite.** Sessions reference a pre-created agent by ID — `model`/`system`/`tools` live on the agent object, never on the session. Every flow starts with `POST /v1/agents`.
|
||||
|
||||
---
|
||||
|
||||
## Session Lifecycle
|
||||
|
||||
```
|
||||
rescheduling → running ↔ idle → terminated
|
||||
```
|
||||
|
||||
| Status | Description |
|
||||
| -------------- | ------------------------------------------------------------------ |
|
||||
| `idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. The `stop_reason` attached contains more information about why the Agent has stopped working. |
|
||||
| `running` | Session has starting running, and the Agent is actively doing work. |
|
||||
| `rescheduling` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. |
|
||||
| `terminated` | Session has terminated, entering an irreversible and unusable state. |
|
||||
|
||||
- Events can be sent when the session is `running` or `idle`. Messages are queued and processed in order.
|
||||
- The agent transitions `idle → running` when it receives a new event, then back to `idle` when done.
|
||||
- Errors surface as `session.error` events in the stream, not as a status value.
|
||||
|
||||
### Built-in session features
|
||||
|
||||
- **Context compaction** — if you approach max context, the API automatically condenses session history to keep the interaction going
|
||||
- **Prompt caching** — historical repeated tokens are cached, reducing processing time and cost
|
||||
- **Extended thinking** — on by default, returned as `agent.thinking` events
|
||||
|
||||
### Session operations
|
||||
|
||||
| Operation | Notes |
|
||||
|---|---|
|
||||
| List / fetch | Paginated list or single resource by ID |
|
||||
| Update | Only `title` is updatable |
|
||||
| Archive | Session becomes **read-only**. Not reversible. |
|
||||
| Delete | Permanently deletes session, event history, container, and checkpoints. |
|
||||
|
||||
---
|
||||
|
||||
## Sessions
|
||||
|
||||
A session is a running agent instance inside an environment.
|
||||
|
||||
### Session Object
|
||||
|
||||
Key fields returned by the API:
|
||||
|
||||
| Field | Type | Description |
|
||||
| --------------- | -------- | --------------------------------------------------- |
|
||||
| `type` | string | Always `"session"` |
|
||||
| `id` | string | Unique session ID |
|
||||
| `title` | string | Human-readable title |
|
||||
| `status` | string | `idle`, `running`, `rescheduling`, `terminated` |
|
||||
| `created_at` | string | ISO 8601 timestamp |
|
||||
| `updated_at` | string | ISO 8601 timestamp |
|
||||
| `archived_at` | string | ISO 8601 timestamp (nullable) |
|
||||
| `environment_id` | string | Environment ID |
|
||||
| `agent` | object | Agent configuration |
|
||||
| `resources` | array | Attached files and repos |
|
||||
| `metadata` | object | User-provided key-value pairs (max 8 keys) |
|
||||
| `usage` | object | Token usage statistics |
|
||||
|
||||
### Creating a session
|
||||
|
||||
**A session is meaningless without an agent.** Sessions reference a pre-created agent by ID. Create the agent first via `agents.create()`, then reference it:
|
||||
|
||||
```ts
|
||||
// 1. Create the agent (reusable, versioned)
|
||||
const agent = await client.beta.agents.create(
|
||||
{
|
||||
name: "Coding Assistant",
|
||||
model: "claude-opus-4-7",
|
||||
system: "You are a helpful coding agent.",
|
||||
tools: [{ type: "agent_toolset_20260401"}],
|
||||
},
|
||||
);
|
||||
|
||||
// 2. Start a session that references it
|
||||
const session = await client.beta.sessions.create(
|
||||
{
|
||||
agent: agent.id, // string shorthand → latest version. Or: { type: "agent", id: agent.id, version: agent.version }
|
||||
environment_id: environmentId,
|
||||
title: "Hello World Session",
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
**Session creation parameters:**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
| --------------- | -------- | -------- | ---------------------------------------------- |
|
||||
| `agent` | string or object | **Yes** | String shorthand `"agent_abc123"` (latest version) or `{type: "agent", id, version}` |
|
||||
| `environment_id`| string | **Yes** | Environment ID |
|
||||
| `title` | string | No | Human-readable name (appears in logs/dashboards) |
|
||||
| `resources` | array | No | Files or GitHub repos, mounted to the container at startup |
|
||||
| `vault_ids` | array | No | Vault IDs (`vlt_*`) — MCP credentials with auto-refresh. See `shared/managed-agents-tools.md` → Vaults. |
|
||||
| `metadata` | object | No | User-provided key-value pairs |
|
||||
|
||||
**Agent configuration fields** (passed to `agents.create()`, not `sessions.create()`):
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
| ------------- | -------- | -------- | ---------------------------------------------- |
|
||||
| `name` | string | **Yes** | Human-readable name (1-256 chars) |
|
||||
| `model` | string or object | **Yes** | Claude model ID (bare string, or `{id, speed}` object). All Claude 4.5+ models supported. |
|
||||
| `system` | string | No | System prompt — defines the agent's behavior (up to 100K chars) |
|
||||
| `tools` | array | No | Encompasses three kinds: (1) pre-built Claude Agent tools (`agent_toolset_20260401`), (2) MCP tools (`mcp_toolset`), and (3) custom client-side tools. Max 128. |
|
||||
| `mcp_servers` | array | No | MCP server connections — standardized third-party capabilities (e.g. GitHub, Asana). Max 20, unique names. See `shared/managed-agents-tools.md` → MCP Servers. |
|
||||
| `skills` | array | No | Customized "best-practices" context with progressive disclosure. Max 64. See `shared/managed-agents-tools.md` → Skills. |
|
||||
| `description` | string | No | Description of the agent (up to 2048 chars) |
|
||||
| `metadata` | object | No | Arbitrary key-value pairs (max 16, keys ≤64 chars, values ≤512 chars) |
|
||||
|
||||
---
|
||||
|
||||
## Agents
|
||||
|
||||
**This is where every Managed Agents flow begins.** The agent object is a persisted, versioned configuration — you create it once, then reference it by ID every time you start a session. No agent → no session.
|
||||
|
||||
### Agent Object
|
||||
|
||||
The API is **flat** — `model`, `system`, `tools` etc. are top-level fields, not wrapped in an `agent:{}` sub-object.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
| ------------------ | -------- | -------- | -------------------------------------------------- |
|
||||
| `name` | string | Yes | Human-readable name |
|
||||
| `model` | string | Yes | Claude model ID |
|
||||
| `system` | string | No | System prompt |
|
||||
| `tools` | array | No | Agent toolset / MCP toolset / custom tools |
|
||||
| `mcp_servers` | array | No | MCP server connections |
|
||||
| `skills` | array | No | Skill references (max 64) |
|
||||
| `description` | string | No | Description of the agent |
|
||||
| `metadata` | object | No | Arbitrary key-value pairs |
|
||||
|
||||
### Lifecycle: create once, run many, update in place
|
||||
|
||||
The agent is a **persistent resource**, not a per-run parameter. The intended pattern:
|
||||
|
||||
```
|
||||
┌─ setup (once) ─────────┐ ┌─ runtime (every invocation) ─┐
|
||||
│ agents.create() │ │ sessions.create( │
|
||||
│ → store agent_id │ ──→ │ agent={type:..., id: ID} │
|
||||
│ in config/env/db │ │ ) │
|
||||
└────────────────────────┘ └──────────────────────────────┘
|
||||
```
|
||||
|
||||
**Anti-pattern:** calling `agents.create()` at the top of every script run. This accumulates orphaned agent objects, pays create latency on every invocation, and defeats the versioning model. If you see `agents.create()` in a function that's called per-request or per-cron-tick, that's wrong — hoist it to one-time setup and persist the ID.
|
||||
|
||||
### Versioning
|
||||
|
||||
Each `POST /v1/agents/{id}` (update) creates a new immutable version (numeric timestamp, e.g. `1772585501101368014`). The agent's history is append-only — you can't edit a past version.
|
||||
|
||||
**Why version:**
|
||||
- **Reproducibility** — pin a session to a known-good config: `{type: "agent", id, version: 3}`
|
||||
- **Safe iteration** — update the agent without breaking sessions already running on the old version
|
||||
- **Rollback** — if a new system prompt regresses, pin new sessions back to the prior version while you debug
|
||||
|
||||
**`version` is optional.** Omit it (or use the string shorthand `agent="agent_abc123"`) to get the latest version at session-creation time. Pass it explicitly (`{type: "agent", id, version: N}`) to pin for reproducibility.
|
||||
|
||||
**Getting the version to pin:** `agents.create()` and `agents.update()` both return `version` in the response. Store it alongside `agent_id`. To fetch the current latest for an existing agent: `GET /v1/agents/{id}` → `.version`.
|
||||
|
||||
**When to update vs create new:** Update (`POST /v1/agents/{id}`) when it's conceptually the same agent with tweaked behavior (better prompt, extra tool). Create a new agent when it's a different persona/purpose. Rule of thumb: if you'd give it the same `name`, update.
|
||||
|
||||
### Agent Endpoints
|
||||
|
||||
| Operation | Method | Path |
|
||||
| ---------------- | -------- | ------------------------------------- |
|
||||
| Create | `POST` | `/v1/agents` |
|
||||
| List | `GET` | `/v1/agents` |
|
||||
| Get | `GET` | `/v1/agents/{id}` |
|
||||
| Update | `POST` | `/v1/agents/{id}` |
|
||||
| Archive | `POST` | `/v1/agents/{id}/archive` |
|
||||
|
||||
> ⚠️ **Archive is permanent.** Archiving makes the agent read-only: existing sessions continue to run, but **new sessions cannot reference it**, and there is no unarchive. Since agents have no `delete`, this is the terminal lifecycle state. Never archive a production agent as routine cleanup — confirm with the user first.
|
||||
|
||||
### Using an Agent in a Session
|
||||
|
||||
Reference the agent by string ID (latest version) or by object with an explicit version:
|
||||
|
||||
```python
|
||||
# String shorthand — uses the agent's latest version
|
||||
session = client.beta.sessions.create(
|
||||
agent=agent.id,
|
||||
environment_id=environment_id,
|
||||
)
|
||||
|
||||
# Or pin to a specific version (int)
|
||||
session = client.beta.sessions.create(
|
||||
agent={"type": "agent", "id": agent.id, "version": agent.version},
|
||||
environment_id=environment_id,
|
||||
)
|
||||
```
|
||||
|
||||
@@ -0,0 +1,212 @@
|
||||
# Managed Agents — Environments & Resources
|
||||
|
||||
## Environments
|
||||
|
||||
Creating a session requires an `environment_id`. Environments are **reusable configuration templates** for spinning up containers in Anthropic's infrastructure — you might create different environments for different use cases (e.g. data visualization vs web development, with different package sets). Anthropic handles scaling, container lifecycle, and work orchestration.
|
||||
|
||||
**Environment names must be unique.** Creating an environment with an existing name returns 409.
|
||||
|
||||
### Networking
|
||||
|
||||
| Network Policy | Description |
|
||||
| ------------------------------- | ------------------------------------------------------------- |
|
||||
| `unrestricted` | Full egress (except legal blocklist) |
|
||||
| `package_managers_and_custom` | Package managers + custom `allowed_hosts` |
|
||||
|
||||
```json
|
||||
{
|
||||
"networking": {
|
||||
"type": "package_managers_and_custom",
|
||||
"allowed_hosts": ["api.example.com"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**MCP caveat:** If using restricted networking, make sure `allowed_hosts` includes your MCP server domains. Otherwise the container can't reach them and tools silently fail.
|
||||
|
||||
### Creating an environment
|
||||
|
||||
The SDK adds `managed-agents-2026-04-01` automatically. TypeScript:
|
||||
|
||||
```ts
|
||||
const env = await client.beta.environments.create({
|
||||
name: "my_env",
|
||||
config: {
|
||||
type: "cloud",
|
||||
networking: { type: "unrestricted" },
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Environment CRUD
|
||||
|
||||
| Operation | Method | Path | Notes |
|
||||
| ---------------- | -------- | ------------------------------------------ | ----- |
|
||||
| Create | `POST` | `/v1/environments` | |
|
||||
| List | `GET` | `/v1/environments` | Paginated (`limit`, `after_id`, `before_id`) |
|
||||
| Get | `GET` | `/v1/environments/{id}` | |
|
||||
| Update | `POST` | `/v1/environments/{id}` | Changes apply only to **new** containers; existing sessions keep their original config |
|
||||
| Delete | `DELETE` | `/v1/environments/{id}` | Returns 204. |
|
||||
| Archive | `POST` | `/v1/environments/{id}/archive` | Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive — terminal state. |
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
Attach files and GitHub repositories to a session. **Session creation blocks until all resources are mounted** — the container won't go `running` until every file and repo is in place. Max **999 file resources** per session. Multiple GitHub repositories per session are supported.
|
||||
|
||||
### File Uploads (input — host → agent)
|
||||
|
||||
Upload a file first via the Files API, then reference by `file_id` + `mount_path`:
|
||||
|
||||
```ts
|
||||
// 1. Upload
|
||||
const file = await client.beta.files.upload({
|
||||
file: fs.createReadStream("data.csv"),
|
||||
purpose: "agent",
|
||||
});
|
||||
|
||||
// 2. Attach as a session resource
|
||||
const session = await client.beta.sessions.create({
|
||||
agent: agent.id,
|
||||
environment_id: envId,
|
||||
resources: [
|
||||
{ type: "file", file_id: file.id, mount_path: "/workspace/data.csv" }
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
**`mount_path` is required** and must be absolute. Parent directories are created automatically. Agent working directory defaults to `/workspace`. Files are mounted read-only — the agent writes modified versions to new paths.
|
||||
|
||||
### Session outputs (output — agent → host)
|
||||
|
||||
The agent can write files to `/mnt/session/outputs/` during a session. These are automatically captured by the Files API and can be listed and downloaded afterwards:
|
||||
|
||||
```ts
|
||||
// After the turn completes, list output files scoped to this session:
|
||||
for await (const f of client.beta.files.list({
|
||||
scope_id: session.id,
|
||||
betas: ["managed-agents-2026-04-01"],
|
||||
})) {
|
||||
console.log(f.filename, f.size_bytes);
|
||||
const resp = await client.beta.files.download(f.id);
|
||||
const text = await resp.text();
|
||||
}
|
||||
```
|
||||
|
||||
**Requirements:**
|
||||
- The `write` tool (or `bash`) must be enabled for the agent to create output files.
|
||||
- Session-scoped `files.list` / `files.download` captures outputs written to `/mnt/session/outputs/`.
|
||||
- The filter parameter is **`scope_id`** (REST query param `?scope_id=<session_id>`). The SDK's files resource auto-adds only the `files-api-2025-04-14` header, so pass `betas: ["managed-agents-2026-04-01"]` explicitly (or both headers on raw HTTP) — without it the API may reject `scope_id` as an unknown field. Requires `@anthropic-ai/sdk` ≥ 0.88.0 / `anthropic` (Python) ≥ 0.92.0 — older versions don't type `scope_id`. The `ant` CLI does **not** expose this flag yet; use the SDK or curl.
|
||||
- Pass the session ID returned by `sessions.create()` verbatim (e.g. `sesn_011CZx...`) — the API validates the prefix.
|
||||
- There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if empty.
|
||||
|
||||
> **Fallback when `scope_id` filtering is unavailable** (older SDK, or endpoint returns an error): send a follow-up `user.message` asking the agent to `read` each file under `/mnt/session/outputs/` and return the contents. The agent streams the file bodies back as `agent.message` text. This works for text files only and costs output tokens — use it to unblock, not as the primary path.
|
||||
|
||||
This gives you a bidirectional file bridge: upload reference data in, download agent artifacts out.
|
||||
|
||||
### GitHub Repositories
|
||||
|
||||
Clones a GitHub repository into the session container during initialization, before the agent begins execution. The agent can read, edit, commit, and push via `bash` (`git`). Multiple repositories per session are supported — add one `resources` entry per repo. Repositories are cached, so future sessions that use the same repository start faster.
|
||||
|
||||
Repositories are attached for the lifetime of the session — to change which repositories are mounted, create a new session. You **can** rotate a repository's `authorization_token` on a running session via `client.beta.sessions.resources.update(resource_id, {session_id, authorization_token})`; the resource `id` is returned at session creation and by `resources.list()`.
|
||||
|
||||
**Fields:**
|
||||
|
||||
| Field | Required | Notes |
|
||||
|---|---|---|
|
||||
| `type` | ✅ | `"github_repository"` |
|
||||
| `url` | ✅ | The GitHub repository URL |
|
||||
| `authorization_token` | ✅ | GitHub Personal Access Token with repository access. **Never echoed in API responses.** |
|
||||
| `mount_path` | ❌ | Path where the repository will be cloned. Defaults to `/workspace/<repo-name>`. |
|
||||
| `checkout` | ❌ | `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Defaults to the repo's default branch. |
|
||||
|
||||
**Token permission levels** (fine-grained PATs):
|
||||
- `Contents: Read` — clone only
|
||||
- `Contents: Read and write` — push changes and create pull requests
|
||||
|
||||
**How auth works:** `authorization_token` is never placed inside the container. `git pull` / `git push` and GitHub REST calls against the attached repository are routed through an Anthropic-side git proxy that injects the token after the request leaves the sandbox. Code running in the container — including anything the agent writes — cannot read or exfiltrate it.
|
||||
|
||||
> ‼️ **To generate pull requests** you also need GitHub **MCP server** access — the `github_repository` resource gives filesystem + git access only. See `shared/managed-agents-tools.md` → MCP Servers. The PR workflow is: edit files in the mounted repo → push branch via `bash` (authenticated via the git proxy using `authorization_token`) → create PR via the MCP `create_pull_request` tool (authenticated via the vault).
|
||||
|
||||
**TypeScript:**
|
||||
|
||||
```ts
|
||||
// 1. Create the agent — declare GitHub MCP (no auth here)
|
||||
const agent = await client.beta.agents.create(
|
||||
{
|
||||
name: 'GitHub Agent',
|
||||
model: 'claude-opus-4-7',
|
||||
mcp_servers: [
|
||||
{ type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/' },
|
||||
],
|
||||
tools: [
|
||||
{ type: 'agent_toolset_20260401', default_config: { enabled: true } },
|
||||
{ type: 'mcp_toolset', mcp_server_name: 'github' },
|
||||
],
|
||||
},
|
||||
);
|
||||
|
||||
// 2. Start a session — attach vault for MCP auth + mount the repo
|
||||
const session = await client.beta.sessions.create({
|
||||
agent: agent.id,
|
||||
environment_id: envId,
|
||||
vault_ids: [vaultId], // vault contains the GitHub MCP OAuth credential
|
||||
resources: [
|
||||
{
|
||||
type: 'github_repository',
|
||||
url: 'https://github.com/owner/repo',
|
||||
authorization_token: process.env.GITHUB_TOKEN, // repo clone token (≠ MCP auth)
|
||||
checkout: { type: 'branch', name: 'main' },
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
**Python:**
|
||||
|
||||
```python
|
||||
import os
|
||||
|
||||
agent = client.beta.agents.create(
|
||||
name="GitHub Agent",
|
||||
model="claude-opus-4-7",
|
||||
mcp_servers=[{
|
||||
"type": "url",
|
||||
"name": "github",
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
}],
|
||||
tools=[
|
||||
{"type": "agent_toolset_20260401", "default_config": {"enabled": True}},
|
||||
{"type": "mcp_toolset", "mcp_server_name": "github"},
|
||||
],
|
||||
)
|
||||
|
||||
session = client.beta.sessions.create(
|
||||
agent=agent.id,
|
||||
environment_id=env_id,
|
||||
vault_ids=[vault_id], # vault contains the GitHub MCP OAuth credential
|
||||
resources=[{
|
||||
"type": "github_repository",
|
||||
"url": "https://github.com/owner/repo",
|
||||
"authorization_token": os.environ["GITHUB_TOKEN"], # repo clone token (≠ MCP auth)
|
||||
"checkout": {"type": "branch", "name": "main"},
|
||||
}],
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Files API
|
||||
|
||||
Upload and manage files for use as session resources, and download files the agent wrote to `/mnt/session/outputs/`.
|
||||
|
||||
| Operation | Method | Path | SDK |
|
||||
| ---------------- | -------- | ------------------------------------- | --- |
|
||||
| Upload | `POST` | `/v1/files` | `client.beta.files.upload({ file })` |
|
||||
| List | `GET` | `/v1/files?scope_id=...` | `client.beta.files.list({ scope_id, betas: ["managed-agents-2026-04-01"] })` |
|
||||
| Get Metadata | `GET` | `/v1/files/{id}` | `client.beta.files.retrieveMetadata(id)` |
|
||||
| Download | `GET` | `/v1/files/{id}/content` | `client.beta.files.download(id)` → `Response` |
|
||||
| Delete | `DELETE` | `/v1/files/{id}` | `client.beta.files.delete(id)` |
|
||||
|
||||
The `scope_id` filter on List scopes the results to files written to `/mnt/session/outputs/` by that session. Without the filter, you get all files uploaded to your account.
|
||||
@@ -0,0 +1,189 @@
|
||||
# Managed Agents — Events & Steering
|
||||
|
||||
## Events
|
||||
|
||||
### Sending Events
|
||||
|
||||
Send events to a session via `POST /v1/sessions/{id}/events`.
|
||||
|
||||
| Event Type | When to Send |
|
||||
| ------------------------- | --------------------------------------------------- |
|
||||
| `user.message` | Send a user message |
|
||||
| `user.interrupt` | Interrupt the agent while it's running |
|
||||
| `user.tool_confirmation` | Approve/deny a tool call (when `always_ask` policy) |
|
||||
| `user.custom_tool_result` | Provide result for a custom tool call |
|
||||
|
||||
### Receiving Events
|
||||
|
||||
Two methods:
|
||||
|
||||
1. **Streaming (SSE)**: `GET /v1/sessions/{id}/events/stream` — real-time Server-Sent Events. **Long-lived** — the server sends periodic heartbeats to keep the connection alive.
|
||||
2. **Polling**: `GET /v1/sessions/{id}/events` — paginated event list (query params: `limit` default 1000, `page`). **Returns immediately** — this is a plain paginated GET, not a long-poll.
|
||||
|
||||
All received events carry `id`, `type`, and `processed_at` (ISO 8601; `null` if not yet processed by the agent).
|
||||
|
||||
> ⚠️ **Robust polling (raw HTTP).** If you bypass the SDK and roll your own poll loop, don't rely on `requests` or `httpx` timeouts as wall-clock caps — they're **per-chunk** read timeouts, reset every time a byte arrives. A trickling response (heartbeats, a wedged chunked-encoding body, a misbehaving proxy) can keep the call blocked indefinitely even with `timeout=(5, 60)` or `httpx.Timeout(120)`. Neither library has a "total wall-clock" timeout built in. For a hard deadline: track `time.monotonic()` at the loop level and break/cancel if a single request exceeds your budget (e.g. via a watchdog thread, or `asyncio.wait_for()` around async httpx). **Prefer the SDK** — `client.beta.sessions.events.stream()` and `client.beta.sessions.events.list()` handle timeout + retry sanely.
|
||||
>
|
||||
> If `GET /v1/sessions/{id}/events` (paginated) ever hangs after headers, you've likely hit `GET /v1/sessions/{id}/events` by mistake or a server-side stall — report it; don't treat it as a client-config problem.
|
||||
|
||||
### Event Types (Received)
|
||||
|
||||
Event types use dot notation, grouped by namespace:
|
||||
|
||||
| Event Type | Description |
|
||||
| --- | --- |
|
||||
| `agent.message` | Agent text output |
|
||||
| `agent.thinking` | Extended thinking blocks |
|
||||
| `agent.tool_use` | Agent used a built-in tool (`agent_toolset_20260401`) |
|
||||
| `agent.tool_result` | Result from a built-in tool |
|
||||
| `agent.mcp_tool_use` | Agent used an MCP tool |
|
||||
| `agent.mcp_tool_result` | Result from an MCP tool |
|
||||
| `agent.custom_tool_use` | Agent invoked a custom tool — session goes idle, you respond with `user.custom_tool_result` |
|
||||
| `agent.thread_context_compacted` | Conversation context was compacted |
|
||||
| `session.status_idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. The `stop_reason` attached contains more information about why the Agent has stopped working. |
|
||||
| `session.status_running` | Session has starting running, and the Agent is actively doing work. |
|
||||
| `session.status_rescheduled` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. |
|
||||
| `session.status_terminated` | Session has terminated, entering an irreversible and unusable state. |
|
||||
| `session.error` | Error occurred during processing |
|
||||
| `span.model_request_start` | Model inference started |
|
||||
| `span.model_request_end` | Model inference completed |
|
||||
|
||||
The stream also echoes back user-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`).
|
||||
|
||||
---
|
||||
|
||||
## Steering Patterns
|
||||
|
||||
Practical patterns for driving a session via the events surface.
|
||||
|
||||
### Stream-first ordering
|
||||
|
||||
**Open the stream before sending events.** The stream only delivers events that occur *after* it's opened — it does not replay current state or historical events. If you send a message first and open the stream second, early events (including fast status transitions) arrive buffered in a single batch and you lose the ability to react to them in real time.
|
||||
|
||||
```ts
|
||||
// ✅ Correct — stream and send concurrently
|
||||
const [response] = await Promise.all([
|
||||
streamEvents(sessionId), // opens SSE connection
|
||||
sendMessage(sessionId, text),
|
||||
]);
|
||||
|
||||
// ❌ Wrong — events before stream opens arrive as a single buffered batch
|
||||
await sendMessage(sessionId, text);
|
||||
const response = await streamEvents(sessionId);
|
||||
```
|
||||
|
||||
**For full history,** use `GET /v1/sessions/{id}/events` (paginated list) — the stream only gives you live events from connection onward.
|
||||
|
||||
### Reconnecting after a dropped stream
|
||||
|
||||
**The SSE stream has no replay.** If your connection drops (httpx read timeout, network blip) and you reconnect, you only get events emitted *after* reconnection. Any events emitted during the gap are lost from the stream.
|
||||
|
||||
**The consolidation pattern:** on every (re)connect, overlap the stream with a history fetch and dedupe by event ID:
|
||||
|
||||
```python
|
||||
def connect_with_consolidation(client, session_id):
|
||||
# 1. Open the SSE stream first
|
||||
stream = client.beta.sessions.events.stream(session_id=session_id)
|
||||
|
||||
# 2. Fetch history to cover any gap
|
||||
history = client.beta.sessions.events.list(
|
||||
session_id=session_id,
|
||||
)
|
||||
|
||||
# 3. Yield history first, then stream — dedupe by event.id
|
||||
seen = set()
|
||||
for ev in history.data:
|
||||
seen.add(ev.id)
|
||||
yield ev
|
||||
for ev in stream:
|
||||
if ev.id not in seen:
|
||||
seen.add(ev.id)
|
||||
yield ev
|
||||
```
|
||||
|
||||
### Message queuing
|
||||
|
||||
**You don't have to wait for a response before sending the next message.** User events are queued server-side and processed in order. This is useful for chat bridges where the user sends rapid follow-ups:
|
||||
|
||||
```ts
|
||||
// All three go into one session; agent processes them in order
|
||||
await sendMessage(sessionId, "Summarize the README");
|
||||
await sendMessage(sessionId, "Actually also check the CONTRIBUTING guide");
|
||||
await sendMessage(sessionId, "And compare the two");
|
||||
// Stream once — agent responds to all three as a coherent turn
|
||||
```
|
||||
|
||||
Events can be sent up to the Session at any time. There is no need to wait on a specific session status to enqueue new events via `client.beta.sessions.events.send()`
|
||||
|
||||
### Interrupt
|
||||
|
||||
An `interrupt` event **jumps the queue** (ahead of any pending user messages) and forces the session into `idle`. Use this for "stop" / "nevermind" / "cancel" commands:
|
||||
|
||||
```ts
|
||||
await client.beta.sessions.events.send(sessionId, {
|
||||
events: [{ type: 'interrupt' }],
|
||||
});
|
||||
```
|
||||
|
||||
The agent stops mid-task. It does not see the interrupt as a message — it just halts. Send a follow-up `user` event to explain what to do instead.
|
||||
|
||||
> **Note**: Interrupt events may have empty IDs in the current implementation. When troubleshooting, use the `processed_at` timestamp along with surrounding event IDs.
|
||||
|
||||
### Event payloads
|
||||
|
||||
some events carry useful metadata beyond the status change itself:
|
||||
|
||||
`session.status_idle` — includes a `stop_reason` field which elaborates on why the session stopped and what type of further action is required by the user.
|
||||
```json
|
||||
{
|
||||
"id": "sevt_456",
|
||||
"processed_at": "2026-04-07T04:27:43.197Z",
|
||||
"stop_reason": {
|
||||
"event_ids": [
|
||||
"sevt_123"
|
||||
],
|
||||
"type": "requires_action"
|
||||
},
|
||||
"type": "status_idle"
|
||||
}
|
||||
```
|
||||
|
||||
`span.model_request_end` contains a `model_usage` field for cost tracking and efficiency analysis:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "span.model_request_end",
|
||||
"id": "sevt_456",
|
||||
"is_error": false,
|
||||
"model_request_start_id": "sevt_123",
|
||||
"model_usage": {
|
||||
"cache_creation_input_tokens": 0,
|
||||
"cache_read_input_tokens": 6656,
|
||||
"input_tokens": 3571,
|
||||
"output_tokens": 727
|
||||
},
|
||||
"processed_at": "2026-04-07T04:11:32.189Z"
|
||||
}
|
||||
```
|
||||
|
||||
**`agent.thread_context_compacted`** — emitted when the conversation history was summarized to fit context. Includes `pre_compaction_tokens` so you know how much was squeezed:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "sevt_abc123",
|
||||
"processed_at": "2026-03-24T14:05:15.787Z",
|
||||
"type": "agent.thread_context_compacted"
|
||||
}
|
||||
```
|
||||
|
||||
### Archive
|
||||
|
||||
When done with a session, archive it to free resources:
|
||||
|
||||
```ts
|
||||
await client.beta.sessions.archive(sessionId);
|
||||
```
|
||||
|
||||
> Archiving a **session** is routine cleanup — sessions are per-run and disposable. **Do not generalize this to agents or environments**: those are persistent, reusable resources, and archiving them is permanent (no unarchive; new sessions cannot reference them). See `shared/managed-agents-overview.md` → Common Pitfalls.
|
||||
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
# Managed Agents — Onboarding Flow
|
||||
|
||||
> **Invoked via `/claude-api managed-agents-onboard`?** You're in the right place. Run the interview below — don't summarize it back to the user, ask the questions.
|
||||
|
||||
Use this when a user wants to set up a Managed Agent from scratch. Three steps: **branch on know-vs-explore → configure the template → set up the session**. End by emitting working code.
|
||||
|
||||
> Read `shared/managed-agents-core.md` alongside this — it has full detail for each knob. This doc is the interview script, not the reference.
|
||||
|
||||
---
|
||||
|
||||
Claude Managed Agents is a hosted agent: Anthropic runs the agent loop on its orchestration layer and provisions a sandboxed container per session where the agent's tools execute. You supply the agent config and the environment config; the harness — event stream, sandbox orchestration, prompt caching, context compaction, and extended thinking — is handled for you.
|
||||
|
||||
**What you supply:**
|
||||
- **An agent config** — tools, skills, model, system prompt. Reusable and versioned.
|
||||
- **An environment config** — the sandbox your agent's tools execute in (networking, packages). Reusable across agents.
|
||||
|
||||
Each run of the agent is a **session**.
|
||||
|
||||
---
|
||||
|
||||
## 1. Know or explore?
|
||||
|
||||
Ask the user:
|
||||
|
||||
> Do you already know the agent you want to build, or would you like to explore some common patterns first?
|
||||
|
||||
### Explore path — show the patterns
|
||||
|
||||
Four shapes, same runtime code path (`sessions.create()` → `sessions.events.send()` → stream). Only the trigger and sink differ.
|
||||
|
||||
| Pattern | Trigger | Example |
|
||||
|---|---|---|
|
||||
| Event-triggered | Webhook | GitHub PR push → CMA (GitHub tool) → Slack | # <------ MC maybe delete?
|
||||
| Scheduled | Cron | Daily brief: browser + GitHub + Jira → CMA → Slack | # <------ MC maybe delete?
|
||||
| Fire-and-forget PR | Human | Slack slash-command → CMA (GitHub tool) → PR passing CI |
|
||||
| Research + dashboard | Human | Topic → CMA (web search + `frontend-design` skill) → HTML dashboard |
|
||||
|
||||
Ask which shape fits, then continue with the Know path using it as the reference.
|
||||
|
||||
### Know path — configure template
|
||||
|
||||
Three rounds. Batch the questions in each round; don't ask them one at a time.
|
||||
|
||||
**Round A — Tools.** Start here; it's the most concrete part. Three types; ask which the user wants (any combination):
|
||||
|
||||
| Type | What it is | How to guide |
|
||||
|---|---|---|
|
||||
| **Prebuilt Claude Agent tools** (`agent_toolset_20260401`) | Ready-to-use: `bash`, `read`, `write`, `edit`, `glob`, `grep`, `web_fetch`, `web_search`. Enable all at once, or individually via `enabled: true/false`. | Recommend enabling the full toolset. List the 8 tools so the user knows what they're getting. Full detail: `shared/managed-agents-tools.md` → Agent Toolset. |
|
||||
| **MCP tools** | Third-party integrations (GitHub, Linear, Asana, etc.) via `mcp_toolset`. Credentials live in a vault, not inline. | Ask which services. For each, walk through MCP server URL + vault credentials. Full detail: `shared/managed-agents-tools.md` → MCP Servers + Vaults. |
|
||||
| **Custom tools** | The user's own app handles these tool calls — agent fires `agent.custom_tool_use`, the app sends a result message back. | Ask for each tool: name, description, input schema. The app code that handles the event is *their* code — don't generate it. Full detail: `shared/managed-agents-tools.md` → Custom Tools. |
|
||||
|
||||
**Round B — Skills, files, and repos.** What the agent has on hand when it starts.
|
||||
|
||||
*Skills* — two types; both work the same way — Claude auto-uses them when relevant. Max 64 per agent.
|
||||
- [ ] **Pre-built Agent Skills**: `xlsx`, `docx`, `pptx`, `pdf`. Reference by name.
|
||||
- [ ] **Custom Skills**: skills uploaded to the user's org via the Skills API. Reference by `skill_id` + optional `version`. If the skill doesn't exist yet, walk the user through `POST /v1/skills` + `POST /v1/skills/{id}/versions` (beta header `skills-2025-10-02`). Full detail: `shared/managed-agents-tools.md` → Skills + Skills API.
|
||||
|
||||
*GitHub repositories* — any repos the agent needs on-disk? For each:
|
||||
- [ ] Repo URL (`https://github.com/org/repo`)
|
||||
- [ ] `authorization_token` (PAT or GitHub App token scoped to the repo)
|
||||
- [ ] Optional `mount_path` (defaults to `/workspace/<repo-name>`) and `checkout` (branch or SHA)
|
||||
|
||||
Emit as `resources: [{type: "github_repository", url, authorization_token, ...}]`. Full detail: `shared/managed-agents-environments.md` → GitHub Repositories.
|
||||
|
||||
> ‼️ **PR creation needs the GitHub MCP server too.** `github_repository` gives filesystem access only — to open PRs, also attach the GitHub MCP server in Round A and credential it via a vault. The workflow is: edit files in the mounted repo → push branch via `bash` → create PR via the MCP `create_pull_request` tool.
|
||||
|
||||
*Files* — any local files to seed the session with? For each:
|
||||
- [ ] Upload via the Files API → persist `file_id`
|
||||
- [ ] Choose a `mount_path` — absolute, e.g. `/workspace/data.csv` (parents auto-created; files mount read-only)
|
||||
|
||||
Emit as `resources: [{type: "file", file_id, mount_path}]`. Max 999 file resources. Agent working directory defaults to `/workspace`. Full detail: `shared/managed-agents-environments.md` → Files API.
|
||||
|
||||
**Round C — Environment + identity:**
|
||||
- [ ] Networking: unrestricted internet from the container, or lock egress to specific hosts? (If locked, MCP server domains must be in `allowed_hosts` or tools silently fail.)
|
||||
- [ ] Name?
|
||||
- [ ] Job (one or two sentences — becomes the system prompt)?
|
||||
- [ ] Model? (default `claude-opus-4-7`)
|
||||
|
||||
---
|
||||
|
||||
## 2. Set up the session
|
||||
|
||||
Per-run. Points at the agent + environment, attaches credentials, kicks off.
|
||||
|
||||
**Vault credentials** (if the agent declared MCP servers):
|
||||
- [ ] Existing vault, or create one? (`client.beta.vaults.create()` + `vaults.credentials.create()`)
|
||||
|
||||
Credentials are write-only, matched to MCP servers by URL, auto-refreshed. See `shared/managed-agents-tools.md` → Vaults.
|
||||
|
||||
**Kickoff:**
|
||||
- [ ] First message to the agent?
|
||||
|
||||
Session creation blocks until all resources mount. Open the event stream before sending the kickoff. Stream is SSE; break on `session.status_terminated`, or on `session.status_idle` with a terminal `stop_reason` — i.e. anything except `requires_action`, which fires transiently while the session waits on a tool confirmation or custom-tool result (see `shared/managed-agents-client-patterns.md` Pattern 5). Usage lands on `span.model_request_end`. Agent-written artifacts end up in `/mnt/session/outputs/` — download via `files.list({scope_id: session.id, betas: ["managed-agents-2026-04-01"]})`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Emit the code
|
||||
|
||||
Go straight from the last interview answer to the code — no preamble about the setup-vs-runtime split, no "the critical thing to internalize…", no lecture about `agents.create()` being one-time. The two-block structure below already shows that; don't narrate it. Generate **two clearly-separated blocks** per language detected (Python/TS/cURL — see SKILL.md → Language Detection):
|
||||
|
||||
**Block 1 — Setup (run once, store the IDs):**
|
||||
1. `environments.create()` → persist `env_id`
|
||||
2. `agents.create()` with everything from §Round A–C → persist `agent_id` and `agent_version`
|
||||
|
||||
Label: `# ONE-TIME SETUP — run once, save the IDs to config/.env`
|
||||
|
||||
**Block 2 — Runtime (run on every invocation):**
|
||||
1. Load `env_id` + `agent_id` from config/env
|
||||
2. `sessions.create(agent=AGENT_ID, environment_id=ENV_ID, resources=[...], vault_ids=[...])`
|
||||
3. Open stream, `events.send()` the kickoff, loop until `session.status_terminated` or `session.status_idle && stop_reason.type !== 'requires_action'` (see `shared/managed-agents-client-patterns.md` Pattern 5 for the full gate — do not break on bare `session.status_idle`)
|
||||
|
||||
> ⚠️ **Never emit `agents.create()` and `sessions.create()` in the same unguarded block.** That teaches the user to create a new agent on every run — the #1 anti-pattern. If they need a single script, wrap agent creation in `if not os.getenv("AGENT_ID"):`.
|
||||
|
||||
Pull exact syntax from `python/managed-agents/README.md`, `typescript/managed-agents/README.md`, or `curl/managed-agents.md`. Don't invent field names.
|
||||
@@ -0,0 +1,63 @@
|
||||
# Managed Agents — Overview
|
||||
|
||||
Managed Agents provisions a container per session as the agent's workspace. The agent loop runs on Anthropic's orchestration layer; the container is where the agent's *tools* execute — bash commands, file operations, code. You create a persisted **Agent** config (model, system prompt, tools, MCP servers, skills), then start **Sessions** that reference it. The session streams events back to you; you send user messages and tool results in.
|
||||
|
||||
## ⚠️ THE MANDATORY FLOW: Agent (once) → Session (every run)
|
||||
|
||||
**Why agents are separate objects: versioning.** An agent is a persisted, versioned config — every update creates a new immutable version, and sessions pin to a version at creation time. This lets you iterate on the agent (tweak the prompt, add a tool) without breaking sessions already running, roll back if a change regresses, and A/B test versions side-by-side. None of that works if you `agents.create()` fresh on every run.
|
||||
|
||||
Every session references a pre-created `/v1/agents` object. Create the agent once, store the ID, and reuse it across runs.
|
||||
|
||||
| Step | Call | Frequency |
|
||||
|---|---|---|
|
||||
| 1 | `POST /v1/agents` — `model`, `system`, `tools`, `mcp_servers`, `skills` live here | **ONCE.** Store `agent.id` **and** `agent.version`. |
|
||||
| 2 | `POST /v1/sessions` — `agent: "agent_abc123"` or `{type: "agent", id, version}` | **Every run.** String shorthand uses latest version. |
|
||||
|
||||
If you're about to write `sessions.create()` with `model`, `system`, or `tools` on the session body — **stop**. Those fields live on `agents.create()`. The session takes a *pointer* only.
|
||||
|
||||
**When generating code, separate setup from runtime.** `agents.create()` belongs in a setup script (or a guarded `if agent_id is None:` block), not at the top of the hot path. If the user's code calls `agents.create()` on every invocation, they're accumulating orphaned agents and paying the create latency for nothing. The correct shape is: create once → persist the ID (config file, env var, secrets manager) → every run loads the ID and calls `sessions.create()`.
|
||||
|
||||
**To change the agent's behavior, use `POST /v1/agents/{id}` — don't create a new one.** Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via `{type: "agent", id, version}`). See `shared/managed-agents-core.md` → Agents → Versioning.
|
||||
|
||||
## Beta Headers
|
||||
|
||||
Managed Agents is in beta. The SDK sets required beta headers automatically:
|
||||
|
||||
| Beta Header | What it enables |
|
||||
| ------------------------------ | ---------------------------------------------------- |
|
||||
| `managed-agents-2026-04-01` | Agents, Environments, Sessions, Events, Session Resources, Vaults, Credentials |
|
||||
| `skills-2025-10-02` | Skills API (for managing custom skill definitions) |
|
||||
| `files-api-2025-04-14` | Files API for file uploads |
|
||||
|
||||
**Which beta header goes where:** The SDK sets `managed-agents-2026-04-01` automatically on `client.beta.{agents,environments,sessions,vaults}.*` calls, and `files-api-2025-04-14` / `skills-2025-10-02` automatically on `client.beta.files.*` / `client.beta.skills.*` calls. You do NOT need to add the Skills or Files beta header when calling Managed Agents endpoints. **Exception — session-scoped file listing:** `client.beta.files.list({scope_id: session.id})` is a Files endpoint that takes a Managed Agents parameter, so it needs **both** headers. Pass `betas: ["managed-agents-2026-04-01"]` explicitly on that call (the SDK adds the Files header; you add the Managed Agents one). See `shared/managed-agents-environments.md` → Session outputs.
|
||||
|
||||
|
||||
## Reading Guide
|
||||
|
||||
| User wants to... | Read these files |
|
||||
| -------------------------------------- | ------------------------------------------------------- |
|
||||
| **Get started from scratch / "help me set up an agent"** | `shared/managed-agents-onboarding.md` — guided interview (WHERE→WHO→WHAT→WATCH), then emit code |
|
||||
| Understand how the API works | `shared/managed-agents-core.md` |
|
||||
| See the full endpoint reference | `shared/managed-agents-api-reference.md` |
|
||||
| **Create an agent** (required first step) | `shared/managed-agents-core.md` (Agents section) + language file |
|
||||
| Update/version an agent | `shared/managed-agents-core.md` (Agents → Versioning) — update, don't re-create |
|
||||
| Create a session | `shared/managed-agents-core.md` + `{lang}/managed-agents/README.md` |
|
||||
| Configure tools and permissions | `shared/managed-agents-tools.md` |
|
||||
| Set up MCP servers | `shared/managed-agents-tools.md` (MCP Servers section) |
|
||||
| Stream events / handle tool_use | `shared/managed-agents-events.md` + language file |
|
||||
| Set up environments | `shared/managed-agents-environments.md` + language file |
|
||||
| Upload files / attach repos | `shared/managed-agents-environments.md` (Resources) |
|
||||
| Store MCP credentials | `shared/managed-agents-tools.md` (Vaults section) |
|
||||
| Call a non-MCP API / CLI that needs a secret | `shared/managed-agents-client-patterns.md` Pattern 9 — no container env vars; vaults are MCP-only; keep the secret host-side via a custom tool |
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Agent FIRST, then session — NO EXCEPTIONS** — the session's `agent` field accepts **only** a string ID or `{type: "agent", id, version}`. `model`, `system`, `tools`, `mcp_servers`, `skills` are **top-level fields on `POST /v1/agents`**, never on `sessions.create()`. If the user hasn't created an agent, that is step zero of every example.
|
||||
- **Agent ONCE, not every run** — `agents.create()` is a setup step. Store the returned `agent_id` and reuse it; don't call `agents.create()` at the top of your hot path. If the agent's config needs to change, `POST /v1/agents/{id}` — each update creates a new version, and sessions can pin to a specific version for reproducibility.
|
||||
- **MCP auth goes through vaults** — the agent's `mcp_servers` array declares `{type, name, url}` only (no auth). Credentials live in vaults (`client.beta.vaults.credentials.create`) and attach to sessions via `vault_ids`. Anthropic auto-refreshes OAuth tokens using the stored refresh token.
|
||||
- **Stream to get events** — `GET /v1/sessions/{id}/events/stream` is the primary way to receive agent output in real-time.
|
||||
- **SSE stream has no replay — reconnect with consolidation** — if the stream drops while a `agent.tool_use`, `agent.mcp_tool_use`, or `agent.custom_tool_use` is pending resolution (`user.tool_confirmation` for the first two, `user.custom_tool_result` for the last one), the session deadlocks (client disconnects → session idles → reconnect happens → no client resolution happens). On every (re)connect: open stream with `GET /v1/sessions/{id}/events/stream` , fetch `GET /v1/sessions/{id}/events`, dedupe by event ID, then proceed. See `shared/managed-agents-events.md` → Reconnecting after a dropped stream.
|
||||
- **Don't trust HTTP-library timeouts as wall-clock caps** — `requests` `timeout=(c, r)` and `httpx.Timeout(n)` are *per-chunk* read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track `time.monotonic()` at the loop level and bail explicitly. Prefer the SDK's `sessions.events.stream()` / `session.events.list()` over hand-rolled HTTP. See `shared/managed-agents-events.md` → Receiving Events.
|
||||
- **Messages queue** — you can send events while the session is `running` or `idle`; they're processed in order. No need to wait for a response before sending the next message.
|
||||
- **Cloud environments only** — `config.type: "cloud"` is the only supported environment type.
|
||||
- **Archive is permanent on every resource** — archiving an agent, environment, session, vault, or credential makes it read-only with no unarchive. For agents and environments specifically, archived resources cannot be referenced by new sessions (existing sessions continue). Do not call `.archive()` on a production agent or environment as cleanup — **always confirm with the user before archiving**.
|
||||
@@ -0,0 +1,315 @@
|
||||
# Managed Agents — Tools & Skills
|
||||
|
||||
## Tools
|
||||
|
||||
### Server tools vs client tools
|
||||
|
||||
| Type | Who runs it | How it works |
|
||||
|---|---|---|
|
||||
| **Prebuilt Claude Agent tools** (`agent_toolset_20260401`) | Anthropic, on the session's container | File ops, bash, web search, etc. Enable all at once or configure individually with `enabled: true/false`. |
|
||||
| **MCP tools** (`mcp_toolset`) | Anthropic, on the session's container | Capabilities exposed by connected MCP servers. Grant access per-server via the toolset. |
|
||||
| **Custom tools** | **You** — your application handles the call and returns results | Agent emits a `agent.custom_tool_use` event, session goes `idle`, you send back a `user.custom_tool_result` event. |
|
||||
|
||||
**Recommendation:** Enable all prebuilt tools via `agent_toolset_20260401`, then disable individually as needed.
|
||||
|
||||
**Versioning:** The toolset is a versioned, static resource. When underlying tools change, a new toolset version is created (hence `_20260401`) so you always know exactly what you're getting.
|
||||
|
||||
### Agent Toolset
|
||||
|
||||
The `agent_toolset_20260401` provides these built-in tools:
|
||||
|
||||
| Tool | Description |
|
||||
| ---------------------- | ---------------------------------------- |
|
||||
| `bash` | Execute bash commands in a shell session |
|
||||
| `read` | Read a file from the local filesystem, including text, images, PDFs, and Jupyter notebooks |
|
||||
| `write` | Write a file to the local filesystem |
|
||||
| `edit` | Perform string replacement in a file |
|
||||
| `glob` | Fast file pattern matching using glob patterns |
|
||||
| `grep` | Text search using regex patterns |
|
||||
| `web_fetch` | Fetch content from a URL |
|
||||
| `web_search` | Search the web for information |
|
||||
|
||||
Enable the full toolset:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{ "type": "agent_toolset_20260401" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Per-Tool Configuration
|
||||
|
||||
Override defaults for individual tools. This example enables everything except bash:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{
|
||||
"type": "agent_toolset_20260401",
|
||||
"default_config": { "enabled": true },
|
||||
"configs": [
|
||||
{ "name": "bash", "enabled": false }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Required | Description |
|
||||
|---|---|---|
|
||||
| `type` | ✅ | `"agent_toolset_20260401"` |
|
||||
| `default_config` | ❌ | Applied to all tools. `{ "enabled": bool, "permission_policy": {...} }` |
|
||||
| `configs` | ❌ | Per-tool overrides: `[{ "name": "...", "enabled": bool, "permission_policy": {...} }]` |
|
||||
|
||||
### Permission Policies
|
||||
|
||||
Control when server-executed tools (agent toolset + MCP) run automatically vs wait for approval. Does not apply to custom tools.
|
||||
|
||||
| Policy | Behavior |
|
||||
|---|---|
|
||||
| `always_allow` | Tool executes automatically (default) |
|
||||
| `always_ask` | Session emits `session.status_idle` and pauses until you send a `tool_confirmation` event |
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "agent_toolset_20260401",
|
||||
"default_config": {
|
||||
"enabled": true,
|
||||
"permission_policy": { "type": "always_allow" }
|
||||
},
|
||||
"configs": [
|
||||
{ "name": "bash", "permission_policy": { "type": "always_ask" } }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Responding to `always_ask`:** Send a `user.tool_confirmation` event with `tool_use_id` from the triggering `agent_tool_use`/`mcp_tool_use` event:
|
||||
|
||||
```json
|
||||
{ "type": "tool_confirmation", "tool_use_id": "sevt_abc123", "result": "allow" }
|
||||
{ "type": "tool_confirmation", "tool_use_id": "sevt_def456", "result": "deny", "message": "Read .env.example instead" }
|
||||
```
|
||||
|
||||
The optional `message` on a deny is delivered to the agent so it can adjust its approach.
|
||||
|
||||
To enable only specific tools, flip the default off and opt-in per tool:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{
|
||||
"type": "agent_toolset_20260401",
|
||||
"default_config": { "enabled": false },
|
||||
"configs": [
|
||||
{ "name": "bash", "enabled": true },
|
||||
{ "name": "read", "enabled": true }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Tools (Client-Side)
|
||||
|
||||
Custom tools are executed by **your application**, not Anthropic. The flow:
|
||||
|
||||
1. Agent decides to use the tool → session emits a `agent.custom_tool_use` event with inputs
|
||||
2. Session goes `idle` waiting for you
|
||||
3. Your application executes the tool
|
||||
4. You send back a `user.custom_tool_result` event with the output
|
||||
5. Session resumes `running`
|
||||
|
||||
No permission policy needed — you're the one executing.
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{
|
||||
"type": "custom",
|
||||
"name": "get_weather",
|
||||
"description": "Fetch current weather for a city.",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"city": { "type": "string", "description": "City name" }
|
||||
},
|
||||
"required": ["city"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### MCP Servers
|
||||
|
||||
MCP (Model Context Protocol) servers expose standardized third-party capabilities (e.g. Asana, GitHub, Linear). **Configuration is split across agent and vault:**
|
||||
|
||||
1. **Agent creation** declares which servers to connect to (`type`, `name`, `url` — no auth). The agent's `mcp_servers` array has no auth field.
|
||||
2. **Vault** stores the OAuth credentials. Attach via `vault_ids` on session create.
|
||||
|
||||
This keeps secrets out of reusable agent definitions. Each vault credential is tied to one MCP server URL; Anthropic matches credentials to servers by URL.
|
||||
|
||||
**Agent side — declare servers (no auth):**
|
||||
|
||||
| Field | Required | Description |
|
||||
|---|---|---|
|
||||
| `type` | ✅ | `"url"` |
|
||||
| `name` | ✅ | Unique name — referenced by `mcp_toolset.mcp_server_name` |
|
||||
| `url` | ✅ | The MCP server's endpoint URL (Streamable HTTP transport) |
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp_servers": [
|
||||
{ "type": "url", "name": "linear", "url": "https://mcp.linear.app/mcp" }
|
||||
],
|
||||
"tools": [
|
||||
{ "type": "mcp_toolset", "mcp_server_name": "linear" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Session side — attach vault:**
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": "agent_abc123",
|
||||
"environment_id": "env_abc123",
|
||||
"vault_ids": ["vlt_abc123"]
|
||||
}
|
||||
```
|
||||
|
||||
> 💡 **Per-tool enablement (empirical):** `mcp_toolset` has been observed accepting `default_config: {enabled: false}` + `configs: [{name, enabled: true}]` for an allowlist pattern. The API ref shows only the minimal `{type, mcp_server_name}` form.
|
||||
|
||||
> ⚠️ **MCP auth tokens ≠ REST API tokens.** Hosted MCP servers (`mcp.notion.com`, `mcp.linear.app`, etc.) typically require **OAuth bearer tokens**, not the service's native API keys. A Notion `ntn_` integration token authenticates against Notion's REST API but will **not** work as a vault credential for the Notion MCP server. These are different auth systems.
|
||||
|
||||
### Vaults — the MCP credential store
|
||||
|
||||
**Vaults** store OAuth credentials (access token + refresh token) that Anthropic auto-refreshes on your behalf via standard OAuth 2.0 `refresh_token` grant. This is the only way to authenticate MCP servers in the launch SDK.
|
||||
|
||||
#### Credentials and the sandbox
|
||||
|
||||
Vaults store credentials; those credentials **never enter the sandbox**. This is a deliberate security boundary — code running in the sandbox (including anything the agent writes) cannot read or exfiltrate a vaulted credential, even under prompt injection. Instead, credentials are injected by Anthropic-side proxies **after** a request leaves the sandbox:
|
||||
|
||||
- **MCP tool calls** are routed through an Anthropic-side proxy that fetches the credential from the vault and adds it to the outbound request.
|
||||
- **Git operations on attached GitHub repositories** (`git pull`, `git push`, GitHub REST calls) are routed through a git proxy that injects the `github_repository` resource's `authorization_token` the same way.
|
||||
|
||||
**Not yet supported:** running other authenticated CLIs (e.g. `aws`, `gcloud`, `stripe`) directly inside the sandbox. There is currently no way to set container environment variables or expose vault credentials to arbitrary processes. If you need one of these today:
|
||||
|
||||
- **Prefer an MCP server** for that service if one exists — it gets the same vault-backed injection.
|
||||
- **Otherwise, register a custom tool:** the agent emits `agent.custom_tool_use`, your orchestrator (which already holds the credential) executes the call and returns `user.custom_tool_result` over the same authenticated event stream. No public endpoint is exposed; the sandbox never sees the secret. See `shared/managed-agents-client-patterns.md` → Pattern 9.
|
||||
|
||||
**Do not put API keys in the system prompt or user messages as a workaround** — they persist in the session's event history.
|
||||
|
||||
> Formerly known internally as TATs (Tool/Tenant Access Tokens).
|
||||
|
||||
**Flow:**
|
||||
|
||||
1. Create a vault (`client.beta.vaults.create(...)`) — one per tenant/user, or one shared, depending on your model
|
||||
2. Add MCP credentials to it (`client.beta.vaults.credentials.create(...)`) — each credential is tied to one MCP server URL
|
||||
3. Reference the vault on session create via `vault_ids: ["vlt_..."]`
|
||||
4. Anthropic auto-refreshes tokens before they expire; the agent uses the current access token when calling MCP tools
|
||||
|
||||
**Credential shape**:
|
||||
|
||||
```json
|
||||
{
|
||||
"display_name": "Notion (workspace-foo)",
|
||||
"auth": {
|
||||
"type": "mcp_oauth",
|
||||
"mcp_server_url": "https://mcp.notion.com/mcp",
|
||||
"access_token": "<current access token>",
|
||||
"expires_at": "2026-04-02T14:00:00Z",
|
||||
"refresh": {
|
||||
"refresh_token": "<refresh token>",
|
||||
"client_id": "<your OAuth client_id>",
|
||||
"token_endpoint": "https://api.notion.com/v1/oauth/token",
|
||||
"token_endpoint_auth": { "type": "none" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `refresh` block is what enables auto-refresh — `token_endpoint` is where Anthropic posts the `refresh_token` grant. `token_endpoint_auth` is a discriminated union:
|
||||
|
||||
| `type` | Shape | Use when |
|
||||
|---|---|---|
|
||||
| `"none"` | `{type: "none"}` | Public OAuth client (no secret) |
|
||||
| `"client_secret_basic"` | `{type: "client_secret_basic", client_secret: "..."}` | Confidential client, secret via HTTP Basic auth |
|
||||
| `"client_secret_post"` | `{type: "client_secret_post", client_secret: "..."}` | Confidential client, secret in request body |
|
||||
|
||||
Omit `refresh` entirely if you only have an access token with no refresh capability — it'll work until it expires, then the agent loses access.
|
||||
|
||||
> 💡 **Getting an OAuth token.** How you obtain the initial access and refresh tokens depends on the MCP server — consult its documentation. Once you have them, store them in a vault credential using the shape above; Anthropic auto-refreshes via the `refresh.token_endpoint` from there.
|
||||
|
||||
**Scoping:** Vaults are workspace-scoped. Anyone with developer+ role in the API workspace can create, read (metadata only — secrets are write-only), and attach vaults. `vault_ids` can be set at session **create** time but not via session update (the SDK docstring says "Not yet supported; requests setting this field are rejected").
|
||||
|
||||
---
|
||||
|
||||
## Skills
|
||||
|
||||
Skills are reusable, filesystem-based resources that provide your agent with domain-specific expertise: workflows, context, and best practices that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations.
|
||||
|
||||
Two types — both work the same way; the agent automatically uses them when relevant to the task at hand:
|
||||
|
||||
| Type | What it is |
|
||||
|---|---|
|
||||
| **Pre-built Anthropic skills** | Common document tasks (PowerPoint, Excel, Word, PDF). Reference by name (e.g. `xlsx`). |
|
||||
| **Custom skills** | Skills you've created in your organization via the Skills API. Reference by `skill_id` + optional `version`. |
|
||||
|
||||
**Max 64 skills per agent.** Agent creation uses `managed-agents-2026-04-01`; the separate Skills API (for managing custom skill definitions) uses `skills-2025-10-02`.
|
||||
|
||||
### Enabling skills on a session
|
||||
|
||||
Skills are attached to the **agent** definition via `agents.create()`:
|
||||
|
||||
```ts
|
||||
const agent = await client.beta.agents.create(
|
||||
{
|
||||
name: "Financial Agent",
|
||||
model: "claude-opus-4-7",
|
||||
system: "You are a financial analysis agent.",
|
||||
skills: [
|
||||
{ type: "anthropic", skill_id: "xlsx" },
|
||||
{ type: "custom", skill_id: "skill_abc123", version: "latest" },
|
||||
],
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
Python:
|
||||
|
||||
```python
|
||||
agent = client.beta.agents.create(
|
||||
name="Financial Agent",
|
||||
model="claude-opus-4-7",
|
||||
system="You are a financial analysis agent.",
|
||||
skills=[
|
||||
{"type": "anthropic", "skill_id": "xlsx"},
|
||||
{"type": "custom", "skill_id": "skill_abc123", "version": "latest"},
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
**Skill reference fields:**
|
||||
|
||||
| Field | Anthropic skill | Custom skill |
|
||||
|---|---|---|
|
||||
| `type` | `"anthropic"` | `"custom"` |
|
||||
| `skill_id` | Skill name (e.g. `"xlsx"`, `"docx"`, `"pptx"`, `"pdf"`) | Skill ID from Skills API (e.g. `"skill_abc123"`) |
|
||||
| `version` | — | `"latest"` or a specific version number |
|
||||
|
||||
### Skills API
|
||||
|
||||
| Operation | Method | Path |
|
||||
| --------------------- | -------- | ----------------------------------------------- |
|
||||
| Create Skill | `POST` | `/v1/skills` |
|
||||
| List Skills | `GET` | `/v1/skills` |
|
||||
| Get Skill | `GET` | `/v1/skills/{id}` |
|
||||
| Delete Skill | `DELETE` | `/v1/skills/{id}` |
|
||||
| Create Version | `POST` | `/v1/skills/{id}/versions` |
|
||||
| List Versions | `GET` | `/v1/skills/{id}/versions` |
|
||||
| Get Version | `GET` | `/v1/skills/{id}/versions/{version}` |
|
||||
| Delete Version | `DELETE` | `/v1/skills/{id}/versions/{version}` |
|
||||
|
||||
@@ -0,0 +1,779 @@
|
||||
# Model Migration Guide
|
||||
|
||||
How to move existing code to newer Claude models. Covers breaking changes, deprecated parameters, and drop-in replacements for retired models.
|
||||
|
||||
For the latest, authoritative version (with code samples in every supported language), WebFetch the **Migration Guide** URL from `shared/live-sources.md`. Use this file for the consolidated, skill-resident reference; fall back to the live docs whenever a model launch or breaking change may have shifted the picture.
|
||||
|
||||
**This file is large.** Use the section names below to jump (or `Grep` this file for the heading text). Read Step 0 and Step 1 first — they apply to every migration. Then read only the per-target section for the model you are migrating to.
|
||||
|
||||
| Section | When you need it |
|
||||
|---|---|
|
||||
| Step 0: Confirm the migration scope | Always — before any edits |
|
||||
| Step 1: Classify each file | Always — decides whether to swap, add-alongside, or skip |
|
||||
| Per-SDK Syntax Reference | Translate the Python examples in this guide to TypeScript / Go / Ruby / Java / C# / PHP |
|
||||
| Destination Models / Retired Model Replacements | Picking a target model |
|
||||
| Breaking Changes by Source Model | Migrating to Opus 4.6 / Sonnet 4.6 |
|
||||
| Migrating to Opus 4.7 | Migrating to Opus 4.7 (breaking changes, silent defaults, behavioral shifts) |
|
||||
| Opus 4.7 Migration Checklist | The required vs optional items for 4.7, tagged `[BLOCKS]` / `[TUNE]` |
|
||||
| Verify the Migration | After edits — runtime spot-check |
|
||||
|
||||
**TL;DR:** Change the model ID string. If you were using `budget_tokens`, switch to `thinking: {type: "adaptive"}`. If you were using assistant prefills, they 400 on both Opus 4.6 and Sonnet 4.6 — switch to one of the prefill replacements (most often `output_config.format`; see the table in Breaking Changes by Source Model). If you're moving from Sonnet 4.5 to Sonnet 4.6, set `effort` explicitly — 4.6 defaults to `high`. Remove the `effort-2025-11-24` and `fine-grained-tool-streaming-2025-05-14` beta headers (GA on 4.6); remove `interleaved-thinking-2025-05-14` once you're on adaptive thinking (keep it only while using the transitional `budget_tokens` escape hatch). Then drop back from `client.beta.messages.create` to `client.messages.create`. Dial back any aggressive "CRITICAL: YOU MUST" tool instructions; 4.6 follows the system prompt much more closely.
|
||||
|
||||
---
|
||||
|
||||
## Step 0: Confirm the migration scope
|
||||
|
||||
**Before any Write, Edit, or MultiEdit call, confirm the scope.** If the user's request does not explicitly name a single file, a specific directory, or an explicit file list, **ask first — do not start editing**. This is non-negotiable: even imperative-sounding requests like "migrate my codebase", "move my project to X", "upgrade to Sonnet 4.6", or bare "migrate to Opus 4.7" leave the scope ambiguous and require a clarifying question. Phrases like "my project", "my code", "my codebase", "the whole thing", "everywhere", or "across the repo" are **ambiguous, not directive** — they tell you *what* to do but not *where*. Ask before doing.
|
||||
|
||||
Offer the common scopes explicitly and wait for the answer before touching any file:
|
||||
|
||||
1. The entire working directory
|
||||
2. A specific subdirectory (e.g. `src/`, `app/`, `services/billing/`)
|
||||
3. A specific file or a list of files
|
||||
|
||||
Surface this as a single clarifying question so the user can answer in one turn. **Proceed without asking only when the scope is already unambiguous** — the user named an exact file ("migrate `extract.py` to Sonnet 4.6"), pointed at a specific directory ("migrate everything under `services/billing/` to Opus 4.6"), listed specific files ("update `a.py` and `b.py`"), or already answered the scope question in an earlier turn. If you can answer the question "which files is this change going to touch?" with a precise list from the prompt alone, proceed. If not, ask.
|
||||
|
||||
**Worked example.** If the user says *"Move my project to Opus 4.6. I want adaptive thinking everywhere it makes sense."* you do not know whether "my project" means the whole working directory, just `src/`, just the production code, or something else — the `everywhere` makes the intent clear (update every call site *within scope*) but the scope itself is still not defined. Do not start editing. Respond with:
|
||||
|
||||
> Before I start editing, can you confirm the scope? I can migrate:
|
||||
> 1. Every `.py` file in the working directory
|
||||
> 2. Just the files under `src/` (production code)
|
||||
> 3. A specific subdirectory or list of files you name
|
||||
>
|
||||
> Which one?
|
||||
|
||||
Then wait for the answer. The same applies to *"Migrate to Opus 4.7"* and bare *"Help me upgrade to Sonnet 4.6"* — ask before editing.
|
||||
|
||||
**Sizing the scope question (large repos).** Before asking, get a per-directory count so the user can pick concretely:
|
||||
|
||||
```sh
|
||||
rg -l "<old-model-id>" --type-not md | cut -d/ -f1 | sort | uniq -c | sort -rn
|
||||
```
|
||||
|
||||
Present the breakdown in your scope question (e.g. *"Found 217 references across 3 directories: api/ (130), api-go/ (62), routing/ (25). Which to migrate?"*). Also confirm `git status` is clean before surveying — unexpected modifications mean a concurrent process; stop and investigate before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Classify each file
|
||||
|
||||
Not every file that contains the old model ID is a **caller** of the API. Before editing, classify each file into one of these buckets — the right action differs:
|
||||
|
||||
| # | Bucket | What it looks like | Action |
|
||||
|---|---|---|---|
|
||||
| 1 | **Calls the API/SDK** | `client.messages.create(model=…)`, `anthropic.Anthropic()`, request payloads | Swap the model ID **and** apply the breaking-change checklist for the target version (below). |
|
||||
| 2 | **Defines or serves the model** | Model registries, OpenAPI specs, routing/queue configs, model-policy enums, generated catalogs | The old entry **stays** (the model is still served). Ask whether to (a) add the new model alongside, (b) leave alone, or (c) retire the old model — never blind-replace. **If you can't ask, default to (a): add the new model alongside and flag it** — replacing would de-register a model that's still in production. |
|
||||
| 3 | **References the ID as an opaque string** | UI fallback constants, capability-gate substring checks, generic test fixtures, label parsers, env defaults | Usually swap the string and verify any parser/regex/substring match handles the new ID — but check the sub-cases below first. |
|
||||
| 4 | **Suffixed variant ID** | `claude-<model>-<suffix>` like `-fast`, `-1024k`, `-200k`, `[1m]`, dated snapshots | These are deployment/routing identifiers, not the public model ID. **Do not assume a new-model equivalent exists.** Verify in the registry first; if absent, leave the string alone and flag it. |
|
||||
|
||||
**Bucket 3 sub-cases — before swapping a string reference, check:**
|
||||
|
||||
- **Capability gate** (e.g. `if 'opus-4-6' in model_id:` enables a feature) → **add the new ID alongside**, don't replace. The old model is still served and still has the capability, so replacing would silently disable the feature for any old-model traffic that still flows through. If you know no old-model traffic will hit this gate (single-caller codebase fully migrating), replacing is fine; if unsure, add alongside.
|
||||
- **Registry-assert test** (e.g. `assert "claude-X" in supported_models`, `test_X_has_N_clusters`) → **add an assertion for the new model alongside; keep the old one.** The old model is still served, so its assertion stays valid — but the registry should also include the new model, so assert that too. Heuristic: if the test references multiple model versions in a list, it's a registry test; if one model in a struct compared only to itself, it's a generic fixture.
|
||||
- **Frozen / generated snapshot** → **regenerate**, don't hand-edit.
|
||||
- **Coupled to a definer** (e.g. an integration test that passes model authorization via a shared `conftest` seed list, or asserts on a billing-tier / rate-limit-group enum or a generated SKU/pricing catalog) → **verify the definer has a new-model entry first.** If not, add a seed entry (reusing the nearest existing tier as a placeholder); if you can't confidently do that, ask the user how to populate the definer. **Do not skip the test.** Swapping without populating the definer will make the test fail at runtime.
|
||||
|
||||
When migrating tests specifically: breaking parameters (`temperature`, `top_p`, `budget_tokens`) are usually absent — test fixtures rarely set sampling params on placeholder models. The breaking-change scan is still required, but expect mostly clean results.
|
||||
|
||||
**Find intentionally-flagged sync points first.** Many codebases tag spots that must change at every model launch with comment markers like `MODEL LAUNCH`, `KEEP IN SYNC`, `@model-update`, or similar. Grep for whatever convention the repo uses *before* the broad model-ID grep — those markers point at the load-bearing changes.
|
||||
|
||||
---
|
||||
|
||||
## Per-SDK Syntax Reference
|
||||
|
||||
Code examples in this guide are Python. **The same fields exist in every official Anthropic SDK** — Stainless generates all 7 from the same OpenAPI spec, so JSON field names map 1:1 with only case-convention differences. Use the rows below to translate the Python examples to the SDK you are migrating.
|
||||
|
||||
> **Verify type and method names against the SDK source before writing them into customer code.** WebFetch the relevant repository from the SDK source-code table in `shared/live-sources.md` (one row per SDK) and confirm the exact symbol — particularly for typed SDKs (Go, Java, C#) where union/builder names can differ from the JSON shape. Do not guess type names that aren't in the table below or in `<lang>/claude-api/README.md`.
|
||||
|
||||
|
||||
### `thinking` — `budget_tokens` → adaptive
|
||||
|
||||
| SDK | Before | After |
|
||||
|---|---|---|
|
||||
| Python | `thinking={"type": "enabled", "budget_tokens": N}` | `thinking={"type": "adaptive"}` |
|
||||
| TypeScript | `thinking: { type: 'enabled', budget_tokens: N }` | `thinking: { type: 'adaptive' }` |
|
||||
| Go | `Thinking: anthropic.ThinkingConfigParamOfEnabled(N)` | `Thinking: anthropic.ThinkingConfigParamUnion{OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{}}` |
|
||||
| Ruby | `thinking: { type: "enabled", budget_tokens: N }` | `thinking: { type: "adaptive" }` |
|
||||
| Java | `.thinking(ThinkingConfigEnabled.builder().budgetTokens(N).build())` | `.thinking(ThinkingConfigAdaptive.builder().build())` |
|
||||
| C# | `Thinking = new ThinkingConfigEnabled { BudgetTokens = N }` | `Thinking = new ThinkingConfigAdaptive()` |
|
||||
| PHP | `thinking: ['type' => 'enabled', 'budget_tokens' => N]` | `thinking: ['type' => 'adaptive']` |
|
||||
|
||||
### Sampling parameters — `temperature` / `top_p` / `top_k`
|
||||
|
||||
(Remove the field entirely on Opus 4.7; on Claude 4.x keep at most one of `temperature` or `top_p`.)
|
||||
|
||||
| SDK | Field(s) to remove |
|
||||
|---|---|
|
||||
| Python | `temperature=…`, `top_p=…`, `top_k=…` |
|
||||
| TypeScript | `temperature: …`, `top_p: …`, `top_k: …` |
|
||||
| Go | `Temperature: anthropic.Float(…)`, `TopP: anthropic.Float(…)`, `TopK: anthropic.Int(…)` |
|
||||
| Ruby | `temperature: …`, `top_p: …`, `top_k: …` |
|
||||
| Java | `.temperature(…)`, `.topP(…)`, `.topK(…)` |
|
||||
| C# | `Temperature = …`, `TopP = …`, `TopK = …` |
|
||||
| PHP | `temperature: …`, `topP: …`, `topK: …` |
|
||||
|
||||
### Prefill replacement — structured outputs via `output_config.format`
|
||||
|
||||
| SDK | Remove (last assistant turn) | Add |
|
||||
|---|---|---|
|
||||
| Python | `{"role": "assistant", "content": "…"}` | `output_config={"format": {"type": "json_schema", "schema": SCHEMA}}` |
|
||||
| TypeScript | `{ role: 'assistant', content: '…' }` | `output_config: { format: { type: 'json_schema', schema: SCHEMA } }` |
|
||||
| Go | trailing `anthropic.MessageParam{Role: "assistant", …}` | `OutputConfig: anthropic.OutputConfigParam{Format: anthropic.JSONOutputFormatParam{…}}` |
|
||||
| Ruby | `{ role: "assistant", content: "…" }` | `output_config: { format: { type: "json_schema", schema: SCHEMA } }` |
|
||||
| Java | trailing `Message.builder().role(ASSISTANT)…` | `.outputConfig(OutputConfig.builder().format(JsonOutputFormat.builder()…build()).build())` |
|
||||
| C# | trailing `new Message { Role = "assistant", … }` | `OutputConfig = new OutputConfig { Format = new JsonOutputFormat { … } }` |
|
||||
| PHP | trailing `['role' => 'assistant', 'content' => '…']` | `outputConfig: ['format' => ['type' => 'json_schema', 'schema' => $SCHEMA]]` |
|
||||
|
||||
### `thinking.display` — opt back into summarized reasoning (Opus 4.7)
|
||||
|
||||
| SDK | Add |
|
||||
|---|---|
|
||||
| Python | `thinking={"type": "adaptive", "display": "summarized"}` |
|
||||
| TypeScript | `thinking: { type: 'adaptive', display: 'summarized' }` |
|
||||
| Go | `Thinking: anthropic.ThinkingConfigParamUnion{OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized}}` |
|
||||
| Ruby | `thinking: { type: "adaptive", display: "summarized" }` (or `display_:` when constructing the model class directly) |
|
||||
| Java | `.thinking(ThinkingConfigAdaptive.builder().display(ThinkingConfigAdaptive.Display.SUMMARIZED).build())` |
|
||||
| C# | `Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized }` |
|
||||
| PHP | `thinking: ['type' => 'adaptive', 'display' => 'summarized']` |
|
||||
|
||||
For any field not in these tables, the JSON key in the Python example translates directly: `snake_case` for Python/TypeScript/Ruby, `camelCase` named args for PHP, `PascalCase` struct fields for Go/C#, `camelCase` builder methods for Java.
|
||||
|
||||
---
|
||||
|
||||
## Explain every change you make
|
||||
|
||||
Migration edits often look arbitrary to a user who hasn't read the release notes — a removed `temperature`, a deleted prefill, a rewritten system-prompt sentence. **For each edit, tell the user what you changed and why**, tied to the specific API or behavioral change that motivates it. Do this in your summary as you work, not just at the end.
|
||||
|
||||
Be especially explicit about **system-prompt edits**. Users are rightly protective of their prompts, and prompt-tuning changes are judgment calls (not hard API requirements). For any prompt edit:
|
||||
|
||||
- Quote the before and after text.
|
||||
- State the behavioral shift that motivates it (e.g. *"Opus 4.7 calibrates response length to task complexity, so I added an explicit length instruction"*, or *"4.6 follows instructions more literally, so 'CRITICAL: YOU MUST use the search tool' will now overtrigger — softened to 'Use the search tool when…'"*).
|
||||
- Make clear which prompt edits are **optional tuning** (tone, length, subagent guidance) versus which code edits are **required to avoid a 400** (sampling params, `budget_tokens`, prefills). Never present an optional prompt change as mandatory.
|
||||
|
||||
If you're applying several prompt-tuning edits at once, offer them as a short list the user can accept or decline item-by-item rather than silently rewriting their system prompt.
|
||||
|
||||
---
|
||||
|
||||
## Before You Migrate
|
||||
|
||||
1. **Confirm the target model ID.** Use only the exact strings from `shared/models.md` — do not append date suffixes to aliases (`claude-opus-4-6`, not `claude-opus-4-6-20251101`). Guessing an ID will 404.
|
||||
2. **Check which features your code uses** with this checklist:
|
||||
- `thinking: {type: "enabled", budget_tokens: N}` → migrate to adaptive thinking on Opus 4.6 / Sonnet 4.6 (still functional but deprecated)
|
||||
- Assistant-turn prefills (`messages` ending with `role: "assistant"`) → must change on Opus 4.6 / Sonnet 4.6 (returns 400)
|
||||
- `output_format` parameter on `messages.create()` → must change on all models (deprecated API-wide)
|
||||
- `max_tokens > ~16000` → must stream on any model (above ~16K risks SDK HTTP timeouts). When streaming, Sonnet 4.6 / Haiku 4.5 cap at 64K and Opus 4.6 caps at 128K
|
||||
- Beta headers `effort-2025-11-24`, `fine-grained-tool-streaming-2025-05-14`, `interleaved-thinking-2025-05-14` → GA on 4.6, remove them and switch from `client.beta.messages.create` to `client.messages.create`
|
||||
- Moving Sonnet 4.5 → Sonnet 4.6 with no `effort` set → 4.6 defaults to `high`, which may change your latency/cost profile
|
||||
- System prompts with `CRITICAL`, `MUST`, `If in doubt, use X` language → likely to overtrigger on 4.6 (see Prompt-Behavior Changes)
|
||||
- Coming from 3.x / 4.0 / 4.1: also check sampling params (`temperature` + `top_p`), tool versions (`text_editor_20250728`), `refusal` + `model_context_window_exceeded` stop reasons, trailing-newline tool-param handling
|
||||
3. **Test on a single request first.** Run one call against the new model, inspect the response, then roll out.
|
||||
|
||||
---
|
||||
|
||||
## Destination Models (recommended targets)
|
||||
|
||||
| If you're on… | Migrate to | Why |
|
||||
| ------------------------------------- | ------------------ | ------------------------------------------------- |
|
||||
| Opus 4.6 | `claude-opus-4-7` | Most capable model; adaptive thinking only; high-res vision; see Migrating to Opus 4.7 |
|
||||
| Opus 4.0 / 4.1 / 4.5 / Opus 3 | `claude-opus-4-6` | Most intelligent 4.x before 4.7; adaptive thinking; 128K output |
|
||||
| Sonnet 4.0 / 4.5 / 3.7 / 3.5 | `claude-sonnet-4-6`| Best speed / intelligence balance; adaptive thinking; 64K output |
|
||||
| Haiku 3 / 3.5 | `claude-haiku-4-5` | Fastest and most cost-effective |
|
||||
|
||||
Default to the latest Opus for the caller's tier unless they explicitly chose otherwise. If you're moving from Opus 4.5 or older directly to Opus 4.7, apply the 4.6 migration first, then layer the Opus 4.7 changes on top (see Migrating to Opus 4.7 below).
|
||||
|
||||
---
|
||||
|
||||
## Retired Model Replacements
|
||||
|
||||
These models return 404 — update immediately:
|
||||
|
||||
| Retired model | Retired | Drop-in replacement |
|
||||
| ----------------------------- | ------------- | -------------------- |
|
||||
| `claude-3-7-sonnet-20250219` | Feb 19, 2026 | `claude-sonnet-4-6` |
|
||||
| `claude-3-5-haiku-20241022` | Feb 19, 2026 | `claude-haiku-4-5` |
|
||||
| `claude-3-opus-20240229` | Jan 5, 2026 | `claude-opus-4-7` |
|
||||
| `claude-3-5-sonnet-20241022` | Oct 28, 2025 | `claude-sonnet-4-6` |
|
||||
| `claude-3-5-sonnet-20240620` | Oct 28, 2025 | `claude-sonnet-4-6` |
|
||||
| `claude-3-sonnet-20240229` | Jul 21, 2025 | `claude-sonnet-4-6` |
|
||||
| `claude-2.1`, `claude-2.0` | Jul 21, 2025 | `claude-sonnet-4-6` |
|
||||
|
||||
## Deprecated Models (retiring soon)
|
||||
|
||||
| Model | Retires | Replacement |
|
||||
| ----------------------------- | ------------- | -------------------- |
|
||||
| `claude-3-haiku-20240307` | Apr 19, 2026 | `claude-haiku-4-5` |
|
||||
| `claude-opus-4-20250514` | June 15, 2026 | `claude-opus-4-7` |
|
||||
| `claude-sonnet-4-20250514` | June 15, 2026 | `claude-sonnet-4-6` |
|
||||
|
||||
---
|
||||
|
||||
## Breaking Changes by Source Model
|
||||
|
||||
### Migrating from Sonnet 4.5 to Sonnet 4.6 (effort default change)
|
||||
|
||||
Sonnet 4.5 had no `effort` parameter; Sonnet 4.6 defaults to `high`. If you just switch the model string and do nothing else, you may see noticeably higher latency and token usage. Set `effort` explicitly.
|
||||
|
||||
**Recommended starting points:**
|
||||
|
||||
| Workload | Start at | Notes |
|
||||
| ------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| Chat, classification, content generation | `low` | With `thinking: {"type": "disabled"}` you'll see similar or better performance vs. Sonnet 4.5 no-thinking |
|
||||
| Most applications (balanced) | `medium` | The default sweet spot for quality vs. cost |
|
||||
| Agentic coding, tool-heavy workflows | `medium` | Pair with adaptive thinking and a generous `max_tokens` (up to 64K with streaming — Sonnet 4.6's ceiling) |
|
||||
| Autonomous multi-step agents, long-horizon loops | `high` | Scale down to `medium` if latency/tokens become a concern |
|
||||
| Computer-use agents | `high` + adaptive | Sonnet 4.6's best computer-use accuracy is on adaptive + high |
|
||||
|
||||
For non-thinking chat workloads specifically:
|
||||
|
||||
```python
|
||||
client.messages.create(
|
||||
model="claude-sonnet-4-6",
|
||||
max_tokens=8192,
|
||||
thinking={"type": "disabled"},
|
||||
output_config={"effort": "low"},
|
||||
messages=[{"role": "user", "content": "..."}],
|
||||
)
|
||||
```
|
||||
|
||||
**When to use Opus 4.6 instead:** hardest and longest-horizon problems — large code migrations, deep research, extended autonomous work. Sonnet 4.6 wins on fast turnaround and cost efficiency.
|
||||
|
||||
### Migrating to Opus 4.6 / Sonnet 4.6 (from any older model)
|
||||
|
||||
**1. Manual extended thinking is deprecated — use adaptive thinking.**
|
||||
|
||||
`thinking: {type: "enabled", budget_tokens: N}` (manual extended thinking with a fixed token budget) is deprecated on Opus 4.6 and Sonnet 4.6. Replace it with `thinking: {type: "adaptive"}`, which lets Claude decide when and how much to think. Adaptive thinking also enables interleaved thinking automatically (no beta header needed).
|
||||
|
||||
```python
|
||||
# Old (still works on older models, deprecated on 4.6)
|
||||
response = client.messages.create(
|
||||
model="claude-sonnet-4-5",
|
||||
max_tokens=16000,
|
||||
thinking={"type": "enabled", "budget_tokens": 8000},
|
||||
messages=[...]
|
||||
)
|
||||
|
||||
# New (Opus 4.6 / Sonnet 4.6)
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-6", # or "claude-sonnet-4-6"
|
||||
max_tokens=16000,
|
||||
thinking={"type": "adaptive"},
|
||||
output_config={"effort": "high"}, # optional: low | medium | high | max
|
||||
messages=[...]
|
||||
)
|
||||
```
|
||||
|
||||
Adaptive thinking is the long-term target, and on internal evaluations it outperforms manual extended thinking. Move when you can.
|
||||
|
||||
**Transitional escape hatch:** manual extended thinking is still *functional* on Opus 4.6 and Sonnet 4.6 (deprecated, will be removed in a future release). If you need a hard ceiling while migrating — for example, to bound token spend on a runaway workload before you've tuned `effort` — you can keep `budget_tokens` around alongside an explicit `effort` value, then remove it in a follow-up. `budget_tokens` must be strictly less than `max_tokens`:
|
||||
|
||||
```python
|
||||
# Transitional only — deprecated, plan to remove
|
||||
client.messages.create(
|
||||
model="claude-sonnet-4-6",
|
||||
max_tokens=16384,
|
||||
thinking={"type": "enabled", "budget_tokens": 8192}, # must be < max_tokens
|
||||
output_config={"effort": "medium"},
|
||||
messages=[...],
|
||||
)
|
||||
```
|
||||
|
||||
If the user asks for a "thinking budget" on 4.6, the preferred answer is `effort` — use `low`, `medium`, `high`, or `max` (Opus-tier only — not Sonnet or Haiku) rather than a token count.
|
||||
|
||||
**2. Effort parameter (Opus 4.5, Opus 4.6, Sonnet 4.6 only).**
|
||||
|
||||
Controls thinking depth and overall token spend. Goes inside `output_config`, not top-level. Default is `high`. `max` is Opus-tier only (Opus 4.6 and later — not Sonnet or Haiku). Errors on Sonnet 4.5 and Haiku 4.5.
|
||||
|
||||
```python
|
||||
output_config={"effort": "medium"} # often the best cost / quality balance
|
||||
```
|
||||
|
||||
### Migrating to the 4.6 family (Opus 4.6 and Sonnet 4.6)
|
||||
|
||||
**3. Assistant-turn prefills return 400 (Opus 4.6 and Sonnet 4.6).**
|
||||
|
||||
Prefilled responses on the final assistant turn are no longer supported on either Opus 4.6 or Sonnet 4.6 — both return a 400. Adding assistant messages *elsewhere* in the conversation (e.g., for few-shot examples) still works. Pick the replacement that matches what the prefill was doing:
|
||||
|
||||
| Prefill was used for | Replacement |
|
||||
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Forcing JSON / YAML / schema output | `output_config.format` with a `json_schema` — see example below |
|
||||
| Forcing a classification label | Tool with an enum field containing valid labels, or structured outputs |
|
||||
| Skipping preambles (`Here is the summary:\n`) | System prompt instruction: *"Respond directly without preamble. Do not start with phrases like 'Here is...' or 'Based on...'."* |
|
||||
| Steering around bad refusals | Usually no longer needed — 4.6 refuses far more appropriately. Plain user-turn prompting is sufficient. |
|
||||
| Continuing an interrupted response | Move continuation into the user turn: *"Your previous response was interrupted and ended with `[last text]`. Continue from there."* |
|
||||
| Injecting reminders / context hydration | Inject into the user turn instead. For complex agent harnesses, expose context via a tool call or during compaction. |
|
||||
|
||||
```python
|
||||
# Old (fails on Opus 4.6 / Sonnet 4.6) — prefill forcing JSON shape
|
||||
messages=[
|
||||
{"role": "user", "content": "Extract the name."},
|
||||
{"role": "assistant", "content": "{\"name\": \""},
|
||||
]
|
||||
|
||||
# New — structured outputs replace the prefill
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-6",
|
||||
max_tokens=1024,
|
||||
output_config={"format": {"type": "json_schema", "schema": {...}}},
|
||||
messages=[{"role": "user", "content": "Extract the name."}],
|
||||
)
|
||||
```
|
||||
|
||||
**4. Stream for `max_tokens > ~16K` (all models); Opus 4.6 alone reaches 128K.**
|
||||
|
||||
Non-streaming requests hit SDK HTTP timeouts at high `max_tokens`, regardless of model — stream for anything above ~16K output. The streamable ceiling differs by model: Sonnet 4.6 and Haiku 4.5 cap at 64K, and Opus 4.6 alone goes up to 128K.
|
||||
|
||||
```python
|
||||
with client.messages.stream(model="claude-opus-4-6", max_tokens=64000, ...) as stream:
|
||||
message = stream.get_final_message()
|
||||
```
|
||||
|
||||
**5. Tool-call JSON escaping may differ (Opus 4.6 and Sonnet 4.6).**
|
||||
|
||||
Both 4.6 models can produce tool call `input` fields with Unicode or forward-slash escaping. Always parse with `json.loads()` / `JSON.parse()` — never raw-string-match the serialized input.
|
||||
|
||||
### All models
|
||||
|
||||
**6. `output_format` → `output_config.format` (API-wide).**
|
||||
|
||||
The old top-level `output_format` parameter on `messages.create()` is deprecated. Use `output_config.format` instead. This is not 4.6-specific — applies to every model.
|
||||
|
||||
---
|
||||
|
||||
## Beta Headers to Remove on 4.6
|
||||
|
||||
Several beta headers that were required on 4.5 are now GA on 4.6 and should be removed. Leaving them in is harmless but misleading; removing them also lets you move from `client.beta.messages.create(...)` back to `client.messages.create(...)`.
|
||||
|
||||
| Header | Status on 4.6 | Action |
|
||||
| ----------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| `effort-2025-11-24` | Effort parameter is GA | Remove |
|
||||
| `fine-grained-tool-streaming-2025-05-14` | GA | Remove |
|
||||
| `interleaved-thinking-2025-05-14` | Adaptive thinking enables interleaved thinking automatically | Remove when using adaptive thinking; still functional on Sonnet 4.6 *with* manual extended thinking, but that path is deprecated |
|
||||
| `token-efficient-tools-2025-02-19` | Built in to all Claude 4+ models | Remove (no effect) |
|
||||
| `output-128k-2025-02-19` | Built in to Claude 4+ models | Remove (no effect) |
|
||||
|
||||
Once you remove all of these and finish moving to adaptive thinking, you can switch the SDK call site from the beta namespace back to the regular one:
|
||||
|
||||
```python
|
||||
# Before
|
||||
response = client.beta.messages.create(
|
||||
model="claude-opus-4-5",
|
||||
betas=["interleaved-thinking-2025-05-14", "effort-2025-11-24"],
|
||||
...
|
||||
)
|
||||
|
||||
# After
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-6",
|
||||
thinking={"type": "adaptive"},
|
||||
output_config={"effort": "high"},
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Additional Changes When Coming from 3.x / 4.0 / 4.1 → 4.6
|
||||
|
||||
If you're jumping from Opus 4.1, Sonnet 4, Sonnet 3.7, or an older Claude 3.x model directly to 4.6, apply everything above *plus* the items in this section. Users already on Opus 4.5 / Sonnet 4.5 can skip this.
|
||||
|
||||
**1. Sampling parameters: `temperature` OR `top_p`, not both.**
|
||||
|
||||
Passing both will error on every Claude 4+ model:
|
||||
|
||||
```python
|
||||
# Old (3.x only — errors on 4+)
|
||||
client.messages.create(temperature=0.7, top_p=0.9, ...)
|
||||
|
||||
# New
|
||||
client.messages.create(temperature=0.7, ...) # or top_p, not both
|
||||
```
|
||||
|
||||
**2. Update tool versions.**
|
||||
|
||||
Legacy tool versions are not supported on 4+. **Both the `type` and the `name` field change** — `text_editor_20250728` and `str_replace_based_edit_tool` are a pair; updating one without the other 400s. Also remove the `undo_edit` command from your text-editor integration:
|
||||
|
||||
| Old | New |
|
||||
| ------------------------------------------------- | ------------------------------------------------------- |
|
||||
| `text_editor_20250124` + `str_replace_editor` | `text_editor_20250728` + `str_replace_based_edit_tool` |
|
||||
| `code_execution_*` (earlier versions) | `code_execution_20250825` |
|
||||
| `undo_edit` command | *(no longer supported — delete call sites)* |
|
||||
|
||||
```python
|
||||
# Before
|
||||
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
|
||||
|
||||
# After — BOTH fields change
|
||||
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
|
||||
```
|
||||
|
||||
**3. Handle the `refusal` stop reason.**
|
||||
|
||||
Claude 4+ can return `stop_reason: "refusal"` on the response. If your code only handles `end_turn` / `tool_use` / `max_tokens`, add a branch:
|
||||
|
||||
```python
|
||||
if response.stop_reason == "refusal":
|
||||
# Surface the refusal to the user; do not retry with the same prompt
|
||||
...
|
||||
```
|
||||
|
||||
**4. Handle the `model_context_window_exceeded` stop reason (4.5+).**
|
||||
|
||||
Distinct from `max_tokens`: it means the model hit the *context window* limit, not the requested output cap. Handle both:
|
||||
|
||||
```python
|
||||
if response.stop_reason == "model_context_window_exceeded":
|
||||
# Context window exhausted — compact or split the conversation
|
||||
...
|
||||
elif response.stop_reason == "max_tokens":
|
||||
# Requested output cap hit — retry with higher max_tokens or stream
|
||||
...
|
||||
```
|
||||
|
||||
**5. Trailing newlines preserved in tool call string parameters (4.5+).**
|
||||
|
||||
4.5 and 4.6 preserve trailing newlines that older models stripped. If your tool implementations do exact string matching against tool-call `input` values (e.g., `if name == "foo"`), verify they still match when the model sends `"foo\n"`. Normalizing with `.rstrip()` on the receiving side is usually the simplest fix.
|
||||
|
||||
**6. Haiku: rate limits reset between generations.**
|
||||
|
||||
Haiku 4.5 has its own rate-limit pool separate from Haiku 3 / 3.5. If you're ramping traffic as you migrate, check your tier's Haiku 4.5 limits at [API rate limits](https://platform.claude.com/docs/en/api/rate-limits) — a quota that comfortably served Haiku 3.5 traffic may need a tier bump for the same volume on 4.5.
|
||||
|
||||
---
|
||||
|
||||
## Prompt-Behavior Changes (Opus 4.5 / 4.6, Sonnet 4.6)
|
||||
|
||||
These don't break your code, but prompts that worked on 4.5-and-earlier may over- or under-trigger on 4.6. Tune as needed.
|
||||
|
||||
**1. Aggressive instructions cause overtriggering.** Opus 4.5 and 4.6 follow the system prompt much more closely than earlier models. Prompts written to *overcome* the old reluctance are now too aggressive:
|
||||
|
||||
| Before (worked on 4.0 / 4.5) | After (use on 4.6) |
|
||||
| ------------------------------------------- | ----------------------------------------- |
|
||||
| `CRITICAL: You MUST use this tool when...` | `Use this tool when...` |
|
||||
| `Default to using [tool]` | `Use [tool] when it would improve X` |
|
||||
| `If in doubt, use [tool]` | *(delete — no longer needed)* |
|
||||
|
||||
If the model is now overtriggering a tool or skill, the fix is almost always to dial back the language, not to add more guardrails.
|
||||
|
||||
**2. Overthinking and excessive exploration (Opus 4.6).** At higher `effort` settings, Opus 4.6 explores more before answering. If that burns too many thinking tokens, lower `effort` first (`medium` is often the sweet spot) before adding prose instructions to constrain reasoning.
|
||||
|
||||
**3. Overeager subagent spawning (Opus 4.6).** Opus 4.6 has a strong preference for delegating to subagents. If you see it spawning a subagent for something a direct `grep` or `read` would solve, add guidance: *"Use subagents only for parallel or independent workstreams. For single-file reads or sequential operations, work directly."*
|
||||
|
||||
**4. Overengineering (Opus 4.5 / 4.6).** Both models may add extra files, abstractions, or defensive error handling beyond what was asked. If you want minimal changes, prompt for it explicitly: *"Only make changes directly requested. Don't add helpers, abstractions, or error handling for scenarios that can't happen."*
|
||||
|
||||
**5. LaTeX math output (Opus 4.6).** Opus 4.6 defaults to LaTeX (`\frac{}{}`, `$...$`) for math and technical content. If you need plain text, instruct it explicitly: *"Format all math as plain text — no LaTeX, no `$`, no `\frac{}{}`. Use `/` for division and `^` for exponents."*
|
||||
|
||||
**6. Skipped verbal summaries (4.6 family).** The 4.6 models are more concise and may skip the summary paragraph after a tool call, jumping straight to the next action. If you rely on those summaries for visibility, add: *"After completing a task that involves tool use, provide a brief summary of what you did."*
|
||||
|
||||
**7. "Think" as a trigger word (Opus 4.5 with thinking disabled).** When `thinking` is off, Opus 4.5 is particularly sensitive to the word *think* and may reason more than you want. Use `consider`, `evaluate`, or `reason through` instead.
|
||||
|
||||
---
|
||||
|
||||
## Model-ID Rename Quick Reference
|
||||
|
||||
| Old string (migration source) | New string |
|
||||
| ------------------------------ | ------------------ |
|
||||
| `claude-opus-4-6` | `claude-opus-4-7` |
|
||||
| `claude-opus-4-5` | `claude-opus-4-7` |
|
||||
| `claude-opus-4-1` | `claude-opus-4-7` |
|
||||
| `claude-opus-4-0` | `claude-opus-4-7` |
|
||||
| `claude-sonnet-4-5` | `claude-sonnet-4-6`|
|
||||
| `claude-sonnet-4-0` | `claude-sonnet-4-6`|
|
||||
|
||||
Older aliases (`claude-opus-4-5`, `claude-sonnet-4-5`, `claude-opus-4-1`, etc.) are still active and can be pinned if you need time before upgrading — see `shared/models.md` for the full legacy list.
|
||||
|
||||
---
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
Every item is tagged: **`[BLOCKS]`** items cause a 400 error, infinite loop, silent timeout, or wrong tool selection if missed — apply these as code edits, not as suggestions. **`[TUNE]`** items are quality/cost adjustments.
|
||||
|
||||
For each file that calls `messages.create()` / equivalent SDK method:
|
||||
|
||||
- [ ] **[BLOCKS]** Update the `model=` string to the new alias
|
||||
- [ ] **[BLOCKS]** Replace `budget_tokens` with `thinking={"type": "adaptive"}` (deprecated on Opus 4.6 / Sonnet 4.6)
|
||||
- [ ] **[BLOCKS]** Move `format` from top-level `output_format` into `output_config.format`
|
||||
- [ ] **[BLOCKS]** Remove any assistant-turn prefills if targeting Opus 4.6 or Sonnet 4.6 (see the prefill replacement table)
|
||||
- [ ] **[BLOCKS]** Switch to streaming if `max_tokens > ~16000` (otherwise SDK HTTP timeout)
|
||||
- [ ] **[TUNE]** Set `output_config={"effort": "..."}` explicitly — especially when moving Sonnet 4.5 → Sonnet 4.6 (4.6 defaults to `high`)
|
||||
- [ ] **[TUNE]** Remove GA beta headers: `effort-2025-11-24`, `fine-grained-tool-streaming-2025-05-14`, `token-efficient-tools-2025-02-19`, `output-128k-2025-02-19`; remove `interleaved-thinking-2025-05-14` once on adaptive thinking
|
||||
- [ ] **[TUNE]** Switch `client.beta.messages.create(...)` → `client.messages.create(...)` once all betas are removed
|
||||
- [ ] **[TUNE]** Review system prompt for aggressive tool language (`CRITICAL:`, `MUST`, `If in doubt`) and dial it back
|
||||
|
||||
**Extra items when coming from 3.x / 4.0 / 4.1:**
|
||||
- [ ] **[BLOCKS]** Remove either `temperature` or `top_p` (passing both 400s on Claude 4+)
|
||||
- [ ] **[BLOCKS]** Update text-editor tool `type` to `text_editor_20250728`
|
||||
- [ ] **[BLOCKS]** Update text-editor tool `name` to `str_replace_based_edit_tool` — **changing only the `type` and keeping `name: "str_replace_editor"` returns a 400**
|
||||
- [ ] **[BLOCKS]** Update code-execution tool to `code_execution_20250825`
|
||||
- [ ] **[BLOCKS]** Delete any `undo_edit` command call sites
|
||||
- [ ] **[TUNE]** Add handling for `stop_reason == "refusal"`
|
||||
- [ ] **[TUNE]** Add handling for `stop_reason == "model_context_window_exceeded"` (4.5+)
|
||||
- [ ] **[TUNE]** Verify tool-param string matching tolerates trailing newlines (preserved on 4.5+)
|
||||
- [ ] **[TUNE]** If moving to Haiku 4.5: review rate-limit tier (separate pool from Haiku 3.x)
|
||||
|
||||
**Verification:**
|
||||
- [ ] Run one test request and inspect `response.stop_reason`, `response.usage`, and whether tool-use / thinking behavior matches expectations
|
||||
|
||||
For cached prompts: the render order and hash inputs did not change, so existing `cache_control` breakpoints keep working. However, **changing the model string invalidates the existing cache** — the first request on the new model will write the cache fresh.
|
||||
|
||||
---
|
||||
|
||||
## Migrating to Opus 4.7
|
||||
|
||||
> **Model ID `claude-opus-4-7` is authoritative as written here.** When the user asks to migrate to Opus 4.7, write `model="claude-opus-4-7"` exactly. Do **not** WebFetch to verify — this guide is the source of truth for migration target IDs. The corresponding entry exists in `shared/models.md`.
|
||||
|
||||
Claude Opus 4.7 is our most capable generally available model to date. It is highly autonomous and performs exceptionally well on long-horizon agentic work, knowledge work, vision tasks, and memory tasks. This section summarizes everything new at launch. It is layered on top of the 4.6 migration above — if the caller is jumping from Opus 4.5 or older, apply the 4.6 changes first, then apply this section.
|
||||
|
||||
**TL;DR for someone already on Opus 4.6:** update the model ID to `claude-opus-4-7`, strip any remaining `budget_tokens` and sampling parameters (both 400 on Opus 4.7), give `max_tokens` extra headroom and re-baseline with `count_tokens()` against the new model, opt back into `thinking.display: "summarized"` if reasoning is surfaced to users, and re-tune `effort` — it matters more on 4.7 than on any prior Opus.
|
||||
|
||||
### Breaking changes (will 400 on Opus 4.7)
|
||||
|
||||
**Extended thinking removed.**
|
||||
|
||||
`thinking: {type: "enabled", budget_tokens: N}` is no longer supported on Claude Opus 4.7 or later models and returns a 400 error. Switch to adaptive thinking (`thinking: {type: "adaptive"}`) and use the effort parameter to control thinking depth. Adaptive thinking is **off by default** on Claude Opus 4.7: requests with no `thinking` field run without thinking, matching Opus 4.6 behavior. Set `thinking: {type: "adaptive"}` explicitly to enable it.
|
||||
|
||||
```python
|
||||
# Before (Opus 4.6)
|
||||
client.messages.create(
|
||||
model="claude-opus-4-6",
|
||||
max_tokens=64000,
|
||||
thinking={"type": "enabled", "budget_tokens": 32000},
|
||||
messages=[{"role": "user", "content": "..."}],
|
||||
)
|
||||
|
||||
# After (Opus 4.7)
|
||||
client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=64000,
|
||||
thinking={"type": "adaptive"},
|
||||
output_config={"effort": "high"}, # or "max", "xhigh", "medium", "low"
|
||||
messages=[{"role": "user", "content": "..."}],
|
||||
)
|
||||
```
|
||||
|
||||
If the caller wasn't using extended thinking, no change is required — thinking is off by default, or can be set explicitly with `thinking={"type": "disabled"}`.
|
||||
|
||||
Delete `budget_tokens` plumbing entirely. For the replacement `effort` value, see **Choosing an effort level on Opus 4.7** below — there is no exact 1:1 mapping from `budget_tokens`.
|
||||
|
||||
**Sampling parameters removed.**
|
||||
|
||||
The `temperature`, `top_p`, and `top_k` parameters are no longer accepted on Claude Opus 4.7. Requests that include them return a 400 error. Remove these fields from your request payloads. Prompting is the recommended way to guide model behavior on Claude Opus 4.7. If you were using `temperature = 0` for determinism, note that it never guaranteed identical outputs on prior models.
|
||||
|
||||
```python
|
||||
# Before — errors on Opus 4.7
|
||||
client.messages.create(temperature=0.7, top_p=0.9, ...)
|
||||
|
||||
# After
|
||||
client.messages.create(...) # no sampling params
|
||||
```
|
||||
|
||||
- **If the intent was determinism** — use `effort: "low"` with a tighter prompt.
|
||||
- **If the intent was creative variance** — the prompt replacement depends on the use case; **ask the user** how they want variance elicited. If you can't ask, add a use-case-appropriate instruction along the lines of *"choose something off-distribution and interesting"* — e.g. for text generation, *"Vary your phrasing and structure across responses"*; for frontend/design, use the propose-4-directions approach under **Design and frontend coding** below.
|
||||
|
||||
### Choosing an effort level on Opus 4.7
|
||||
|
||||
`budget_tokens` controlled how much to *think*; `effort` controls how much to think *and* act, so there is no exact 1:1 mapping. **Use `xhigh` for best results in coding and agentic use cases, and a minimum of `high` for most intelligence-sensitive use cases.** Experiment with other levels to further tune token usage and intelligence:
|
||||
|
||||
| Level | Use when | Notes |
|
||||
| --- | --- | --- |
|
||||
| `max` | Intelligence-demanding tasks worth testing at the ceiling | Can deliver gains in some use cases but may show diminishing returns from increased token usage; can be prone to overthinking |
|
||||
| `xhigh` | **Most coding and agentic use cases** | The best setting for these; used as the default in Claude Code |
|
||||
| `high` | Intelligence-sensitive use cases generally | Balances token usage and intelligence; recommended minimum for most intelligence-sensitive work |
|
||||
| `medium` | Cost-sensitive use cases that need to reduce token usage while trading off intelligence | |
|
||||
| `low` | Short, scoped tasks and latency-sensitive workloads that are not intelligence-sensitive | |
|
||||
|
||||
### Silent default changes (no error, but behavior differs)
|
||||
|
||||
**Thinking content omitted by default.**
|
||||
|
||||
Thinking blocks still appear in the response stream on Claude Opus 4.7, but their `thinking` field is empty unless you explicitly opt in. This is a silent change from Claude Opus 4.6, where the default was to return summarized thinking text. To restore summarized thinking content on Claude Opus 4.7, set `thinking.display` to `"summarized"`. **The block-field name is unchanged** — it is still `block.thinking` on a `thinking`-type block; do not rename it.
|
||||
|
||||
**Detect this:** any code that reads `block.thinking` (or equivalent) from a `thinking`-type block and renders it in a UI, log, or trace. **The fix is the request parameter, not the response handling** — add `display: "summarized"` to the `thinking` parameter:
|
||||
|
||||
```python
|
||||
thinking={"type": "adaptive", "display": "summarized"} # "display" is new on Opus 4.7; values: "omitted" (default) | "summarized"
|
||||
```
|
||||
|
||||
The default is `"omitted"` on Claude Opus 4.7. If thinking content was never surfaced anywhere, no change needed. If your product streams reasoning to users, the new default appears as a long pause before output begins; set `display: "summarized"` to restore visible progress during thinking.
|
||||
|
||||
**Updated token counting.**
|
||||
|
||||
Claude Opus 4.7 and Claude Opus 4.6 count tokens differently. The same input text produces a higher token count on Claude Opus 4.7 than on Claude Opus 4.6, and `/v1/messages/count_tokens` will return a different number of tokens for Claude Opus 4.7 than it did for Claude Opus 4.6. The token efficiency of Claude Opus 4.7 can vary by workload shape. Prompting interventions, `task_budget`, and `effort` can help control costs and ensure appropriate token usage. Keep in mind that these controls may trade off model intelligence. **Update your `max_tokens` parameters to give additional headroom, including compaction triggers.** Claude Opus 4.7 provides a 1M context window at standard API pricing with no long-context premium.
|
||||
|
||||
What else to check:
|
||||
|
||||
- Client-side token estimators (tiktoken-style approximations) calibrated against 4.6
|
||||
- Cost calculators that multiply tokens by a fixed per-token rate
|
||||
- Rate-limit retry thresholds keyed to measured token counts
|
||||
|
||||
Re-baseline by re-running `client.messages.count_tokens()` against `claude-opus-4-7` on a representative sample of the caller's prompts. Do not apply a blanket multiplier. For cost-sensitive workloads, consider reducing `effort` by one level (e.g. `high` → `medium`). For agentic loops, consider adopting Task Budgets (below).
|
||||
|
||||
### New feature: Task Budgets (beta)
|
||||
|
||||
Opus 4.7 introduces **task budgets** — tell Claude how many tokens it has for a full agentic loop (thinking + tool calls + final output). The model sees a running countdown and uses it to prioritize work and wrap up gracefully as the budget is consumed.
|
||||
|
||||
This is a **suggestion the model is aware of**, not a hard cap. It is distinct from `max_tokens`, which remains the enforced per-response limit and is *not* surfaced to the model. Use `task_budget` when you want the model to self-moderate; use `max_tokens` as a hard ceiling to cap usage.
|
||||
|
||||
Requires beta header `task-budgets-2026-03-13`:
|
||||
|
||||
```python
|
||||
client.beta.messages.create(
|
||||
betas=["task-budgets-2026-03-13"],
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=64000,
|
||||
thinking={"type": "adaptive"},
|
||||
output_config={
|
||||
"effort": "high",
|
||||
"task_budget": {"type": "tokens", "total": 128000},
|
||||
},
|
||||
messages=[...],
|
||||
)
|
||||
```
|
||||
|
||||
Set a generous budget for open-ended agentic tasks and tighten it for latency-sensitive ones. **Minimum `task_budget.total` is 20,000 tokens.** If the budget is too restrictive for the task, the model may complete it less thoroughly, referencing its budget as the constraint. **Do not add `task_budget` during a migration unless you are sure the budget value is right** — if you can run the workload and measure, do so; otherwise ask the user for the value rather than guessing. This is the primary lever for offsetting the token-counting shift on agentic workloads.
|
||||
|
||||
### Capability improvements
|
||||
|
||||
**High-resolution vision.** Opus 4.7 is the first Claude model with high-resolution image support. Maximum image resolution is **2576 pixels on the long edge** (up from 1568px on Opus 4.6 and prior). This unlocks gains on vision-heavy workloads, especially computer use and screenshot/artifact/document understanding. Coordinates returned by the model now map 1:1 to actual image pixels, so no scale-factor math is needed.
|
||||
|
||||
High-res support is **automatic on Opus 4.7** — no beta header, no client-side opt-in required. The model accepts larger inputs and returns pixel-accurate coordinates out of the box.
|
||||
|
||||
**Token cost.** Full-resolution images on Opus 4.7 can use up to ~3× more image tokens than on prior models (up to ~4784 tokens per image, vs. the previous ~1,600-token cap). If the extra fidelity isn't needed, downsample client-side before sending to control cost — but **do not add downsampling by default during a migration**. If you're not sure whether the pipeline needs the fidelity, ask the user rather than guessing. Use `count_tokens()` on representative images on Opus 4.7 to re-baseline before reacting to any measured cost shift.
|
||||
|
||||
Beyond resolution, Opus 4.7 also improves on low-level perception (pointing, measuring, counting) and natural-image bounding-box localization and detection.
|
||||
|
||||
**Knowledge work.** Meaningful gains on tasks where the model visually verifies its own output — `.docx` redlining, `.pptx` editing, and programmatic chart/figure analysis (e.g. pixel-level data transcription via image-processing libraries). If prompts have scaffolding like *"double-check the slide layout before returning"*, try removing it and re-baselining.
|
||||
|
||||
**Memory.** Opus 4.7 is better at writing and using file-system-based memory. If an agent maintains a scratchpad, notes file, or structured memory store across turns, that agent should improve at jotting down notes to itself and leveraging its notes in future tasks.
|
||||
|
||||
**User-facing progress updates.** Opus 4.7 provides more regular, higher-quality interim updates during long agentic traces. If the system prompt has scaffolding like *"After every 3 tool calls, summarize progress"*, try removing it to avoid excessive user-facing text. If the length or contents of Opus 4.7's updates are not well-calibrated to your use case, explicitly describe what these updates should look like in the prompt and provide examples.
|
||||
|
||||
### Real-time cybersecurity safeguards
|
||||
|
||||
Requests that involve prohibited or high-risk topics may lead to refusals.
|
||||
|
||||
### Fast Mode: not available on Opus 4.7
|
||||
|
||||
Opus 4.7 does not have a Fast Mode variant. **Opus 4.6 Fast remains supported**. Only surface this if the caller's code actually uses a Fast Mode model string (e.g. `claude-opus-4-6-fast`); if the word "fast" does not appear in the code, say nothing about Fast Mode.
|
||||
|
||||
When you see `model="claude-opus-4-6-fast"` (or similar), **the migration edit is**:
|
||||
|
||||
```python
|
||||
# Opus 4.7 has no Fast Mode — keeping on 4.6 Fast (caller's choice to switch to standard Opus 4.7).
|
||||
model="claude-opus-4-6-fast",
|
||||
```
|
||||
|
||||
That is: leave the model string **unchanged**, add the comment above it, and tell the user their two options — (a) stay on Opus 4.6 Fast, which remains supported, or (b) move latency-tolerant traffic to standard Opus 4.7 for the intelligence gain. Do **not** rewrite the model string to `claude-opus-4-7` yourself; that silently trades latency for intelligence, which is the caller's decision.
|
||||
|
||||
### Behavioral shifts (prompt-tunable)
|
||||
|
||||
These don't break anything, but prompts tuned for Opus 4.6 may land differently. Opus 4.7 is more steerable than 4.6, so small prompt nudges usually close the gap.
|
||||
|
||||
**More literal instruction following.** Claude Opus 4.7 interprets prompts more literally and explicitly than Claude Opus 4.6, particularly at lower effort levels. It will not silently generalize an instruction from one item to another, and it will not infer requests you didn't make. The upside of this literalism is precision and less thrash. It generally performs better for API use cases with carefully tuned prompts, structured extraction, and pipelines where you want predictable behavior. A prompt and harness review may be especially helpful for migration to Claude Opus 4.7.
|
||||
|
||||
**Verbosity calibrates to task complexity.** Opus 4.7 scales response length to how complex it judges the task to be, rather than defaulting to a fixed verbosity — shorter answers on simple lookups, much longer on open-ended analysis. If the product depends on a particular length or style, tune the prompt explicitly. To reduce verbosity:
|
||||
|
||||
> *"Provide concise, focused responses. Skip non-essential context, and keep examples minimal."*
|
||||
|
||||
If you see specific kinds of over-verbosity (e.g. over-explaining), add instructions targeting those. Positive examples showing the desired level of concision tend to be more effective than negative examples or instructions telling the model what not to do. Do **not** assume existing "be concise" instructions should be removed — test first.
|
||||
|
||||
**Tone and writing style.** Opus 4.7 is more direct and opinionated, with less validation-forward phrasing and fewer emoji than Opus 4.6's warmer style. As with any new model, prose style on long-form writing may shift. If the product relies on a specific voice, re-evaluate style prompts against the new baseline. If a warmer or more conversational voice is wanted, specify it:
|
||||
|
||||
> *"Use a warm, collaborative tone. Acknowledge the user's framing before answering."*
|
||||
|
||||
**`effort` matters more than on any prior Opus.** Opus 4.7 respects `effort` levels more strictly, especially at the low end. At `low` and `medium` it scopes work to what was asked rather than going above and beyond — good for latency and cost, but on moderate tasks at `low` there is some risk of under-thinking.
|
||||
|
||||
- If shallow reasoning shows up on complex problems, raise `effort` to `high` or `xhigh` rather than prompting around it.
|
||||
- If `effort` must stay `low` for latency, add targeted guidance: *"This task involves multi-step reasoning. Think carefully through the problem before responding."*
|
||||
- **At `xhigh` or `max`, set a large `max_tokens`** so the model has room to think and act across tool calls and subagents. Start at 64K and tune from there. (`xhigh` is a new effort level on Opus 4.7, between `high` and `max`.)
|
||||
|
||||
Adaptive-thinking triggering is also steerable. If the model thinks more often than wanted — which can happen with large or complex system prompts — add: *"Thinking adds latency and should only be used when it will meaningfully improve answer quality — typically for problems that require multi-step reasoning. When in doubt, respond directly."*
|
||||
|
||||
**Uses tools less often by default.** Opus 4.7 tends to use tools less often than 4.6 and to use reasoning more. This produces better results in most cases, but for products that rely on tools (search/retrieval, function-calling, computer-use steps), it can drop tool-use rate. Two levers:
|
||||
|
||||
- **Raise `effort`** — `high` or `xhigh` show substantially more tool usage in agentic search and coding, and are especially useful for knowledge work.
|
||||
- **Prompt for it** — be explicit in tool descriptions or the system prompt about when and how to use the tool, and encourage the model to err on the side of using it more often:
|
||||
|
||||
> *"When the answer depends on information not present in the conversation, you MUST call the `search` tool before answering — do not answer from prior knowledge."*
|
||||
|
||||
**Fewer subagents by default.** Opus 4.7 tends to spawn fewer subagents than 4.6. This is steerable — give explicit guidance on when delegation is desirable. For a coding agent, for example:
|
||||
|
||||
> *"Do NOT spawn a subagent for work you can complete directly in a single response (e.g. refactoring a function you can already see). Spawn multiple subagents in the same turn when fanning out across items or reading multiple files."*
|
||||
|
||||
**Design and frontend coding.** Opus 4.7 has stronger design instincts than 4.6, with a consistent default house style: warm cream/off-white backgrounds (around `#F4F1EA`), serif display type (Georgia, Fraunces, Playfair), italic word-accents, and a terracotta/amber accent. This reads well for editorial, hospitality, and portfolio briefs, but will feel off for dashboards, dev tools, fintech, healthcare, or enterprise apps — and it appears in slide decks as well as web UIs.
|
||||
|
||||
The default is persistent. Generic instructions ("don't use cream," "make it clean and minimal") tend to shift the model to a different fixed palette rather than producing variety. Two approaches work reliably:
|
||||
|
||||
1. **Specify a concrete alternative.** The model follows explicit specs precisely — give exact hex values, typefaces, and layout constraints.
|
||||
2. **Have the model propose options before building.** This breaks the default and gives the user control:
|
||||
|
||||
> *"Before building, propose 4 distinct visual directions tailored to this brief (each as: bg hex / accent hex / typeface — one-line rationale). Ask the user to pick one, then implement only that direction."*
|
||||
|
||||
If the caller previously relied on `temperature` for design variety, use approach (2) — it produces meaningfully different directions across runs.
|
||||
|
||||
Opus 4.7 also requires less frontend-design prompting than previous models to avoid generic "AI slop" aesthetics. Where earlier models needed a lengthy anti-slop snippet, Opus 4.7 generates distinctive, creative frontends with a much shorter nudge. This snippet works well alongside the variety approaches above:
|
||||
|
||||
> *"NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white or dark backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. Use unique fonts, cohesive colors and themes, and animations for effects and micro-interactions."*
|
||||
|
||||
**Interactive coding products.** Opus 4.7's token usage and behavior can differ between autonomous, asynchronous coding agents with a single user turn and interactive, synchronous coding agents with multiple user turns. Specifically, it tends to use more tokens in interactive settings, primarily because it reasons more after user turns. This can improve long-horizon coherence, instruction following, and coding capabilities in long interactive coding sessions, but also comes with more token usage. To maximize both performance and token efficiency in coding products, use `effort: "xhigh"` or `"high"`, add autonomous features (like an auto mode), and reduce the number of human interactions required from users.
|
||||
|
||||
When limiting required user interactions, specify the task, intent, and relevant constraints upfront in the first human turn. Well-specified, clear, and accurate task descriptions upfront help maximize autonomy and intelligence while minimizing extra token usage after user turns — because Opus 4.7 is more autonomous than prior models, this usage pattern helps to maximize performance. In contrast, ambiguous or underspecified prompts conveyed progressively over multiple user turns tend to reduce token efficiency and sometimes performance.
|
||||
|
||||
**Code review.** Opus 4.7 is meaningfully better at finding bugs than prior models, with both higher recall and precision. However, if a code-review harness was tuned for an earlier model, it may initially show *lower* recall — this is likely a harness effect, not a capability regression. When a review prompt says "only report high-severity issues," "be conservative," or "don't nitpick," Opus 4.7 follows that instruction more faithfully than earlier models did: it investigates just as thoroughly, identifies the bugs, and then declines to report findings it judges to be below the stated bar. Precision rises, but measured recall can fall even though underlying bug-finding has improved.
|
||||
|
||||
Recommended prompt language:
|
||||
|
||||
> *"Report every issue you find, including ones you are uncertain about or consider low-severity. Do not filter for importance or confidence at this stage — a separate verification step will do that. Your goal here is coverage: it is better to surface a finding that later gets filtered out than to silently drop a bug. For each finding, include your confidence level and an estimated severity so a downstream filter can rank them."*
|
||||
|
||||
This can be used without an actual second step, but moving confidence filtering out of the finding step often helps. If the harness has a separate verification/dedup/ranking stage, tell the model explicitly that its job at the finding stage is coverage, not filtering. If single-pass self-filtering is wanted, be concrete about the bar rather than using qualitative terms like "important" — e.g. *"report any bugs that could cause incorrect behavior, a test failure, or a misleading result; only omit nits like pure style or naming preferences."* Iterate on prompts against a subset of evals to validate recall or F1 gains.
|
||||
|
||||
**Computer use.** Computer use works across resolutions up to the new 2576px / 3.75MP maximum. Sending images at **1080p** provides a good balance of performance and cost. For particularly cost-sensitive workloads, **720p** or **1366×768** are lower-cost options with strong performance. Test to find the ideal settings for the use case; experimenting with `effort` can also help tune behavior.
|
||||
|
||||
---
|
||||
|
||||
## Opus 4.7 Migration Checklist
|
||||
|
||||
Every item is tagged: **`[BLOCKS]`** items cause a 400 error, infinite loop, silent truncation, or empty output if missed — apply these as code edits, not as suggestions. **`[TUNE]`** items are quality/cost adjustments — surface them to the user as recommendations.
|
||||
|
||||
`[BLOCKS]` items prefixed with **"If…"** or **"At…"** are conditional. Before working through the list, **scan the file** for the conditions: does it surface thinking text to a UI/log? Does it set `output_config.effort` to `"x-high"` or `"max"`? Is it a security workload? Is it a multi-turn agentic loop? Apply only the items whose condition matches.
|
||||
|
||||
- [ ] **[BLOCKS]** Replace `thinking: {type: "enabled", budget_tokens: N}` with `thinking: {type: "adaptive"}` + `output_config.effort`; delete `budget_tokens` plumbing entirely
|
||||
- [ ] **[BLOCKS]** Strip `temperature`, `top_p`, `top_k` from request construction
|
||||
- [ ] **[BLOCKS]** If thinking content is surfaced to users or stored in logs: add `thinking.display: "summarized"` (otherwise the rendered text is empty)
|
||||
- [ ] **[BLOCKS]** At `output_config.effort` of `xhigh` or `max`: set `max_tokens` ≥ 64000 (otherwise output truncates mid-thought)
|
||||
- [ ] **[TUNE]** Give `max_tokens` and compaction triggers extra headroom; re-run `count_tokens()` against `claude-opus-4-7` on representative prompts to re-baseline (no blanket multiplier)
|
||||
- [ ] **[TUNE]** Re-baseline cost and rate-limit dashboards *before* reacting to measured shifts
|
||||
- [ ] **[TUNE]** Re-evaluate `effort` per route — use `xhigh` for coding/agentic and a minimum of `high` for most intelligence-sensitive work; it matters more on 4.7 than any prior Opus
|
||||
- [ ] **[TUNE]** Multi-turn agentic loops: adopt the API-native Task Budgets (`output_config.task_budget`, beta `task-budgets-2026-03-13`, minimum 20k tokens) — this is for capping *cumulative* spend across a loop; per-turn depth is `effort`
|
||||
- [ ] **[TUNE]** Check for ambiguous or underspecified instructions that relied on 4.6 generalizing intent, and update them to be clearer or more precise — 4.7 follows them literally
|
||||
- [ ] **[TUNE]** Tool-use workloads: add explicit when/how-to-use guidance to tool descriptions (4.7 reaches for tools less often)
|
||||
- [ ] **[TUNE]** Verbosity: test existing length instructions before changing them — 4.7 calibrates length to task complexity, so tune for the desired output rather than assuming a direction
|
||||
- [ ] **[TUNE]** Remove forced-progress-update scaffolding (*"after every N tool calls…"*)
|
||||
- [ ] **[TUNE]** Remove knowledge-work verification scaffolding (*"double-check the slide layout…"*) and re-baseline
|
||||
- [ ] **[TUNE]** Add tone instruction if a warmer / more conversational voice is needed; re-evaluate style prompts on writing-heavy routes
|
||||
- [ ] **[TUNE]** Subagent tool present: add explicit spawn / don't-spawn guidance
|
||||
- [ ] **[TUNE]** Frontend/design output: specify a concrete palette/typeface, or have the model propose 4 visual directions before building (the default cream/serif house style is persistent)
|
||||
- [ ] **[TUNE]** Interactive coding products: use `effort: "xhigh"` or `"high"`, add autonomous features (e.g. an auto mode) to reduce human interactions, and specify task/intent/constraints upfront in the first turn
|
||||
- [ ] **[TUNE]** Code-review harnesses: remove or loosen "only report high-severity" / "be conservative" filters and have the model report every finding with confidence + severity; move filtering to a downstream step (4.7 follows severity filters more literally, which can depress measured recall)
|
||||
- [ ] **[TUNE]** Vision-heavy pipelines (screenshots, charts, document understanding): leave images at native resolution up to 2576px long edge for the accuracy gain; remove any scale-factor math from coordinate handling (coords are now 1:1 with pixels). No beta header / opt-in needed — high-res is automatic on Opus 4.7.
|
||||
- [ ] **[TUNE]** Computer-use pipelines: send screenshots at 1080p for a good performance/cost balance (720p or 1366×768 for cost-sensitive workloads); experiment with `effort` to tune behavior
|
||||
- [ ] **[TUNE]** Cost-sensitive image pipelines: full-res images on 4.7 use up to ~4784 tokens vs ~1,600 on prior models (~3×). Downsampling client-side before upload avoids the increase, but **do not downsample by default** — if you're unsure whether fidelity is needed, ask the user. Re-baseline with `count_tokens()` on representative images before reacting to cost shifts.
|
||||
|
||||
---
|
||||
|
||||
## Verify the Migration
|
||||
|
||||
After updating, spot-check that the new model is actually being used. Replace `YOUR_TARGET_MODEL` with the model string you migrated to (e.g. `claude-opus-4-7`, `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5`) and keep the assertion prefix in sync:
|
||||
|
||||
```python
|
||||
YOUR_TARGET_MODEL = "claude-opus-4-7" # or "claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5"
|
||||
response = client.messages.create(model=YOUR_TARGET_MODEL, max_tokens=64, messages=[...])
|
||||
assert response.model.startswith(YOUR_TARGET_MODEL), response.model
|
||||
```
|
||||
|
||||
For rate-limit headroom changes, pricing, or capability deltas (vision, structured outputs, effort support), query the Models API:
|
||||
|
||||
```python
|
||||
m = client.models.retrieve(YOUR_TARGET_MODEL)
|
||||
m.max_input_tokens, m.max_tokens
|
||||
m.capabilities["effort"]["max"]["supported"]
|
||||
```
|
||||
|
||||
See `shared/models.md` for the full capability lookup pattern.
|
||||
@@ -0,0 +1,121 @@
|
||||
# Claude Model Catalog
|
||||
|
||||
**Only use exact model IDs listed in this file.** Never guess or construct model IDs — incorrect IDs will cause API errors. Use aliases wherever available. For the latest information, WebFetch the Models Overview URL in `shared/live-sources.md`, or query the Models API directly (see Programmatic Model Discovery below).
|
||||
|
||||
## Programmatic Model Discovery
|
||||
|
||||
For **live** capability data — context window, max output tokens, feature support (thinking, vision, effort, structured outputs, etc.) — query the Models API instead of relying on the cached tables below. Use this when the user asks "what's the context window for X", "does model X support vision/thinking/effort", "which models support feature Y", or wants to select a model by capability at runtime.
|
||||
|
||||
```python
|
||||
m = client.models.retrieve("claude-opus-4-7")
|
||||
m.id # "claude-opus-4-7"
|
||||
m.display_name # "Claude Opus 4.7"
|
||||
m.max_input_tokens # context window (int)
|
||||
m.max_tokens # max output tokens (int)
|
||||
|
||||
# capabilities is an untyped nested dict — bracket access, check ["supported"] at the leaf
|
||||
caps = m.capabilities
|
||||
caps["image_input"]["supported"] # vision
|
||||
caps["thinking"]["types"]["adaptive"]["supported"] # adaptive thinking
|
||||
caps["effort"]["max"]["supported"] # effort: max (also low/medium/high)
|
||||
caps["structured_outputs"]["supported"]
|
||||
caps["context_management"]["compact_20260112"]["supported"]
|
||||
|
||||
# filter across all models — iterate the page object directly (auto-paginates); do NOT use .data
|
||||
[m for m in client.models.list()
|
||||
if m.capabilities["thinking"]["types"]["adaptive"]["supported"]
|
||||
and m.max_input_tokens >= 200_000]
|
||||
```
|
||||
|
||||
Top-level fields (`id`, `display_name`, `max_input_tokens`, `max_tokens`) are typed attributes. `capabilities` is a dict — use bracket access, not attribute access. The API returns the full capability tree for every model with `supported: true/false` at each leaf, so bracket chains are safe without `.get()` guards. TypeScript SDK: same method names, also auto-paginates on iteration.
|
||||
|
||||
### Raw HTTP
|
||||
|
||||
```bash
|
||||
curl https://api.anthropic.com/v1/models/claude-opus-4-7 \
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||
-H "anthropic-version: 2023-06-01"
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "claude-opus-4-7",
|
||||
"display_name": "Claude Opus 4.7",
|
||||
"max_input_tokens": 200000,
|
||||
"max_tokens": 128000,
|
||||
"capabilities": {
|
||||
"image_input": {"supported": true},
|
||||
"structured_outputs": {"supported": true},
|
||||
"thinking": {"supported": true, "types": {"enabled": {"supported": false}, "adaptive": {"supported": true}}},
|
||||
"effort": {"supported": true, "low": {"supported": true}, …, "max": {"supported": true}},
|
||||
…
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Current Models (recommended)
|
||||
|
||||
| Friendly Name | Alias (use this) | Full ID | Context | Max Output | Status |
|
||||
|-------------------|---------------------|-------------------------------|----------------|------------|--------|
|
||||
| Claude Opus 4.7 | `claude-opus-4-7` | — | 1M | 128K | Active |
|
||||
| Claude Opus 4.6 | `claude-opus-4-6` | — | 1M | 128K | Active |
|
||||
| Claude Sonnet 4.6 | `claude-sonnet-4-6` | - | 1M | 64K | Active |
|
||||
| Claude Haiku 4.5 | `claude-haiku-4-5` | `claude-haiku-4-5-20251001` | 200K | 64K | Active |
|
||||
|
||||
### Model Descriptions
|
||||
- **Claude Opus 4.7** — The most capable Claude model to date — highly autonomous, strong on long-horizon agentic work, knowledge work, vision, and memory. Adaptive thinking only; sampling parameters and `budget_tokens` are removed. 1M context window at standard API pricing (no long-context premium) — see `shared/model-migration.md` → Migrating to Opus 4.7 for breaking changes.
|
||||
- **Claude Opus 4.6** — Previous-generation Opus. Supports adaptive thinking (recommended), 128K max output tokens (requires streaming for large outputs). 1M context window.
|
||||
- **Claude Sonnet 4.6** — Our best combination of speed and intelligence. Supports adaptive thinking (recommended). 1M context window. 64K max output tokens.
|
||||
- **Claude Haiku 4.5** — Fastest and most cost-effective model for simple tasks.
|
||||
|
||||
## Legacy Models (still active)
|
||||
|
||||
| Friendly Name | Alias (use this) | Full ID | Status |
|
||||
|-------------------|---------------------|-------------------------------|--------|
|
||||
| Claude Opus 4.5 | `claude-opus-4-5` | `claude-opus-4-5-20251101` | Active |
|
||||
| Claude Opus 4.1 | `claude-opus-4-1` | `claude-opus-4-1-20250805` | Active |
|
||||
| Claude Sonnet 4.5 | `claude-sonnet-4-5` | `claude-sonnet-4-5-20250929` | Active |
|
||||
| Claude Sonnet 4 | `claude-sonnet-4-0` | `claude-sonnet-4-20250514` | Active |
|
||||
| Claude Opus 4 | `claude-opus-4-0` | `claude-opus-4-20250514` | Active |
|
||||
|
||||
## Deprecated Models (retiring soon)
|
||||
|
||||
| Friendly Name | Alias (use this) | Full ID | Status | Retires |
|
||||
|-------------------|---------------------|-------------------------------|------------|--------------|
|
||||
| Claude Haiku 3 | — | `claude-3-haiku-20240307` | Deprecated | Apr 19, 2026 |
|
||||
|
||||
## Retired Models (no longer available)
|
||||
|
||||
| Friendly Name | Full ID | Retired |
|
||||
|-------------------|-------------------------------|-------------|
|
||||
| Claude Sonnet 3.7 | `claude-3-7-sonnet-20250219` | Feb 19, 2026 |
|
||||
| Claude Haiku 3.5 | `claude-3-5-haiku-20241022` | Feb 19, 2026 |
|
||||
| Claude Opus 3 | `claude-3-opus-20240229` | Jan 5, 2026 |
|
||||
| Claude Sonnet 3.5 | `claude-3-5-sonnet-20241022` | Oct 28, 2025 |
|
||||
| Claude Sonnet 3.5 | `claude-3-5-sonnet-20240620` | Oct 28, 2025 |
|
||||
| Claude Sonnet 3 | `claude-3-sonnet-20240229` | Jul 21, 2025 |
|
||||
| Claude 2.1 | `claude-2.1` | Jul 21, 2025 |
|
||||
| Claude 2.0 | `claude-2.0` | Jul 21, 2025 |
|
||||
|
||||
## Resolving User Requests
|
||||
|
||||
When a user asks for a model by name, use this table to find the correct model ID:
|
||||
|
||||
| User says... | Use this model ID |
|
||||
|-------------------------------------------|--------------------------------|
|
||||
| "opus", "most powerful" | `claude-opus-4-7` |
|
||||
| "opus 4.7" | `claude-opus-4-7` |
|
||||
| "opus 4.6" | `claude-opus-4-6` |
|
||||
| "opus 4.5" | `claude-opus-4-5` |
|
||||
| "opus 4.1" | `claude-opus-4-1` |
|
||||
| "opus 4", "opus 4.0" | `claude-opus-4-0` |
|
||||
| "sonnet", "balanced" | `claude-sonnet-4-6` |
|
||||
| "sonnet 4.6" | `claude-sonnet-4-6` |
|
||||
| "sonnet 4.5" | `claude-sonnet-4-5` |
|
||||
| "sonnet 4", "sonnet 4.0" | `claude-sonnet-4-0` |
|
||||
| "sonnet 3.7" | Retired — suggest `claude-sonnet-4-5` |
|
||||
| "sonnet 3.5" | Retired — suggest `claude-sonnet-4-5` |
|
||||
| "haiku", "fast", "cheap" | `claude-haiku-4-5` |
|
||||
| "haiku 4.5" | `claude-haiku-4-5` |
|
||||
| "haiku 3.5" | Retired — suggest `claude-haiku-4-5` |
|
||||
| "haiku 3" | Deprecated — suggest `claude-haiku-4-5` |
|
||||
@@ -0,0 +1,171 @@
|
||||
# Prompt Caching — Design & Optimization
|
||||
|
||||
This file covers how to design prompt-building code for effective caching. For language-specific syntax, see the `## Prompt Caching` section in each language's README or single-file doc.
|
||||
|
||||
## The one invariant everything follows from
|
||||
|
||||
**Prompt caching is a prefix match. Any change anywhere in the prefix invalidates everything after it.**
|
||||
|
||||
The cache key is derived from the exact bytes of the rendered prompt up to each `cache_control` breakpoint. A single byte difference at position N — a timestamp, a reordered JSON key, a different tool in the list — invalidates the cache for all breakpoints at positions ≥ N.
|
||||
|
||||
Render order is: `tools` → `system` → `messages`. A breakpoint on the last system block caches both tools and system together.
|
||||
|
||||
Design the prompt-building path around this constraint. Get the ordering right and most caching works for free. Get it wrong and no amount of `cache_control` markers will help.
|
||||
|
||||
---
|
||||
|
||||
## Workflow for optimizing existing code
|
||||
|
||||
When asked to add or optimize caching:
|
||||
|
||||
1. **Trace the prompt assembly path.** Find where `system`, `tools`, and `messages` are constructed. Identify every input that flows into them.
|
||||
2. **Classify each input by stability:**
|
||||
- Never changes → belongs early in the prompt, before any breakpoint
|
||||
- Changes per-session → belongs after the global prefix, cache per-session
|
||||
- Changes per-turn → belongs at the end, after the last breakpoint
|
||||
- Changes per-request (timestamps, UUIDs, random IDs) → **eliminate or move to the very end**
|
||||
3. **Check rendered order matches stability order.** Stable content must physically precede volatile content. If a timestamp is interpolated into the system prompt header, everything after it is uncacheable regardless of markers.
|
||||
4. **Place breakpoints at stability boundaries.** See placement patterns below.
|
||||
5. **Audit for silent invalidators.** See anti-patterns table.
|
||||
|
||||
---
|
||||
|
||||
## Placement patterns
|
||||
|
||||
### Large system prompt shared across many requests
|
||||
|
||||
Put a breakpoint on the last system text block. If there are tools, they render before system — the marker on the last system block caches tools + system together.
|
||||
|
||||
```json
|
||||
"system": [
|
||||
{"type": "text", "text": "<large shared prompt>", "cache_control": {"type": "ephemeral"}}
|
||||
]
|
||||
```
|
||||
|
||||
### Multi-turn conversations
|
||||
|
||||
Put a breakpoint on the last content block of the most-recently-appended turn. Each subsequent request reuses the entire prior conversation prefix. Earlier breakpoints remain valid read points, so hits accrue incrementally as the conversation grows.
|
||||
|
||||
```json
|
||||
// Last content block of the last user turn
|
||||
messages[-1].content[-1].cache_control = {"type": "ephemeral"}
|
||||
```
|
||||
|
||||
### Shared prefix, varying suffix
|
||||
|
||||
Many requests share a large fixed preamble (few-shot examples, retrieved docs, instructions) but differ in the final question. Put the breakpoint at the end of the **shared** portion, not at the end of the whole prompt — otherwise every request writes a distinct cache entry and nothing is ever read.
|
||||
|
||||
```json
|
||||
"messages": [{"role": "user", "content": [
|
||||
{"type": "text", "text": "<shared context>", "cache_control": {"type": "ephemeral"}},
|
||||
{"type": "text", "text": "<varying question>"} // no marker — differs every time
|
||||
]}]
|
||||
```
|
||||
|
||||
### Prompts that change from the beginning every time
|
||||
|
||||
Don't cache. If the first 1K tokens differ per request, there is no reusable prefix. Adding `cache_control` only pays the cache-write premium with zero reads. Leave it off.
|
||||
|
||||
---
|
||||
|
||||
## Architectural guidance
|
||||
|
||||
These are the decisions that matter more than marker placement. Fix these first.
|
||||
|
||||
**Keep the system prompt frozen.** Don't interpolate "current date: X", "mode: Y", "user name: Z" into the system prompt — those sit at the front of the prefix and invalidate everything downstream. Inject dynamic context as a user or assistant message later in `messages`. A message at turn 5 invalidates nothing before turn 5.
|
||||
|
||||
**Don't change tools or model mid-conversation.** Tools render at position 0; adding, removing, or reordering a tool invalidates the entire cache. Same for switching models (caches are model-scoped). If you need "modes", don't swap the tool set — give Claude a tool that records the mode transition, or pass the mode as message content. Serialize tools deterministically (sort by name).
|
||||
|
||||
**Fork operations must reuse the parent's exact prefix.** Side computations (summarization, compaction, sub-agents) often spin up a separate API call. If the fork rebuilds `system` / `tools` / `model` with any difference, it misses the parent's cache entirely. Copy the parent's `system`, `tools`, and `model` verbatim, then append fork-specific content at the end.
|
||||
|
||||
---
|
||||
|
||||
## Silent invalidators
|
||||
|
||||
When reviewing code, grep for these inside anything that feeds the prompt prefix:
|
||||
|
||||
| Pattern | Why it breaks caching |
|
||||
|---|---|
|
||||
| `datetime.now()` / `Date.now()` / `time.time()` in system prompt | Prefix changes every request |
|
||||
| `uuid4()` / `crypto.randomUUID()` / request IDs early in content | Same — every request is unique |
|
||||
| `json.dumps(d)` without `sort_keys=True` / iterating a `set` | Non-deterministic serialization → prefix bytes differ |
|
||||
| f-string interpolating session/user ID into system prompt | Per-user prefix; no cross-user sharing |
|
||||
| Conditional system sections (`if flag: system += ...`) | Every flag combination is a distinct prefix |
|
||||
| `tools=build_tools(user)` where set varies per user | Tools render at position 0; nothing caches across users |
|
||||
|
||||
Fix by moving the dynamic piece after the last breakpoint, making it deterministic, or deleting it if it's not load-bearing.
|
||||
|
||||
---
|
||||
|
||||
## API reference
|
||||
|
||||
```json
|
||||
"cache_control": {"type": "ephemeral"} // 5-minute TTL (default)
|
||||
"cache_control": {"type": "ephemeral", "ttl": "1h"} // 1-hour TTL
|
||||
```
|
||||
|
||||
- Max **4** `cache_control` breakpoints per request.
|
||||
- Goes on any content block: system text blocks, tool definitions, message content blocks (`text`, `image`, `tool_use`, `tool_result`, `document`).
|
||||
- Top-level `cache_control` on `messages.create()` auto-places on the last cacheable block — simplest option when you don't need fine-grained placement.
|
||||
- Minimum cacheable prefix is model-dependent. Shorter prefixes silently won't cache even with a marker — no error, just `cache_creation_input_tokens: 0`:
|
||||
|
||||
| Model | Minimum |
|
||||
|---|---:|
|
||||
| Opus 4.7, Opus 4.6, Opus 4.5, Haiku 4.5 | 4096 tokens |
|
||||
| Sonnet 4.6, Haiku 3.5, Haiku 3 | 2048 tokens |
|
||||
| Sonnet 4.5, Sonnet 4.1, Sonnet 4, Sonnet 3.7 | 1024 tokens |
|
||||
|
||||
A 3K-token prompt caches on Sonnet 4.5 but silently won't on Opus 4.7.
|
||||
|
||||
**Economics:** Cache reads cost ~0.1× base input price. Cache writes cost **1.25× for 5-minute TTL, 2× for 1-hour TTL**. Break-even depends on TTL: with 5-minute TTL, two requests break even (1.25× + 0.1× = 1.35× vs 2× uncached); with 1-hour TTL, you need at least three requests (2× + 0.2× = 2.2× vs 3× uncached). The 1-hour TTL keeps entries alive across gaps in bursty traffic, but the doubled write cost means it needs more reads to pay off.
|
||||
|
||||
---
|
||||
|
||||
## Verifying cache hits
|
||||
|
||||
The response `usage` object reports cache activity:
|
||||
|
||||
| Field | Meaning |
|
||||
|---|---|
|
||||
| `cache_creation_input_tokens` | Tokens written to cache this request (you paid the ~1.25× write premium) |
|
||||
| `cache_read_input_tokens` | Tokens served from cache this request (you paid ~0.1×) |
|
||||
| `input_tokens` | Tokens processed at full price (not cached) |
|
||||
|
||||
If `cache_read_input_tokens` is zero across repeated requests with identical prefixes, a silent invalidator is at work — diff the rendered prompt bytes between two requests to find it.
|
||||
|
||||
**`input_tokens` is the uncached remainder only.** Total prompt size = `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. If your agent ran for hours but `input_tokens` shows 4K, the rest was served from cache — check the sum, not the single field.
|
||||
|
||||
Language-specific access: `response.usage.cache_read_input_tokens` (Python/TS/Ruby), `$message->usage->cacheReadInputTokens` (PHP), `resp.Usage.CacheReadInputTokens` (Go/C#), `.usage().cacheReadInputTokens()` (Java).
|
||||
|
||||
---
|
||||
|
||||
## Invalidation hierarchy
|
||||
|
||||
Not every parameter change invalidates everything. The API has three cache tiers, and changes only invalidate their own tier and below:
|
||||
|
||||
| Change | Tools cache | System cache | Messages cache |
|
||||
|---|:---:|:---:|:---:|
|
||||
| Tool definitions (add/remove/reorder) | ❌ | ❌ | ❌ |
|
||||
| Model switch | ❌ | ❌ | ❌ |
|
||||
| `speed`, web-search, citations toggle | ✅ | ❌ | ❌ |
|
||||
| System prompt content | ✅ | ❌ | ❌ |
|
||||
| `tool_choice`, images, `thinking` enable/disable | ✅ | ✅ | ❌ |
|
||||
| Message content | ✅ | ✅ | ❌ |
|
||||
|
||||
Implication: you can change `tool_choice` per-request or toggle `thinking` without losing the tools+system cache. Don't over-worry about these — only tool-definition and model changes force a full rebuild.
|
||||
|
||||
---
|
||||
|
||||
## 20-block lookback window
|
||||
|
||||
Each breakpoint walks backward **at most 20 content blocks** to find a prior cache entry. If a single turn adds more than 20 blocks (common in agentic loops with many tool_use/tool_result pairs), the next request's breakpoint won't find the previous cache and silently misses.
|
||||
|
||||
Fix: place an intermediate breakpoint every ~15 blocks in long turns, or put the marker on a block that's within 20 of the previous turn's last cached block.
|
||||
|
||||
---
|
||||
|
||||
## Concurrent-request timing
|
||||
|
||||
A cache entry becomes readable only after the first response **begins streaming**. N parallel requests with identical prefixes all pay full price — none can read what the others are still writing.
|
||||
|
||||
For fan-out patterns: send 1 request, await the first streamed token (not the full response), then fire the remaining N−1. They'll read the cache the first one just wrote.
|
||||
@@ -0,0 +1,327 @@
|
||||
# Tool Use Concepts
|
||||
|
||||
This file covers the conceptual foundations of tool use with the Claude API. For language-specific code examples, see the `python/`, `typescript/`, or other language folders. For decision heuristics on which tools to expose, how to manage context in long-running agents, and caching strategy, see `agent-design.md`.
|
||||
|
||||
## User-Defined Tools
|
||||
|
||||
### Tool Definition Structure
|
||||
|
||||
> **Note:** When using the Tool Runner (beta), tool schemas are generated automatically from your function signatures (Python), Zod schemas (TypeScript), annotated classes (Java), `jsonschema` struct tags (Go), or `BaseTool` subclasses (Ruby). The raw JSON schema format below is for the manual approach — including PHP's `BetaRunnableTool`, which wraps a run closure around a hand-written schema — or SDKs without tool runner support.
|
||||
|
||||
Each tool requires a name, description, and JSON Schema for its inputs:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "get_weather",
|
||||
"description": "Get current weather for a location",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"location": {
|
||||
"type": "string",
|
||||
"description": "City and state, e.g., San Francisco, CA"
|
||||
},
|
||||
"unit": {
|
||||
"type": "string",
|
||||
"enum": ["celsius", "fahrenheit"],
|
||||
"description": "Temperature unit"
|
||||
}
|
||||
},
|
||||
"required": ["location"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Best practices for tool definitions:**
|
||||
|
||||
- Use clear, descriptive names (e.g., `get_weather`, `search_database`, `send_email`)
|
||||
- Write detailed descriptions — Claude uses these to decide when to use the tool
|
||||
- Include descriptions for each property
|
||||
- Use `enum` for parameters with a fixed set of values
|
||||
- Mark truly required parameters in `required`; make others optional with defaults
|
||||
|
||||
---
|
||||
|
||||
### Tool Choice Options
|
||||
|
||||
Control when Claude uses tools:
|
||||
|
||||
| Value | Behavior |
|
||||
| --------------------------------- | --------------------------------------------- |
|
||||
| `{"type": "auto"}` | Claude decides whether to use tools (default) |
|
||||
| `{"type": "any"}` | Claude must use at least one tool |
|
||||
| `{"type": "tool", "name": "..."}` | Claude must use the specified tool |
|
||||
| `{"type": "none"}` | Claude cannot use tools |
|
||||
|
||||
Any `tool_choice` value can also include `"disable_parallel_tool_use": true` to force Claude to use at most one tool per response. By default, Claude may request multiple tool calls in a single response.
|
||||
|
||||
---
|
||||
|
||||
### Tool Runner vs Manual Loop
|
||||
|
||||
**Tool Runner (Recommended):** The SDK's tool runner handles the agentic loop automatically — it calls the API, detects tool use requests, executes your tool functions, feeds results back to Claude, and repeats until Claude stops calling tools. Available in Python, TypeScript, Java, Go, Ruby, and PHP SDKs (beta). The Python SDK also provides MCP conversion helpers (`anthropic.lib.tools.mcp`) to convert MCP tools, prompts, and resources for use with the tool runner — see `python/claude-api/tool-use.md` for details.
|
||||
|
||||
**Manual Agentic Loop:** Use when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval). Loop until `stop_reason == "end_turn"`, always append the full `response.content` to preserve tool_use blocks, and ensure each `tool_result` includes the matching `tool_use_id`.
|
||||
|
||||
**Stop reasons for server-side tools:** When using server-side tools (code execution, web search, etc.), the API runs a server-side sampling loop. If this loop reaches its default limit of 10 iterations, the response will have `stop_reason: "pause_turn"`. To continue, re-send the user message and assistant response and make another API request — the server will resume where it left off. Do NOT add an extra user message like "Continue." — the API detects the trailing `server_tool_use` block and knows to resume automatically.
|
||||
|
||||
```python
|
||||
# Handle pause_turn in your agentic loop
|
||||
if response.stop_reason == "pause_turn":
|
||||
messages = [
|
||||
{"role": "user", "content": user_query},
|
||||
{"role": "assistant", "content": response.content},
|
||||
]
|
||||
# Make another API request — server resumes automatically
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7", messages=messages, tools=tools
|
||||
)
|
||||
```
|
||||
|
||||
Set a `max_continuations` limit (e.g., 5) to prevent infinite loops. For the full guide, see: `https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons`
|
||||
|
||||
> **Security:** The tool runner executes your tool functions automatically whenever Claude requests them. For tools with side effects (sending emails, modifying databases, financial transactions), validate inputs within your tool functions and consider requiring confirmation for destructive operations. Use the manual agentic loop if you need human-in-the-loop approval before each tool execution.
|
||||
|
||||
---
|
||||
|
||||
### Handling Tool Results
|
||||
|
||||
When Claude uses a tool, the response contains a `tool_use` block. You must:
|
||||
|
||||
1. Execute the tool with the provided input
|
||||
2. Send the result back in a `tool_result` message
|
||||
3. Continue the conversation
|
||||
|
||||
**Error handling in tool results:** When a tool execution fails, set `"is_error": true` and provide an informative error message. Claude will typically acknowledge the error and either try a different approach or ask for clarification.
|
||||
|
||||
**Multiple tool calls:** Claude can request multiple tools in a single response. Handle them all before continuing — send all results back in a single `user` message.
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Tools: Code Execution
|
||||
|
||||
The code execution tool lets Claude run code in a secure, sandboxed container. Unlike user-defined tools, server-side tools run on Anthropic's infrastructure — you don't execute anything client-side. Just include the tool definition and Claude handles the rest.
|
||||
|
||||
### Key Facts
|
||||
|
||||
- Runs in an isolated container (1 CPU, 5 GiB RAM, 5 GiB disk)
|
||||
- No internet access (fully sandboxed)
|
||||
- Python 3.11 with data science libraries pre-installed
|
||||
- Containers persist for 30 days and can be reused across requests
|
||||
- Free when used with web search/web fetch tools; otherwise $0.05/hour after 1,550 free hours/month per organization
|
||||
|
||||
### Tool Definition
|
||||
|
||||
The tool requires no schema — just declare it in the `tools` array:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "code_execution_20260120",
|
||||
"name": "code_execution"
|
||||
}
|
||||
```
|
||||
|
||||
Claude automatically gains access to `bash_code_execution` (run shell commands) and `text_editor_code_execution` (create/view/edit files).
|
||||
|
||||
### Pre-installed Python Libraries
|
||||
|
||||
- **Data science**: pandas, numpy, scipy, scikit-learn, statsmodels
|
||||
- **Visualization**: matplotlib, seaborn
|
||||
- **File processing**: openpyxl, xlsxwriter, pillow, pypdf, pdfplumber, python-docx, python-pptx
|
||||
- **Math**: sympy, mpmath
|
||||
- **Utilities**: tqdm, python-dateutil, pytz, sqlite3
|
||||
|
||||
Additional packages can be installed at runtime via `pip install`.
|
||||
|
||||
### Supported File Types for Upload
|
||||
|
||||
| Type | Extensions |
|
||||
| ------ | ---------------------------------- |
|
||||
| Data | CSV, Excel (.xlsx/.xls), JSON, XML |
|
||||
| Images | JPEG, PNG, GIF, WebP |
|
||||
| Text | .txt, .md, .py, .js, etc. |
|
||||
|
||||
### Container Reuse
|
||||
|
||||
Reuse containers across requests to maintain state (files, installed packages, variables). Extract the `container_id` from the first response and pass it to subsequent requests.
|
||||
|
||||
### Response Structure
|
||||
|
||||
The response contains interleaved text and tool result blocks:
|
||||
|
||||
- `text` — Claude's explanation
|
||||
- `server_tool_use` — What Claude is doing
|
||||
- `bash_code_execution_tool_result` — Code execution output (check `return_code` for success/failure)
|
||||
- `text_editor_code_execution_tool_result` — File operation results
|
||||
|
||||
> **Security:** Always sanitize filenames with `os.path.basename()` / `path.basename()` before writing downloaded files to disk to prevent path traversal attacks. Write files to a dedicated output directory.
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Tools: Web Search and Web Fetch
|
||||
|
||||
Web search and web fetch let Claude search the web and retrieve page content. They run server-side — just include the tool definitions and Claude handles queries, fetching, and result processing automatically.
|
||||
|
||||
### Tool Definitions
|
||||
|
||||
```json
|
||||
[
|
||||
{ "type": "web_search_20260209", "name": "web_search" },
|
||||
{ "type": "web_fetch_20260209", "name": "web_fetch" }
|
||||
]
|
||||
```
|
||||
|
||||
### Dynamic Filtering (Opus 4.7 / Opus 4.6 / Sonnet 4.6)
|
||||
|
||||
The `web_search_20260209` and `web_fetch_20260209` versions support **dynamic filtering** — Claude writes and executes code to filter search results before they reach the context window, improving accuracy and token efficiency. Dynamic filtering is built into these tool versions and activates automatically; you do not need to separately declare the `code_execution` tool or pass any beta header.
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{ "type": "web_search_20260209", "name": "web_search" },
|
||||
{ "type": "web_fetch_20260209", "name": "web_fetch" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Without dynamic filtering, the previous `web_search_20250305` version is also available.
|
||||
|
||||
> **Note:** Only include the standalone `code_execution` tool when your application needs code execution for its own purposes (data analysis, file processing, visualization) independent of web search. Including it alongside `_20260209` web tools creates a second execution environment that can confuse the model.
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Tools: Programmatic Tool Calling
|
||||
|
||||
With standard tool use, each tool call is a round trip: Claude calls, the result enters Claude's context, Claude reasons, then calls the next tool. Chained calls accumulate latency and tokens — most of that intermediate data is never needed again.
|
||||
|
||||
Programmatic tool calling lets Claude compose those calls into a script. The script runs in the code execution container; when it invokes a tool, the container pauses, the call executes, and the result returns to the running code (not to Claude's context). The script processes it with normal control flow. Only the final output returns to Claude. Use it when chaining many tool calls or when intermediate results are large and should be filtered before reaching the context window.
|
||||
|
||||
For full documentation, use WebFetch:
|
||||
|
||||
- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling`
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Tools: Tool Search
|
||||
|
||||
The tool search tool lets Claude dynamically discover tools from large libraries without loading all definitions into the context window. Use it when you have many tools but only a few are relevant to any given request. Discovered tool schemas are appended to the request, not swapped in — this preserves the prompt cache (see `agent-design.md` §Caching for Agents).
|
||||
|
||||
For full documentation, use WebFetch:
|
||||
|
||||
- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool`
|
||||
|
||||
---
|
||||
|
||||
## Skills
|
||||
|
||||
Skills package task-specific instructions that Claude loads only when relevant. Each skill is a folder containing a `SKILL.md` file. The skill's short description sits in context by default; Claude reads the full file when the current task calls for it. Use skills to keep specialized instructions out of the base system prompt without losing discoverability.
|
||||
|
||||
For full documentation, use WebFetch:
|
||||
|
||||
- URL: `https://platform.claude.com/docs/en/agents-and-tools/skills`
|
||||
|
||||
---
|
||||
|
||||
## Tool Use Examples
|
||||
|
||||
You can provide sample tool calls directly in your tool definitions to demonstrate usage patterns and reduce parameter errors. This helps Claude understand how to correctly format tool inputs, especially for tools with complex schemas.
|
||||
|
||||
For full documentation, use WebFetch:
|
||||
|
||||
- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use`
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Tools: Computer Use
|
||||
|
||||
Computer use lets Claude interact with a desktop environment (screenshots, mouse, keyboard). It can be Anthropic-hosted (server-side, like code execution) or self-hosted (you provide the environment and execute actions client-side).
|
||||
|
||||
For full documentation, use WebFetch:
|
||||
|
||||
- URL: `https://platform.claude.com/docs/en/agents-and-tools/computer-use/overview`
|
||||
|
||||
---
|
||||
|
||||
## Context Editing
|
||||
|
||||
Context editing clears stale tool results and thinking blocks from the transcript as a long-running agent accumulates turns. Unlike compaction (which summarizes), context editing prunes — the cleared content is removed, not replaced. Use it when old tool outputs are no longer relevant and you want to keep the transcript lean without losing the conversation structure. Thresholds for what to clear are configurable.
|
||||
|
||||
For full documentation, use WebFetch:
|
||||
|
||||
- URL: `https://platform.claude.com/docs/en/build-with-claude/context-editing`
|
||||
|
||||
---
|
||||
|
||||
## Client-Side Tools: Memory
|
||||
|
||||
The memory tool enables Claude to store and retrieve information across conversations through a memory file directory. Claude can create, read, update, and delete files that persist between sessions.
|
||||
|
||||
### Key Facts
|
||||
|
||||
- Client-side tool — you control storage via your implementation
|
||||
- Supports commands: `view`, `create`, `str_replace`, `insert`, `delete`, `rename`
|
||||
- Operates on files in a `/memories` directory
|
||||
- The Python, TypeScript, and Java SDKs provide helper classes/functions for implementing the memory backend
|
||||
|
||||
> **Security:** Never store API keys, passwords, tokens, or other secrets in memory files. Be cautious with personally identifiable information (PII) — check data privacy regulations (GDPR, CCPA) before persisting user data. The reference implementations have no built-in access control; in multi-user systems, implement per-user memory directories and authentication in your tool handlers.
|
||||
|
||||
For full implementation examples, use WebFetch:
|
||||
|
||||
- Docs: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md`
|
||||
|
||||
---
|
||||
|
||||
## Structured Outputs
|
||||
|
||||
Structured outputs constrain Claude's responses to follow a specific JSON schema, guaranteeing valid, parseable output. This is not a separate tool — it enhances the Messages API response format and/or tool parameter validation.
|
||||
|
||||
Two features are available:
|
||||
|
||||
- **JSON outputs** (`output_config.format`): Control Claude's response format
|
||||
- **Strict tool use** (`strict: true`): Guarantee valid tool parameter schemas
|
||||
|
||||
**Supported models:** Claude Opus 4.7, Claude Sonnet 4.6, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs.
|
||||
|
||||
> **Recommended:** Use `client.messages.parse()` which automatically validates responses against your schema. When using `messages.create()` directly, use `output_config: {format: {...}}`. The `output_format` convenience parameter is also accepted by some SDK methods (e.g., `.parse()`), but `output_config.format` is the canonical API-level parameter.
|
||||
|
||||
### JSON Schema Limitations
|
||||
|
||||
**Supported:**
|
||||
|
||||
- Basic types: object, array, string, integer, number, boolean, null
|
||||
- `enum`, `const`, `anyOf`, `allOf`, `$ref`/`$def`
|
||||
- String formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `uri`, `ipv4`, `ipv6`, `uuid`
|
||||
- `additionalProperties: false` (required for all objects)
|
||||
|
||||
**Not supported:**
|
||||
|
||||
- Recursive schemas
|
||||
- Numerical constraints (`minimum`, `maximum`, `multipleOf`)
|
||||
- String constraints (`minLength`, `maxLength`)
|
||||
- Complex array constraints
|
||||
- `additionalProperties` set to anything other than `false`
|
||||
|
||||
The Python and TypeScript SDKs automatically handle unsupported constraints by removing them from the schema sent to the API and validating them client-side.
|
||||
|
||||
### Important Notes
|
||||
|
||||
- **First request latency**: New schemas incur a one-time compilation cost. Subsequent requests with the same schema use a 24-hour cache.
|
||||
- **Refusals**: If Claude refuses for safety reasons (`stop_reason: "refusal"`), the output may not match your schema.
|
||||
- **Token limits**: If `stop_reason: "max_tokens"`, output may be incomplete. Increase `max_tokens`.
|
||||
- **Incompatible with**: Citations (returns 400 error), message prefilling.
|
||||
- **Works with**: Batches API, streaming, token counting, extended thinking.
|
||||
|
||||
---
|
||||
|
||||
## Tips for Effective Tool Use
|
||||
|
||||
1. **Provide detailed descriptions**: Claude relies heavily on descriptions to understand when and how to use tools
|
||||
2. **Use specific tool names**: `get_current_weather` is better than `weather`
|
||||
3. **Validate inputs**: Always validate tool inputs before execution
|
||||
4. **Handle errors gracefully**: Return informative error messages so Claude can adapt
|
||||
5. **Limit tool count**: Too many tools can confuse the model — keep the set focused
|
||||
6. **Test tool interactions**: Verify Claude uses tools correctly in various scenarios
|
||||
|
||||
For detailed tool use documentation, use WebFetch:
|
||||
|
||||
- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview`
|
||||
@@ -0,0 +1,333 @@
|
||||
# Claude API — TypeScript
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @anthropic-ai/sdk
|
||||
```
|
||||
|
||||
## Client Initialization
|
||||
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
|
||||
// Default (uses ANTHROPIC_API_KEY env var)
|
||||
const client = new Anthropic();
|
||||
|
||||
// Explicit API key
|
||||
const client = new Anthropic({ apiKey: "your-api-key" });
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Basic Message Request
|
||||
|
||||
```typescript
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: [{ role: "user", content: "What is the capital of France?" }],
|
||||
});
|
||||
// response.content is ContentBlock[] — a discriminated union. Narrow by .type
|
||||
// before accessing .text (TypeScript will error on content[0].text without this).
|
||||
for (const block of response.content) {
|
||||
if (block.type === "text") {
|
||||
console.log(block.text);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## System Prompts
|
||||
|
||||
```typescript
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
system:
|
||||
"You are a helpful coding assistant. Always provide examples in Python.",
|
||||
messages: [{ role: "user", content: "How do I read a JSON file?" }],
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Vision (Images)
|
||||
|
||||
### URL
|
||||
|
||||
```typescript
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: [
|
||||
{
|
||||
role: "user",
|
||||
content: [
|
||||
{
|
||||
type: "image",
|
||||
source: { type: "url", url: "https://example.com/image.png" },
|
||||
},
|
||||
{ type: "text", text: "Describe this image" },
|
||||
],
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
### Base64
|
||||
|
||||
```typescript
|
||||
import fs from "fs";
|
||||
|
||||
const imageData = fs.readFileSync("image.png").toString("base64");
|
||||
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: [
|
||||
{
|
||||
role: "user",
|
||||
content: [
|
||||
{
|
||||
type: "image",
|
||||
source: { type: "base64", media_type: "image/png", data: imageData },
|
||||
},
|
||||
{ type: "text", text: "What's in this image?" },
|
||||
],
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompt Caching
|
||||
|
||||
**Caching is a prefix match** — any byte change anywhere in the prefix invalidates everything after it. For placement patterns, architectural guidance (frozen system prompt, deterministic tool order, where to put volatile content), and the silent-invalidator audit checklist, read `shared/prompt-caching.md`.
|
||||
|
||||
### Automatic Caching (Recommended)
|
||||
|
||||
Use top-level `cache_control` to automatically cache the last cacheable block in the request:
|
||||
|
||||
```typescript
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
cache_control: { type: "ephemeral" }, // auto-caches the last cacheable block
|
||||
system: "You are an expert on this large document...",
|
||||
messages: [{ role: "user", content: "Summarize the key points" }],
|
||||
});
|
||||
```
|
||||
|
||||
### Manual Cache Control
|
||||
|
||||
For fine-grained control, add `cache_control` to specific content blocks:
|
||||
|
||||
```typescript
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
system: [
|
||||
{
|
||||
type: "text",
|
||||
text: "You are an expert on this large document...",
|
||||
cache_control: { type: "ephemeral" }, // default TTL is 5 minutes
|
||||
},
|
||||
],
|
||||
messages: [{ role: "user", content: "Summarize the key points" }],
|
||||
});
|
||||
|
||||
// With explicit TTL (time-to-live)
|
||||
const response2 = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
system: [
|
||||
{
|
||||
type: "text",
|
||||
text: "You are an expert on this large document...",
|
||||
cache_control: { type: "ephemeral", ttl: "1h" }, // 1 hour TTL
|
||||
},
|
||||
],
|
||||
messages: [{ role: "user", content: "Summarize the key points" }],
|
||||
});
|
||||
```
|
||||
|
||||
### Verifying Cache Hits
|
||||
|
||||
```typescript
|
||||
console.log(response.usage.cache_creation_input_tokens); // tokens written to cache (~1.25x cost)
|
||||
console.log(response.usage.cache_read_input_tokens); // tokens served from cache (~0.1x cost)
|
||||
console.log(response.usage.input_tokens); // uncached tokens (full cost)
|
||||
```
|
||||
|
||||
If `cache_read_input_tokens` is zero across repeated identical-prefix requests, a silent invalidator is at work — `Date.now()` or a UUID in the system prompt, non-deterministic key ordering, or a varying tool set. See `shared/prompt-caching.md` for the full audit table.
|
||||
|
||||
---
|
||||
|
||||
## Extended Thinking
|
||||
|
||||
> **Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Opus 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
|
||||
> **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024).
|
||||
|
||||
```typescript
|
||||
// Opus 4.7 / 4.6: adaptive thinking (recommended)
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
thinking: { type: "adaptive" },
|
||||
output_config: { effort: "high" }, // low | medium | high | max
|
||||
messages: [
|
||||
{ role: "user", content: "Solve this math problem step by step..." },
|
||||
],
|
||||
});
|
||||
|
||||
for (const block of response.content) {
|
||||
if (block.type === "thinking") {
|
||||
console.log("Thinking:", block.thinking);
|
||||
} else if (block.type === "text") {
|
||||
console.log("Response:", block.text);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
Use the SDK's typed exception classes — never check error messages with string matching:
|
||||
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
|
||||
try {
|
||||
const response = await client.messages.create({...});
|
||||
} catch (error) {
|
||||
if (error instanceof Anthropic.BadRequestError) {
|
||||
console.error("Bad request:", error.message);
|
||||
} else if (error instanceof Anthropic.AuthenticationError) {
|
||||
console.error("Invalid API key");
|
||||
} else if (error instanceof Anthropic.RateLimitError) {
|
||||
console.error("Rate limited - retry later");
|
||||
} else if (error instanceof Anthropic.APIError) {
|
||||
console.error(`API error ${error.status}:`, error.message);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
All classes extend `Anthropic.APIError` with a typed `status` field. Check from most specific to least specific. See [shared/error-codes.md](../../shared/error-codes.md) for the full error code reference.
|
||||
|
||||
---
|
||||
|
||||
## Multi-Turn Conversations
|
||||
|
||||
The API is stateless — send the full conversation history each time. Use `Anthropic.MessageParam[]` to type the messages array:
|
||||
|
||||
```typescript
|
||||
const messages: Anthropic.MessageParam[] = [
|
||||
{ role: "user", content: "My name is Alice." },
|
||||
{ role: "assistant", content: "Hello Alice! Nice to meet you." },
|
||||
{ role: "user", content: "What's my name?" },
|
||||
];
|
||||
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: messages,
|
||||
});
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Consecutive same-role messages are allowed — the API combines them into a single turn
|
||||
- First message must be `user`
|
||||
- Use SDK types (`Anthropic.MessageParam`, `Anthropic.Message`, `Anthropic.Tool`, etc.) for all API data structures — don't redefine equivalent interfaces
|
||||
|
||||
---
|
||||
|
||||
### Compaction (long conversations)
|
||||
|
||||
> **Beta, Opus 4.7, Opus 4.6, and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text.
|
||||
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
|
||||
const client = new Anthropic();
|
||||
const messages: Anthropic.Beta.BetaMessageParam[] = [];
|
||||
|
||||
async function chat(userMessage: string): Promise<string> {
|
||||
messages.push({ role: "user", content: userMessage });
|
||||
|
||||
const response = await client.beta.messages.create({
|
||||
betas: ["compact-2026-01-12"],
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages,
|
||||
context_management: {
|
||||
edits: [{ type: "compact_20260112" }],
|
||||
},
|
||||
});
|
||||
|
||||
// Append full content — compaction blocks must be preserved
|
||||
messages.push({ role: "assistant", content: response.content });
|
||||
|
||||
const textBlock = response.content.find(
|
||||
(b): b is Anthropic.Beta.BetaTextBlock => b.type === "text",
|
||||
);
|
||||
return textBlock?.text ?? "";
|
||||
}
|
||||
|
||||
// Compaction triggers automatically when context grows large
|
||||
console.log(await chat("Help me build a Python web scraper"));
|
||||
console.log(await chat("Add support for JavaScript-rendered pages"));
|
||||
console.log(await chat("Now add rate limiting and error handling"));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stop Reasons
|
||||
|
||||
The `stop_reason` field in the response indicates why the model stopped generating:
|
||||
|
||||
| Value | Meaning |
|
||||
| --------------- | --------------------------------------------------------------- |
|
||||
| `end_turn` | Claude finished its response naturally |
|
||||
| `max_tokens` | Hit the `max_tokens` limit — increase it or use streaming |
|
||||
| `stop_sequence` | Hit a custom stop sequence |
|
||||
| `tool_use` | Claude wants to call a tool — execute it and continue |
|
||||
| `pause_turn` | Model paused and can be resumed (agentic flows) |
|
||||
| `refusal` | Claude refused for safety reasons — output may not match schema |
|
||||
|
||||
---
|
||||
|
||||
## Cost Optimization Strategies
|
||||
|
||||
### 1. Use Prompt Caching for Repeated Context
|
||||
|
||||
```typescript
|
||||
// Automatic caching (simplest — caches the last cacheable block)
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
cache_control: { type: "ephemeral" },
|
||||
system: largeDocumentText, // e.g., 50KB of context
|
||||
messages: [{ role: "user", content: "Summarize the key points" }],
|
||||
});
|
||||
|
||||
// First request: full cost
|
||||
// Subsequent requests: ~90% cheaper for cached portion
|
||||
```
|
||||
|
||||
### 2. Use Token Counting Before Requests
|
||||
|
||||
```typescript
|
||||
const countResponse = await client.messages.countTokens({
|
||||
model: "claude-opus-4-7",
|
||||
messages: messages,
|
||||
system: system,
|
||||
});
|
||||
|
||||
const estimatedInputCost = countResponse.input_tokens * 0.000005; // $5/1M tokens
|
||||
console.log(`Estimated input cost: $${estimatedInputCost.toFixed(4)}`);
|
||||
```
|
||||
@@ -0,0 +1,106 @@
|
||||
# Message Batches API — TypeScript
|
||||
|
||||
The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices.
|
||||
|
||||
## Key Facts
|
||||
|
||||
- Up to 100,000 requests or 256 MB per batch
|
||||
- Most batches complete within 1 hour; maximum 24 hours
|
||||
- Results available for 29 days after creation
|
||||
- 50% cost reduction on all token usage
|
||||
- All Messages API features supported (vision, tools, caching, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Create a Batch
|
||||
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
|
||||
const client = new Anthropic();
|
||||
|
||||
const messageBatch = await client.messages.batches.create({
|
||||
requests: [
|
||||
{
|
||||
custom_id: "request-1",
|
||||
params: {
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: [
|
||||
{ role: "user", content: "Summarize climate change impacts" },
|
||||
],
|
||||
},
|
||||
},
|
||||
{
|
||||
custom_id: "request-2",
|
||||
params: {
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: [
|
||||
{ role: "user", content: "Explain quantum computing basics" },
|
||||
],
|
||||
},
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
console.log(`Batch ID: ${messageBatch.id}`);
|
||||
console.log(`Status: ${messageBatch.processing_status}`);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Poll for Completion
|
||||
|
||||
```typescript
|
||||
let batch;
|
||||
while (true) {
|
||||
batch = await client.messages.batches.retrieve(messageBatch.id);
|
||||
if (batch.processing_status === "ended") break;
|
||||
console.log(
|
||||
`Status: ${batch.processing_status}, processing: ${batch.request_counts.processing}`,
|
||||
);
|
||||
await new Promise((resolve) => setTimeout(resolve, 60_000));
|
||||
}
|
||||
|
||||
console.log("Batch complete!");
|
||||
console.log(`Succeeded: ${batch.request_counts.succeeded}`);
|
||||
console.log(`Errored: ${batch.request_counts.errored}`);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Retrieve Results
|
||||
|
||||
```typescript
|
||||
for await (const result of await client.messages.batches.results(
|
||||
messageBatch.id,
|
||||
)) {
|
||||
switch (result.result.type) {
|
||||
case "succeeded":
|
||||
console.log(
|
||||
`[${result.custom_id}] ${result.result.message.content[0].text.slice(0, 100)}`,
|
||||
);
|
||||
break;
|
||||
case "errored":
|
||||
if (result.result.error.type === "invalid_request") {
|
||||
console.log(`[${result.custom_id}] Validation error - fix and retry`);
|
||||
} else {
|
||||
console.log(`[${result.custom_id}] Server error - safe to retry`);
|
||||
}
|
||||
break;
|
||||
case "expired":
|
||||
console.log(`[${result.custom_id}] Expired - resubmit`);
|
||||
break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cancel a Batch
|
||||
|
||||
```typescript
|
||||
const cancelled = await client.messages.batches.cancel(messageBatch.id);
|
||||
console.log(`Status: ${cancelled.processing_status}`); // "canceling"
|
||||
```
|
||||
@@ -0,0 +1,98 @@
|
||||
# Files API — TypeScript
|
||||
|
||||
The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls.
|
||||
|
||||
**Beta:** Pass `betas: ["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically).
|
||||
|
||||
## Key Facts
|
||||
|
||||
- Maximum file size: 500 MB
|
||||
- Total storage: 100 GB per organization
|
||||
- Files persist until deleted
|
||||
- File operations (upload, list, delete) are free; content used in messages is billed as input tokens
|
||||
- Not available on Amazon Bedrock or Google Vertex AI
|
||||
|
||||
---
|
||||
|
||||
## Upload a File
|
||||
|
||||
```typescript
|
||||
import Anthropic, { toFile } from "@anthropic-ai/sdk";
|
||||
import fs from "fs";
|
||||
|
||||
const client = new Anthropic();
|
||||
|
||||
const uploaded = await client.beta.files.upload({
|
||||
file: await toFile(fs.createReadStream("report.pdf"), undefined, {
|
||||
type: "application/pdf",
|
||||
}),
|
||||
betas: ["files-api-2025-04-14"],
|
||||
});
|
||||
|
||||
console.log(`File ID: ${uploaded.id}`);
|
||||
console.log(`Size: ${uploaded.size_bytes} bytes`);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Use a File in Messages
|
||||
|
||||
### PDF / Text Document
|
||||
|
||||
```typescript
|
||||
const response = await client.beta.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: [
|
||||
{
|
||||
role: "user",
|
||||
content: [
|
||||
{ type: "text", text: "Summarize the key findings in this report." },
|
||||
{
|
||||
type: "document",
|
||||
source: { type: "file", file_id: uploaded.id },
|
||||
title: "Q4 Report",
|
||||
citations: { enabled: true },
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
betas: ["files-api-2025-04-14"],
|
||||
});
|
||||
|
||||
console.log(response.content[0].text);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Manage Files
|
||||
|
||||
### List Files
|
||||
|
||||
```typescript
|
||||
const files = await client.beta.files.list({
|
||||
betas: ["files-api-2025-04-14"],
|
||||
});
|
||||
for (const f of files.data) {
|
||||
console.log(`${f.id}: ${f.filename} (${f.size_bytes} bytes)`);
|
||||
}
|
||||
```
|
||||
|
||||
### Delete a File
|
||||
|
||||
```typescript
|
||||
await client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w", {
|
||||
betas: ["files-api-2025-04-14"],
|
||||
});
|
||||
```
|
||||
|
||||
### Download a File
|
||||
|
||||
```typescript
|
||||
const response = await client.beta.files.download(
|
||||
"file_011CNha8iCJcU1wXNR6q4V8w",
|
||||
{ betas: ["files-api-2025-04-14"] },
|
||||
);
|
||||
const content = Buffer.from(await response.arrayBuffer());
|
||||
await fs.promises.writeFile("output.txt", content);
|
||||
```
|
||||
@@ -0,0 +1,178 @@
|
||||
# Streaming — TypeScript
|
||||
|
||||
## Quick Start
|
||||
|
||||
```typescript
|
||||
const stream = client.messages.stream({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 64000,
|
||||
messages: [{ role: "user", content: "Write a story" }],
|
||||
});
|
||||
|
||||
for await (const event of stream) {
|
||||
if (
|
||||
event.type === "content_block_delta" &&
|
||||
event.delta.type === "text_delta"
|
||||
) {
|
||||
process.stdout.write(event.delta.text);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Handling Different Content Types
|
||||
|
||||
> **Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead.
|
||||
|
||||
```typescript
|
||||
const stream = client.messages.stream({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 64000,
|
||||
thinking: { type: "adaptive" },
|
||||
messages: [{ role: "user", content: "Analyze this problem" }],
|
||||
});
|
||||
|
||||
for await (const event of stream) {
|
||||
switch (event.type) {
|
||||
case "content_block_start":
|
||||
switch (event.content_block.type) {
|
||||
case "thinking":
|
||||
console.log("\n[Thinking...]");
|
||||
break;
|
||||
case "text":
|
||||
console.log("\n[Response:]");
|
||||
break;
|
||||
}
|
||||
break;
|
||||
case "content_block_delta":
|
||||
switch (event.delta.type) {
|
||||
case "thinking_delta":
|
||||
process.stdout.write(event.delta.thinking);
|
||||
break;
|
||||
case "text_delta":
|
||||
process.stdout.write(event.delta.text);
|
||||
break;
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Streaming with Tool Use (Tool Runner)
|
||||
|
||||
Use the tool runner with `stream: true`. The outer loop iterates over tool runner iterations (messages), the inner loop processes stream events:
|
||||
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
|
||||
import { z } from "zod";
|
||||
|
||||
const client = new Anthropic();
|
||||
|
||||
const getWeather = betaZodTool({
|
||||
name: "get_weather",
|
||||
description: "Get current weather for a location",
|
||||
inputSchema: z.object({
|
||||
location: z.string().describe("City and state, e.g., San Francisco, CA"),
|
||||
}),
|
||||
run: async ({ location }) => `72°F and sunny in ${location}`,
|
||||
});
|
||||
|
||||
const runner = client.beta.messages.toolRunner({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 64000,
|
||||
tools: [getWeather],
|
||||
messages: [
|
||||
{ role: "user", content: "What's the weather in Paris and London?" },
|
||||
],
|
||||
stream: true,
|
||||
});
|
||||
|
||||
// Outer loop: each tool runner iteration
|
||||
for await (const messageStream of runner) {
|
||||
// Inner loop: stream events for this iteration
|
||||
for await (const event of messageStream) {
|
||||
switch (event.type) {
|
||||
case "content_block_delta":
|
||||
switch (event.delta.type) {
|
||||
case "text_delta":
|
||||
process.stdout.write(event.delta.text);
|
||||
break;
|
||||
case "input_json_delta":
|
||||
// Tool input being streamed
|
||||
break;
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting the Final Message
|
||||
|
||||
```typescript
|
||||
const stream = client.messages.stream({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 64000,
|
||||
messages: [{ role: "user", content: "Hello" }],
|
||||
});
|
||||
|
||||
for await (const event of stream) {
|
||||
// Process events...
|
||||
}
|
||||
|
||||
const finalMessage = await stream.finalMessage();
|
||||
console.log(`Tokens used: ${finalMessage.usage.output_tokens}`);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stream Event Types
|
||||
|
||||
| Event Type | Description | When it fires |
|
||||
| --------------------- | --------------------------- | --------------------------------- |
|
||||
| `message_start` | Contains message metadata | Once at the beginning |
|
||||
| `content_block_start` | New content block beginning | When a text/tool_use block starts |
|
||||
| `content_block_delta` | Incremental content update | For each token/chunk |
|
||||
| `content_block_stop` | Content block complete | When a block finishes |
|
||||
| `message_delta` | Message-level updates | Contains `stop_reason`, usage |
|
||||
| `message_stop` | Message complete | Once at the end |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always flush output** — Use `process.stdout.write()` for immediate display
|
||||
2. **Handle partial responses** — If the stream is interrupted, you may have incomplete content
|
||||
3. **Track token usage** — The `message_delta` event contains usage information
|
||||
4. **Use `finalMessage()`** — Get the complete `Anthropic.Message` object even when streaming. Don't wrap `.on()` events in `new Promise()` — `finalMessage()` handles all completion/error/abort states internally
|
||||
5. **Buffer for web UIs** — Consider buffering a few tokens before rendering to avoid excessive DOM updates
|
||||
6. **Use `stream.on("text", ...)` for deltas** — The `text` event provides just the delta string, simpler than manually filtering `content_block_delta` events
|
||||
7. **For agentic loops with streaming** — See the [Streaming Manual Loop](./tool-use.md#streaming-manual-loop) section in tool-use.md for combining `stream()` + `finalMessage()` with a tool-use loop
|
||||
|
||||
## Raw SSE Format
|
||||
|
||||
If using raw HTTP (not SDKs), the stream returns Server-Sent Events:
|
||||
|
||||
```
|
||||
event: message_start
|
||||
data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}}
|
||||
|
||||
event: content_block_start
|
||||
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
|
||||
|
||||
event: content_block_delta
|
||||
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
|
||||
|
||||
event: content_block_stop
|
||||
data: {"type":"content_block_stop","index":0}
|
||||
|
||||
event: message_delta
|
||||
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}
|
||||
|
||||
event: message_stop
|
||||
data: {"type":"message_stop"}
|
||||
```
|
||||
@@ -0,0 +1,527 @@
|
||||
# Tool Use — TypeScript
|
||||
|
||||
For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md).
|
||||
|
||||
## Tool Runner (Recommended)
|
||||
|
||||
**Beta:** The tool runner is in beta in the TypeScript SDK.
|
||||
|
||||
Use `betaZodTool` with Zod schemas to define tools with a `run` function, then pass them to `client.beta.messages.toolRunner()`:
|
||||
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
|
||||
import { z } from "zod";
|
||||
|
||||
const client = new Anthropic();
|
||||
|
||||
const getWeather = betaZodTool({
|
||||
name: "get_weather",
|
||||
description: "Get current weather for a location",
|
||||
inputSchema: z.object({
|
||||
location: z.string().describe("City and state, e.g., San Francisco, CA"),
|
||||
unit: z.enum(["celsius", "fahrenheit"]).optional(),
|
||||
}),
|
||||
run: async (input) => {
|
||||
// Your implementation here
|
||||
return `72°F and sunny in ${input.location}`;
|
||||
},
|
||||
});
|
||||
|
||||
// The tool runner handles the agentic loop and returns the final message
|
||||
const finalMessage = await client.beta.messages.toolRunner({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
tools: [getWeather],
|
||||
messages: [{ role: "user", content: "What's the weather in Paris?" }],
|
||||
});
|
||||
|
||||
console.log(finalMessage.content);
|
||||
```
|
||||
|
||||
**Key benefits of the tool runner:**
|
||||
|
||||
- No manual loop — the SDK handles calling tools and feeding results back
|
||||
- Type-safe tool inputs via Zod schemas
|
||||
- Tool schemas are generated automatically from Zod definitions
|
||||
- Iteration stops automatically when Claude has no more tool calls
|
||||
|
||||
---
|
||||
|
||||
## Manual Agentic Loop
|
||||
|
||||
Use this when you need fine-grained control (custom logging, conditional tool execution, streaming individual iterations, human-in-the-loop approval):
|
||||
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
|
||||
const client = new Anthropic();
|
||||
const tools: Anthropic.Tool[] = [...]; // Your tool definitions
|
||||
let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }];
|
||||
|
||||
while (true) {
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
tools: tools,
|
||||
messages: messages,
|
||||
});
|
||||
|
||||
if (response.stop_reason === "end_turn") break;
|
||||
|
||||
// Server-side tool hit iteration limit; append assistant turn and re-send to continue
|
||||
if (response.stop_reason === "pause_turn") {
|
||||
messages.push({ role: "assistant", content: response.content });
|
||||
continue;
|
||||
}
|
||||
|
||||
const toolUseBlocks = response.content.filter(
|
||||
(b): b is Anthropic.ToolUseBlock => b.type === "tool_use",
|
||||
);
|
||||
|
||||
messages.push({ role: "assistant", content: response.content });
|
||||
|
||||
const toolResults: Anthropic.ToolResultBlockParam[] = [];
|
||||
for (const tool of toolUseBlocks) {
|
||||
const result = await executeTool(tool.name, tool.input);
|
||||
toolResults.push({
|
||||
type: "tool_result",
|
||||
tool_use_id: tool.id,
|
||||
content: result,
|
||||
});
|
||||
}
|
||||
|
||||
messages.push({ role: "user", content: toolResults });
|
||||
}
|
||||
```
|
||||
|
||||
### Streaming Manual Loop
|
||||
|
||||
Use `client.messages.stream()` + `finalMessage()` instead of `.create()` when you need streaming within a manual loop. Text deltas are streamed on each iteration; `finalMessage()` collects the complete `Message` so you can inspect `stop_reason` and extract tool-use blocks:
|
||||
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
|
||||
const client = new Anthropic();
|
||||
const tools: Anthropic.Tool[] = [...];
|
||||
let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }];
|
||||
|
||||
while (true) {
|
||||
const stream = client.messages.stream({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 64000,
|
||||
tools,
|
||||
messages,
|
||||
});
|
||||
|
||||
// Stream text deltas on each iteration
|
||||
stream.on("text", (delta) => {
|
||||
process.stdout.write(delta);
|
||||
});
|
||||
|
||||
// finalMessage() resolves with the complete Message — no need to
|
||||
// manually wire up .on("message") / .on("error") / .on("abort")
|
||||
const message = await stream.finalMessage();
|
||||
|
||||
if (message.stop_reason === "end_turn") break;
|
||||
|
||||
// Server-side tool hit iteration limit; append assistant turn and re-send to continue
|
||||
if (message.stop_reason === "pause_turn") {
|
||||
messages.push({ role: "assistant", content: message.content });
|
||||
continue;
|
||||
}
|
||||
|
||||
const toolUseBlocks = message.content.filter(
|
||||
(b): b is Anthropic.ToolUseBlock => b.type === "tool_use",
|
||||
);
|
||||
|
||||
messages.push({ role: "assistant", content: message.content });
|
||||
|
||||
const toolResults: Anthropic.ToolResultBlockParam[] = [];
|
||||
for (const tool of toolUseBlocks) {
|
||||
const result = await executeTool(tool.name, tool.input);
|
||||
toolResults.push({
|
||||
type: "tool_result",
|
||||
tool_use_id: tool.id,
|
||||
content: result,
|
||||
});
|
||||
}
|
||||
|
||||
messages.push({ role: "user", content: toolResults });
|
||||
}
|
||||
```
|
||||
|
||||
> **Important:** Don't wrap `.on()` events in `new Promise()` to collect the final message — use `stream.finalMessage()` instead. The SDK handles all error/abort/completion states internally.
|
||||
|
||||
> **Error handling in the loop:** Use the SDK's typed exceptions (e.g., `Anthropic.RateLimitError`, `Anthropic.APIError`) — see [Error Handling](./README.md#error-handling) for examples. Don't check error messages with string matching.
|
||||
|
||||
> **SDK types:** Use `Anthropic.MessageParam`, `Anthropic.Tool`, `Anthropic.ToolUseBlock`, `Anthropic.ToolResultBlockParam`, `Anthropic.Message`, etc. for all API-related data structures. Don't redefine equivalent interfaces.
|
||||
|
||||
---
|
||||
|
||||
## Handling Tool Results
|
||||
|
||||
```typescript
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
tools: tools,
|
||||
messages: [{ role: "user", content: "What's the weather in Paris?" }],
|
||||
});
|
||||
|
||||
for (const block of response.content) {
|
||||
if (block.type === "tool_use") {
|
||||
const result = await executeTool(block.name, block.input);
|
||||
|
||||
const followup = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
tools: tools,
|
||||
messages: [
|
||||
{ role: "user", content: "What's the weather in Paris?" },
|
||||
{ role: "assistant", content: response.content },
|
||||
{
|
||||
role: "user",
|
||||
content: [
|
||||
{ type: "tool_result", tool_use_id: block.id, content: result },
|
||||
],
|
||||
},
|
||||
],
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tool Choice
|
||||
|
||||
```typescript
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
tools: tools,
|
||||
tool_choice: { type: "tool", name: "get_weather" },
|
||||
messages: [{ role: "user", content: "What's the weather in Paris?" }],
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Tools
|
||||
|
||||
Version-suffixed `type` literals; `name` is fixed per interface. Pass plain object literals — the `ToolUnion` type is satisfied structurally. **The `name`/`type` pair must match the interface**: mixing `str_replace_based_edit_tool` (20250728 name) with `text_editor_20250124` (which expects `str_replace_editor`) is a TS2322.
|
||||
|
||||
**Don't type-annotate as `Tool[]`** — `Tool` is just the custom-tool variant. Let structural typing infer from the `tools` param, or annotate as `Anthropic.Messages.ToolUnion[]` if you must:
|
||||
|
||||
```typescript
|
||||
// ✓ let inference work — no annotation
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
tools: [
|
||||
{ type: "text_editor_20250728", name: "str_replace_based_edit_tool" },
|
||||
{ type: "bash_20250124", name: "bash" },
|
||||
{ type: "web_search_20260209", name: "web_search" },
|
||||
{ type: "code_execution_20260120", name: "code_execution" },
|
||||
],
|
||||
messages: [{ role: "user", content: "..." }],
|
||||
});
|
||||
|
||||
// ✗ this is a TS2352 — Tool is the CUSTOM tool variant only
|
||||
// const tools: Anthropic.Tool[] = [{ type: "text_editor_20250728", ... }]
|
||||
```
|
||||
|
||||
| Interface | `name` | `type` |
|
||||
|---|---|---|
|
||||
| `ToolTextEditor20250124` | `str_replace_editor` | `text_editor_20250124` |
|
||||
| `ToolTextEditor20250429` | `str_replace_based_edit_tool` | `text_editor_20250429` |
|
||||
| `ToolTextEditor20250728` | `str_replace_based_edit_tool` | `text_editor_20250728` |
|
||||
| `ToolBash20250124` | `bash` | `bash_20250124` |
|
||||
| `WebSearchTool20260209` | `web_search` | `web_search_20260209` |
|
||||
| `WebFetchTool20260209` | `web_fetch` | `web_fetch_20260209` |
|
||||
| `CodeExecutionTool20260120` | `code_execution` | `code_execution_20260120` |
|
||||
|
||||
**Don't mix beta and non-beta types**: if you call `client.beta.messages.create()`, the response `content` is `BetaContentBlock[]` — you cannot pass that to a non-beta `ContentBlockParam[]` without narrowing each element.
|
||||
|
||||
---
|
||||
|
||||
|
||||
## Code Execution
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
|
||||
const client = new Anthropic();
|
||||
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: [
|
||||
{
|
||||
role: "user",
|
||||
content:
|
||||
"Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]",
|
||||
},
|
||||
],
|
||||
tools: [{ type: "code_execution_20260120", name: "code_execution" }],
|
||||
});
|
||||
```
|
||||
|
||||
### Reading Local Files (ESM note)
|
||||
|
||||
`__dirname` doesn't exist in ES modules. For script-relative paths use `import.meta.url`:
|
||||
|
||||
```typescript
|
||||
import { readFileSync } from "fs";
|
||||
import { fileURLToPath } from "url";
|
||||
import { dirname, join } from "path";
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const pdfBytes = readFileSync(join(__dirname, "sample.pdf"));
|
||||
```
|
||||
|
||||
Or use a CWD-relative path if the script runs from a known directory: `readFileSync("./sample.pdf")`.
|
||||
|
||||
### Upload Files for Analysis
|
||||
|
||||
```typescript
|
||||
import Anthropic, { toFile } from "@anthropic-ai/sdk";
|
||||
import { createReadStream } from "fs";
|
||||
|
||||
const client = new Anthropic();
|
||||
|
||||
// 1. Upload a file
|
||||
const uploaded = await client.beta.files.upload({
|
||||
file: await toFile(createReadStream("sales_data.csv"), undefined, {
|
||||
type: "text/csv",
|
||||
}),
|
||||
betas: ["files-api-2025-04-14"],
|
||||
});
|
||||
|
||||
// 2. Pass to code execution
|
||||
// Code execution is GA; Files API is still beta (pass via RequestOptions)
|
||||
const response = await client.messages.create(
|
||||
{
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: [
|
||||
{
|
||||
role: "user",
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: "Analyze this sales data. Show trends and create a visualization.",
|
||||
},
|
||||
{ type: "container_upload", file_id: uploaded.id },
|
||||
],
|
||||
},
|
||||
],
|
||||
tools: [{ type: "code_execution_20260120", name: "code_execution" }],
|
||||
},
|
||||
{ headers: { "anthropic-beta": "files-api-2025-04-14" } },
|
||||
);
|
||||
```
|
||||
|
||||
### Retrieve Generated Files
|
||||
|
||||
```typescript
|
||||
import path from "path";
|
||||
import fs from "fs";
|
||||
|
||||
const OUTPUT_DIR = "./claude_outputs";
|
||||
await fs.promises.mkdir(OUTPUT_DIR, { recursive: true });
|
||||
|
||||
for (const block of response.content) {
|
||||
if (block.type === "bash_code_execution_tool_result") {
|
||||
const result = block.content;
|
||||
if (result.type === "bash_code_execution_result" && result.content) {
|
||||
for (const fileRef of result.content) {
|
||||
if (fileRef.type === "bash_code_execution_output") {
|
||||
const metadata = await client.beta.files.retrieveMetadata(
|
||||
fileRef.file_id,
|
||||
);
|
||||
const downloadResponse = await client.beta.files.download(fileRef.file_id);
|
||||
const fileBytes = Buffer.from(await downloadResponse.arrayBuffer());
|
||||
const safeName = path.basename(metadata.filename);
|
||||
if (!safeName || safeName === "." || safeName === "..") {
|
||||
console.warn(`Skipping invalid filename: ${metadata.filename}`);
|
||||
continue;
|
||||
}
|
||||
const outputPath = path.join(OUTPUT_DIR, safeName);
|
||||
await fs.promises.writeFile(outputPath, fileBytes);
|
||||
console.log(`Saved: ${outputPath}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Container Reuse
|
||||
|
||||
```typescript
|
||||
// First request: set up environment
|
||||
const response1 = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: [
|
||||
{
|
||||
role: "user",
|
||||
content: "Install tabulate and create data.json with sample user data",
|
||||
},
|
||||
],
|
||||
tools: [{ type: "code_execution_20260120", name: "code_execution" }],
|
||||
});
|
||||
|
||||
// Reuse container
|
||||
// container is nullable — set only when using server-side code execution
|
||||
const containerId = response1.container!.id;
|
||||
|
||||
const response2 = await client.messages.create({
|
||||
container: containerId,
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: [
|
||||
{
|
||||
role: "user",
|
||||
content: "Read data.json and display as a formatted table",
|
||||
},
|
||||
],
|
||||
tools: [{ type: "code_execution_20260120", name: "code_execution" }],
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Memory Tool
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```typescript
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: [
|
||||
{
|
||||
role: "user",
|
||||
content: "Remember that my preferred language is TypeScript.",
|
||||
},
|
||||
],
|
||||
tools: [{ type: "memory_20250818", name: "memory" }],
|
||||
});
|
||||
```
|
||||
|
||||
### SDK Memory Helper
|
||||
|
||||
Use `betaMemoryTool` with a `MemoryToolHandlers` implementation:
|
||||
|
||||
```typescript
|
||||
import {
|
||||
betaMemoryTool,
|
||||
type MemoryToolHandlers,
|
||||
} from "@anthropic-ai/sdk/helpers/beta/memory";
|
||||
|
||||
const handlers: MemoryToolHandlers = {
|
||||
async view(command) { ... },
|
||||
async create(command) { ... },
|
||||
async str_replace(command) { ... },
|
||||
async insert(command) { ... },
|
||||
async delete(command) { ... },
|
||||
async rename(command) { ... },
|
||||
};
|
||||
|
||||
const memory = betaMemoryTool(handlers);
|
||||
|
||||
const runner = client.beta.messages.toolRunner({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
tools: [memory],
|
||||
messages: [{ role: "user", content: "Remember my preferences" }],
|
||||
});
|
||||
|
||||
for await (const message of runner) {
|
||||
console.log(message);
|
||||
}
|
||||
```
|
||||
|
||||
For full implementation examples, use WebFetch:
|
||||
|
||||
- `https://github.com/anthropics/anthropic-sdk-typescript/blob/main/examples/tools-helpers-memory.ts`
|
||||
|
||||
---
|
||||
|
||||
## Structured Outputs
|
||||
|
||||
### JSON Outputs (Zod — Recommended)
|
||||
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
import { z } from "zod";
|
||||
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
|
||||
|
||||
const ContactInfoSchema = z.object({
|
||||
name: z.string(),
|
||||
email: z.string(),
|
||||
plan: z.string(),
|
||||
interests: z.array(z.string()),
|
||||
demo_requested: z.boolean(),
|
||||
});
|
||||
|
||||
const client = new Anthropic();
|
||||
|
||||
const response = await client.messages.parse({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: [
|
||||
{
|
||||
role: "user",
|
||||
content:
|
||||
"Extract: Jane Doe (jane@co.com) wants Enterprise, interested in API and SDKs, wants a demo.",
|
||||
},
|
||||
],
|
||||
output_config: {
|
||||
format: zodOutputFormat(ContactInfoSchema),
|
||||
},
|
||||
});
|
||||
|
||||
// parsed_output is null if parsing failed — assert or guard
|
||||
console.log(response.parsed_output!.name); // "Jane Doe"
|
||||
```
|
||||
|
||||
### Strict Tool Use
|
||||
|
||||
```typescript
|
||||
const response = await client.messages.create({
|
||||
model: "claude-opus-4-7",
|
||||
max_tokens: 16000,
|
||||
messages: [
|
||||
{
|
||||
role: "user",
|
||||
content: "Book a flight to Tokyo for 2 passengers on March 15",
|
||||
},
|
||||
],
|
||||
tools: [
|
||||
{
|
||||
name: "book_flight",
|
||||
description: "Book a flight to a destination",
|
||||
strict: true,
|
||||
input_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
destination: { type: "string" },
|
||||
date: { type: "string", format: "date" },
|
||||
passengers: {
|
||||
type: "integer",
|
||||
enum: [1, 2, 3, 4, 5, 6, 7, 8],
|
||||
},
|
||||
},
|
||||
required: ["destination", "date", "passengers"],
|
||||
additionalProperties: false,
|
||||
},
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
@@ -0,0 +1,360 @@
|
||||
# Managed Agents — TypeScript
|
||||
|
||||
> **Bindings not shown here:** This README covers the most common managed-agents flows for TypeScript. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the TypeScript SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
|
||||
|
||||
> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @anthropic-ai/sdk
|
||||
```
|
||||
|
||||
## Client Initialization
|
||||
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
|
||||
// Default (uses ANTHROPIC_API_KEY env var)
|
||||
const client = new Anthropic();
|
||||
|
||||
// Explicit API key
|
||||
const client = new Anthropic({ apiKey: "your-api-key" });
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create an Environment
|
||||
|
||||
```typescript
|
||||
const environment = await client.beta.environments.create(
|
||||
{
|
||||
name: "my-dev-env",
|
||||
config: {
|
||||
type: "cloud",
|
||||
networking: { type: "unrestricted" },
|
||||
},
|
||||
},
|
||||
);
|
||||
console.log(environment.id); // env_...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create an Agent (required first step)
|
||||
|
||||
> ⚠️ **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `agents.create()` — the session only takes `agent: { type: "agent", id: agent.id }`.
|
||||
|
||||
### Minimal
|
||||
|
||||
```typescript
|
||||
// 1. Create the agent (reusable, versioned)
|
||||
const agent = await client.beta.agents.create(
|
||||
{
|
||||
name: "Coding Assistant",
|
||||
model: "claude-opus-4-7",
|
||||
tools: [{ type: "agent_toolset_20260401", default_config: { enabled: true } }],
|
||||
},
|
||||
);
|
||||
|
||||
// 2. Start a session
|
||||
const session = await client.beta.sessions.create(
|
||||
{
|
||||
agent: { type: "agent", id: agent.id, version: agent.version },
|
||||
environment_id: environment.id,
|
||||
},
|
||||
);
|
||||
console.log(session.id, session.status);
|
||||
```
|
||||
|
||||
### With system prompt and custom tools
|
||||
|
||||
```typescript
|
||||
const agent = await client.beta.agents.create(
|
||||
{
|
||||
name: "Code Reviewer",
|
||||
model: "claude-opus-4-7",
|
||||
system: "You are a senior code reviewer.",
|
||||
tools: [
|
||||
{ type: "agent_toolset_20260401", default_config: { enabled: true } },
|
||||
{
|
||||
type: "custom",
|
||||
name: "run_tests",
|
||||
description: "Run the test suite",
|
||||
input_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
test_path: { type: "string", description: "Path to test file" },
|
||||
},
|
||||
required: ["test_path"],
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
);
|
||||
|
||||
const session = await client.beta.sessions.create(
|
||||
{
|
||||
agent: { type: "agent", id: agent.id, version: agent.version },
|
||||
environment_id: environment.id,
|
||||
title: "Code review session",
|
||||
resources: [
|
||||
{
|
||||
type: "github_repository",
|
||||
url: "https://github.com/owner/repo",
|
||||
mount_path: "/workspace/repo",
|
||||
authorization_token: process.env.GITHUB_TOKEN,
|
||||
branch: "main",
|
||||
},
|
||||
],
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Send a User Message
|
||||
|
||||
```typescript
|
||||
await client.beta.sessions.events.send(
|
||||
session.id,
|
||||
{
|
||||
events: [
|
||||
{
|
||||
type: "user.message",
|
||||
content: [{ type: "text", text: "Review the auth module" }],
|
||||
},
|
||||
],
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns).
|
||||
|
||||
---
|
||||
|
||||
## Stream Events (SSE)
|
||||
|
||||
```typescript
|
||||
// Stream-first: open stream and send concurrently
|
||||
const [events] = await Promise.all([
|
||||
collectStream(session.id),
|
||||
client.beta.sessions.events.send(
|
||||
session.id,
|
||||
{ events: [{ type: "user.message", content: [{ type: "text", text: "..." }] }] },
|
||||
),
|
||||
]);
|
||||
|
||||
// Standalone stream iteration:
|
||||
const stream = await client.beta.sessions.stream(
|
||||
session.id,
|
||||
);
|
||||
|
||||
for await (const event of stream) {
|
||||
switch (event.type) {
|
||||
case "agent.message":
|
||||
for (const block of event.content) {
|
||||
if (block.type === "text") {
|
||||
process.stdout.write(block.text);
|
||||
}
|
||||
}
|
||||
break;
|
||||
case "agent.custom_tool_use":
|
||||
// Custom tool invocation — session is now idle
|
||||
console.log(`\nCustom tool call: ${event.tool_name}`);
|
||||
console.log(`Input: ${JSON.stringify(event.input)}`);
|
||||
break;
|
||||
case "session.status_idle":
|
||||
console.log("\n--- Agent idle ---");
|
||||
break;
|
||||
case "session.status_terminated":
|
||||
console.log("\n--- Session terminated ---");
|
||||
break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Provide Custom Tool Result
|
||||
|
||||
```typescript
|
||||
await client.beta.sessions.events.send(
|
||||
session.id,
|
||||
{
|
||||
events: [
|
||||
{
|
||||
type: "user.custom_tool_result",
|
||||
custom_tool_use_id: "sevt_abc123",
|
||||
content: [{ type: "text", text: "All 42 tests passed." }],
|
||||
},
|
||||
],
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Poll Events
|
||||
|
||||
```typescript
|
||||
const events = await client.beta.sessions.events.list(
|
||||
session.id,
|
||||
);
|
||||
for (const event of events.data) {
|
||||
console.log(`${event.type}: ${event.id}`);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Full Streaming Loop with Custom Tools
|
||||
|
||||
```typescript
|
||||
function runCustomTool(toolName: string, toolInput: unknown): string {
|
||||
if (toolName === "run_tests") {
|
||||
// Your tool implementation here
|
||||
return "All tests passed.";
|
||||
}
|
||||
return `Unknown tool: ${toolName}`;
|
||||
}
|
||||
|
||||
async function runSession(client: Anthropic, sessionId: string) {
|
||||
while (true) {
|
||||
const stream = await client.beta.sessions.stream(
|
||||
sessionId,
|
||||
);
|
||||
|
||||
const toolCalls: Array<{ custom_tool_use_id: string; tool_name: string; input: unknown }> = [];
|
||||
|
||||
for await (const event of stream) {
|
||||
if (event.type === "agent.message") {
|
||||
for (const block of event.content) {
|
||||
if (block.type === "text") {
|
||||
process.stdout.write(block.text);
|
||||
}
|
||||
}
|
||||
} else if (event.type === "agent.custom_tool_use") {
|
||||
toolCalls.push({
|
||||
id: event.id,
|
||||
tool_name: event.tool_name,
|
||||
input: event.input,
|
||||
});
|
||||
} else if (event.type === "session.status_idle") {
|
||||
break;
|
||||
} else if (event.type === "session.status_terminated") {
|
||||
return;
|
||||
}
|
||||
}
|
||||
|
||||
if (toolCalls.length === 0) break;
|
||||
|
||||
// Process custom tool calls
|
||||
const results = toolCalls.map((call) => ({
|
||||
type: "user.custom_tool_result" as const,
|
||||
custom_tool_use_id: call.id,
|
||||
content: [{ type: "text" as const, text: runCustomTool(call.tool_name, call.input) }],
|
||||
}));
|
||||
|
||||
await client.beta.sessions.events.send(
|
||||
sessionId,
|
||||
{ events: results },
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Upload a File
|
||||
|
||||
```typescript
|
||||
import fs from "fs";
|
||||
|
||||
const file = await client.beta.files.upload({
|
||||
file: fs.createReadStream("data.csv"),
|
||||
purpose: "agent",
|
||||
});
|
||||
|
||||
// Use in a session
|
||||
const session = await client.beta.sessions.create(
|
||||
{
|
||||
agent: { type: "agent", id: agent.id, version: agent.version },
|
||||
environment_id: environment.id,
|
||||
resources: [{ type: "file", file_id: file.id, mount_path: "/workspace/data.csv" }],
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## List and Download Session Files
|
||||
|
||||
List files the agent wrote to `/mnt/session/outputs/` during a session, then download them.
|
||||
|
||||
```typescript
|
||||
import fs from "fs";
|
||||
|
||||
// List files associated with a session
|
||||
const files = await client.beta.files.list({
|
||||
scope_id: session.id,
|
||||
betas: ["managed-agents-2026-04-01"],
|
||||
});
|
||||
for (const f of files.data) {
|
||||
console.log(f.filename, f.size_bytes);
|
||||
|
||||
// Download and save to disk
|
||||
const resp = await client.beta.files.download(f.id);
|
||||
const buffer = Buffer.from(await resp.arrayBuffer());
|
||||
fs.writeFileSync(f.filename, buffer);
|
||||
}
|
||||
```
|
||||
|
||||
> 💡 There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if the list is empty.
|
||||
|
||||
---
|
||||
|
||||
## Session Management
|
||||
|
||||
```typescript
|
||||
// Get session details
|
||||
const session = await client.beta.sessions.retrieve("sesn_011CZxAbc123Def456");
|
||||
console.log(session.status, session.usage);
|
||||
|
||||
// List sessions
|
||||
const sessions = await client.beta.sessions.list();
|
||||
|
||||
// Delete a session
|
||||
await client.beta.sessions.delete("sesn_011CZxAbc123Def456");
|
||||
|
||||
// Archive a session
|
||||
await client.beta.sessions.archive("sesn_011CZxAbc123Def456");
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Integration
|
||||
|
||||
```typescript
|
||||
// Agent declares MCP server (no auth here — auth goes in a vault)
|
||||
const agent = await client.beta.agents.create({
|
||||
name: "MCP Agent",
|
||||
model: "claude-opus-4-7",
|
||||
mcp_servers: [
|
||||
{ type: "url", name: "my-tools", url: "https://my-mcp-server.example.com/sse" },
|
||||
],
|
||||
tools: [
|
||||
{ type: "agent_toolset_20260401", default_config: { enabled: true } },
|
||||
{ type: "mcp_toolset", mcp_server_name: "my-tools" },
|
||||
],
|
||||
});
|
||||
|
||||
// Session attaches vault(s) containing credentials for those MCP server URLs
|
||||
const session = await client.beta.sessions.create({
|
||||
agent: agent.id,
|
||||
environment_id: environment.id,
|
||||
vault_ids: [vault.id],
|
||||
});
|
||||
```
|
||||
|
||||
See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials.
|
||||
@@ -0,0 +1,202 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
@@ -0,0 +1,456 @@
|
||||
---
|
||||
name: create-skill
|
||||
description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
|
||||
license: Complete terms in LICENSE.txt
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
|
||||
A skill for creating new skills and iteratively improving them.
|
||||
|
||||
At a high level, the process of creating a skill goes like this:
|
||||
|
||||
- Decide what you want the skill to do and roughly how it should do it
|
||||
- Write a draft of the skill
|
||||
- Create a few test prompts and run the agent with access to the skill on them
|
||||
- Help the user evaluate the results both qualitatively and quantitatively
|
||||
- While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them). Then explain them to the user (or if they already existed, explain the ones that already exist)
|
||||
- Use the `eval-viewer/generate_review.py` script to show the user the results for them to look at, and also let them look at the quantitative metrics
|
||||
- Rewrite the skill based on feedback from the user's evaluation of the results (and also if there are any glaring flaws that become apparent from the quantitative benchmarks)
|
||||
- Repeat until you're satisfied
|
||||
- Expand the test set and try again at larger scale
|
||||
|
||||
Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages. So for instance, maybe they're like "I want to make a skill for X". You can help narrow down what they mean, write a draft, write the test cases, figure out how they want to evaluate, run all the prompts, and repeat.
|
||||
|
||||
On the other hand, maybe they already have a draft of the skill. In this case you can go straight to the eval/iterate part of the loop.
|
||||
|
||||
Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead.
|
||||
|
||||
Then after the skill is done (but again, the order is flexible), you can also run the skill description improver, which we have a whole separate script for, to optimize the triggering of the skill.
|
||||
|
||||
Cool? Cool.
|
||||
|
||||
## Communicating with the user
|
||||
|
||||
The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. There's a trend now where the power of AI agents is inspiring non-developers to open up their terminals. On the other hand, the bulk of users are probably fairly computer-literate.
|
||||
|
||||
So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea:
|
||||
|
||||
- "evaluation" and "benchmark" are borderline, but OK
|
||||
- for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them
|
||||
|
||||
It's OK to briefly explain terms if you're in doubt, and feel free to clarify terms with a short definition if you're unsure if the user will get it.
|
||||
|
||||
---
|
||||
|
||||
## Creating a skill
|
||||
|
||||
### Capture Intent
|
||||
|
||||
Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill the gaps, and should confirm before proceeding to the next step.
|
||||
|
||||
1. What should this skill enable the agent to do?
|
||||
2. When should this skill trigger? (what user phrases/contexts)
|
||||
3. What's the expected output format?
|
||||
4. Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them. Suggest the appropriate default based on the skill type, but let the user decide.
|
||||
|
||||
### Interview and Research
|
||||
|
||||
Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out.
|
||||
|
||||
Check available MCPs - if useful for research (searching docs, finding similar skills, looking up best practices), research in parallel via subagents if available, otherwise inline. Come prepared with context to reduce burden on the user.
|
||||
|
||||
### Write the SKILL.md
|
||||
|
||||
Based on the user interview, fill in these components:
|
||||
|
||||
- **name**: Skill identifier
|
||||
- **description**: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently agents have a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal data.", you might write "How to build a simple fast dashboard to display internal data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
|
||||
- **compatibility**: Required tools, dependencies (optional, rarely needed)
|
||||
- **the rest of the skill :)**
|
||||
|
||||
### Skill Writing Guide
|
||||
|
||||
#### Anatomy of a Skill
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (required)
|
||||
│ ├── YAML frontmatter (name, description required)
|
||||
│ └── Markdown instructions
|
||||
└── Bundled Resources (optional)
|
||||
├── scripts/ - Executable code for deterministic/repetitive tasks
|
||||
├── references/ - Docs loaded into context as needed
|
||||
└── assets/ - Files used in output (templates, icons, fonts)
|
||||
```
|
||||
|
||||
#### Progressive Disclosure
|
||||
|
||||
Skills use a three-level loading system:
|
||||
1. **Metadata** (name + description) - Always in context (~100 words)
|
||||
2. **SKILL.md body** - In context whenever skill triggers (<500 lines ideal)
|
||||
3. **Bundled resources** - As needed (unlimited, scripts can execute without loading)
|
||||
|
||||
These word counts are approximate and you can feel free to go longer if needed.
|
||||
|
||||
**Key patterns:**
|
||||
- Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next to follow up.
|
||||
- Reference files clearly from SKILL.md with guidance on when to read them
|
||||
- For large reference files (>300 lines), include a table of contents
|
||||
|
||||
**Domain organization**: When a skill supports multiple domains/frameworks, organize by variant:
|
||||
```
|
||||
cloud-deploy/
|
||||
├── SKILL.md (workflow + selection)
|
||||
└── references/
|
||||
├── aws.md
|
||||
├── gcp.md
|
||||
└── azure.md
|
||||
```
|
||||
The agent reads only the relevant reference file.
|
||||
|
||||
#### Principle of Lack of Surprise
|
||||
|
||||
This goes without saying, but skills must not contain malware, exploit code, or any content that could compromise system security. A skill's contents should not surprise the user in their intent if described. Don't go along with requests to create misleading skills or skills designed to facilitate unauthorized access, data exfiltration, or other malicious activities. Things like a "roleplay as an XYZ" are OK though.
|
||||
|
||||
#### Writing Patterns
|
||||
|
||||
Prefer using the imperative form in instructions.
|
||||
|
||||
**Defining output formats** - You can do it like this:
|
||||
```markdown
|
||||
## Report structure
|
||||
ALWAYS use this exact template:
|
||||
# [Title]
|
||||
## Executive summary
|
||||
## Key findings
|
||||
## Recommendations
|
||||
```
|
||||
|
||||
**Examples pattern** - It's useful to include examples. You can format them like this (but if "Input" and "Output" are in the examples you might want to deviate a little):
|
||||
```markdown
|
||||
## Commit message format
|
||||
**Example 1:**
|
||||
Input: Added user authentication with JWT tokens
|
||||
Output: feat(auth): implement JWT-based authentication
|
||||
```
|
||||
|
||||
### Writing Style
|
||||
|
||||
Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs. Use theory of mind and try to make the skill general and not super-narrow to specific examples. Start by writing a draft and then look at it with fresh eyes and improve it.
|
||||
|
||||
### Test Cases
|
||||
|
||||
After writing the skill draft, come up with 2-3 realistic test prompts — the kind of thing a real user would actually say. Share them with the user: [you don't have to use this exact language] "Here are a few test cases I'd like to try. Do these look right, or do you want to add more?" Then run them.
|
||||
|
||||
Save test cases to `evals/evals.json`. Don't write assertions yet — just the prompts. You'll draft assertions in the next step while the runs are in progress.
|
||||
|
||||
```json
|
||||
{
|
||||
"skill_name": "example-skill",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "User's task prompt",
|
||||
"expected_output": "Description of expected result",
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
See `references/schemas.md` for the full schema (including the `assertions` field, which you'll add later).
|
||||
|
||||
## Running and evaluating test cases
|
||||
|
||||
This section is one continuous sequence — don't stop partway through. Do NOT use `/skill-test` or any other testing skill.
|
||||
|
||||
Put results in `<skill-name>-workspace/` as a sibling to the skill directory. Within the workspace, organize results by iteration (`iteration-1/`, `iteration-2/`, etc.) and within that, each test case gets a directory (`eval-0/`, `eval-1/`, etc.). Don't create all of this upfront — just create directories as you go.
|
||||
|
||||
### Step 1: Spawn all runs (with-skill AND baseline) in the same turn
|
||||
|
||||
For each test case, spawn two subagents in the same turn — one with the skill, one without. This is important: don't spawn the with-skill runs first and then come back for baselines later. Launch everything at once so it all finishes around the same time.
|
||||
|
||||
**With-skill run:**
|
||||
|
||||
```
|
||||
Execute this task:
|
||||
- Skill path: <path-to-skill>
|
||||
- Task: <eval prompt>
|
||||
- Input files: <eval files if any, or "none">
|
||||
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
|
||||
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">
|
||||
```
|
||||
|
||||
**Baseline run** (same prompt, but the baseline depends on context):
|
||||
- **Creating a new skill**: no skill at all. Same prompt, no skill path, save to `without_skill/outputs/`.
|
||||
- **Improving an existing skill**: the old version. Before editing, snapshot the skill (`cp -r <skill-path> <workspace>/skill-snapshot/`), then point the baseline subagent at the snapshot. Save to `old_skill/outputs/`.
|
||||
|
||||
Write an `eval_metadata.json` for each test case (assertions can be empty for now). Give each eval a descriptive name based on what it's testing — not just "eval-0". Use this name for the directory too. If this iteration uses new or modified eval prompts, create these files for each new eval directory — don't assume they carry over from previous iterations.
|
||||
|
||||
```json
|
||||
{
|
||||
"eval_id": 0,
|
||||
"eval_name": "descriptive-name-here",
|
||||
"prompt": "The user's task prompt",
|
||||
"assertions": []
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: While runs are in progress, draft assertions
|
||||
|
||||
Don't just wait for the runs to finish — you can use this time productively. Draft quantitative assertions for each test case and explain them to the user. If assertions already exist in `evals/evals.json`, review them and explain what they check.
|
||||
|
||||
Good assertions are objectively verifiable and have descriptive names — they should read clearly in the benchmark viewer so someone glancing at the results immediately understands what each one checks. Subjective skills (writing style, design quality) are better evaluated qualitatively — don't force assertions onto things that need human judgment.
|
||||
|
||||
Update the `eval_metadata.json` files and `evals/evals.json` with the assertions once drafted. Also explain to the user what they'll see in the viewer — both the qualitative outputs and the quantitative benchmark.
|
||||
|
||||
### Step 3: As runs complete, capture timing data
|
||||
|
||||
When each subagent task completes, you receive a notification containing `total_tokens` and `duration_ms`. Save this data immediately to `timing.json` in the run directory:
|
||||
|
||||
```json
|
||||
{
|
||||
"total_tokens": 84852,
|
||||
"duration_ms": 23332,
|
||||
"total_duration_seconds": 23.3
|
||||
}
|
||||
```
|
||||
|
||||
This is the only opportunity to capture this data — it comes through the task notification and isn't persisted elsewhere. Process each notification as it arrives rather than trying to batch them.
|
||||
|
||||
### Step 4: Grade, aggregate, and launch the viewer
|
||||
|
||||
Once all runs are done:
|
||||
|
||||
1. **Grade each run** — spawn a grader subagent (or grade inline) that reads `agents/grader.md` and evaluates each assertion against the outputs. Save results to `grading.json` in each run directory. The grading.json expectations array must use the fields `text`, `passed`, and `evidence` (not `name`/`met`/`details` or other variants) — the viewer depends on these exact field names. For assertions that can be checked programmatically, write and run a script rather than eyeballing it — scripts are faster, more reliable, and can be reused across iterations.
|
||||
|
||||
2. **Aggregate into benchmark** — run the aggregation script from the skill-creator directory:
|
||||
```bash
|
||||
python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
|
||||
```
|
||||
This produces `benchmark.json` and `benchmark.md` with pass_rate, time, and tokens for each configuration, with mean ± stddev and the delta. If generating benchmark.json manually, see `references/schemas.md` for the exact schema the viewer expects.
|
||||
Put each with_skill version before its baseline counterpart.
|
||||
|
||||
3. **Do an analyst pass** — read the benchmark data and surface patterns the aggregate stats might hide. See `agents/analyzer.md` (the "Analyzing Benchmark Results" section) for what to look for — things like assertions that always pass regardless of skill (non-discriminating), high-variance evals (possibly flaky), and time/token tradeoffs.
|
||||
|
||||
4. **Launch the viewer** with both qualitative outputs and quantitative data:
|
||||
```bash
|
||||
nohup python <skill-creator-path>/eval-viewer/generate_review.py \
|
||||
<workspace>/iteration-N \
|
||||
--skill-name "my-skill" \
|
||||
--benchmark <workspace>/iteration-N/benchmark.json \
|
||||
> /dev/null 2>&1 &
|
||||
VIEWER_PID=$!
|
||||
```
|
||||
For iteration 2+, also pass `--previous-workspace <workspace>/iteration-<N-1>`.
|
||||
|
||||
**Headless environments:** If `webbrowser.open()` is not available or the environment has no display, use `--static <output_path>` to write a standalone HTML file instead of starting a server. Feedback will be downloaded as a `feedback.json` file when the user clicks "Submit All Reviews". After download, copy `feedback.json` into the workspace directory for the next iteration to pick up.
|
||||
|
||||
Note: please use generate_review.py to create the viewer; there's no need to write custom HTML.
|
||||
|
||||
5. **Tell the user** something like: "I've opened the results in your browser. There are two tabs — 'Outputs' lets you click through each test case and leave feedback, 'Benchmark' shows the quantitative comparison. When you're done, come back here and let me know."
|
||||
|
||||
### What the user sees in the viewer
|
||||
|
||||
The "Outputs" tab shows one test case at a time:
|
||||
- **Prompt**: the task that was given
|
||||
- **Output**: the files the skill produced, rendered inline where possible
|
||||
- **Previous Output** (iteration 2+): collapsed section showing last iteration's output
|
||||
- **Formal Grades** (if grading was run): collapsed section showing assertion pass/fail
|
||||
- **Feedback**: a textbox that auto-saves as they type
|
||||
- **Previous Feedback** (iteration 2+): their comments from last time, shown below the textbox
|
||||
|
||||
The "Benchmark" tab shows the stats summary: pass rates, timing, and token usage for each configuration, with per-eval breakdowns and analyst observations.
|
||||
|
||||
Navigation is via prev/next buttons or arrow keys. When done, they click "Submit All Reviews" which saves all feedback to `feedback.json`.
|
||||
|
||||
### Step 5: Read the feedback
|
||||
|
||||
When the user tells you they're done, read `feedback.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"reviews": [
|
||||
{"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
|
||||
{"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
|
||||
{"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
|
||||
],
|
||||
"status": "complete"
|
||||
}
|
||||
```
|
||||
|
||||
Empty feedback means the user thought it was fine. Focus your improvements on the test cases where the user had specific complaints.
|
||||
|
||||
Kill the viewer server when you're done with it:
|
||||
|
||||
```bash
|
||||
kill $VIEWER_PID 2>/dev/null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Improving the skill
|
||||
|
||||
This is the heart of the loop. You've run the test cases, the user has reviewed the results, and now you need to make the skill better based on their feedback.
|
||||
|
||||
### How to think about improvements
|
||||
|
||||
1. **Generalize from the feedback.** The big picture thing that's happening here is that we're trying to create skills that can be used a million times (maybe literally, maybe even more who knows) across many different prompts. Here you and the user are iterating on only a few examples over and over again because it helps move faster. The user knows these examples in and out and it's quick for them to assess new outputs. But if the skill you and the user are codeveloping works only for those examples, it's useless. Rather than put in fiddly overfitty changes, or oppressively constrictive MUSTs, if there's some stubborn issue, you might try branching out and using different metaphors, or recommending different patterns of working. It's relatively cheap to try and maybe you'll land on something great.
|
||||
|
||||
2. **Keep the prompt lean.** Remove things that aren't pulling their weight. Make sure to read the transcripts, not just the final outputs — if it looks like the skill is making the model waste a bunch of time doing things that are unproductive, you can try getting rid of the parts of the skill that are making it do that and seeing what happens.
|
||||
|
||||
3. **Explain the why.** Try hard to explain the **why** behind everything you're asking the model to do. Today's LLMs are *smart*. They have good theory of mind and when given a good harness can go beyond rote instructions and really make things happen. Even if the feedback from the user is terse or frustrated, try to actually understand the task and why the user is writing what they wrote, and what they actually wrote, and then transmit this understanding into the instructions. If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag — if possible, reframe and explain the reasoning so that the model understands why the thing you're asking for is important. That's a more humane, powerful, and effective approach.
|
||||
|
||||
4. **Look for repeated work across test cases.** Read the transcripts from the test runs and notice if the subagents all independently wrote similar helper scripts or took the same multi-step approach to something. If all 3 test cases resulted in the subagent writing a `create_docx.py` or a `build_chart.py`, that's a strong signal the skill should bundle that script. Write it once, put it in `scripts/`, and tell the skill to use it. This saves every future invocation from reinventing the wheel.
|
||||
|
||||
This task is pretty important and your thinking time is not the blocker; take your time and really mull things over. I'd suggest writing a draft revision and then looking at it anew and making improvements. Really do your best to get into the head of the user and understand what they want and need.
|
||||
|
||||
### The iteration loop
|
||||
|
||||
After improving the skill:
|
||||
|
||||
1. Apply your improvements to the skill
|
||||
2. Rerun all test cases into a new `iteration-<N+1>/` directory, including baseline runs. If you're creating a new skill, the baseline is always `without_skill` (no skill) — that stays the same across iterations. If you're improving an existing skill, use your judgment on what makes sense as the baseline: the original version the user came in with, or the previous iteration.
|
||||
3. Launch the reviewer with `--previous-workspace` pointing at the previous iteration
|
||||
4. Wait for the user to review and tell you they're done
|
||||
5. Read the new feedback, improve again, repeat
|
||||
|
||||
Keep going until:
|
||||
- The user says they're happy
|
||||
- The feedback is all empty (everything looks good)
|
||||
- You're not making meaningful progress
|
||||
|
||||
---
|
||||
|
||||
## Advanced: Blind comparison
|
||||
|
||||
For situations where you want a more rigorous comparison between two versions of a skill (e.g., the user asks "is the new version actually better?"), there's a blind comparison system. Read `agents/comparator.md` and `agents/analyzer.md` for the details. The basic idea is: give two outputs to an independent agent without telling it which is which, and let it judge quality. Then analyze why the winner won.
|
||||
|
||||
This is optional, requires subagents, and most users won't need it. The human review loop is usually sufficient.
|
||||
|
||||
---
|
||||
|
||||
## Description Optimization
|
||||
|
||||
The description field in SKILL.md frontmatter is the primary mechanism that determines whether the agent invokes a skill. After creating or improving a skill, offer to optimize the description for better triggering accuracy.
|
||||
|
||||
### Step 1: Generate trigger eval queries
|
||||
|
||||
Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save as JSON:
|
||||
|
||||
```json
|
||||
[
|
||||
{"query": "the user prompt", "should_trigger": true},
|
||||
{"query": "another prompt", "should_trigger": false}
|
||||
]
|
||||
```
|
||||
|
||||
The queries must be realistic and something a user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them).
|
||||
|
||||
Bad: `"Format this data"`, `"Extract text from PDF"`, `"Create a chart"`
|
||||
|
||||
Good: `"ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"`
|
||||
|
||||
For the **should-trigger** queries (8-10), think about coverage. You want different phrasings of the same intent — some formal, some casual. Include cases where the user doesn't explicitly name the skill or file type but clearly needs it. Throw in some uncommon use cases and cases where this skill competes with another but should win.
|
||||
|
||||
For the **should-not-trigger** queries (8-10), the most valuable ones are the near-misses — queries that share keywords or concepts with the skill but actually need something different. Think adjacent domains, ambiguous phrasing where a naive keyword match would trigger but shouldn't, and cases where the query touches on something the skill does but in a context where another tool is more appropriate.
|
||||
|
||||
The key thing to avoid: don't make should-not-trigger queries obviously irrelevant. "Write a fibonacci function" as a negative test for a PDF skill is too easy — it doesn't test anything. The negative cases should be genuinely tricky.
|
||||
|
||||
### Step 2: Review with user
|
||||
|
||||
Present the eval set to the user for review using the HTML template:
|
||||
|
||||
1. Read the template from `assets/eval_review.html`
|
||||
2. Replace the placeholders:
|
||||
- `__EVAL_DATA_PLACEHOLDER__` → the JSON array of eval items (no quotes around it — it's a JS variable assignment)
|
||||
- `__SKILL_NAME_PLACEHOLDER__` → the skill's name
|
||||
- `__SKILL_DESCRIPTION_PLACEHOLDER__` → the skill's current description
|
||||
3. Write to a temp file (e.g., `/tmp/eval_review_<skill-name>.html`) and open it: `open /tmp/eval_review_<skill-name>.html`
|
||||
4. The user can edit queries, toggle should-trigger, add/remove entries, then click "Export Eval Set"
|
||||
5. The file downloads to `~/Downloads/eval_set.json` — check the Downloads folder for the most recent version in case there are multiple (e.g., `eval_set (1).json`)
|
||||
|
||||
This step matters — bad eval queries lead to bad descriptions.
|
||||
|
||||
### Step 3: Run the optimization loop
|
||||
|
||||
Tell the user: "This will take some time — I'll run the optimization loop in the background and check on it periodically."
|
||||
|
||||
Save the eval set to the workspace, then run in the background:
|
||||
|
||||
```bash
|
||||
python -m scripts.run_loop \
|
||||
--eval-set <path-to-trigger-eval.json> \
|
||||
--skill-path <path-to-skill> \
|
||||
--model <model-id-powering-this-session> \
|
||||
--max-iterations 5 \
|
||||
--verbose
|
||||
```
|
||||
|
||||
Use the model ID from your system prompt (the one powering the current session) so the triggering test matches what the user actually experiences.
|
||||
|
||||
While it runs, periodically tail the output to give the user updates on which iteration it's on and what the scores look like.
|
||||
|
||||
This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls the model to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with `best_description` — selected by test score rather than train score to avoid overfitting.
|
||||
|
||||
### How skill triggering works
|
||||
|
||||
Understanding the triggering mechanism helps design better eval queries. Skills appear in the agent's `available_skills` list with their name + description, and the agent decides whether to consult a skill based on that description. The important thing to know is that the agent only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because the agent can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches.
|
||||
|
||||
This means your eval queries should be substantive enough that the agent would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality.
|
||||
|
||||
### Step 4: Apply the result
|
||||
|
||||
Take `best_description` from the JSON output and update the skill's SKILL.md frontmatter. Show the user before/after and report the scores.
|
||||
|
||||
---
|
||||
|
||||
### Package and Present (only if `present_files` tool is available)
|
||||
|
||||
Check whether you have access to the `present_files` tool. If you don't, skip this step. If you do, package the skill and present the .skill file to the user:
|
||||
|
||||
```bash
|
||||
python -m scripts.package_skill <path/to/skill-folder>
|
||||
```
|
||||
|
||||
After packaging, direct the user to the resulting `.skill` file path so they can install it.
|
||||
|
||||
---
|
||||
|
||||
### Updating an existing skill
|
||||
|
||||
The user might be asking you to update an existing skill, not create a new one. In this case:
|
||||
- **Preserve the original name.** Note the skill's directory name and `name` frontmatter field -- use them unchanged. E.g., if the installed skill is `research-helper`, output `research-helper.skill` (not `research-helper-v2`).
|
||||
- **Copy to a writeable location before editing.** The installed skill path may be read-only. Copy to `/tmp/skill-name/`, edit there, and package from the copy.
|
||||
- **If packaging manually, stage in `/tmp/` first**, then copy to the output directory -- direct writes may fail due to permissions.
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
The agents/ directory contains instructions for specialized subagents. Read them when you need to spawn the relevant subagent.
|
||||
|
||||
- `agents/grader.md` — How to evaluate assertions against outputs
|
||||
- `agents/comparator.md` — How to do blind A/B comparison between two outputs
|
||||
- `agents/analyzer.md` — How to analyze why one version beat another
|
||||
|
||||
The references/ directory has additional documentation:
|
||||
- `references/schemas.md` — JSON structures for evals.json, grading.json, etc.
|
||||
|
||||
---
|
||||
|
||||
Repeating one more time the core loop here for emphasis:
|
||||
|
||||
- Figure out what the skill is about
|
||||
- Draft or edit the skill
|
||||
- Run the agent with access to the skill on test prompts
|
||||
- With the user, evaluate the outputs:
|
||||
- Create benchmark.json and run `eval-viewer/generate_review.py` to help the user review them
|
||||
- Run quantitative evals
|
||||
- Repeat until you and the user are satisfied
|
||||
- Package the final skill and return it to the user.
|
||||
|
||||
Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. Specifically put "Create evals JSON and run `eval-viewer/generate_review.py` so human can review test cases" in your TodoList to make sure it happens.
|
||||
|
||||
Good luck!
|
||||
@@ -0,0 +1,274 @@
|
||||
# Post-hoc Analyzer Agent
|
||||
|
||||
Analyze blind comparison results to understand WHY the winner won and generate improvement suggestions.
|
||||
|
||||
## Role
|
||||
|
||||
After the blind comparator determines a winner, the Post-hoc Analyzer "unblids" the results by examining the skills and transcripts. The goal is to extract actionable insights: what made the winner better, and how can the loser be improved?
|
||||
|
||||
## Inputs
|
||||
|
||||
You receive these parameters in your prompt:
|
||||
|
||||
- **winner**: "A" or "B" (from blind comparison)
|
||||
- **winner_skill_path**: Path to the skill that produced the winning output
|
||||
- **winner_transcript_path**: Path to the execution transcript for the winner
|
||||
- **loser_skill_path**: Path to the skill that produced the losing output
|
||||
- **loser_transcript_path**: Path to the execution transcript for the loser
|
||||
- **comparison_result_path**: Path to the blind comparator's output JSON
|
||||
- **output_path**: Where to save the analysis results
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Read Comparison Result
|
||||
|
||||
1. Read the blind comparator's output at comparison_result_path
|
||||
2. Note the winning side (A or B), the reasoning, and any scores
|
||||
3. Understand what the comparator valued in the winning output
|
||||
|
||||
### Step 2: Read Both Skills
|
||||
|
||||
1. Read the winner skill's SKILL.md and key referenced files
|
||||
2. Read the loser skill's SKILL.md and key referenced files
|
||||
3. Identify structural differences:
|
||||
- Instructions clarity and specificity
|
||||
- Script/tool usage patterns
|
||||
- Example coverage
|
||||
- Edge case handling
|
||||
|
||||
### Step 3: Read Both Transcripts
|
||||
|
||||
1. Read the winner's transcript
|
||||
2. Read the loser's transcript
|
||||
3. Compare execution patterns:
|
||||
- How closely did each follow their skill's instructions?
|
||||
- What tools were used differently?
|
||||
- Where did the loser diverge from optimal behavior?
|
||||
- Did either encounter errors or make recovery attempts?
|
||||
|
||||
### Step 4: Analyze Instruction Following
|
||||
|
||||
For each transcript, evaluate:
|
||||
- Did the agent follow the skill's explicit instructions?
|
||||
- Did the agent use the skill's provided tools/scripts?
|
||||
- Were there missed opportunities to leverage skill content?
|
||||
- Did the agent add unnecessary steps not in the skill?
|
||||
|
||||
Score instruction following 1-10 and note specific issues.
|
||||
|
||||
### Step 5: Identify Winner Strengths
|
||||
|
||||
Determine what made the winner better:
|
||||
- Clearer instructions that led to better behavior?
|
||||
- Better scripts/tools that produced better output?
|
||||
- More comprehensive examples that guided edge cases?
|
||||
- Better error handling guidance?
|
||||
|
||||
Be specific. Quote from skills/transcripts where relevant.
|
||||
|
||||
### Step 6: Identify Loser Weaknesses
|
||||
|
||||
Determine what held the loser back:
|
||||
- Ambiguous instructions that led to suboptimal choices?
|
||||
- Missing tools/scripts that forced workarounds?
|
||||
- Gaps in edge case coverage?
|
||||
- Poor error handling that caused failures?
|
||||
|
||||
### Step 7: Generate Improvement Suggestions
|
||||
|
||||
Based on the analysis, produce actionable suggestions for improving the loser skill:
|
||||
- Specific instruction changes to make
|
||||
- Tools/scripts to add or modify
|
||||
- Examples to include
|
||||
- Edge cases to address
|
||||
|
||||
Prioritize by impact. Focus on changes that would have changed the outcome.
|
||||
|
||||
### Step 8: Write Analysis Results
|
||||
|
||||
Save structured analysis to `{output_path}`.
|
||||
|
||||
## Output Format
|
||||
|
||||
Write a JSON file with this structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"comparison_summary": {
|
||||
"winner": "A",
|
||||
"winner_skill": "path/to/winner/skill",
|
||||
"loser_skill": "path/to/loser/skill",
|
||||
"comparator_reasoning": "Brief summary of why comparator chose winner"
|
||||
},
|
||||
"winner_strengths": [
|
||||
"Clear step-by-step instructions for handling multi-page documents",
|
||||
"Included validation script that caught formatting errors",
|
||||
"Explicit guidance on fallback behavior when OCR fails"
|
||||
],
|
||||
"loser_weaknesses": [
|
||||
"Vague instruction 'process the document appropriately' led to inconsistent behavior",
|
||||
"No script for validation, agent had to improvise and made errors",
|
||||
"No guidance on OCR failure, agent gave up instead of trying alternatives"
|
||||
],
|
||||
"instruction_following": {
|
||||
"winner": {
|
||||
"score": 9,
|
||||
"issues": [
|
||||
"Minor: skipped optional logging step"
|
||||
]
|
||||
},
|
||||
"loser": {
|
||||
"score": 6,
|
||||
"issues": [
|
||||
"Did not use the skill's formatting template",
|
||||
"Invented own approach instead of following step 3",
|
||||
"Missed the 'always validate output' instruction"
|
||||
]
|
||||
}
|
||||
},
|
||||
"improvement_suggestions": [
|
||||
{
|
||||
"priority": "high",
|
||||
"category": "instructions",
|
||||
"suggestion": "Replace 'process the document appropriately' with explicit steps: 1) Extract text, 2) Identify sections, 3) Format per template",
|
||||
"expected_impact": "Would eliminate ambiguity that caused inconsistent behavior"
|
||||
},
|
||||
{
|
||||
"priority": "high",
|
||||
"category": "tools",
|
||||
"suggestion": "Add validate_output.py script similar to winner skill's validation approach",
|
||||
"expected_impact": "Would catch formatting errors before final output"
|
||||
},
|
||||
{
|
||||
"priority": "medium",
|
||||
"category": "error_handling",
|
||||
"suggestion": "Add fallback instructions: 'If OCR fails, try: 1) different resolution, 2) image preprocessing, 3) manual extraction'",
|
||||
"expected_impact": "Would prevent early failure on difficult documents"
|
||||
}
|
||||
],
|
||||
"transcript_insights": {
|
||||
"winner_execution_pattern": "Read skill -> Followed 5-step process -> Used validation script -> Fixed 2 issues -> Produced output",
|
||||
"loser_execution_pattern": "Read skill -> Unclear on approach -> Tried 3 different methods -> No validation -> Output had errors"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Be specific**: Quote from skills and transcripts, don't just say "instructions were unclear"
|
||||
- **Be actionable**: Suggestions should be concrete changes, not vague advice
|
||||
- **Focus on skill improvements**: The goal is to improve the losing skill, not critique the agent
|
||||
- **Prioritize by impact**: Which changes would most likely have changed the outcome?
|
||||
- **Consider causation**: Did the skill weakness actually cause the worse output, or is it incidental?
|
||||
- **Stay objective**: Analyze what happened, don't editorialize
|
||||
- **Think about generalization**: Would this improvement help on other evals too?
|
||||
|
||||
## Categories for Suggestions
|
||||
|
||||
Use these categories to organize improvement suggestions:
|
||||
|
||||
| Category | Description |
|
||||
|----------|-------------|
|
||||
| `instructions` | Changes to the skill's prose instructions |
|
||||
| `tools` | Scripts, templates, or utilities to add/modify |
|
||||
| `examples` | Example inputs/outputs to include |
|
||||
| `error_handling` | Guidance for handling failures |
|
||||
| `structure` | Reorganization of skill content |
|
||||
| `references` | External docs or resources to add |
|
||||
|
||||
## Priority Levels
|
||||
|
||||
- **high**: Would likely change the outcome of this comparison
|
||||
- **medium**: Would improve quality but may not change win/loss
|
||||
- **low**: Nice to have, marginal improvement
|
||||
|
||||
---
|
||||
|
||||
# Analyzing Benchmark Results
|
||||
|
||||
When analyzing benchmark results, the analyzer's purpose is to **surface patterns and anomalies** across multiple runs, not suggest skill improvements.
|
||||
|
||||
## Role
|
||||
|
||||
Review all benchmark run results and generate freeform notes that help the user understand skill performance. Focus on patterns that wouldn't be visible from aggregate metrics alone.
|
||||
|
||||
## Inputs
|
||||
|
||||
You receive these parameters in your prompt:
|
||||
|
||||
- **benchmark_data_path**: Path to the in-progress benchmark.json with all run results
|
||||
- **skill_path**: Path to the skill being benchmarked
|
||||
- **output_path**: Where to save the notes (as JSON array of strings)
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Read Benchmark Data
|
||||
|
||||
1. Read the benchmark.json containing all run results
|
||||
2. Note the configurations tested (with_skill, without_skill)
|
||||
3. Understand the run_summary aggregates already calculated
|
||||
|
||||
### Step 2: Analyze Per-Assertion Patterns
|
||||
|
||||
For each expectation across all runs:
|
||||
- Does it **always pass** in both configurations? (may not differentiate skill value)
|
||||
- Does it **always fail** in both configurations? (may be broken or beyond capability)
|
||||
- Does it **always pass with skill but fail without**? (skill clearly adds value here)
|
||||
- Does it **always fail with skill but pass without**? (skill may be hurting)
|
||||
- Is it **highly variable**? (flaky expectation or non-deterministic behavior)
|
||||
|
||||
### Step 3: Analyze Cross-Eval Patterns
|
||||
|
||||
Look for patterns across evals:
|
||||
- Are certain eval types consistently harder/easier?
|
||||
- Do some evals show high variance while others are stable?
|
||||
- Are there surprising results that contradict expectations?
|
||||
|
||||
### Step 4: Analyze Metrics Patterns
|
||||
|
||||
Look at time_seconds, tokens, tool_calls:
|
||||
- Does the skill significantly increase execution time?
|
||||
- Is there high variance in resource usage?
|
||||
- Are there outlier runs that skew the aggregates?
|
||||
|
||||
### Step 5: Generate Notes
|
||||
|
||||
Write freeform observations as a list of strings. Each note should:
|
||||
- State a specific observation
|
||||
- Be grounded in the data (not speculation)
|
||||
- Help the user understand something the aggregate metrics don't show
|
||||
|
||||
Examples:
|
||||
- "Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value"
|
||||
- "Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure that may be flaky"
|
||||
- "Without-skill runs consistently fail on table extraction expectations (0% pass rate)"
|
||||
- "Skill adds 13s average execution time but improves pass rate by 50%"
|
||||
- "Token usage is 80% higher with skill, primarily due to script output parsing"
|
||||
- "All 3 without-skill runs for eval 1 produced empty output"
|
||||
|
||||
### Step 6: Write Notes
|
||||
|
||||
Save notes to `{output_path}` as a JSON array of strings:
|
||||
|
||||
```json
|
||||
[
|
||||
"Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value",
|
||||
"Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure",
|
||||
"Without-skill runs consistently fail on table extraction expectations",
|
||||
"Skill adds 13s average execution time but improves pass rate by 50%"
|
||||
]
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
**DO:**
|
||||
- Report what you observe in the data
|
||||
- Be specific about which evals, expectations, or runs you're referring to
|
||||
- Note patterns that aggregate metrics would hide
|
||||
- Provide context that helps interpret the numbers
|
||||
|
||||
**DO NOT:**
|
||||
- Suggest improvements to the skill (that's for the improvement step, not benchmarking)
|
||||
- Make subjective quality judgments ("the output was good/bad")
|
||||
- Speculate about causes without evidence
|
||||
- Repeat information already in the run_summary aggregates
|
||||
@@ -0,0 +1,202 @@
|
||||
# Blind Comparator Agent
|
||||
|
||||
Compare two outputs WITHOUT knowing which skill produced them.
|
||||
|
||||
## Role
|
||||
|
||||
The Blind Comparator judges which output better accomplishes the eval task. You receive two outputs labeled A and B, but you do NOT know which skill produced which. This prevents bias toward a particular skill or approach.
|
||||
|
||||
Your judgment is based purely on output quality and task completion.
|
||||
|
||||
## Inputs
|
||||
|
||||
You receive these parameters in your prompt:
|
||||
|
||||
- **output_a_path**: Path to the first output file or directory
|
||||
- **output_b_path**: Path to the second output file or directory
|
||||
- **eval_prompt**: The original task/prompt that was executed
|
||||
- **expectations**: List of expectations to check (optional - may be empty)
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Read Both Outputs
|
||||
|
||||
1. Examine output A (file or directory)
|
||||
2. Examine output B (file or directory)
|
||||
3. Note the type, structure, and content of each
|
||||
4. If outputs are directories, examine all relevant files inside
|
||||
|
||||
### Step 2: Understand the Task
|
||||
|
||||
1. Read the eval_prompt carefully
|
||||
2. Identify what the task requires:
|
||||
- What should be produced?
|
||||
- What qualities matter (accuracy, completeness, format)?
|
||||
- What would distinguish a good output from a poor one?
|
||||
|
||||
### Step 3: Generate Evaluation Rubric
|
||||
|
||||
Based on the task, generate a rubric with two dimensions:
|
||||
|
||||
**Content Rubric** (what the output contains):
|
||||
| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
|
||||
|-----------|----------|----------------|---------------|
|
||||
| Correctness | Major errors | Minor errors | Fully correct |
|
||||
| Completeness | Missing key elements | Mostly complete | All elements present |
|
||||
| Accuracy | Significant inaccuracies | Minor inaccuracies | Accurate throughout |
|
||||
|
||||
**Structure Rubric** (how the output is organized):
|
||||
| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
|
||||
|-----------|----------|----------------|---------------|
|
||||
| Organization | Disorganized | Reasonably organized | Clear, logical structure |
|
||||
| Formatting | Inconsistent/broken | Mostly consistent | Professional, polished |
|
||||
| Usability | Difficult to use | Usable with effort | Easy to use |
|
||||
|
||||
Adapt criteria to the specific task. For example:
|
||||
- PDF form → "Field alignment", "Text readability", "Data placement"
|
||||
- Document → "Section structure", "Heading hierarchy", "Paragraph flow"
|
||||
- Data output → "Schema correctness", "Data types", "Completeness"
|
||||
|
||||
### Step 4: Evaluate Each Output Against the Rubric
|
||||
|
||||
For each output (A and B):
|
||||
|
||||
1. **Score each criterion** on the rubric (1-5 scale)
|
||||
2. **Calculate dimension totals**: Content score, Structure score
|
||||
3. **Calculate overall score**: Average of dimension scores, scaled to 1-10
|
||||
|
||||
### Step 5: Check Assertions (if provided)
|
||||
|
||||
If expectations are provided:
|
||||
|
||||
1. Check each expectation against output A
|
||||
2. Check each expectation against output B
|
||||
3. Count pass rates for each output
|
||||
4. Use expectation scores as secondary evidence (not the primary decision factor)
|
||||
|
||||
### Step 6: Determine the Winner
|
||||
|
||||
Compare A and B based on (in priority order):
|
||||
|
||||
1. **Primary**: Overall rubric score (content + structure)
|
||||
2. **Secondary**: Assertion pass rates (if applicable)
|
||||
3. **Tiebreaker**: If truly equal, declare a TIE
|
||||
|
||||
Be decisive - ties should be rare. One output is usually better, even if marginally.
|
||||
|
||||
### Step 7: Write Comparison Results
|
||||
|
||||
Save results to a JSON file at the path specified (or `comparison.json` if not specified).
|
||||
|
||||
## Output Format
|
||||
|
||||
Write a JSON file with this structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"winner": "A",
|
||||
"reasoning": "Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies.",
|
||||
"rubric": {
|
||||
"A": {
|
||||
"content": {
|
||||
"correctness": 5,
|
||||
"completeness": 5,
|
||||
"accuracy": 4
|
||||
},
|
||||
"structure": {
|
||||
"organization": 4,
|
||||
"formatting": 5,
|
||||
"usability": 4
|
||||
},
|
||||
"content_score": 4.7,
|
||||
"structure_score": 4.3,
|
||||
"overall_score": 9.0
|
||||
},
|
||||
"B": {
|
||||
"content": {
|
||||
"correctness": 3,
|
||||
"completeness": 2,
|
||||
"accuracy": 3
|
||||
},
|
||||
"structure": {
|
||||
"organization": 3,
|
||||
"formatting": 2,
|
||||
"usability": 3
|
||||
},
|
||||
"content_score": 2.7,
|
||||
"structure_score": 2.7,
|
||||
"overall_score": 5.4
|
||||
}
|
||||
},
|
||||
"output_quality": {
|
||||
"A": {
|
||||
"score": 9,
|
||||
"strengths": ["Complete solution", "Well-formatted", "All fields present"],
|
||||
"weaknesses": ["Minor style inconsistency in header"]
|
||||
},
|
||||
"B": {
|
||||
"score": 5,
|
||||
"strengths": ["Readable output", "Correct basic structure"],
|
||||
"weaknesses": ["Missing date field", "Formatting inconsistencies", "Partial data extraction"]
|
||||
}
|
||||
},
|
||||
"expectation_results": {
|
||||
"A": {
|
||||
"passed": 4,
|
||||
"total": 5,
|
||||
"pass_rate": 0.80,
|
||||
"details": [
|
||||
{"text": "Output includes name", "passed": true},
|
||||
{"text": "Output includes date", "passed": true},
|
||||
{"text": "Format is PDF", "passed": true},
|
||||
{"text": "Contains signature", "passed": false},
|
||||
{"text": "Readable text", "passed": true}
|
||||
]
|
||||
},
|
||||
"B": {
|
||||
"passed": 3,
|
||||
"total": 5,
|
||||
"pass_rate": 0.60,
|
||||
"details": [
|
||||
{"text": "Output includes name", "passed": true},
|
||||
{"text": "Output includes date", "passed": false},
|
||||
{"text": "Format is PDF", "passed": true},
|
||||
{"text": "Contains signature", "passed": false},
|
||||
{"text": "Readable text", "passed": true}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If no expectations were provided, omit the `expectation_results` field entirely.
|
||||
|
||||
## Field Descriptions
|
||||
|
||||
- **winner**: "A", "B", or "TIE"
|
||||
- **reasoning**: Clear explanation of why the winner was chosen (or why it's a tie)
|
||||
- **rubric**: Structured rubric evaluation for each output
|
||||
- **content**: Scores for content criteria (correctness, completeness, accuracy)
|
||||
- **structure**: Scores for structure criteria (organization, formatting, usability)
|
||||
- **content_score**: Average of content criteria (1-5)
|
||||
- **structure_score**: Average of structure criteria (1-5)
|
||||
- **overall_score**: Combined score scaled to 1-10
|
||||
- **output_quality**: Summary quality assessment
|
||||
- **score**: 1-10 rating (should match rubric overall_score)
|
||||
- **strengths**: List of positive aspects
|
||||
- **weaknesses**: List of issues or shortcomings
|
||||
- **expectation_results**: (Only if expectations provided)
|
||||
- **passed**: Number of expectations that passed
|
||||
- **total**: Total number of expectations
|
||||
- **pass_rate**: Fraction passed (0.0 to 1.0)
|
||||
- **details**: Individual expectation results
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Stay blind**: DO NOT try to infer which skill produced which output. Judge purely on output quality.
|
||||
- **Be specific**: Cite specific examples when explaining strengths and weaknesses.
|
||||
- **Be decisive**: Choose a winner unless outputs are genuinely equivalent.
|
||||
- **Output quality first**: Assertion scores are secondary to overall task completion.
|
||||
- **Be objective**: Don't favor outputs based on style preferences; focus on correctness and completeness.
|
||||
- **Explain your reasoning**: The reasoning field should make it clear why you chose the winner.
|
||||
- **Handle edge cases**: If both outputs fail, pick the one that fails less badly. If both are excellent, pick the one that's marginally better.
|
||||
@@ -0,0 +1,223 @@
|
||||
# Grader Agent
|
||||
|
||||
Evaluate expectations against an execution transcript and outputs.
|
||||
|
||||
## Role
|
||||
|
||||
The Grader reviews a transcript and output files, then determines whether each expectation passes or fails. Provide clear evidence for each judgment.
|
||||
|
||||
You have two jobs: grade the outputs, and critique the evals themselves. A passing grade on a weak assertion is worse than useless — it creates false confidence. When you notice an assertion that's trivially satisfied, or an important outcome that no assertion checks, say so.
|
||||
|
||||
## Inputs
|
||||
|
||||
You receive these parameters in your prompt:
|
||||
|
||||
- **expectations**: List of expectations to evaluate (strings)
|
||||
- **transcript_path**: Path to the execution transcript (markdown file)
|
||||
- **outputs_dir**: Directory containing output files from execution
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Read the Transcript
|
||||
|
||||
1. Read the transcript file completely
|
||||
2. Note the eval prompt, execution steps, and final result
|
||||
3. Identify any issues or errors documented
|
||||
|
||||
### Step 2: Examine Output Files
|
||||
|
||||
1. List files in outputs_dir
|
||||
2. Read/examine each file relevant to the expectations. If outputs aren't plain text, use the inspection tools provided in your prompt — don't rely solely on what the transcript says the executor produced.
|
||||
3. Note contents, structure, and quality
|
||||
|
||||
### Step 3: Evaluate Each Assertion
|
||||
|
||||
For each expectation:
|
||||
|
||||
1. **Search for evidence** in the transcript and outputs
|
||||
2. **Determine verdict**:
|
||||
- **PASS**: Clear evidence the expectation is true AND the evidence reflects genuine task completion, not just surface-level compliance
|
||||
- **FAIL**: No evidence, or evidence contradicts the expectation, or the evidence is superficial (e.g., correct filename but empty/wrong content)
|
||||
3. **Cite the evidence**: Quote the specific text or describe what you found
|
||||
|
||||
### Step 4: Extract and Verify Claims
|
||||
|
||||
Beyond the predefined expectations, extract implicit claims from the outputs and verify them:
|
||||
|
||||
1. **Extract claims** from the transcript and outputs:
|
||||
- Factual statements ("The form has 12 fields")
|
||||
- Process claims ("Used pypdf to fill the form")
|
||||
- Quality claims ("All fields were filled correctly")
|
||||
|
||||
2. **Verify each claim**:
|
||||
- **Factual claims**: Can be checked against the outputs or external sources
|
||||
- **Process claims**: Can be verified from the transcript
|
||||
- **Quality claims**: Evaluate whether the claim is justified
|
||||
|
||||
3. **Flag unverifiable claims**: Note claims that cannot be verified with available information
|
||||
|
||||
This catches issues that predefined expectations might miss.
|
||||
|
||||
### Step 5: Read User Notes
|
||||
|
||||
If `{outputs_dir}/user_notes.md` exists:
|
||||
1. Read it and note any uncertainties or issues flagged by the executor
|
||||
2. Include relevant concerns in the grading output
|
||||
3. These may reveal problems even when expectations pass
|
||||
|
||||
### Step 6: Critique the Evals
|
||||
|
||||
After grading, consider whether the evals themselves could be improved. Only surface suggestions when there's a clear gap.
|
||||
|
||||
Good suggestions test meaningful outcomes — assertions that are hard to satisfy without actually doing the work correctly. Think about what makes an assertion *discriminating*: it passes when the skill genuinely succeeds and fails when it doesn't.
|
||||
|
||||
Suggestions worth raising:
|
||||
- An assertion that passed but would also pass for a clearly wrong output (e.g., checking filename existence but not file content)
|
||||
- An important outcome you observed — good or bad — that no assertion covers at all
|
||||
- An assertion that can't actually be verified from the available outputs
|
||||
|
||||
Keep the bar high. The goal is to flag things the eval author would say "good catch" about, not to nitpick every assertion.
|
||||
|
||||
### Step 7: Write Grading Results
|
||||
|
||||
Save results to `{outputs_dir}/../grading.json` (sibling to outputs_dir).
|
||||
|
||||
## Grading Criteria
|
||||
|
||||
**PASS when**:
|
||||
- The transcript or outputs clearly demonstrate the expectation is true
|
||||
- Specific evidence can be cited
|
||||
- The evidence reflects genuine substance, not just surface compliance (e.g., a file exists AND contains correct content, not just the right filename)
|
||||
|
||||
**FAIL when**:
|
||||
- No evidence found for the expectation
|
||||
- Evidence contradicts the expectation
|
||||
- The expectation cannot be verified from available information
|
||||
- The evidence is superficial — the assertion is technically satisfied but the underlying task outcome is wrong or incomplete
|
||||
- The output appears to meet the assertion by coincidence rather than by actually doing the work
|
||||
|
||||
**When uncertain**: The burden of proof to pass is on the expectation.
|
||||
|
||||
### Step 8: Read Executor Metrics and Timing
|
||||
|
||||
1. If `{outputs_dir}/metrics.json` exists, read it and include in grading output
|
||||
2. If `{outputs_dir}/../timing.json` exists, read it and include timing data
|
||||
|
||||
## Output Format
|
||||
|
||||
Write a JSON file with this structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"expectations": [
|
||||
{
|
||||
"text": "The output includes the name 'John Smith'",
|
||||
"passed": true,
|
||||
"evidence": "Found in transcript Step 3: 'Extracted names: John Smith, Sarah Johnson'"
|
||||
},
|
||||
{
|
||||
"text": "The spreadsheet has a SUM formula in cell B10",
|
||||
"passed": false,
|
||||
"evidence": "No spreadsheet was created. The output was a text file."
|
||||
},
|
||||
{
|
||||
"text": "The assistant used the skill's OCR script",
|
||||
"passed": true,
|
||||
"evidence": "Transcript Step 2 shows: 'Tool: Bash - python ocr_script.py image.png'"
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"passed": 2,
|
||||
"failed": 1,
|
||||
"total": 3,
|
||||
"pass_rate": 0.67
|
||||
},
|
||||
"execution_metrics": {
|
||||
"tool_calls": {
|
||||
"Read": 5,
|
||||
"Write": 2,
|
||||
"Bash": 8
|
||||
},
|
||||
"total_tool_calls": 15,
|
||||
"total_steps": 6,
|
||||
"errors_encountered": 0,
|
||||
"output_chars": 12450,
|
||||
"transcript_chars": 3200
|
||||
},
|
||||
"timing": {
|
||||
"executor_duration_seconds": 165.0,
|
||||
"grader_duration_seconds": 26.0,
|
||||
"total_duration_seconds": 191.0
|
||||
},
|
||||
"claims": [
|
||||
{
|
||||
"claim": "The form has 12 fillable fields",
|
||||
"type": "factual",
|
||||
"verified": true,
|
||||
"evidence": "Counted 12 fields in field_info.json"
|
||||
},
|
||||
{
|
||||
"claim": "All required fields were populated",
|
||||
"type": "quality",
|
||||
"verified": false,
|
||||
"evidence": "Reference section was left blank despite data being available"
|
||||
}
|
||||
],
|
||||
"user_notes_summary": {
|
||||
"uncertainties": ["Used 2023 data, may be stale"],
|
||||
"needs_review": [],
|
||||
"workarounds": ["Fell back to text overlay for non-fillable fields"]
|
||||
},
|
||||
"eval_feedback": {
|
||||
"suggestions": [
|
||||
{
|
||||
"assertion": "The output includes the name 'John Smith'",
|
||||
"reason": "A hallucinated document that mentions the name would also pass — consider checking it appears as the primary contact with matching phone and email from the input"
|
||||
},
|
||||
{
|
||||
"reason": "No assertion checks whether the extracted phone numbers match the input — I observed incorrect numbers in the output that went uncaught"
|
||||
}
|
||||
],
|
||||
"overall": "Assertions check presence but not correctness. Consider adding content verification."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Field Descriptions
|
||||
|
||||
- **expectations**: Array of graded expectations
|
||||
- **text**: The original expectation text
|
||||
- **passed**: Boolean - true if expectation passes
|
||||
- **evidence**: Specific quote or description supporting the verdict
|
||||
- **summary**: Aggregate statistics
|
||||
- **passed**: Count of passed expectations
|
||||
- **failed**: Count of failed expectations
|
||||
- **total**: Total expectations evaluated
|
||||
- **pass_rate**: Fraction passed (0.0 to 1.0)
|
||||
- **execution_metrics**: Copied from executor's metrics.json (if available)
|
||||
- **output_chars**: Total character count of output files (proxy for tokens)
|
||||
- **transcript_chars**: Character count of transcript
|
||||
- **timing**: Wall clock timing from timing.json (if available)
|
||||
- **executor_duration_seconds**: Time spent in executor subagent
|
||||
- **total_duration_seconds**: Total elapsed time for the run
|
||||
- **claims**: Extracted and verified claims from the output
|
||||
- **claim**: The statement being verified
|
||||
- **type**: "factual", "process", or "quality"
|
||||
- **verified**: Boolean - whether the claim holds
|
||||
- **evidence**: Supporting or contradicting evidence
|
||||
- **user_notes_summary**: Issues flagged by the executor
|
||||
- **uncertainties**: Things the executor wasn't sure about
|
||||
- **needs_review**: Items requiring human attention
|
||||
- **workarounds**: Places where the skill didn't work as expected
|
||||
- **eval_feedback**: Improvement suggestions for the evals (only when warranted)
|
||||
- **suggestions**: List of concrete suggestions, each with a `reason` and optionally an `assertion` it relates to
|
||||
- **overall**: Brief assessment — can be "No suggestions, evals look solid" if nothing to flag
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Be objective**: Base verdicts on evidence, not assumptions
|
||||
- **Be specific**: Quote the exact text that supports your verdict
|
||||
- **Be thorough**: Check both transcript and output files
|
||||
- **Be consistent**: Apply the same standard to each expectation
|
||||
- **Explain failures**: Make it clear why evidence was insufficient
|
||||
- **No partial credit**: Each expectation is pass or fail, not partial
|
||||
@@ -0,0 +1,146 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Eval Set Review - __SKILL_NAME_PLACEHOLDER__</title>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@500;600&family=Lora:wght@400;500&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
* { box-sizing: border-box; margin: 0; padding: 0; }
|
||||
body { font-family: 'Lora', Georgia, serif; background: #faf9f5; padding: 2rem; color: #141413; }
|
||||
h1 { font-family: 'Poppins', sans-serif; margin-bottom: 0.5rem; font-size: 1.5rem; }
|
||||
.description { color: #b0aea5; margin-bottom: 1.5rem; font-style: italic; max-width: 900px; }
|
||||
.controls { margin-bottom: 1rem; display: flex; gap: 0.5rem; }
|
||||
.btn { font-family: 'Poppins', sans-serif; padding: 0.5rem 1rem; border: none; border-radius: 6px; cursor: pointer; font-size: 0.875rem; font-weight: 500; }
|
||||
.btn-add { background: #6a9bcc; color: white; }
|
||||
.btn-add:hover { background: #5889b8; }
|
||||
.btn-export { background: #d97757; color: white; }
|
||||
.btn-export:hover { background: #c4613f; }
|
||||
table { width: 100%; max-width: 1100px; border-collapse: collapse; background: white; border-radius: 6px; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.08); }
|
||||
th { font-family: 'Poppins', sans-serif; background: #141413; color: #faf9f5; padding: 0.75rem 1rem; text-align: left; font-size: 0.875rem; }
|
||||
td { padding: 0.75rem 1rem; border-bottom: 1px solid #e8e6dc; vertical-align: top; }
|
||||
tr:nth-child(even) td { background: #faf9f5; }
|
||||
tr:hover td { background: #f3f1ea; }
|
||||
.section-header td { background: #e8e6dc; font-family: 'Poppins', sans-serif; font-weight: 500; font-size: 0.8rem; color: #141413; text-transform: uppercase; letter-spacing: 0.05em; }
|
||||
.query-input { width: 100%; padding: 0.4rem; border: 1px solid #e8e6dc; border-radius: 4px; font-size: 0.875rem; font-family: 'Lora', Georgia, serif; resize: vertical; min-height: 60px; }
|
||||
.query-input:focus { outline: none; border-color: #d97757; box-shadow: 0 0 0 2px rgba(217,119,87,0.15); }
|
||||
.toggle { position: relative; display: inline-block; width: 44px; height: 24px; }
|
||||
.toggle input { opacity: 0; width: 0; height: 0; }
|
||||
.toggle .slider { position: absolute; inset: 0; background: #b0aea5; border-radius: 24px; cursor: pointer; transition: 0.2s; }
|
||||
.toggle .slider::before { content: ""; position: absolute; width: 18px; height: 18px; left: 3px; bottom: 3px; background: white; border-radius: 50%; transition: 0.2s; }
|
||||
.toggle input:checked + .slider { background: #d97757; }
|
||||
.toggle input:checked + .slider::before { transform: translateX(20px); }
|
||||
.btn-delete { background: #c44; color: white; padding: 0.3rem 0.6rem; border: none; border-radius: 4px; cursor: pointer; font-size: 0.75rem; font-family: 'Poppins', sans-serif; }
|
||||
.btn-delete:hover { background: #a33; }
|
||||
.summary { margin-top: 1rem; color: #b0aea5; font-size: 0.875rem; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Eval Set Review: <span id="skill-name">__SKILL_NAME_PLACEHOLDER__</span></h1>
|
||||
<p class="description">Current description: <span id="skill-desc">__SKILL_DESCRIPTION_PLACEHOLDER__</span></p>
|
||||
|
||||
<div class="controls">
|
||||
<button class="btn btn-add" onclick="addRow()">+ Add Query</button>
|
||||
<button class="btn btn-export" onclick="exportEvalSet()">Export Eval Set</button>
|
||||
</div>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th style="width:65%">Query</th>
|
||||
<th style="width:18%">Should Trigger</th>
|
||||
<th style="width:10%">Actions</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody id="eval-body"></tbody>
|
||||
</table>
|
||||
|
||||
<p class="summary" id="summary"></p>
|
||||
|
||||
<script>
|
||||
const EVAL_DATA = __EVAL_DATA_PLACEHOLDER__;
|
||||
|
||||
let evalItems = [...EVAL_DATA];
|
||||
|
||||
function render() {
|
||||
const tbody = document.getElementById('eval-body');
|
||||
tbody.innerHTML = '';
|
||||
|
||||
// Sort: should-trigger first, then should-not-trigger
|
||||
const sorted = evalItems
|
||||
.map((item, origIdx) => ({ ...item, origIdx }))
|
||||
.sort((a, b) => (b.should_trigger ? 1 : 0) - (a.should_trigger ? 1 : 0));
|
||||
|
||||
let lastGroup = null;
|
||||
sorted.forEach(item => {
|
||||
const group = item.should_trigger ? 'trigger' : 'no-trigger';
|
||||
if (group !== lastGroup) {
|
||||
const headerRow = document.createElement('tr');
|
||||
headerRow.className = 'section-header';
|
||||
headerRow.innerHTML = `<td colspan="3">${item.should_trigger ? 'Should Trigger' : 'Should NOT Trigger'}</td>`;
|
||||
tbody.appendChild(headerRow);
|
||||
lastGroup = group;
|
||||
}
|
||||
|
||||
const idx = item.origIdx;
|
||||
const tr = document.createElement('tr');
|
||||
tr.innerHTML = `
|
||||
<td><textarea class="query-input" onchange="updateQuery(${idx}, this.value)">${escapeHtml(item.query)}</textarea></td>
|
||||
<td>
|
||||
<label class="toggle">
|
||||
<input type="checkbox" ${item.should_trigger ? 'checked' : ''} onchange="updateTrigger(${idx}, this.checked)">
|
||||
<span class="slider"></span>
|
||||
</label>
|
||||
<span style="margin-left:8px;font-size:0.8rem;color:#b0aea5">${item.should_trigger ? 'Yes' : 'No'}</span>
|
||||
</td>
|
||||
<td><button class="btn-delete" onclick="deleteRow(${idx})">Delete</button></td>
|
||||
`;
|
||||
tbody.appendChild(tr);
|
||||
});
|
||||
updateSummary();
|
||||
}
|
||||
|
||||
function escapeHtml(text) {
|
||||
const div = document.createElement('div');
|
||||
div.textContent = text;
|
||||
return div.innerHTML;
|
||||
}
|
||||
|
||||
function updateQuery(idx, value) { evalItems[idx].query = value; updateSummary(); }
|
||||
function updateTrigger(idx, value) { evalItems[idx].should_trigger = value; render(); }
|
||||
function deleteRow(idx) { evalItems.splice(idx, 1); render(); }
|
||||
|
||||
function addRow() {
|
||||
evalItems.push({ query: '', should_trigger: true });
|
||||
render();
|
||||
const inputs = document.querySelectorAll('.query-input');
|
||||
inputs[inputs.length - 1].focus();
|
||||
}
|
||||
|
||||
function updateSummary() {
|
||||
const trigger = evalItems.filter(i => i.should_trigger).length;
|
||||
const noTrigger = evalItems.filter(i => !i.should_trigger).length;
|
||||
document.getElementById('summary').textContent =
|
||||
`${evalItems.length} queries total: ${trigger} should trigger, ${noTrigger} should not trigger`;
|
||||
}
|
||||
|
||||
function exportEvalSet() {
|
||||
const valid = evalItems.filter(i => i.query.trim() !== '');
|
||||
const data = valid.map(i => ({ query: i.query.trim(), should_trigger: i.should_trigger }));
|
||||
const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
|
||||
const url = URL.createObjectURL(blob);
|
||||
const a = document.createElement('a');
|
||||
a.href = url;
|
||||
a.download = 'eval_set.json';
|
||||
document.body.appendChild(a);
|
||||
a.click();
|
||||
document.body.removeChild(a);
|
||||
URL.revokeObjectURL(url);
|
||||
}
|
||||
|
||||
render();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,471 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Generate and serve a review page for eval results.
|
||||
|
||||
Reads the workspace directory, discovers runs (directories with outputs/),
|
||||
embeds all output data into a self-contained HTML page, and serves it via
|
||||
a tiny HTTP server. Feedback auto-saves to feedback.json in the workspace.
|
||||
|
||||
Usage:
|
||||
python generate_review.py <workspace-path> [--port PORT] [--skill-name NAME]
|
||||
python generate_review.py <workspace-path> --previous-feedback /path/to/old/feedback.json
|
||||
|
||||
No dependencies beyond the Python stdlib are required.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import base64
|
||||
import json
|
||||
import mimetypes
|
||||
import os
|
||||
import re
|
||||
import signal
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
import webbrowser
|
||||
from functools import partial
|
||||
from http.server import HTTPServer, BaseHTTPRequestHandler
|
||||
from pathlib import Path
|
||||
|
||||
# Files to exclude from output listings
|
||||
METADATA_FILES = {"transcript.md", "user_notes.md", "metrics.json"}
|
||||
|
||||
# Extensions we render as inline text
|
||||
TEXT_EXTENSIONS = {
|
||||
".txt", ".md", ".json", ".csv", ".py", ".js", ".ts", ".tsx", ".jsx",
|
||||
".yaml", ".yml", ".xml", ".html", ".css", ".sh", ".rb", ".go", ".rs",
|
||||
".java", ".c", ".cpp", ".h", ".hpp", ".sql", ".r", ".toml",
|
||||
}
|
||||
|
||||
# Extensions we render as inline images
|
||||
IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"}
|
||||
|
||||
# MIME type overrides for common types
|
||||
MIME_OVERRIDES = {
|
||||
".svg": "image/svg+xml",
|
||||
".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
|
||||
".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
|
||||
".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
|
||||
}
|
||||
|
||||
|
||||
def get_mime_type(path: Path) -> str:
|
||||
ext = path.suffix.lower()
|
||||
if ext in MIME_OVERRIDES:
|
||||
return MIME_OVERRIDES[ext]
|
||||
mime, _ = mimetypes.guess_type(str(path))
|
||||
return mime or "application/octet-stream"
|
||||
|
||||
|
||||
def find_runs(workspace: Path) -> list[dict]:
|
||||
"""Recursively find directories that contain an outputs/ subdirectory."""
|
||||
runs: list[dict] = []
|
||||
_find_runs_recursive(workspace, workspace, runs)
|
||||
runs.sort(key=lambda r: (r.get("eval_id", float("inf")), r["id"]))
|
||||
return runs
|
||||
|
||||
|
||||
def _find_runs_recursive(root: Path, current: Path, runs: list[dict]) -> None:
|
||||
if not current.is_dir():
|
||||
return
|
||||
|
||||
outputs_dir = current / "outputs"
|
||||
if outputs_dir.is_dir():
|
||||
run = build_run(root, current)
|
||||
if run:
|
||||
runs.append(run)
|
||||
return
|
||||
|
||||
skip = {"node_modules", ".git", "__pycache__", "skill", "inputs"}
|
||||
for child in sorted(current.iterdir()):
|
||||
if child.is_dir() and child.name not in skip:
|
||||
_find_runs_recursive(root, child, runs)
|
||||
|
||||
|
||||
def build_run(root: Path, run_dir: Path) -> dict | None:
|
||||
"""Build a run dict with prompt, outputs, and grading data."""
|
||||
prompt = ""
|
||||
eval_id = None
|
||||
|
||||
# Try eval_metadata.json
|
||||
for candidate in [run_dir / "eval_metadata.json", run_dir.parent / "eval_metadata.json"]:
|
||||
if candidate.exists():
|
||||
try:
|
||||
metadata = json.loads(candidate.read_text())
|
||||
prompt = metadata.get("prompt", "")
|
||||
eval_id = metadata.get("eval_id")
|
||||
except (json.JSONDecodeError, OSError):
|
||||
pass
|
||||
if prompt:
|
||||
break
|
||||
|
||||
# Fall back to transcript.md
|
||||
if not prompt:
|
||||
for candidate in [run_dir / "transcript.md", run_dir / "outputs" / "transcript.md"]:
|
||||
if candidate.exists():
|
||||
try:
|
||||
text = candidate.read_text()
|
||||
match = re.search(r"## Eval Prompt\n\n([\s\S]*?)(?=\n##|$)", text)
|
||||
if match:
|
||||
prompt = match.group(1).strip()
|
||||
except OSError:
|
||||
pass
|
||||
if prompt:
|
||||
break
|
||||
|
||||
if not prompt:
|
||||
prompt = "(No prompt found)"
|
||||
|
||||
run_id = str(run_dir.relative_to(root)).replace("/", "-").replace("\\", "-")
|
||||
|
||||
# Collect output files
|
||||
outputs_dir = run_dir / "outputs"
|
||||
output_files: list[dict] = []
|
||||
if outputs_dir.is_dir():
|
||||
for f in sorted(outputs_dir.iterdir()):
|
||||
if f.is_file() and f.name not in METADATA_FILES:
|
||||
output_files.append(embed_file(f))
|
||||
|
||||
# Load grading if present
|
||||
grading = None
|
||||
for candidate in [run_dir / "grading.json", run_dir.parent / "grading.json"]:
|
||||
if candidate.exists():
|
||||
try:
|
||||
grading = json.loads(candidate.read_text())
|
||||
except (json.JSONDecodeError, OSError):
|
||||
pass
|
||||
if grading:
|
||||
break
|
||||
|
||||
return {
|
||||
"id": run_id,
|
||||
"prompt": prompt,
|
||||
"eval_id": eval_id,
|
||||
"outputs": output_files,
|
||||
"grading": grading,
|
||||
}
|
||||
|
||||
|
||||
def embed_file(path: Path) -> dict:
|
||||
"""Read a file and return an embedded representation."""
|
||||
ext = path.suffix.lower()
|
||||
mime = get_mime_type(path)
|
||||
|
||||
if ext in TEXT_EXTENSIONS:
|
||||
try:
|
||||
content = path.read_text(errors="replace")
|
||||
except OSError:
|
||||
content = "(Error reading file)"
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "text",
|
||||
"content": content,
|
||||
}
|
||||
elif ext in IMAGE_EXTENSIONS:
|
||||
try:
|
||||
raw = path.read_bytes()
|
||||
b64 = base64.b64encode(raw).decode("ascii")
|
||||
except OSError:
|
||||
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "image",
|
||||
"mime": mime,
|
||||
"data_uri": f"data:{mime};base64,{b64}",
|
||||
}
|
||||
elif ext == ".pdf":
|
||||
try:
|
||||
raw = path.read_bytes()
|
||||
b64 = base64.b64encode(raw).decode("ascii")
|
||||
except OSError:
|
||||
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "pdf",
|
||||
"data_uri": f"data:{mime};base64,{b64}",
|
||||
}
|
||||
elif ext == ".xlsx":
|
||||
try:
|
||||
raw = path.read_bytes()
|
||||
b64 = base64.b64encode(raw).decode("ascii")
|
||||
except OSError:
|
||||
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "xlsx",
|
||||
"data_b64": b64,
|
||||
}
|
||||
else:
|
||||
# Binary / unknown — base64 download link
|
||||
try:
|
||||
raw = path.read_bytes()
|
||||
b64 = base64.b64encode(raw).decode("ascii")
|
||||
except OSError:
|
||||
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "binary",
|
||||
"mime": mime,
|
||||
"data_uri": f"data:{mime};base64,{b64}",
|
||||
}
|
||||
|
||||
|
||||
def load_previous_iteration(workspace: Path) -> dict[str, dict]:
|
||||
"""Load previous iteration's feedback and outputs.
|
||||
|
||||
Returns a map of run_id -> {"feedback": str, "outputs": list[dict]}.
|
||||
"""
|
||||
result: dict[str, dict] = {}
|
||||
|
||||
# Load feedback
|
||||
feedback_map: dict[str, str] = {}
|
||||
feedback_path = workspace / "feedback.json"
|
||||
if feedback_path.exists():
|
||||
try:
|
||||
data = json.loads(feedback_path.read_text())
|
||||
feedback_map = {
|
||||
r["run_id"]: r["feedback"]
|
||||
for r in data.get("reviews", [])
|
||||
if r.get("feedback", "").strip()
|
||||
}
|
||||
except (json.JSONDecodeError, OSError, KeyError):
|
||||
pass
|
||||
|
||||
# Load runs (to get outputs)
|
||||
prev_runs = find_runs(workspace)
|
||||
for run in prev_runs:
|
||||
result[run["id"]] = {
|
||||
"feedback": feedback_map.get(run["id"], ""),
|
||||
"outputs": run.get("outputs", []),
|
||||
}
|
||||
|
||||
# Also add feedback for run_ids that had feedback but no matching run
|
||||
for run_id, fb in feedback_map.items():
|
||||
if run_id not in result:
|
||||
result[run_id] = {"feedback": fb, "outputs": []}
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def generate_html(
|
||||
runs: list[dict],
|
||||
skill_name: str,
|
||||
previous: dict[str, dict] | None = None,
|
||||
benchmark: dict | None = None,
|
||||
) -> str:
|
||||
"""Generate the complete standalone HTML page with embedded data."""
|
||||
template_path = Path(__file__).parent / "viewer.html"
|
||||
template = template_path.read_text()
|
||||
|
||||
# Build previous_feedback and previous_outputs maps for the template
|
||||
previous_feedback: dict[str, str] = {}
|
||||
previous_outputs: dict[str, list[dict]] = {}
|
||||
if previous:
|
||||
for run_id, data in previous.items():
|
||||
if data.get("feedback"):
|
||||
previous_feedback[run_id] = data["feedback"]
|
||||
if data.get("outputs"):
|
||||
previous_outputs[run_id] = data["outputs"]
|
||||
|
||||
embedded = {
|
||||
"skill_name": skill_name,
|
||||
"runs": runs,
|
||||
"previous_feedback": previous_feedback,
|
||||
"previous_outputs": previous_outputs,
|
||||
}
|
||||
if benchmark:
|
||||
embedded["benchmark"] = benchmark
|
||||
|
||||
data_json = json.dumps(embedded)
|
||||
|
||||
return template.replace("/*__EMBEDDED_DATA__*/", f"const EMBEDDED_DATA = {data_json};")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# HTTP server (stdlib only, zero dependencies)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _kill_port(port: int) -> None:
|
||||
"""Kill any process listening on the given port."""
|
||||
try:
|
||||
result = subprocess.run(
|
||||
["lsof", "-ti", f":{port}"],
|
||||
capture_output=True, text=True, timeout=5,
|
||||
)
|
||||
for pid_str in result.stdout.strip().split("\n"):
|
||||
if pid_str.strip():
|
||||
try:
|
||||
os.kill(int(pid_str.strip()), signal.SIGTERM)
|
||||
except (ProcessLookupError, ValueError):
|
||||
pass
|
||||
if result.stdout.strip():
|
||||
time.sleep(0.5)
|
||||
except subprocess.TimeoutExpired:
|
||||
pass
|
||||
except FileNotFoundError:
|
||||
print("Note: lsof not found, cannot check if port is in use", file=sys.stderr)
|
||||
|
||||
class ReviewHandler(BaseHTTPRequestHandler):
|
||||
"""Serves the review HTML and handles feedback saves.
|
||||
|
||||
Regenerates the HTML on each page load so that refreshing the browser
|
||||
picks up new eval outputs without restarting the server.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
workspace: Path,
|
||||
skill_name: str,
|
||||
feedback_path: Path,
|
||||
previous: dict[str, dict],
|
||||
benchmark_path: Path | None,
|
||||
*args,
|
||||
**kwargs,
|
||||
):
|
||||
self.workspace = workspace
|
||||
self.skill_name = skill_name
|
||||
self.feedback_path = feedback_path
|
||||
self.previous = previous
|
||||
self.benchmark_path = benchmark_path
|
||||
super().__init__(*args, **kwargs)
|
||||
|
||||
def do_GET(self) -> None:
|
||||
if self.path == "/" or self.path == "/index.html":
|
||||
# Regenerate HTML on each request (re-scans workspace for new outputs)
|
||||
runs = find_runs(self.workspace)
|
||||
benchmark = None
|
||||
if self.benchmark_path and self.benchmark_path.exists():
|
||||
try:
|
||||
benchmark = json.loads(self.benchmark_path.read_text())
|
||||
except (json.JSONDecodeError, OSError):
|
||||
pass
|
||||
html = generate_html(runs, self.skill_name, self.previous, benchmark)
|
||||
content = html.encode("utf-8")
|
||||
self.send_response(200)
|
||||
self.send_header("Content-Type", "text/html; charset=utf-8")
|
||||
self.send_header("Content-Length", str(len(content)))
|
||||
self.end_headers()
|
||||
self.wfile.write(content)
|
||||
elif self.path == "/api/feedback":
|
||||
data = b"{}"
|
||||
if self.feedback_path.exists():
|
||||
data = self.feedback_path.read_bytes()
|
||||
self.send_response(200)
|
||||
self.send_header("Content-Type", "application/json")
|
||||
self.send_header("Content-Length", str(len(data)))
|
||||
self.end_headers()
|
||||
self.wfile.write(data)
|
||||
else:
|
||||
self.send_error(404)
|
||||
|
||||
def do_POST(self) -> None:
|
||||
if self.path == "/api/feedback":
|
||||
length = int(self.headers.get("Content-Length", 0))
|
||||
body = self.rfile.read(length)
|
||||
try:
|
||||
data = json.loads(body)
|
||||
if not isinstance(data, dict) or "reviews" not in data:
|
||||
raise ValueError("Expected JSON object with 'reviews' key")
|
||||
self.feedback_path.write_text(json.dumps(data, indent=2) + "\n")
|
||||
resp = b'{"ok":true}'
|
||||
self.send_response(200)
|
||||
except (json.JSONDecodeError, OSError, ValueError) as e:
|
||||
resp = json.dumps({"error": str(e)}).encode()
|
||||
self.send_response(500)
|
||||
self.send_header("Content-Type", "application/json")
|
||||
self.send_header("Content-Length", str(len(resp)))
|
||||
self.end_headers()
|
||||
self.wfile.write(resp)
|
||||
else:
|
||||
self.send_error(404)
|
||||
|
||||
def log_message(self, format: str, *args: object) -> None:
|
||||
# Suppress request logging to keep terminal clean
|
||||
pass
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description="Generate and serve eval review")
|
||||
parser.add_argument("workspace", type=Path, help="Path to workspace directory")
|
||||
parser.add_argument("--port", "-p", type=int, default=3117, help="Server port (default: 3117)")
|
||||
parser.add_argument("--skill-name", "-n", type=str, default=None, help="Skill name for header")
|
||||
parser.add_argument(
|
||||
"--previous-workspace", type=Path, default=None,
|
||||
help="Path to previous iteration's workspace (shows old outputs and feedback as context)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--benchmark", type=Path, default=None,
|
||||
help="Path to benchmark.json to show in the Benchmark tab",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--static", "-s", type=Path, default=None,
|
||||
help="Write standalone HTML to this path instead of starting a server",
|
||||
)
|
||||
args = parser.parse_args()
|
||||
|
||||
workspace = args.workspace.resolve()
|
||||
if not workspace.is_dir():
|
||||
print(f"Error: {workspace} is not a directory", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
runs = find_runs(workspace)
|
||||
if not runs:
|
||||
print(f"No runs found in {workspace}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
skill_name = args.skill_name or workspace.name.replace("-workspace", "")
|
||||
feedback_path = workspace / "feedback.json"
|
||||
|
||||
previous: dict[str, dict] = {}
|
||||
if args.previous_workspace:
|
||||
previous = load_previous_iteration(args.previous_workspace.resolve())
|
||||
|
||||
benchmark_path = args.benchmark.resolve() if args.benchmark else None
|
||||
benchmark = None
|
||||
if benchmark_path and benchmark_path.exists():
|
||||
try:
|
||||
benchmark = json.loads(benchmark_path.read_text())
|
||||
except (json.JSONDecodeError, OSError):
|
||||
pass
|
||||
|
||||
if args.static:
|
||||
html = generate_html(runs, skill_name, previous, benchmark)
|
||||
args.static.parent.mkdir(parents=True, exist_ok=True)
|
||||
args.static.write_text(html)
|
||||
print(f"\n Static viewer written to: {args.static}\n")
|
||||
sys.exit(0)
|
||||
|
||||
# Kill any existing process on the target port
|
||||
port = args.port
|
||||
_kill_port(port)
|
||||
handler = partial(ReviewHandler, workspace, skill_name, feedback_path, previous, benchmark_path)
|
||||
try:
|
||||
server = HTTPServer(("127.0.0.1", port), handler)
|
||||
except OSError:
|
||||
# Port still in use after kill attempt — find a free one
|
||||
server = HTTPServer(("127.0.0.1", 0), handler)
|
||||
port = server.server_address[1]
|
||||
|
||||
url = f"http://localhost:{port}"
|
||||
print(f"\n Eval Viewer")
|
||||
print(f" ─────────────────────────────────")
|
||||
print(f" URL: {url}")
|
||||
print(f" Workspace: {workspace}")
|
||||
print(f" Feedback: {feedback_path}")
|
||||
if previous:
|
||||
print(f" Previous: {args.previous_workspace} ({len(previous)} runs)")
|
||||
if benchmark_path:
|
||||
print(f" Benchmark: {benchmark_path}")
|
||||
print(f"\n Press Ctrl+C to stop.\n")
|
||||
|
||||
webbrowser.open(url)
|
||||
|
||||
try:
|
||||
server.serve_forever()
|
||||
except KeyboardInterrupt:
|
||||
print("\nStopped.")
|
||||
server.server_close()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,430 @@
|
||||
# JSON Schemas
|
||||
|
||||
This document defines the JSON schemas used by skill-creator.
|
||||
|
||||
---
|
||||
|
||||
## evals.json
|
||||
|
||||
Defines the evals for a skill. Located at `evals/evals.json` within the skill directory.
|
||||
|
||||
```json
|
||||
{
|
||||
"skill_name": "example-skill",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "User's example prompt",
|
||||
"expected_output": "Description of expected result",
|
||||
"files": ["evals/files/sample1.pdf"],
|
||||
"expectations": [
|
||||
"The output includes X",
|
||||
"The skill used script Y"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `skill_name`: Name matching the skill's frontmatter
|
||||
- `evals[].id`: Unique integer identifier
|
||||
- `evals[].prompt`: The task to execute
|
||||
- `evals[].expected_output`: Human-readable description of success
|
||||
- `evals[].files`: Optional list of input file paths (relative to skill root)
|
||||
- `evals[].expectations`: List of verifiable statements
|
||||
|
||||
---
|
||||
|
||||
## history.json
|
||||
|
||||
Tracks version progression in Improve mode. Located at workspace root.
|
||||
|
||||
```json
|
||||
{
|
||||
"started_at": "2026-01-15T10:30:00Z",
|
||||
"skill_name": "pdf",
|
||||
"current_best": "v2",
|
||||
"iterations": [
|
||||
{
|
||||
"version": "v0",
|
||||
"parent": null,
|
||||
"expectation_pass_rate": 0.65,
|
||||
"grading_result": "baseline",
|
||||
"is_current_best": false
|
||||
},
|
||||
{
|
||||
"version": "v1",
|
||||
"parent": "v0",
|
||||
"expectation_pass_rate": 0.75,
|
||||
"grading_result": "won",
|
||||
"is_current_best": false
|
||||
},
|
||||
{
|
||||
"version": "v2",
|
||||
"parent": "v1",
|
||||
"expectation_pass_rate": 0.85,
|
||||
"grading_result": "won",
|
||||
"is_current_best": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `started_at`: ISO timestamp of when improvement started
|
||||
- `skill_name`: Name of the skill being improved
|
||||
- `current_best`: Version identifier of the best performer
|
||||
- `iterations[].version`: Version identifier (v0, v1, ...)
|
||||
- `iterations[].parent`: Parent version this was derived from
|
||||
- `iterations[].expectation_pass_rate`: Pass rate from grading
|
||||
- `iterations[].grading_result`: "baseline", "won", "lost", or "tie"
|
||||
- `iterations[].is_current_best`: Whether this is the current best version
|
||||
|
||||
---
|
||||
|
||||
## grading.json
|
||||
|
||||
Output from the grader agent. Located at `<run-dir>/grading.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"expectations": [
|
||||
{
|
||||
"text": "The output includes the name 'John Smith'",
|
||||
"passed": true,
|
||||
"evidence": "Found in transcript Step 3: 'Extracted names: John Smith, Sarah Johnson'"
|
||||
},
|
||||
{
|
||||
"text": "The spreadsheet has a SUM formula in cell B10",
|
||||
"passed": false,
|
||||
"evidence": "No spreadsheet was created. The output was a text file."
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"passed": 2,
|
||||
"failed": 1,
|
||||
"total": 3,
|
||||
"pass_rate": 0.67
|
||||
},
|
||||
"execution_metrics": {
|
||||
"tool_calls": {
|
||||
"Read": 5,
|
||||
"Write": 2,
|
||||
"Bash": 8
|
||||
},
|
||||
"total_tool_calls": 15,
|
||||
"total_steps": 6,
|
||||
"errors_encountered": 0,
|
||||
"output_chars": 12450,
|
||||
"transcript_chars": 3200
|
||||
},
|
||||
"timing": {
|
||||
"executor_duration_seconds": 165.0,
|
||||
"grader_duration_seconds": 26.0,
|
||||
"total_duration_seconds": 191.0
|
||||
},
|
||||
"claims": [
|
||||
{
|
||||
"claim": "The form has 12 fillable fields",
|
||||
"type": "factual",
|
||||
"verified": true,
|
||||
"evidence": "Counted 12 fields in field_info.json"
|
||||
}
|
||||
],
|
||||
"user_notes_summary": {
|
||||
"uncertainties": ["Used 2023 data, may be stale"],
|
||||
"needs_review": [],
|
||||
"workarounds": ["Fell back to text overlay for non-fillable fields"]
|
||||
},
|
||||
"eval_feedback": {
|
||||
"suggestions": [
|
||||
{
|
||||
"assertion": "The output includes the name 'John Smith'",
|
||||
"reason": "A hallucinated document that mentions the name would also pass"
|
||||
}
|
||||
],
|
||||
"overall": "Assertions check presence but not correctness."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `expectations[]`: Graded expectations with evidence
|
||||
- `summary`: Aggregate pass/fail counts
|
||||
- `execution_metrics`: Tool usage and output size (from executor's metrics.json)
|
||||
- `timing`: Wall clock timing (from timing.json)
|
||||
- `claims`: Extracted and verified claims from the output
|
||||
- `user_notes_summary`: Issues flagged by the executor
|
||||
- `eval_feedback`: (optional) Improvement suggestions for the evals, only present when the grader identifies issues worth raising
|
||||
|
||||
---
|
||||
|
||||
## metrics.json
|
||||
|
||||
Output from the executor agent. Located at `<run-dir>/outputs/metrics.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"tool_calls": {
|
||||
"Read": 5,
|
||||
"Write": 2,
|
||||
"Bash": 8,
|
||||
"Edit": 1,
|
||||
"Glob": 2,
|
||||
"Grep": 0
|
||||
},
|
||||
"total_tool_calls": 18,
|
||||
"total_steps": 6,
|
||||
"files_created": ["filled_form.pdf", "field_values.json"],
|
||||
"errors_encountered": 0,
|
||||
"output_chars": 12450,
|
||||
"transcript_chars": 3200
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `tool_calls`: Count per tool type
|
||||
- `total_tool_calls`: Sum of all tool calls
|
||||
- `total_steps`: Number of major execution steps
|
||||
- `files_created`: List of output files created
|
||||
- `errors_encountered`: Number of errors during execution
|
||||
- `output_chars`: Total character count of output files
|
||||
- `transcript_chars`: Character count of transcript
|
||||
|
||||
---
|
||||
|
||||
## timing.json
|
||||
|
||||
Wall clock timing for a run. Located at `<run-dir>/timing.json`.
|
||||
|
||||
**How to capture:** When a subagent task completes, the task notification includes `total_tokens` and `duration_ms`. Save these immediately — they are not persisted anywhere else and cannot be recovered after the fact.
|
||||
|
||||
```json
|
||||
{
|
||||
"total_tokens": 84852,
|
||||
"duration_ms": 23332,
|
||||
"total_duration_seconds": 23.3,
|
||||
"executor_start": "2026-01-15T10:30:00Z",
|
||||
"executor_end": "2026-01-15T10:32:45Z",
|
||||
"executor_duration_seconds": 165.0,
|
||||
"grader_start": "2026-01-15T10:32:46Z",
|
||||
"grader_end": "2026-01-15T10:33:12Z",
|
||||
"grader_duration_seconds": 26.0
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## benchmark.json
|
||||
|
||||
Output from Benchmark mode. Located at `benchmarks/<timestamp>/benchmark.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"skill_name": "pdf",
|
||||
"skill_path": "/path/to/pdf",
|
||||
"executor_model": "claude-sonnet-4-20250514",
|
||||
"analyzer_model": "most-capable-model",
|
||||
"timestamp": "2026-01-15T10:30:00Z",
|
||||
"evals_run": [1, 2, 3],
|
||||
"runs_per_configuration": 3
|
||||
},
|
||||
|
||||
"runs": [
|
||||
{
|
||||
"eval_id": 1,
|
||||
"eval_name": "Ocean",
|
||||
"configuration": "with_skill",
|
||||
"run_number": 1,
|
||||
"result": {
|
||||
"pass_rate": 0.85,
|
||||
"passed": 6,
|
||||
"failed": 1,
|
||||
"total": 7,
|
||||
"time_seconds": 42.5,
|
||||
"tokens": 3800,
|
||||
"tool_calls": 18,
|
||||
"errors": 0
|
||||
},
|
||||
"expectations": [
|
||||
{"text": "...", "passed": true, "evidence": "..."}
|
||||
],
|
||||
"notes": [
|
||||
"Used 2023 data, may be stale",
|
||||
"Fell back to text overlay for non-fillable fields"
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
"run_summary": {
|
||||
"with_skill": {
|
||||
"pass_rate": {"mean": 0.85, "stddev": 0.05, "min": 0.80, "max": 0.90},
|
||||
"time_seconds": {"mean": 45.0, "stddev": 12.0, "min": 32.0, "max": 58.0},
|
||||
"tokens": {"mean": 3800, "stddev": 400, "min": 3200, "max": 4100}
|
||||
},
|
||||
"without_skill": {
|
||||
"pass_rate": {"mean": 0.35, "stddev": 0.08, "min": 0.28, "max": 0.45},
|
||||
"time_seconds": {"mean": 32.0, "stddev": 8.0, "min": 24.0, "max": 42.0},
|
||||
"tokens": {"mean": 2100, "stddev": 300, "min": 1800, "max": 2500}
|
||||
},
|
||||
"delta": {
|
||||
"pass_rate": "+0.50",
|
||||
"time_seconds": "+13.0",
|
||||
"tokens": "+1700"
|
||||
}
|
||||
},
|
||||
|
||||
"notes": [
|
||||
"Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value",
|
||||
"Eval 3 shows high variance (50% ± 40%) - may be flaky or model-dependent",
|
||||
"Without-skill runs consistently fail on table extraction expectations",
|
||||
"Skill adds 13s average execution time but improves pass rate by 50%"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `metadata`: Information about the benchmark run
|
||||
- `skill_name`: Name of the skill
|
||||
- `timestamp`: When the benchmark was run
|
||||
- `evals_run`: List of eval names or IDs
|
||||
- `runs_per_configuration`: Number of runs per config (e.g. 3)
|
||||
- `runs[]`: Individual run results
|
||||
- `eval_id`: Numeric eval identifier
|
||||
- `eval_name`: Human-readable eval name (used as section header in the viewer)
|
||||
- `configuration`: Must be `"with_skill"` or `"without_skill"` (the viewer uses this exact string for grouping and color coding)
|
||||
- `run_number`: Integer run number (1, 2, 3...)
|
||||
- `result`: Nested object with `pass_rate`, `passed`, `total`, `time_seconds`, `tokens`, `errors`
|
||||
- `run_summary`: Statistical aggregates per configuration
|
||||
- `with_skill` / `without_skill`: Each contains `pass_rate`, `time_seconds`, `tokens` objects with `mean` and `stddev` fields
|
||||
- `delta`: Difference strings like `"+0.50"`, `"+13.0"`, `"+1700"`
|
||||
- `notes`: Freeform observations from the analyzer
|
||||
|
||||
**Important:** The viewer reads these field names exactly. Using `config` instead of `configuration`, or putting `pass_rate` at the top level of a run instead of nested under `result`, will cause the viewer to show empty/zero values. Always reference this schema when generating benchmark.json manually.
|
||||
|
||||
---
|
||||
|
||||
## comparison.json
|
||||
|
||||
Output from blind comparator. Located at `<grading-dir>/comparison-N.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"winner": "A",
|
||||
"reasoning": "Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies.",
|
||||
"rubric": {
|
||||
"A": {
|
||||
"content": {
|
||||
"correctness": 5,
|
||||
"completeness": 5,
|
||||
"accuracy": 4
|
||||
},
|
||||
"structure": {
|
||||
"organization": 4,
|
||||
"formatting": 5,
|
||||
"usability": 4
|
||||
},
|
||||
"content_score": 4.7,
|
||||
"structure_score": 4.3,
|
||||
"overall_score": 9.0
|
||||
},
|
||||
"B": {
|
||||
"content": {
|
||||
"correctness": 3,
|
||||
"completeness": 2,
|
||||
"accuracy": 3
|
||||
},
|
||||
"structure": {
|
||||
"organization": 3,
|
||||
"formatting": 2,
|
||||
"usability": 3
|
||||
},
|
||||
"content_score": 2.7,
|
||||
"structure_score": 2.7,
|
||||
"overall_score": 5.4
|
||||
}
|
||||
},
|
||||
"output_quality": {
|
||||
"A": {
|
||||
"score": 9,
|
||||
"strengths": ["Complete solution", "Well-formatted", "All fields present"],
|
||||
"weaknesses": ["Minor style inconsistency in header"]
|
||||
},
|
||||
"B": {
|
||||
"score": 5,
|
||||
"strengths": ["Readable output", "Correct basic structure"],
|
||||
"weaknesses": ["Missing date field", "Formatting inconsistencies", "Partial data extraction"]
|
||||
}
|
||||
},
|
||||
"expectation_results": {
|
||||
"A": {
|
||||
"passed": 4,
|
||||
"total": 5,
|
||||
"pass_rate": 0.80,
|
||||
"details": [
|
||||
{"text": "Output includes name", "passed": true}
|
||||
]
|
||||
},
|
||||
"B": {
|
||||
"passed": 3,
|
||||
"total": 5,
|
||||
"pass_rate": 0.60,
|
||||
"details": [
|
||||
{"text": "Output includes name", "passed": true}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## analysis.json
|
||||
|
||||
Output from post-hoc analyzer. Located at `<grading-dir>/analysis.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"comparison_summary": {
|
||||
"winner": "A",
|
||||
"winner_skill": "path/to/winner/skill",
|
||||
"loser_skill": "path/to/loser/skill",
|
||||
"comparator_reasoning": "Brief summary of why comparator chose winner"
|
||||
},
|
||||
"winner_strengths": [
|
||||
"Clear step-by-step instructions for handling multi-page documents",
|
||||
"Included validation script that caught formatting errors"
|
||||
],
|
||||
"loser_weaknesses": [
|
||||
"Vague instruction 'process the document appropriately' led to inconsistent behavior",
|
||||
"No script for validation, agent had to improvise"
|
||||
],
|
||||
"instruction_following": {
|
||||
"winner": {
|
||||
"score": 9,
|
||||
"issues": ["Minor: skipped optional logging step"]
|
||||
},
|
||||
"loser": {
|
||||
"score": 6,
|
||||
"issues": [
|
||||
"Did not use the skill's formatting template",
|
||||
"Invented own approach instead of following step 3"
|
||||
]
|
||||
}
|
||||
},
|
||||
"improvement_suggestions": [
|
||||
{
|
||||
"priority": "high",
|
||||
"category": "instructions",
|
||||
"suggestion": "Replace 'process the document appropriately' with explicit steps",
|
||||
"expected_impact": "Would eliminate ambiguity that caused inconsistent behavior"
|
||||
}
|
||||
],
|
||||
"transcript_insights": {
|
||||
"winner_execution_pattern": "Read skill -> Followed 5-step process -> Used validation script",
|
||||
"loser_execution_pattern": "Read skill -> Unclear on approach -> Tried 3 different methods"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,401 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Aggregate individual run results into benchmark summary statistics.
|
||||
|
||||
Reads grading.json files from run directories and produces:
|
||||
- run_summary with mean, stddev, min, max for each metric
|
||||
- delta between with_skill and without_skill configurations
|
||||
|
||||
Usage:
|
||||
python aggregate_benchmark.py <benchmark_dir>
|
||||
|
||||
Example:
|
||||
python aggregate_benchmark.py benchmarks/2026-01-15T10-30-00/
|
||||
|
||||
The script supports two directory layouts:
|
||||
|
||||
Workspace layout (from skill-creator iterations):
|
||||
<benchmark_dir>/
|
||||
└── eval-N/
|
||||
├── with_skill/
|
||||
│ ├── run-1/grading.json
|
||||
│ └── run-2/grading.json
|
||||
└── without_skill/
|
||||
├── run-1/grading.json
|
||||
└── run-2/grading.json
|
||||
|
||||
Legacy layout (with runs/ subdirectory):
|
||||
<benchmark_dir>/
|
||||
└── runs/
|
||||
└── eval-N/
|
||||
├── with_skill/
|
||||
│ └── run-1/grading.json
|
||||
└── without_skill/
|
||||
└── run-1/grading.json
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import math
|
||||
import sys
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def calculate_stats(values: list[float]) -> dict:
|
||||
"""Calculate mean, stddev, min, max for a list of values."""
|
||||
if not values:
|
||||
return {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0}
|
||||
|
||||
n = len(values)
|
||||
mean = sum(values) / n
|
||||
|
||||
if n > 1:
|
||||
variance = sum((x - mean) ** 2 for x in values) / (n - 1)
|
||||
stddev = math.sqrt(variance)
|
||||
else:
|
||||
stddev = 0.0
|
||||
|
||||
return {
|
||||
"mean": round(mean, 4),
|
||||
"stddev": round(stddev, 4),
|
||||
"min": round(min(values), 4),
|
||||
"max": round(max(values), 4)
|
||||
}
|
||||
|
||||
|
||||
def load_run_results(benchmark_dir: Path) -> dict:
|
||||
"""
|
||||
Load all run results from a benchmark directory.
|
||||
|
||||
Returns dict keyed by config name (e.g. "with_skill"/"without_skill",
|
||||
or "new_skill"/"old_skill"), each containing a list of run results.
|
||||
"""
|
||||
# Support both layouts: eval dirs directly under benchmark_dir, or under runs/
|
||||
runs_dir = benchmark_dir / "runs"
|
||||
if runs_dir.exists():
|
||||
search_dir = runs_dir
|
||||
elif list(benchmark_dir.glob("eval-*")):
|
||||
search_dir = benchmark_dir
|
||||
else:
|
||||
print(f"No eval directories found in {benchmark_dir} or {benchmark_dir / 'runs'}")
|
||||
return {}
|
||||
|
||||
results: dict[str, list] = {}
|
||||
|
||||
for eval_idx, eval_dir in enumerate(sorted(search_dir.glob("eval-*"))):
|
||||
metadata_path = eval_dir / "eval_metadata.json"
|
||||
if metadata_path.exists():
|
||||
try:
|
||||
with open(metadata_path) as mf:
|
||||
eval_id = json.load(mf).get("eval_id", eval_idx)
|
||||
except (json.JSONDecodeError, OSError):
|
||||
eval_id = eval_idx
|
||||
else:
|
||||
try:
|
||||
eval_id = int(eval_dir.name.split("-")[1])
|
||||
except ValueError:
|
||||
eval_id = eval_idx
|
||||
|
||||
# Discover config directories dynamically rather than hardcoding names
|
||||
for config_dir in sorted(eval_dir.iterdir()):
|
||||
if not config_dir.is_dir():
|
||||
continue
|
||||
# Skip non-config directories (inputs, outputs, etc.)
|
||||
if not list(config_dir.glob("run-*")):
|
||||
continue
|
||||
config = config_dir.name
|
||||
if config not in results:
|
||||
results[config] = []
|
||||
|
||||
for run_dir in sorted(config_dir.glob("run-*")):
|
||||
run_number = int(run_dir.name.split("-")[1])
|
||||
grading_file = run_dir / "grading.json"
|
||||
|
||||
if not grading_file.exists():
|
||||
print(f"Warning: grading.json not found in {run_dir}")
|
||||
continue
|
||||
|
||||
try:
|
||||
with open(grading_file) as f:
|
||||
grading = json.load(f)
|
||||
except json.JSONDecodeError as e:
|
||||
print(f"Warning: Invalid JSON in {grading_file}: {e}")
|
||||
continue
|
||||
|
||||
# Extract metrics
|
||||
result = {
|
||||
"eval_id": eval_id,
|
||||
"run_number": run_number,
|
||||
"pass_rate": grading.get("summary", {}).get("pass_rate", 0.0),
|
||||
"passed": grading.get("summary", {}).get("passed", 0),
|
||||
"failed": grading.get("summary", {}).get("failed", 0),
|
||||
"total": grading.get("summary", {}).get("total", 0),
|
||||
}
|
||||
|
||||
# Extract timing — check grading.json first, then sibling timing.json
|
||||
timing = grading.get("timing", {})
|
||||
result["time_seconds"] = timing.get("total_duration_seconds", 0.0)
|
||||
timing_file = run_dir / "timing.json"
|
||||
if result["time_seconds"] == 0.0 and timing_file.exists():
|
||||
try:
|
||||
with open(timing_file) as tf:
|
||||
timing_data = json.load(tf)
|
||||
result["time_seconds"] = timing_data.get("total_duration_seconds", 0.0)
|
||||
result["tokens"] = timing_data.get("total_tokens", 0)
|
||||
except json.JSONDecodeError:
|
||||
pass
|
||||
|
||||
# Extract metrics if available
|
||||
metrics = grading.get("execution_metrics", {})
|
||||
result["tool_calls"] = metrics.get("total_tool_calls", 0)
|
||||
if not result.get("tokens"):
|
||||
result["tokens"] = metrics.get("output_chars", 0)
|
||||
result["errors"] = metrics.get("errors_encountered", 0)
|
||||
|
||||
# Extract expectations — viewer requires fields: text, passed, evidence
|
||||
raw_expectations = grading.get("expectations", [])
|
||||
for exp in raw_expectations:
|
||||
if "text" not in exp or "passed" not in exp:
|
||||
print(f"Warning: expectation in {grading_file} missing required fields (text, passed, evidence): {exp}")
|
||||
result["expectations"] = raw_expectations
|
||||
|
||||
# Extract notes from user_notes_summary
|
||||
notes_summary = grading.get("user_notes_summary", {})
|
||||
notes = []
|
||||
notes.extend(notes_summary.get("uncertainties", []))
|
||||
notes.extend(notes_summary.get("needs_review", []))
|
||||
notes.extend(notes_summary.get("workarounds", []))
|
||||
result["notes"] = notes
|
||||
|
||||
results[config].append(result)
|
||||
|
||||
return results
|
||||
|
||||
|
||||
def aggregate_results(results: dict) -> dict:
|
||||
"""
|
||||
Aggregate run results into summary statistics.
|
||||
|
||||
Returns run_summary with stats for each configuration and delta.
|
||||
"""
|
||||
run_summary = {}
|
||||
configs = list(results.keys())
|
||||
|
||||
for config in configs:
|
||||
runs = results.get(config, [])
|
||||
|
||||
if not runs:
|
||||
run_summary[config] = {
|
||||
"pass_rate": {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0},
|
||||
"time_seconds": {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0},
|
||||
"tokens": {"mean": 0, "stddev": 0, "min": 0, "max": 0}
|
||||
}
|
||||
continue
|
||||
|
||||
pass_rates = [r["pass_rate"] for r in runs]
|
||||
times = [r["time_seconds"] for r in runs]
|
||||
tokens = [r.get("tokens", 0) for r in runs]
|
||||
|
||||
run_summary[config] = {
|
||||
"pass_rate": calculate_stats(pass_rates),
|
||||
"time_seconds": calculate_stats(times),
|
||||
"tokens": calculate_stats(tokens)
|
||||
}
|
||||
|
||||
# Calculate delta between the first two configs (if two exist)
|
||||
if len(configs) >= 2:
|
||||
primary = run_summary.get(configs[0], {})
|
||||
baseline = run_summary.get(configs[1], {})
|
||||
else:
|
||||
primary = run_summary.get(configs[0], {}) if configs else {}
|
||||
baseline = {}
|
||||
|
||||
delta_pass_rate = primary.get("pass_rate", {}).get("mean", 0) - baseline.get("pass_rate", {}).get("mean", 0)
|
||||
delta_time = primary.get("time_seconds", {}).get("mean", 0) - baseline.get("time_seconds", {}).get("mean", 0)
|
||||
delta_tokens = primary.get("tokens", {}).get("mean", 0) - baseline.get("tokens", {}).get("mean", 0)
|
||||
|
||||
run_summary["delta"] = {
|
||||
"pass_rate": f"{delta_pass_rate:+.2f}",
|
||||
"time_seconds": f"{delta_time:+.1f}",
|
||||
"tokens": f"{delta_tokens:+.0f}"
|
||||
}
|
||||
|
||||
return run_summary
|
||||
|
||||
|
||||
def generate_benchmark(benchmark_dir: Path, skill_name: str = "", skill_path: str = "") -> dict:
|
||||
"""
|
||||
Generate complete benchmark.json from run results.
|
||||
"""
|
||||
results = load_run_results(benchmark_dir)
|
||||
run_summary = aggregate_results(results)
|
||||
|
||||
# Build runs array for benchmark.json
|
||||
runs = []
|
||||
for config in results:
|
||||
for result in results[config]:
|
||||
runs.append({
|
||||
"eval_id": result["eval_id"],
|
||||
"configuration": config,
|
||||
"run_number": result["run_number"],
|
||||
"result": {
|
||||
"pass_rate": result["pass_rate"],
|
||||
"passed": result["passed"],
|
||||
"failed": result["failed"],
|
||||
"total": result["total"],
|
||||
"time_seconds": result["time_seconds"],
|
||||
"tokens": result.get("tokens", 0),
|
||||
"tool_calls": result.get("tool_calls", 0),
|
||||
"errors": result.get("errors", 0)
|
||||
},
|
||||
"expectations": result["expectations"],
|
||||
"notes": result["notes"]
|
||||
})
|
||||
|
||||
# Determine eval IDs from results
|
||||
eval_ids = sorted(set(
|
||||
r["eval_id"]
|
||||
for config in results.values()
|
||||
for r in config
|
||||
))
|
||||
|
||||
benchmark = {
|
||||
"metadata": {
|
||||
"skill_name": skill_name or "<skill-name>",
|
||||
"skill_path": skill_path or "<path/to/skill>",
|
||||
"executor_model": "<model-name>",
|
||||
"analyzer_model": "<model-name>",
|
||||
"timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
|
||||
"evals_run": eval_ids,
|
||||
"runs_per_configuration": 3
|
||||
},
|
||||
"runs": runs,
|
||||
"run_summary": run_summary,
|
||||
"notes": [] # To be filled by analyzer
|
||||
}
|
||||
|
||||
return benchmark
|
||||
|
||||
|
||||
def generate_markdown(benchmark: dict) -> str:
|
||||
"""Generate human-readable benchmark.md from benchmark data."""
|
||||
metadata = benchmark["metadata"]
|
||||
run_summary = benchmark["run_summary"]
|
||||
|
||||
# Determine config names (excluding "delta")
|
||||
configs = [k for k in run_summary if k != "delta"]
|
||||
config_a = configs[0] if len(configs) >= 1 else "config_a"
|
||||
config_b = configs[1] if len(configs) >= 2 else "config_b"
|
||||
label_a = config_a.replace("_", " ").title()
|
||||
label_b = config_b.replace("_", " ").title()
|
||||
|
||||
lines = [
|
||||
f"# Skill Benchmark: {metadata['skill_name']}",
|
||||
"",
|
||||
f"**Model**: {metadata['executor_model']}",
|
||||
f"**Date**: {metadata['timestamp']}",
|
||||
f"**Evals**: {', '.join(map(str, metadata['evals_run']))} ({metadata['runs_per_configuration']} runs each per configuration)",
|
||||
"",
|
||||
"## Summary",
|
||||
"",
|
||||
f"| Metric | {label_a} | {label_b} | Delta |",
|
||||
"|--------|------------|---------------|-------|",
|
||||
]
|
||||
|
||||
a_summary = run_summary.get(config_a, {})
|
||||
b_summary = run_summary.get(config_b, {})
|
||||
delta = run_summary.get("delta", {})
|
||||
|
||||
# Format pass rate
|
||||
a_pr = a_summary.get("pass_rate", {})
|
||||
b_pr = b_summary.get("pass_rate", {})
|
||||
lines.append(f"| Pass Rate | {a_pr.get('mean', 0)*100:.0f}% ± {a_pr.get('stddev', 0)*100:.0f}% | {b_pr.get('mean', 0)*100:.0f}% ± {b_pr.get('stddev', 0)*100:.0f}% | {delta.get('pass_rate', '—')} |")
|
||||
|
||||
# Format time
|
||||
a_time = a_summary.get("time_seconds", {})
|
||||
b_time = b_summary.get("time_seconds", {})
|
||||
lines.append(f"| Time | {a_time.get('mean', 0):.1f}s ± {a_time.get('stddev', 0):.1f}s | {b_time.get('mean', 0):.1f}s ± {b_time.get('stddev', 0):.1f}s | {delta.get('time_seconds', '—')}s |")
|
||||
|
||||
# Format tokens
|
||||
a_tokens = a_summary.get("tokens", {})
|
||||
b_tokens = b_summary.get("tokens", {})
|
||||
lines.append(f"| Tokens | {a_tokens.get('mean', 0):.0f} ± {a_tokens.get('stddev', 0):.0f} | {b_tokens.get('mean', 0):.0f} ± {b_tokens.get('stddev', 0):.0f} | {delta.get('tokens', '—')} |")
|
||||
|
||||
# Notes section
|
||||
if benchmark.get("notes"):
|
||||
lines.extend([
|
||||
"",
|
||||
"## Notes",
|
||||
""
|
||||
])
|
||||
for note in benchmark["notes"]:
|
||||
lines.append(f"- {note}")
|
||||
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Aggregate benchmark run results into summary statistics"
|
||||
)
|
||||
parser.add_argument(
|
||||
"benchmark_dir",
|
||||
type=Path,
|
||||
help="Path to the benchmark directory"
|
||||
)
|
||||
parser.add_argument(
|
||||
"--skill-name",
|
||||
default="",
|
||||
help="Name of the skill being benchmarked"
|
||||
)
|
||||
parser.add_argument(
|
||||
"--skill-path",
|
||||
default="",
|
||||
help="Path to the skill being benchmarked"
|
||||
)
|
||||
parser.add_argument(
|
||||
"--output", "-o",
|
||||
type=Path,
|
||||
help="Output path for benchmark.json (default: <benchmark_dir>/benchmark.json)"
|
||||
)
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
if not args.benchmark_dir.exists():
|
||||
print(f"Directory not found: {args.benchmark_dir}")
|
||||
sys.exit(1)
|
||||
|
||||
# Generate benchmark
|
||||
benchmark = generate_benchmark(args.benchmark_dir, args.skill_name, args.skill_path)
|
||||
|
||||
# Determine output paths
|
||||
output_json = args.output or (args.benchmark_dir / "benchmark.json")
|
||||
output_md = output_json.with_suffix(".md")
|
||||
|
||||
# Write benchmark.json
|
||||
with open(output_json, "w") as f:
|
||||
json.dump(benchmark, f, indent=2)
|
||||
print(f"Generated: {output_json}")
|
||||
|
||||
# Write benchmark.md
|
||||
markdown = generate_markdown(benchmark)
|
||||
with open(output_md, "w") as f:
|
||||
f.write(markdown)
|
||||
print(f"Generated: {output_md}")
|
||||
|
||||
# Print summary
|
||||
run_summary = benchmark["run_summary"]
|
||||
configs = [k for k in run_summary if k != "delta"]
|
||||
delta = run_summary.get("delta", {})
|
||||
|
||||
print(f"\nSummary:")
|
||||
for config in configs:
|
||||
pr = run_summary[config]["pass_rate"]["mean"]
|
||||
label = config.replace("_", " ").title()
|
||||
print(f" {label}: {pr*100:.1f}% pass rate")
|
||||
print(f" Delta: {delta.get('pass_rate', '—')}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,326 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Generate an HTML report from run_loop.py output.
|
||||
|
||||
Takes the JSON output from run_loop.py and generates a visual HTML report
|
||||
showing each description attempt with check/x for each test case.
|
||||
Distinguishes between train and test queries.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import html
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def generate_html(data: dict, auto_refresh: bool = False, skill_name: str = "") -> str:
|
||||
"""Generate HTML report from loop output data. If auto_refresh is True, adds a meta refresh tag."""
|
||||
history = data.get("history", [])
|
||||
holdout = data.get("holdout", 0)
|
||||
title_prefix = html.escape(skill_name + " \u2014 ") if skill_name else ""
|
||||
|
||||
# Get all unique queries from train and test sets, with should_trigger info
|
||||
train_queries: list[dict] = []
|
||||
test_queries: list[dict] = []
|
||||
if history:
|
||||
for r in history[0].get("train_results", history[0].get("results", [])):
|
||||
train_queries.append({"query": r["query"], "should_trigger": r.get("should_trigger", True)})
|
||||
if history[0].get("test_results"):
|
||||
for r in history[0].get("test_results", []):
|
||||
test_queries.append({"query": r["query"], "should_trigger": r.get("should_trigger", True)})
|
||||
|
||||
refresh_tag = ' <meta http-equiv="refresh" content="5">\n' if auto_refresh else ""
|
||||
|
||||
html_parts = ["""<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
""" + refresh_tag + """ <title>""" + title_prefix + """Skill Description Optimization</title>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@500;600&family=Lora:wght@400;500&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body {
|
||||
font-family: 'Lora', Georgia, serif;
|
||||
max-width: 100%;
|
||||
margin: 0 auto;
|
||||
padding: 20px;
|
||||
background: #faf9f5;
|
||||
color: #141413;
|
||||
}
|
||||
h1 { font-family: 'Poppins', sans-serif; color: #141413; }
|
||||
.explainer {
|
||||
background: white;
|
||||
padding: 15px;
|
||||
border-radius: 6px;
|
||||
margin-bottom: 20px;
|
||||
border: 1px solid #e8e6dc;
|
||||
color: #b0aea5;
|
||||
font-size: 0.875rem;
|
||||
line-height: 1.6;
|
||||
}
|
||||
.summary {
|
||||
background: white;
|
||||
padding: 15px;
|
||||
border-radius: 6px;
|
||||
margin-bottom: 20px;
|
||||
border: 1px solid #e8e6dc;
|
||||
}
|
||||
.summary p { margin: 5px 0; }
|
||||
.best { color: #788c5d; font-weight: bold; }
|
||||
.table-container {
|
||||
overflow-x: auto;
|
||||
width: 100%;
|
||||
}
|
||||
table {
|
||||
border-collapse: collapse;
|
||||
background: white;
|
||||
border: 1px solid #e8e6dc;
|
||||
border-radius: 6px;
|
||||
font-size: 12px;
|
||||
min-width: 100%;
|
||||
}
|
||||
th, td {
|
||||
padding: 8px;
|
||||
text-align: left;
|
||||
border: 1px solid #e8e6dc;
|
||||
white-space: normal;
|
||||
word-wrap: break-word;
|
||||
}
|
||||
th {
|
||||
font-family: 'Poppins', sans-serif;
|
||||
background: #141413;
|
||||
color: #faf9f5;
|
||||
font-weight: 500;
|
||||
}
|
||||
th.test-col {
|
||||
background: #6a9bcc;
|
||||
}
|
||||
th.query-col { min-width: 200px; }
|
||||
td.description {
|
||||
font-family: monospace;
|
||||
font-size: 11px;
|
||||
word-wrap: break-word;
|
||||
max-width: 400px;
|
||||
}
|
||||
td.result {
|
||||
text-align: center;
|
||||
font-size: 16px;
|
||||
min-width: 40px;
|
||||
}
|
||||
td.test-result {
|
||||
background: #f0f6fc;
|
||||
}
|
||||
.pass { color: #788c5d; }
|
||||
.fail { color: #c44; }
|
||||
.rate {
|
||||
font-size: 9px;
|
||||
color: #b0aea5;
|
||||
display: block;
|
||||
}
|
||||
tr:hover { background: #faf9f5; }
|
||||
.score {
|
||||
display: inline-block;
|
||||
padding: 2px 6px;
|
||||
border-radius: 4px;
|
||||
font-weight: bold;
|
||||
font-size: 11px;
|
||||
}
|
||||
.score-good { background: #eef2e8; color: #788c5d; }
|
||||
.score-ok { background: #fef3c7; color: #d97706; }
|
||||
.score-bad { background: #fceaea; color: #c44; }
|
||||
.train-label { color: #b0aea5; font-size: 10px; }
|
||||
.test-label { color: #6a9bcc; font-size: 10px; font-weight: bold; }
|
||||
.best-row { background: #f5f8f2; }
|
||||
th.positive-col { border-bottom: 3px solid #788c5d; }
|
||||
th.negative-col { border-bottom: 3px solid #c44; }
|
||||
th.test-col.positive-col { border-bottom: 3px solid #788c5d; }
|
||||
th.test-col.negative-col { border-bottom: 3px solid #c44; }
|
||||
.legend { font-family: 'Poppins', sans-serif; display: flex; gap: 20px; margin-bottom: 10px; font-size: 13px; align-items: center; }
|
||||
.legend-item { display: flex; align-items: center; gap: 6px; }
|
||||
.legend-swatch { width: 16px; height: 16px; border-radius: 3px; display: inline-block; }
|
||||
.swatch-positive { background: #141413; border-bottom: 3px solid #788c5d; }
|
||||
.swatch-negative { background: #141413; border-bottom: 3px solid #c44; }
|
||||
.swatch-test { background: #6a9bcc; }
|
||||
.swatch-train { background: #141413; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>""" + title_prefix + """Skill Description Optimization</h1>
|
||||
<div class="explainer">
|
||||
<strong>Optimizing your skill's description.</strong> This page updates automatically as the agent tests different versions of your skill's description. Each row is an iteration — a new description attempt. The columns show test queries: green checkmarks mean the skill triggered correctly (or correctly didn't trigger), red crosses mean it got it wrong. The "Train" score shows performance on queries used to improve the description; the "Test" score shows performance on held-out queries the optimizer hasn't seen. When it's done, the agent will apply the best-performing description to your skill.
|
||||
</div>
|
||||
"""]
|
||||
|
||||
# Summary section
|
||||
best_test_score = data.get('best_test_score')
|
||||
best_train_score = data.get('best_train_score')
|
||||
html_parts.append(f"""
|
||||
<div class="summary">
|
||||
<p><strong>Original:</strong> {html.escape(data.get('original_description', 'N/A'))}</p>
|
||||
<p class="best"><strong>Best:</strong> {html.escape(data.get('best_description', 'N/A'))}</p>
|
||||
<p><strong>Best Score:</strong> {data.get('best_score', 'N/A')} {'(test)' if best_test_score else '(train)'}</p>
|
||||
<p><strong>Iterations:</strong> {data.get('iterations_run', 0)} | <strong>Train:</strong> {data.get('train_size', '?')} | <strong>Test:</strong> {data.get('test_size', '?')}</p>
|
||||
</div>
|
||||
""")
|
||||
|
||||
# Legend
|
||||
html_parts.append("""
|
||||
<div class="legend">
|
||||
<span style="font-weight:600">Query columns:</span>
|
||||
<span class="legend-item"><span class="legend-swatch swatch-positive"></span> Should trigger</span>
|
||||
<span class="legend-item"><span class="legend-swatch swatch-negative"></span> Should NOT trigger</span>
|
||||
<span class="legend-item"><span class="legend-swatch swatch-train"></span> Train</span>
|
||||
<span class="legend-item"><span class="legend-swatch swatch-test"></span> Test</span>
|
||||
</div>
|
||||
""")
|
||||
|
||||
# Table header
|
||||
html_parts.append("""
|
||||
<div class="table-container">
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Iter</th>
|
||||
<th>Train</th>
|
||||
<th>Test</th>
|
||||
<th class="query-col">Description</th>
|
||||
""")
|
||||
|
||||
# Add column headers for train queries
|
||||
for qinfo in train_queries:
|
||||
polarity = "positive-col" if qinfo["should_trigger"] else "negative-col"
|
||||
html_parts.append(f' <th class="{polarity}">{html.escape(qinfo["query"])}</th>\n')
|
||||
|
||||
# Add column headers for test queries (different color)
|
||||
for qinfo in test_queries:
|
||||
polarity = "positive-col" if qinfo["should_trigger"] else "negative-col"
|
||||
html_parts.append(f' <th class="test-col {polarity}">{html.escape(qinfo["query"])}</th>\n')
|
||||
|
||||
html_parts.append(""" </tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
""")
|
||||
|
||||
# Find best iteration for highlighting
|
||||
if test_queries:
|
||||
best_iter = max(history, key=lambda h: h.get("test_passed") or 0).get("iteration")
|
||||
else:
|
||||
best_iter = max(history, key=lambda h: h.get("train_passed", h.get("passed", 0))).get("iteration")
|
||||
|
||||
# Add rows for each iteration
|
||||
for h in history:
|
||||
iteration = h.get("iteration", "?")
|
||||
train_passed = h.get("train_passed", h.get("passed", 0))
|
||||
train_total = h.get("train_total", h.get("total", 0))
|
||||
test_passed = h.get("test_passed")
|
||||
test_total = h.get("test_total")
|
||||
description = h.get("description", "")
|
||||
train_results = h.get("train_results", h.get("results", []))
|
||||
test_results = h.get("test_results", [])
|
||||
|
||||
# Create lookups for results by query
|
||||
train_by_query = {r["query"]: r for r in train_results}
|
||||
test_by_query = {r["query"]: r for r in test_results} if test_results else {}
|
||||
|
||||
# Compute aggregate correct/total runs across all retries
|
||||
def aggregate_runs(results: list[dict]) -> tuple[int, int]:
|
||||
correct = 0
|
||||
total = 0
|
||||
for r in results:
|
||||
runs = r.get("runs", 0)
|
||||
triggers = r.get("triggers", 0)
|
||||
total += runs
|
||||
if r.get("should_trigger", True):
|
||||
correct += triggers
|
||||
else:
|
||||
correct += runs - triggers
|
||||
return correct, total
|
||||
|
||||
train_correct, train_runs = aggregate_runs(train_results)
|
||||
test_correct, test_runs = aggregate_runs(test_results)
|
||||
|
||||
# Determine score classes
|
||||
def score_class(correct: int, total: int) -> str:
|
||||
if total > 0:
|
||||
ratio = correct / total
|
||||
if ratio >= 0.8:
|
||||
return "score-good"
|
||||
elif ratio >= 0.5:
|
||||
return "score-ok"
|
||||
return "score-bad"
|
||||
|
||||
train_class = score_class(train_correct, train_runs)
|
||||
test_class = score_class(test_correct, test_runs)
|
||||
|
||||
row_class = "best-row" if iteration == best_iter else ""
|
||||
|
||||
html_parts.append(f""" <tr class="{row_class}">
|
||||
<td>{iteration}</td>
|
||||
<td><span class="score {train_class}">{train_correct}/{train_runs}</span></td>
|
||||
<td><span class="score {test_class}">{test_correct}/{test_runs}</span></td>
|
||||
<td class="description">{html.escape(description)}</td>
|
||||
""")
|
||||
|
||||
# Add result for each train query
|
||||
for qinfo in train_queries:
|
||||
r = train_by_query.get(qinfo["query"], {})
|
||||
did_pass = r.get("pass", False)
|
||||
triggers = r.get("triggers", 0)
|
||||
runs = r.get("runs", 0)
|
||||
|
||||
icon = "✓" if did_pass else "✗"
|
||||
css_class = "pass" if did_pass else "fail"
|
||||
|
||||
html_parts.append(f' <td class="result {css_class}">{icon}<span class="rate">{triggers}/{runs}</span></td>\n')
|
||||
|
||||
# Add result for each test query (with different background)
|
||||
for qinfo in test_queries:
|
||||
r = test_by_query.get(qinfo["query"], {})
|
||||
did_pass = r.get("pass", False)
|
||||
triggers = r.get("triggers", 0)
|
||||
runs = r.get("runs", 0)
|
||||
|
||||
icon = "✓" if did_pass else "✗"
|
||||
css_class = "pass" if did_pass else "fail"
|
||||
|
||||
html_parts.append(f' <td class="result test-result {css_class}">{icon}<span class="rate">{triggers}/{runs}</span></td>\n')
|
||||
|
||||
html_parts.append(" </tr>\n")
|
||||
|
||||
html_parts.append(""" </tbody>
|
||||
</table>
|
||||
</div>
|
||||
""")
|
||||
|
||||
html_parts.append("""
|
||||
</body>
|
||||
</html>
|
||||
""")
|
||||
|
||||
return "".join(html_parts)
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="Generate HTML report from run_loop output")
|
||||
parser.add_argument("input", help="Path to JSON output from run_loop.py (or - for stdin)")
|
||||
parser.add_argument("-o", "--output", default=None, help="Output HTML file (default: stdout)")
|
||||
parser.add_argument("--skill-name", default="", help="Skill name to include in the report title")
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.input == "-":
|
||||
data = json.load(sys.stdin)
|
||||
else:
|
||||
data = json.loads(Path(args.input).read_text())
|
||||
|
||||
html_output = generate_html(data, skill_name=args.skill_name)
|
||||
|
||||
if args.output:
|
||||
Path(args.output).write_text(html_output)
|
||||
print(f"Report written to {args.output}", file=sys.stderr)
|
||||
else:
|
||||
print(html_output)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,246 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Improve a skill description based on eval results.
|
||||
|
||||
Takes eval results (from run_eval.py) and generates an improved description
|
||||
by calling `claude -p` as a subprocess (same auth pattern as run_eval.py).
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
from scripts.utils import parse_skill_md
|
||||
|
||||
|
||||
def _call_claude(prompt: str, model: str | None, timeout: int = 300) -> str:
|
||||
"""Run `claude -p` with the prompt on stdin and return the text response.
|
||||
|
||||
Prompt goes over stdin (not argv) because it embeds the full SKILL.md
|
||||
body and can easily exceed comfortable argv length.
|
||||
"""
|
||||
cmd = ["claude", "-p", "--output-format", "text"]
|
||||
if model:
|
||||
cmd.extend(["--model", model])
|
||||
|
||||
# Remove CLAUDECODE env var to allow nesting claude -p inside an
|
||||
# interactive session. The guard is for interactive terminal conflicts;
|
||||
# programmatic subprocess usage is safe. Same pattern as run_eval.py.
|
||||
env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
|
||||
|
||||
result = subprocess.run(
|
||||
cmd,
|
||||
input=prompt,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
env=env,
|
||||
timeout=timeout,
|
||||
)
|
||||
if result.returncode != 0:
|
||||
raise RuntimeError(
|
||||
f"claude -p exited {result.returncode}\nstderr: {result.stderr}"
|
||||
)
|
||||
return result.stdout
|
||||
|
||||
|
||||
def improve_description(
|
||||
skill_name: str,
|
||||
skill_content: str,
|
||||
current_description: str,
|
||||
eval_results: dict,
|
||||
history: list[dict],
|
||||
model: str,
|
||||
test_results: dict | None = None,
|
||||
log_dir: Path | None = None,
|
||||
iteration: int | None = None,
|
||||
) -> str:
|
||||
"""Call the agent to improve the description based on eval results."""
|
||||
failed_triggers = [
|
||||
r for r in eval_results["results"]
|
||||
if r["should_trigger"] and not r["pass"]
|
||||
]
|
||||
false_triggers = [
|
||||
r for r in eval_results["results"]
|
||||
if not r["should_trigger"] and not r["pass"]
|
||||
]
|
||||
|
||||
# Build scores summary
|
||||
train_score = f"{eval_results['summary']['passed']}/{eval_results['summary']['total']}"
|
||||
if test_results:
|
||||
test_score = f"{test_results['summary']['passed']}/{test_results['summary']['total']}"
|
||||
scores_summary = f"Train: {train_score}, Test: {test_score}"
|
||||
else:
|
||||
scores_summary = f"Train: {train_score}"
|
||||
|
||||
prompt = f"""You are optimizing a skill description for a skill called "{skill_name}". A "skill" is sort of like a prompt, but with progressive disclosure -- there's a title and description that the agent sees when deciding whether to use the skill, and then if it does use the skill, it reads the .md file which has lots more details and potentially links to other resources in the skill folder like helper files and scripts and additional documentation or examples.
|
||||
|
||||
The description appears in the agent's "available_skills" list. When a user sends a query, the agent decides whether to invoke the skill based solely on the title and on this description. Your goal is to write a description that triggers for relevant queries, and doesn't trigger for irrelevant ones.
|
||||
|
||||
Here's the current description:
|
||||
<current_description>
|
||||
"{current_description}"
|
||||
</current_description>
|
||||
|
||||
Current scores ({scores_summary}):
|
||||
<scores_summary>
|
||||
"""
|
||||
if failed_triggers:
|
||||
prompt += "FAILED TO TRIGGER (should have triggered but didn't):\n"
|
||||
for r in failed_triggers:
|
||||
prompt += f' - "{r["query"]}" (triggered {r["triggers"]}/{r["runs"]} times)\n'
|
||||
prompt += "\n"
|
||||
|
||||
if false_triggers:
|
||||
prompt += "FALSE TRIGGERS (triggered but shouldn't have):\n"
|
||||
for r in false_triggers:
|
||||
prompt += f' - "{r["query"]}" (triggered {r["triggers"]}/{r["runs"]} times)\n'
|
||||
prompt += "\n"
|
||||
|
||||
if history:
|
||||
prompt += "PREVIOUS ATTEMPTS (do NOT repeat these — try something structurally different):\n\n"
|
||||
for h in history:
|
||||
train_s = f"{h.get('train_passed', h.get('passed', 0))}/{h.get('train_total', h.get('total', 0))}"
|
||||
test_s = f"{h.get('test_passed', '?')}/{h.get('test_total', '?')}" if h.get('test_passed') is not None else None
|
||||
score_str = f"train={train_s}" + (f", test={test_s}" if test_s else "")
|
||||
prompt += f'<attempt {score_str}>\n'
|
||||
prompt += f'Description: "{h["description"]}"\n'
|
||||
if "results" in h:
|
||||
prompt += "Train results:\n"
|
||||
for r in h["results"]:
|
||||
status = "PASS" if r["pass"] else "FAIL"
|
||||
prompt += f' [{status}] "{r["query"][:80]}" (triggered {r["triggers"]}/{r["runs"]})\n'
|
||||
if h.get("note"):
|
||||
prompt += f'Note: {h["note"]}\n'
|
||||
prompt += "</attempt>\n\n"
|
||||
|
||||
prompt += f"""</scores_summary>
|
||||
|
||||
Skill content (for context on what the skill does):
|
||||
<skill_content>
|
||||
{skill_content}
|
||||
</skill_content>
|
||||
|
||||
Based on the failures, write a new and improved description that is more likely to trigger correctly. When I say "based on the failures", it's a bit of a tricky line to walk because we don't want to overfit to the specific cases you're seeing. So what I DON'T want you to do is produce an ever-expanding list of specific queries that this skill should or shouldn't trigger for. Instead, try to generalize from the failures to broader categories of user intent and situations where this skill would be useful or not useful. The reason for this is twofold:
|
||||
|
||||
1. Avoid overfitting
|
||||
2. The list might get loooong and it's injected into ALL queries and there might be a lot of skills, so we don't want to blow too much space on any given description.
|
||||
|
||||
Concretely, your description should not be more than about 100-200 words, even if that comes at the cost of accuracy. There is a hard limit of 1024 characters — descriptions over that will be truncated, so stay comfortably under it.
|
||||
|
||||
Here are some tips that we've found to work well in writing these descriptions:
|
||||
- The skill should be phrased in the imperative -- "Use this skill for" rather than "this skill does"
|
||||
- The skill description should focus on the user's intent, what they are trying to achieve, vs. the implementation details of how the skill works.
|
||||
- The description competes with other skills for the agent's attention — make it distinctive and immediately recognizable.
|
||||
- If you're getting lots of failures after repeated attempts, change things up. Try different sentence structures or wordings.
|
||||
|
||||
I'd encourage you to be creative and mix up the style in different iterations since you'll have multiple opportunities to try different approaches and we'll just grab the highest-scoring one at the end.
|
||||
|
||||
Please respond with only the new description text in <new_description> tags, nothing else."""
|
||||
|
||||
text = _call_claude(prompt, model)
|
||||
|
||||
match = re.search(r"<new_description>(.*?)</new_description>", text, re.DOTALL)
|
||||
description = match.group(1).strip().strip('"') if match else text.strip().strip('"')
|
||||
|
||||
transcript: dict = {
|
||||
"iteration": iteration,
|
||||
"prompt": prompt,
|
||||
"response": text,
|
||||
"parsed_description": description,
|
||||
"char_count": len(description),
|
||||
"over_limit": len(description) > 1024,
|
||||
}
|
||||
|
||||
# Safety net: the prompt already states the 1024-char hard limit, but if
|
||||
# the model blew past it anyway, make one fresh single-turn call that
|
||||
# quotes the too-long version and asks for a shorter rewrite. (The old
|
||||
# SDK path did this as a true multi-turn; `claude -p` is one-shot, so we
|
||||
# inline the prior output into the new prompt instead.)
|
||||
if len(description) > 1024:
|
||||
shorten_prompt = (
|
||||
f"{prompt}\n\n"
|
||||
f"---\n\n"
|
||||
f"A previous attempt produced this description, which at "
|
||||
f"{len(description)} characters is over the 1024-character hard limit:\n\n"
|
||||
f'"{description}"\n\n'
|
||||
f"Rewrite it to be under 1024 characters while keeping the most "
|
||||
f"important trigger words and intent coverage. Respond with only "
|
||||
f"the new description in <new_description> tags."
|
||||
)
|
||||
shorten_text = _call_claude(shorten_prompt, model)
|
||||
match = re.search(r"<new_description>(.*?)</new_description>", shorten_text, re.DOTALL)
|
||||
shortened = match.group(1).strip().strip('"') if match else shorten_text.strip().strip('"')
|
||||
|
||||
transcript["rewrite_prompt"] = shorten_prompt
|
||||
transcript["rewrite_response"] = shorten_text
|
||||
transcript["rewrite_description"] = shortened
|
||||
transcript["rewrite_char_count"] = len(shortened)
|
||||
description = shortened
|
||||
|
||||
transcript["final_description"] = description
|
||||
|
||||
if log_dir:
|
||||
log_dir.mkdir(parents=True, exist_ok=True)
|
||||
log_file = log_dir / f"improve_iter_{iteration or 'unknown'}.json"
|
||||
log_file.write_text(json.dumps(transcript, indent=2))
|
||||
|
||||
return description
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="Improve a skill description based on eval results")
|
||||
parser.add_argument("--eval-results", required=True, help="Path to eval results JSON (from run_eval.py)")
|
||||
parser.add_argument("--skill-path", required=True, help="Path to skill directory")
|
||||
parser.add_argument("--history", default=None, help="Path to history JSON (previous attempts)")
|
||||
parser.add_argument("--model", required=True, help="Model for improvement")
|
||||
parser.add_argument("--verbose", action="store_true", help="Print thinking to stderr")
|
||||
args = parser.parse_args()
|
||||
|
||||
skill_path = Path(args.skill_path)
|
||||
if not (skill_path / "SKILL.md").exists():
|
||||
print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
eval_results = json.loads(Path(args.eval_results).read_text())
|
||||
history = []
|
||||
if args.history:
|
||||
history = json.loads(Path(args.history).read_text())
|
||||
|
||||
name, _, content = parse_skill_md(skill_path)
|
||||
current_description = eval_results["description"]
|
||||
|
||||
if args.verbose:
|
||||
print(f"Current: {current_description}", file=sys.stderr)
|
||||
print(f"Score: {eval_results['summary']['passed']}/{eval_results['summary']['total']}", file=sys.stderr)
|
||||
|
||||
new_description = improve_description(
|
||||
skill_name=name,
|
||||
skill_content=content,
|
||||
current_description=current_description,
|
||||
eval_results=eval_results,
|
||||
history=history,
|
||||
model=args.model,
|
||||
)
|
||||
|
||||
if args.verbose:
|
||||
print(f"Improved: {new_description}", file=sys.stderr)
|
||||
|
||||
# Output as JSON with both the new description and updated history
|
||||
output = {
|
||||
"description": new_description,
|
||||
"history": history + [{
|
||||
"description": current_description,
|
||||
"passed": eval_results["summary"]["passed"],
|
||||
"failed": eval_results["summary"]["failed"],
|
||||
"total": eval_results["summary"]["total"],
|
||||
"results": eval_results["results"],
|
||||
}],
|
||||
}
|
||||
print(json.dumps(output, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,136 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Skill Packager - Creates a distributable .skill file of a skill folder
|
||||
|
||||
Usage:
|
||||
python utils/package_skill.py <path/to/skill-folder> [output-directory]
|
||||
|
||||
Example:
|
||||
python utils/package_skill.py skills/public/my-skill
|
||||
python utils/package_skill.py skills/public/my-skill ./dist
|
||||
"""
|
||||
|
||||
import fnmatch
|
||||
import sys
|
||||
import zipfile
|
||||
from pathlib import Path
|
||||
from scripts.quick_validate import validate_skill
|
||||
|
||||
# Patterns to exclude when packaging skills.
|
||||
EXCLUDE_DIRS = {"__pycache__", "node_modules"}
|
||||
EXCLUDE_GLOBS = {"*.pyc"}
|
||||
EXCLUDE_FILES = {".DS_Store"}
|
||||
# Directories excluded only at the skill root (not when nested deeper).
|
||||
ROOT_EXCLUDE_DIRS = {"evals"}
|
||||
|
||||
|
||||
def should_exclude(rel_path: Path) -> bool:
|
||||
"""Check if a path should be excluded from packaging."""
|
||||
parts = rel_path.parts
|
||||
if any(part in EXCLUDE_DIRS for part in parts):
|
||||
return True
|
||||
# rel_path is relative to skill_path.parent, so parts[0] is the skill
|
||||
# folder name and parts[1] (if present) is the first subdir.
|
||||
if len(parts) > 1 and parts[1] in ROOT_EXCLUDE_DIRS:
|
||||
return True
|
||||
name = rel_path.name
|
||||
if name in EXCLUDE_FILES:
|
||||
return True
|
||||
return any(fnmatch.fnmatch(name, pat) for pat in EXCLUDE_GLOBS)
|
||||
|
||||
|
||||
def package_skill(skill_path, output_dir=None):
|
||||
"""
|
||||
Package a skill folder into a .skill file.
|
||||
|
||||
Args:
|
||||
skill_path: Path to the skill folder
|
||||
output_dir: Optional output directory for the .skill file (defaults to current directory)
|
||||
|
||||
Returns:
|
||||
Path to the created .skill file, or None if error
|
||||
"""
|
||||
skill_path = Path(skill_path).resolve()
|
||||
|
||||
# Validate skill folder exists
|
||||
if not skill_path.exists():
|
||||
print(f"❌ Error: Skill folder not found: {skill_path}")
|
||||
return None
|
||||
|
||||
if not skill_path.is_dir():
|
||||
print(f"❌ Error: Path is not a directory: {skill_path}")
|
||||
return None
|
||||
|
||||
# Validate SKILL.md exists
|
||||
skill_md = skill_path / "SKILL.md"
|
||||
if not skill_md.exists():
|
||||
print(f"❌ Error: SKILL.md not found in {skill_path}")
|
||||
return None
|
||||
|
||||
# Run validation before packaging
|
||||
print("🔍 Validating skill...")
|
||||
valid, message = validate_skill(skill_path)
|
||||
if not valid:
|
||||
print(f"❌ Validation failed: {message}")
|
||||
print(" Please fix the validation errors before packaging.")
|
||||
return None
|
||||
print(f"✅ {message}\n")
|
||||
|
||||
# Determine output location
|
||||
skill_name = skill_path.name
|
||||
if output_dir:
|
||||
output_path = Path(output_dir).resolve()
|
||||
output_path.mkdir(parents=True, exist_ok=True)
|
||||
else:
|
||||
output_path = Path.cwd()
|
||||
|
||||
skill_filename = output_path / f"{skill_name}.skill"
|
||||
|
||||
# Create the .skill file (zip format)
|
||||
try:
|
||||
with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
|
||||
# Walk through the skill directory, excluding build artifacts
|
||||
for file_path in skill_path.rglob('*'):
|
||||
if not file_path.is_file():
|
||||
continue
|
||||
arcname = file_path.relative_to(skill_path.parent)
|
||||
if should_exclude(arcname):
|
||||
print(f" Skipped: {arcname}")
|
||||
continue
|
||||
zipf.write(file_path, arcname)
|
||||
print(f" Added: {arcname}")
|
||||
|
||||
print(f"\n✅ Successfully packaged skill to: {skill_filename}")
|
||||
return skill_filename
|
||||
|
||||
except Exception as e:
|
||||
print(f"❌ Error creating .skill file: {e}")
|
||||
return None
|
||||
|
||||
|
||||
def main():
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
|
||||
print("\nExample:")
|
||||
print(" python utils/package_skill.py skills/public/my-skill")
|
||||
print(" python utils/package_skill.py skills/public/my-skill ./dist")
|
||||
sys.exit(1)
|
||||
|
||||
skill_path = sys.argv[1]
|
||||
output_dir = sys.argv[2] if len(sys.argv) > 2 else None
|
||||
|
||||
print(f"📦 Packaging skill: {skill_path}")
|
||||
if output_dir:
|
||||
print(f" Output directory: {output_dir}")
|
||||
print()
|
||||
|
||||
result = package_skill(skill_path, output_dir)
|
||||
|
||||
if result:
|
||||
sys.exit(0)
|
||||
else:
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,103 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Quick validation script for skills - minimal version
|
||||
"""
|
||||
|
||||
import sys
|
||||
import os
|
||||
import re
|
||||
import yaml
|
||||
from pathlib import Path
|
||||
|
||||
def validate_skill(skill_path):
|
||||
"""Basic validation of a skill"""
|
||||
skill_path = Path(skill_path)
|
||||
|
||||
# Check SKILL.md exists
|
||||
skill_md = skill_path / 'SKILL.md'
|
||||
if not skill_md.exists():
|
||||
return False, "SKILL.md not found"
|
||||
|
||||
# Read and validate frontmatter
|
||||
content = skill_md.read_text()
|
||||
if not content.startswith('---'):
|
||||
return False, "No YAML frontmatter found"
|
||||
|
||||
# Extract frontmatter
|
||||
match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
|
||||
if not match:
|
||||
return False, "Invalid frontmatter format"
|
||||
|
||||
frontmatter_text = match.group(1)
|
||||
|
||||
# Parse YAML frontmatter
|
||||
try:
|
||||
frontmatter = yaml.safe_load(frontmatter_text)
|
||||
if not isinstance(frontmatter, dict):
|
||||
return False, "Frontmatter must be a YAML dictionary"
|
||||
except yaml.YAMLError as e:
|
||||
return False, f"Invalid YAML in frontmatter: {e}"
|
||||
|
||||
# Define allowed properties
|
||||
ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'}
|
||||
|
||||
# Check for unexpected properties (excluding nested keys under metadata)
|
||||
unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
|
||||
if unexpected_keys:
|
||||
return False, (
|
||||
f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
|
||||
f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
|
||||
)
|
||||
|
||||
# Check required fields
|
||||
if 'name' not in frontmatter:
|
||||
return False, "Missing 'name' in frontmatter"
|
||||
if 'description' not in frontmatter:
|
||||
return False, "Missing 'description' in frontmatter"
|
||||
|
||||
# Extract name for validation
|
||||
name = frontmatter.get('name', '')
|
||||
if not isinstance(name, str):
|
||||
return False, f"Name must be a string, got {type(name).__name__}"
|
||||
name = name.strip()
|
||||
if name:
|
||||
# Check naming convention (kebab-case: lowercase with hyphens)
|
||||
if not re.match(r'^[a-z0-9-]+$', name):
|
||||
return False, f"Name '{name}' should be kebab-case (lowercase letters, digits, and hyphens only)"
|
||||
if name.startswith('-') or name.endswith('-') or '--' in name:
|
||||
return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
|
||||
# Check name length (max 64 characters per spec)
|
||||
if len(name) > 64:
|
||||
return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."
|
||||
|
||||
# Extract and validate description
|
||||
description = frontmatter.get('description', '')
|
||||
if not isinstance(description, str):
|
||||
return False, f"Description must be a string, got {type(description).__name__}"
|
||||
description = description.strip()
|
||||
if description:
|
||||
# Check for angle brackets
|
||||
if '<' in description or '>' in description:
|
||||
return False, "Description cannot contain angle brackets (< or >)"
|
||||
# Check description length (max 1024 characters per spec)
|
||||
if len(description) > 1024:
|
||||
return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."
|
||||
|
||||
# Validate compatibility field if present (optional)
|
||||
compatibility = frontmatter.get('compatibility', '')
|
||||
if compatibility:
|
||||
if not isinstance(compatibility, str):
|
||||
return False, f"Compatibility must be a string, got {type(compatibility).__name__}"
|
||||
if len(compatibility) > 500:
|
||||
return False, f"Compatibility is too long ({len(compatibility)} characters). Maximum is 500 characters."
|
||||
|
||||
return True, "Skill is valid!"
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) != 2:
|
||||
print("Usage: python quick_validate.py <skill_directory>")
|
||||
sys.exit(1)
|
||||
|
||||
valid, message = validate_skill(sys.argv[1])
|
||||
print(message)
|
||||
sys.exit(0 if valid else 1)
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user