Plugin Creator

Quick Start

1. Run the scaffold script:

  # Plugin names are normalized to lower-case hyphen-case and must be <= 64 chars.
  # The generated folder and plugin.json name are always the same.
# Run from repo root (or replace .agents/... with the absolute path to this SKILL).
# By default creates in ~/plugins/<plugin-name>.
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-name>

2. Open <plugin-path>/.codex-plugin/plugin.json and replace [TODO: ...] placeholders.

3. Generate or update the personal marketplace entry when the plugin should appear in Codex UI ordering:

# Personal marketplace entries default to ~/.agents/plugins/marketplace.json.
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --with-marketplace

If the current Git repo already has .agents/plugins/marketplace.json and the user has not said whether the plugin is personal or shared with their team, ask before generating a marketplace entry. When they choose the repo marketplace, use:

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
  --path ./plugins \
  --marketplace-path ./.agents/plugins/marketplace.json \
  --with-marketplace

4. Generate/adjust optional companion folders as needed:

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
  --path <parent-plugin-directory> \
  --marketplace-path <marketplace-json-path> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

<parent-plugin-directory> is the directory where the plugin folder <plugin-name> will be created (for example ~/code/plugins).

What this skill creates

• Default marketplace-backed scaffolds are personal: ~/plugins/<plugin-name>/ plus ~/.agents/plugins/marketplace.json.
• If the current Git repo already has .agents/plugins/marketplace.json and the user has not said personal vs team, ask which marketplace to update before generating a marketplace entry.
• Creates plugin root at /<parent-plugin-directory>/<plugin-name>/.
• Always creates /<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json.
• Fills the manifest with the full schema shape, placeholder values, and the complete interface section.
• Creates or updates the selected marketplace when --with-marketplace is set.
  • If the marketplace file does not exist yet, seed top-level name plus interface.displayName placeholders before adding the first plugin entry.
• <plugin-name> is normalized using skill-creator naming rules:
  • My Plugin → my-plugin
  • My--Plugin → my-plugin
  • underscores, spaces, and punctuation are converted to -
  • result is lower-case hyphen-delimited with consecutive hyphens collapsed
• Supports optional creation of:
  • skills/
  • hooks/
  • scripts/
  • assets/
  • .mcp.json
  • .app.json

Marketplace workflow

• Personal plugins use ~/.agents/plugins/marketplace.json.
• Repo/team plugins use <repo-root>/.agents/plugins/marketplace.json.
• Marketplace root metadata supports top-level name plus optional interface.displayName.
• Treat plugin order in plugins[] as render order in Codex. Append new entries unless a user explicitly asks to reorder the list.
• displayName belongs inside the marketplace interface object, not individual plugins[] entries.
• Each generated marketplace entry must include all of:
  • policy.installation
  • policy.authentication
  • category
• Default new entries to:
  • policy.installation: "AVAILABLE"
  • policy.authentication: "ON_INSTALL"
• Override defaults only when the user explicitly specifies another allowed value.
• Allowed policy.installation values:
  • NOT_AVAILABLE
  • AVAILABLE
  • INSTALLED_BY_DEFAULT
• Allowed policy.authentication values:
  • ON_INSTALL
  • ON_USE
• Treat policy.products as an override. Omit it unless the user explicitly requests product gating.
• The generated plugin entry shape is:

{
  "name": "plugin-name",
  "source": {
    "source": "local",
    "path": "./plugins/plugin-name"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

• Use --force only when intentionally replacing an existing marketplace entry for the same plugin name.

• If the selected marketplace file does not exist yet, create it with top-level "name", an "interface" object containing "displayName", and a plugins array, then add the new entry.

• For a brand-new marketplace file, the root object should look like:

{
  "name": "[TODO: marketplace-name]",
  "interface": {
    "displayName": "[TODO: Marketplace Display Name]"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": {
        "source": "local",
        "path": "./plugins/plugin-name"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Required behavior

• Outer folder name and plugin.json "name" are always the same normalized plugin name.
• Do not remove required structure; keep .codex-plugin/plugin.json present.
• Keep manifest values as placeholders until a human or follow-up step explicitly fills them.
• If creating files inside an existing plugin path, use --force only when overwrite is intentional.
• Preserve any existing marketplace interface.displayName.
• When generating marketplace entries, always write policy.installation, policy.authentication, and category even if their values are defaults.
• Add policy.products only when the user explicitly asks for that override.
• Keep marketplace source.path relative to the selected marketplace root as ./plugins/<plugin-name>.
• When the workflow created or updated a marketplace-backed plugin, end the final user-facing response with a short Codex app handoff. Say To view this in the Codex app: and write View <normalized plugin name> and Share <normalized plugin name> as Markdown links, not raw URLs or code spans.
• The View deeplink uses codex://plugins/<normalized plugin name>?marketplacePath=<absolute marketplace.json path>. The Share deeplink uses the same URL with &mode=share.
• Replace the placeholders with the real normalized plugin name and absolute marketplace.json path from the scaffolded plugin. URL-encode the path segment and query value when needed.
• Do not add pluginName or hostId query parameters to these deeplinks. Codex derives both after the user clicks the link.
• Do not emit the View <normalized plugin name> or Share <normalized plugin name> links when no marketplace entry was created or updated.

Reference to exact spec sample

For the exact canonical sample JSON for both plugin manifests and marketplace entries, use:

• references/plugin-json-spec.md

Validation

After editing SKILL.md, run:

python3 <path-to-skill-creator>/scripts/quick_validate.py .agents/skills/plugin-creator

airtable-mcp

Self-discovery

Tools are fetched from the MCP server at runtime, so the CLI never has a hardcoded command list. Discover what's available:

airtable-mcp tools            # human-readable list
airtable-mcp tools --json     # machine-parseable list
airtable-mcp <tool> --help    # show flags and descriptions for a tool

Run airtable-mcp tools before assuming a tool exists. Tool names, arguments, and output shapes can change between server releases without a CLI update.

Install

npm install -g @airtable/mcp-cli

Auth

The CLI needs an Airtable personal access token (PAT). Two paths:

Environment variable (preferred for scripts/agents):

export AIRTABLE_TOKEN=pat_xxx

Interactive configure (stores token in ~/.airtable/cli.json with 0600 permissions):

airtable-mcp configure

Create tokens at https://airtable.com/create/tokens. Ensure the token has the scopes required by the tools being called.

AIRTABLE_TOKEN takes precedence over saved profiles when no --profile flag is set. Never log or echo tokens.

Quick reference

Tool names use hyphens on the CLI (list-records) but underscores in MCP (list_records). The CLI translates automatically.

Workflow

1. Auth — set AIRTABLE_TOKEN or run airtable-mcp configure
2. Discover — run airtable-mcp tools to see available tools
3. Inspect — run airtable-mcp <tool> --help for flags and descriptions
4. Check access — in tools --json output, check the access field: read-only, write, or destructive. Confirm with the user before running destructive tools.
5. Execute — run airtable-mcp <tool> --flagName value

Output & automation

• Default output is formatted JSON to stdout. Status messages go to stderr.
• --json on tools gives a JSON array of {name, title, access}.
• -q / --quiet suppresses stderr status messages (cache warnings, etc).
• --output raw returns the raw server response text instead of parsed JSON.
• --input - reads tool arguments as a JSON object from stdin, bypassing flag parsing.
• Exit codes: 0 success, 1 error (auth, tool failure, not found), 2 usage error (bad flags, bad input).

Common tasks

Find a base and list its tables:

airtable-mcp search-bases --searchQuery "Project Tracker" -q
airtable-mcp list-tables-for-base --baseId appK9MtBqFw3o5jGN -q

List records with specific fields:

airtable-mcp list-records-for-table \
  --baseId appK9MtBqFw3o5jGN --tableId tblL4GpTfEz8byRsW \
  --fieldIds '["Name","Status"]' --pageSize 10 -q

Filter records — filters use structured JSON, not formula strings. Wrap conditions in an operands array; the top-level operator defaults to and if omitted:

airtable-mcp list-records-for-table \
  --baseId appK9MtBqFw3o5jGN --tableId tblL4GpTfEz8byRsW \
  --filters '{"operator":"and","operands":[{"operator":"=","operands":["Status","Done"]}]}' -q

For select fields, filter by choice ID (from get-table-schema), not the display name. The airtable-filters skill covers compound filters, date filters, and operator-by-field-type details.

Search records — use search-records for free-text/fuzzy queries on large tables. Use list-records-for-table with --filters when filtering by exact field values:

airtable-mcp search-records \
  --baseId appK9MtBqFw3o5jGN --table tblL4GpTfEz8byRsW \
  --query "acme" --fields '["Name","Notes"]' -q

Pass --fields ALL_SEARCHABLE_FIELDS to search across every indexed field. Date, rating, checkbox, and button fields are not searchable.

Update records — complex args are easier via --input -:

echo '{"baseId":"appK9MtBqFw3o5jGN","tableId":"tblL4GpTfEz8byRsW","records":[{"id":"recVnR3xPq8sD2yLk","fields":{"fld8WsrpLHHevsnW8":"Done"}}]}' \
  | airtable-mcp update-records-for-table --input - -q

Select field values are returned as objects ({"id":"sel...","name":"Done"}) but must be written as plain strings ("Done"). Record field keys in create/update currently require field IDs (fldXXX) — use get-table-schema to resolve names to IDs before writing. Note that fieldIds, sort, and filters accept both names and IDs.

Gotchas

Airtable MCP Filters

MCP tools that list or display records from tables or interface pages accept an optional filters parameter, using the same schema.

When querying records from an interface page, these filters are combined with the page's built-in filters using AND.

Schema shape

When no top-level operator is specified, conditions are combined with AND. The first element in a condition's operands array is always a field ID — look up the table's schema to find field IDs before filtering.

Field type categories

• Text-like: singleLineText, multilineText, email, url, phoneNumber, richText, barcode
• Numeric: number, percent, currency, rating, duration, autoNumber, count
• Date: date, dateTime, createdTime, lastModifiedTime
• Single select: singleSelect
• Multiple selects: multipleSelects
• Single collaborator: singleCollaborator
• Multiple collaborators: multipleCollaborators
• Linked records: multipleRecordLinks
• Attachment: multipleAttachments
• Checkbox: checkbox

Computed fields (formula, rollup, lookup) support whichever operators match their result type.

Comparison operators

When matching a field against multiple values, prefer dedicated operators (isAnyOf, isNoneOf, hasAnyOf, hasAllOf) over combining multiple = conditions with or/and, when those operators are available for the field type.

Field-type rules

Select fields

For select fields, operand values must be choice IDs (e.g., "selABCDEFGHIJKLM"), not display names. Look up the table's schema to find choice IDs before filtering.

Collaborator fields

When filtering by a collaborator group ID, use operatorOptions to match individual members of the group instead of the literal group ID. See the tool's operatorOptions parameter for details.

Example operand: {"operator": "hasAnyOf", "operands": ["fldCRi9oz2vRLcIWr", "ugpDUVUnftA7H9bG8"], "operatorOptions": {"matchGroupsByMembership": true}}

Attachment fields

Use fileType to filter attachments by type (e.g., "image", "text") rather than isNotEmpty when the user specifies a file type.

Date fields

Date comparisons (=, !=, <, >, <=, >=) use a date value object instead of a raw date string, and isWithin uses a date range object. The tool schema defines the available modes for each. Always include timeZone.

Composing conditions

A filter's top-level operands array can contain two or more conditions, which are combined with the top-level operator (AND by default). For simple multi-condition filters, this flat structure is sufficient.

When the logic requires mixing AND and OR, nest a filter object as one of the operands. Each nested filter has its own operator and operands.

OR inside AND — useful when one condition is fixed and another allows multiple alternatives:

"Scripted videos that are either in Writing or Pre-Production" → Bucket = Scripted AND (Status = Writing OR Status = Pre-Production)

AND inside OR — useful when you want records matching either a simple condition or a combination:

"Approved videos, or videos assigned to Bailey that are in Cut 2" → Status = Approved OR (Editor = Bailey AND Status = Cut 2 Ready)

When combining many conditions on different fields, prefer a flat AND rather than unnecessary nesting. Only nest when the logic genuinely requires mixed AND/OR at different levels.

Prefer composing all conditions into a single filters object rather than splitting them across multiple calls. A single call with a composed filter is more efficient and returns the correct result set directly.

Examples

Filter where a text field equals "orange" OR a number field is greater than 5:

{
    "operator": "or",
    "operands": [
        {"operator": "=", "operands": ["fld8WsrpLHHevsnW8", "orange"]},
        {"operator": ">", "operands": ["fldulcCPDVz87Bmnw", 5]}
    ]
}

Filter for records where a date field is within the past week:

{
    "operands": [
        {
            "operator": "isWithin",
            "operands": ["fldABC12345678x", {"mode": "pastWeek", "timeZone": "America/New_York"}]
        }
    ]
}

Airtable Overview

Airtable is a no-code platform where teams build custom applications and AI-powered workflows from structured data. Users organize their data into bases, define tables with typed fields, set up automations to act on changes, and create interfaces that give different audiences tailored views of the same data.

Data model

Bases

A base is an Airtable database. It is the top-level container for all related data. A base contains one or more tables.

Tables

A table is a collection of structured data within a base, similar to a sheet in a spreadsheet or a table in a relational database. Each table has a defined set of fields and contains records.

Fields

A field defines a named, typed property on every record in a table.

Records

A record is a single entry in a table. Each record has a unique ID and stores a cell value for each field defined on that table.

Views

A view is a saved configuration for how to display records in a table. Views can filter, sort, group, and hide fields without changing the underlying data. Multiple views can exist on the same table, each showing the data differently.

Automations

An automation is a workflow that runs in response to a defined trigger (e.g. a record entering a view) and executes one or more actions (e.g. sending an email or updating a record).

Interfaces

Interfaces are custom app-like pages built on top of base data. They provide tailored, user-friendly ways to view and interact with records without exposing the full base structure or all of its data. A base can have multiple interfaces, each designed for a specific workflow or audience.

Some users can only access a base through its interfaces and cannot read or modify the underlying tables directly.

Capture Tasks from Meeting Notes

Keywords

meeting notes, action items, create tasks, create tickets, extract tasks, parse notes, analyze notes, assigned work, assignees, from meeting, post-meeting, capture tasks, generate tasks, turn into tasks, convert to tasks, action item, to-do, task list, follow-up, assigned to, create Jira tasks, create Jira tickets, meeting action items, extract action items, find action items, analyze meeting

Overview

Automatically extract action items from meeting notes and create Jira tasks with proper assignees. This skill parses unstructured meeting notes (from Confluence or pasted text), identifies action items with assignees, looks up Jira account IDs, and creates tasks—eliminating the tedious post-meeting ticket creation process.

Use this skill when: Users have meeting notes with action items that need to become Jira tasks.

Workflow

Follow this 7-step process to turn meeting notes into actionable Jira tasks:

Step 1: Get Meeting Notes

Obtain the meeting notes from the user.

Option A: Confluence Page URL

If user provides a Confluence URL:

getConfluencePage(
  cloudId="...",
  pageId="[extracted from URL]",
  contentFormat="markdown"
)

URL patterns:

• https://[site].atlassian.net/wiki/spaces/[SPACE]/pages/[PAGE_ID]/[title]
• Extract PAGE_ID from the numeric portion
• Get cloudId from site name or use getAccessibleAtlassianResources

Option B: Pasted Text

If user pastes meeting notes directly:

• Use the text as-is
• No fetching needed

If Unclear

Ask: "Do you have a Confluence link to the meeting notes, or would you like to paste them directly?"

Step 2: Parse Action Items

Scan the notes for action items with assignees.

Common Patterns

Pattern 1: @mention format (highest priority)

@Sarah to create user stories for chat feature
@Mike will update architecture doc

Pattern 2: Name + action verb

Sarah to create user stories
Mike will update architecture doc
Lisa should review the mockups

Pattern 3: Action: Name - Task

Action: Sarah - create user stories
Action Item: Mike - update architecture

Pattern 4: TODO with assignee

TODO: Create user stories (Sarah)
TODO: Update docs - Mike

Pattern 5: Bullet with name

- Sarah: create user stories
- Mike - update architecture

Extraction Logic

For each action item, extract:

1. Assignee Name

   • Text after @ symbol
   • Name before "to", "will", "should"
   • Name after "Action:" or in parentheses
   • First/last name or full name

2. Task Description

   • Text after "to", "will", "should", "-", ":"
   • Remove markers (@, Action:, TODO:)
   • Keep original wording
   • Include enough context

3. Context (optional but helpful)

   • Meeting title/date if available
   • Surrounding discussion context
   • Related decisions

Example Parsing

Input:

# Product Planning - Dec 3

Action Items:
- @Sarah to create user stories for chat feature
- Mike will update the architecture doc
- Lisa: review and approve design mockups

Parsed:

1. Assignee: Sarah
   Task: Create user stories for chat feature
   Context: Product Planning meeting - Dec 3

2. Assignee: Mike
   Task: Update the architecture doc
   Context: Product Planning meeting - Dec 3

3. Assignee: Lisa
   Task: Review and approve design mockups
   Context: Product Planning meeting - Dec 3

Step 3: Ask for Project Key

Before looking up users or creating tasks, identify the Jira project.

Ask: "Which Jira project should I create these tasks in? (e.g., PROJ, PRODUCT, ENG)"

If User is Unsure

Call getVisibleJiraProjects to show options:

getVisibleJiraProjects(
  cloudId="...",
  action="create"
)

Present: "I found these projects you can create tasks in: PROJ (Project Alpha), PRODUCT (Product Team), ENG (Engineering)"

Step 4: Lookup Account IDs

For each assignee name, find their Jira account ID.

Lookup Process

lookupJiraAccountId(
  cloudId="...",
  searchString="[assignee name]"
)

The search string can be:

• Full name: "Sarah Johnson"
• First name: "Sarah"
• Last name: "Johnson"
• Email: "sarah@company.com"

Handle Results

Scenario A: Exact Match (1 result)

✅ Found: Sarah Johnson (sarah.johnson@company.com)
→ Use accountId from result

Scenario B: No Match (0 results)

⚠️ Couldn't find user "Sarah" in Jira.

Options:
1. Create task unassigned (assign manually later)
2. Skip this task
3. Try different name format (e.g., "Sarah Johnson")

Which would you prefer?

Scenario C: Multiple Matches (2+ results)

⚠️ Found multiple users named "Sarah":
1. Sarah Johnson (sarah.johnson@company.com)
2. Sarah Smith (sarah.smith@company.com)

Which user should be assigned the task "Create user stories"?

Best Practices

• Try full name first ("Sarah Johnson")
• If no match, try first name only ("Sarah")
• If still no match, ask user
• Cache results (don't lookup same person twice)

Step 5: Present Action Items

CRITICAL: Always show the parsed action items to the user BEFORE creating any tasks.

Presentation Format

I found [N] action items from the meeting notes. Should I create these Jira tasks in [PROJECT]?

1. [TASK] [Task description]
   Assigned to: [Name] ([email if found])
   Context: [Meeting title/date]

2. [TASK] [Task description]
   Assigned to: [Name] ([email if found])
   Context: [Meeting title/date]

[...continue for all tasks...]

Would you like me to:
1. Create all tasks
2. Skip some tasks (which ones?)
3. Modify any descriptions or assignees

Wait for Confirmation

Do NOT create tasks until user confirms. Options:

• "Yes, create all" → proceed
• "Skip task 3" → create all except #3
• "Change assignee for task 2" → ask for new assignee
• "Edit description" → ask for changes

Step 6: Create Tasks

Once confirmed, create each Jira task.

Determine Issue Type

Before creating tasks, check what issue types are available in the project:

getJiraProjectIssueTypesMetadata(
  cloudId="...",
  projectIdOrKey="PROJ"
)

Choose the appropriate issue type:

• Use "Task" if available (most common)
• Use "Story" for user-facing features
• Use "Bug" if it's a defect
• If "Task" doesn't exist, use the first available issue type or ask the user

For Each Action Item

createJiraIssue(
  cloudId="...",
  projectKey="PROJ",
  issueTypeName="[Task or available type]",
  summary="[Task description]",
  description="[Full description with context]",
  assignee_account_id="[looked up account ID]"
)

Task Summary Format

Use action verbs and be specific:

• ✅ "Create user stories for chat feature"
• ✅ "Update architecture documentation"
• ✅ "Review and approve design mockups"
• ❌ "Do the thing" (too vague)

Task Description Format

**Action Item from Meeting Notes**

**Task:** [Original action item text]

**Context:**
[Meeting title/date]
[Relevant discussion points or decisions]

**Source:** [Link to Confluence meeting notes if available]

**Original Note:**
> [Exact quote from meeting notes]

Example:

**Action Item from Meeting Notes**

**Task:** Create user stories for chat feature

**Context:**
Product Planning Meeting - December 3, 2025
Discussed Q1 roadmap priorities and new feature requirements

**Source:** https://yoursite.atlassian.net/wiki/spaces/TEAM/pages/12345

**Original Note:**
> @Sarah to create user stories for chat feature

Step 7: Provide Summary

After all tasks are created, present a comprehensive summary.

Format:

✅ Created [N] tasks in [PROJECT]:

1. [PROJ-123] - [Task summary]
   Assigned to: [Name]
   https://yoursite.atlassian.net/browse/PROJ-123

2. [PROJ-124] - [Task summary]
   Assigned to: [Name]
   https://yoursite.atlassian.net/browse/PROJ-124

[...continue for all created tasks...]

**Source:** [Link to meeting notes]

**Next Steps:**
- Review tasks in Jira for accuracy
- Add any additional details or attachments
- Adjust priorities if needed
- Link related tickets if applicable

Action Item Pattern Examples

Pattern 1: @Mentions (Most Explicit)

@john to update documentation
@sarah will create the report
@mike should review PR #123

Parsed:

• Assignee: john/sarah/mike
• Task: update documentation / create the report / review PR #123

Pattern 2: Name + Action Verb

John to update documentation
Sarah will create the report
Mike should review PR #123
Lisa needs to test the feature

Parsed:

• Assignee: name before action verb
• Task: text after "to/will/should/needs to"

Pattern 3: Structured Action Format

Action: John - update documentation
Action Item: Sarah - create the report
AI: Mike - review PR #123

Parsed:

• Assignee: name after "Action:" and before "-"
• Task: text after "-"

Pattern 4: TODO Format

TODO: Update documentation (John)
TODO: Create report - Sarah
[ ] Mike: review PR #123

Parsed:

• Assignee: name in parentheses or after ":"
• Task: text between TODO and assignee

Pattern 5: Bullet Lists

- John: update documentation
- Sarah - create the report
* Mike will review PR #123

Parsed:

• Assignee: name before ":" or "-" or action verb
• Task: remaining text

Handling Edge Cases

No Action Items Found

If no action items with assignees are detected:

I analyzed the meeting notes but couldn't find any action items with clear assignees.

Action items typically follow patterns like:
- @Name to do X
- Name will do X
- Action: Name - do X
- TODO: X (Name)

Options:
1. I can search for TODO items without assignees
2. You can point out specific action items to create
3. I can create tasks for bullet points you specify

What would you like to do?

Mixed Formats

If some action items have assignees and some don't:

I found [N] action items:
- [X] with clear assignees
- [Y] without assignees

Should I:
1. Create all [N] tasks ([X] assigned, [Y] unassigned)
2. Only create the [X] tasks with assignees
3. Ask you to assign the [Y] unassigned tasks

Which option would you prefer?

Assignee Name Variations

If the same person is mentioned different ways:

Notes mention: @sarah, Sarah, Sarah J.

These likely refer to the same person. I'll look up "Sarah" once and use 
that account ID for all three mentions. Is that correct?

Duplicate Action Items

If the same task appears multiple times:

I found what appears to be the same action item twice:
1. "@Sarah to create user stories" (line 15)
2. "Action: Sarah - create user stories" (line 42)

Should I:
1. Create one task (combine duplicates)
2. Create two separate tasks
3. Skip the duplicate

What would you prefer?

Long Task Descriptions

If action item text is very long (>200 characters):

The task "[long text...]" is quite detailed.

Should I:
1. Use first sentence as summary, rest in description
2. Use full text as summary
3. Let you edit it to be more concise

Which would you prefer?

Tips for High-Quality Results

Do:

✅ Use consistent @mention format in notes
✅ Include full names when possible
✅ Be specific in action item descriptions
✅ Add context (why/what/when)
✅ Review parsed tasks before confirming

Don't:

❌ Mix multiple tasks for one person in one bullet
❌ Use ambiguous names (just "John" if you have 5 Johns)
❌ Skip action verbs (unclear what to do)
❌ Forget to specify project

Best Meeting Notes Format

# Meeting Title - Date

Attendees: [Names]

## Decisions
[What was decided]

## Action Items
- @FullName to [specific task with context]
- @AnotherPerson will [specific task with context]
- etc.

When NOT to Use This Skill

This skill is for converting meeting action items to Jira tasks only.

Don't use for: ❌ Summarizing meetings (no task creation)
❌ Finding meeting notes (use search skill)
❌ Creating calendar events
❌ Sending meeting notes via email
❌ General note-taking

Use only when: Meeting notes exist and action items need to become Jira tasks.

Examples

Example 1: Simple @Mentions

Input:

Team Sync - Dec 3, 2025

Action Items:
- @Sarah to create user stories for chat feature
- @Mike will update the architecture doc
- @Lisa should review design mockups

Process:

1. Parse → 3 action items found
2. Project → "PROJ"
3. Lookup → Sarah (123), Mike (456), Lisa (789)
4. Present → User confirms
5. Create → PROJ-100, PROJ-101, PROJ-102

Output:

✅ Created 3 tasks in PROJ:

1. PROJ-100 - Create user stories for chat feature
   Assigned to: Sarah Johnson
   
2. PROJ-101 - Update the architecture doc
   Assigned to: Mike Chen
   
3. PROJ-102 - Review design mockups
   Assigned to: Lisa Park

Example 2: Mixed Formats

Input:

Product Review Meeting

Discussed new features and priorities.

Follow-ups:
- Sarah will draft the PRD
- Mike: implement API changes
- TODO: Review security audit (Lisa)
- Update stakeholders on timeline

Process:

1. Parse → Found 4 items (3 with assignees, 1 without)
2. Ask → "Found 3 with assignees, 1 without. Create all or only assigned?"
3. User → "All, make the last one unassigned"
4. Create → 4 tasks (3 assigned, 1 unassigned)

Example 3: Name Lookup Issue

Input:

Sprint Planning

Action Items:
- @John to update tests
- @Sarah to refactor code

Process:

1. Parse → 2 action items
2. Lookup "John" → Found 3 Johns!
3. Ask → "Which John? (John Smith, John Doe, John Wilson)"
4. User → "John Smith"
5. Create → Both tasks assigned correctly

Quick Reference

Primary tool: getConfluencePage (if URL) or use pasted text
Account lookup: lookupJiraAccountId(searchString)
Task creation: createJiraIssue with assignee_account_id

Action patterns to look for:

• @Name to/will/should X
• Name to/will/should X
• Action: Name - X
• TODO: X (Name)
• Name: X

Always:

• Present parsed tasks before creating
• Handle name lookup failures gracefully
• Include context in task descriptions
• Provide summary with links

Remember:

• Human-in-loop is critical (show before creating)
• Name lookup can fail (have fallback)
• Be flexible with pattern matching
• Context preservation is important

Generate Status Report

Keywords

status report, project status, weekly update, daily standup, Jira report, project summary, blockers, progress update, Confluence report, sprint report, project update, publish to Confluence, write to Confluence, post report

Automatically query Jira for project status, analyze issues, and generate formatted status reports published to Confluence.

CRITICAL: This skill should be interactive. Always clarify scope (time period, audience, Confluence destination) with the user before or after generating the report. Do not silently skip Confluence publishing—always offer it.

Workflow

Generating a status report follows these steps:

1. Identify scope - Determine project, time period, and target audience
2. Query Jira - Fetch relevant issues using JQL queries
3. Analyze data - Categorize issues and identify key insights
4. Format report - Structure content based on audience and purpose
5. Publish to Confluence - Create or update a page with the report

Step 1: Identify Scope

IMPORTANT: If the user's request is missing key information, ASK before proceeding with queries. Do not assume defaults without confirmation for Confluence publishing.

Clarify these details:

Project identification:

• Which Jira project key? (e.g., "PROJ", "ENG", "MKTG")
• If the user mentions a project by name but not key, search Jira to find the project key

Time period:

• If not specified, ask: "What time period should this report cover? (default: last 7 days)"
• Options: Weekly (7 days), Daily (24 hours), Sprint-based (2 weeks), Custom period

Target audience:

• If not specified, ask: "Who is this report for? (Executives/Delivery Managers, Team-level, or Daily standup)"
• Executives/Delivery Managers: High-level summary with key metrics and blockers
• Team-level: Detailed breakdown with issue-by-issue status
• Daily standup: Brief update on yesterday/today/blockers

Report destination:

• ALWAYS ASK if not specified: "Would you like me to publish this report to Confluence? If so, which space should I use?"
• If user says yes: Ask for space name or offer to list available spaces
• Determine: New page or update existing page?
• Ask about parent page if creating under a specific section

Step 2: Query Jira

Use the searchJiraIssuesUsingJql tool to fetch issues. Build JQL queries based on report needs.

Common Query Patterns

For comprehensive queries, use the scripts/jql_builder.py utility to programmatically build JQL strings. For quick queries, reference references/jql-patterns.md for examples.

All open issues in project:

project = "PROJECT_KEY" AND status != Done ORDER BY priority DESC, updated DESC

Issues updated in last week:

project = "PROJECT_KEY" AND updated >= -7d ORDER BY priority DESC

High priority and blocked issues:

project = "PROJECT_KEY" AND (priority IN (Highest, High) OR status = Blocked) AND status != Done ORDER BY priority DESC

Completed in reporting period:

project = "PROJECT_KEY" AND status = Done AND resolved >= -7d ORDER BY resolved DESC

Query Strategy

For most reports, execute multiple targeted queries rather than one large query:

1. Completed issues: Get recently resolved tickets
2. In-progress issues: Get active work items
3. Blocked issues: Get blockers requiring attention
4. High priority open: Get critical upcoming work

Use maxResults: 100 for initial queries. If pagination is needed, use nextPageToken from results.

Data to Extract

For each issue, capture:

• key (e.g., "PROJ-123")
• summary (issue title)
• status (current state)
• priority (importance level)
• assignee (who's working on it)
• created / updated / resolved dates
• description (if needed for context on blockers)

Step 3: Analyze Data

Process the retrieved issues to identify:

Metrics:

• Total issues by status (Done, In Progress, Blocked, etc.)
• Completion rate (if historical data available)
• Number of high priority items
• Unassigned issue count

Key insights:

• Major accomplishments (recently completed high-value items)
• Critical blockers (blocked high priority issues)
• At-risk items (overdue or stuck in progress)
• Resource bottlenecks (one assignee with many issues)

Categorization: Group issues logically:

• By status (Done, In Progress, Blocked)
• By priority (Highest → Low)
• By assignee or team
• By component or epic (if relevant)

Step 4: Format Report

Select the appropriate template based on audience. Templates are in references/report-templates.md.

For Executives and Delivery Managers

Use Executive Summary Format:

• Brief overall status (🟢 On Track / 🟡 At Risk / 🔴 Blocked)
• Key metrics (total, completed, in progress, blocked)
• Top 3 highlights (major accomplishments)
• Critical blockers with impact
• Upcoming priorities

Keep it concise - 1-2 pages maximum. Focus on what matters to decision-makers.

For Team-Level Reports

Use Detailed Technical Format:

• Completed issues listed with keys
• In-progress issues with assignee and priority
• Blocked issues with blocker description and action needed
• Risks and dependencies
• Next period priorities

Include more detail - Team needs issue-level visibility.

For Daily Updates

Use Daily Standup Format:

• What was completed yesterday
• What's planned for today
• Current blockers
• Brief notes

Keep it brief - This is a quick sync, not comprehensive analysis.

Step 5: Publish to Confluence

After generating the report, ALWAYS offer to publish to Confluence (unless user explicitly said not to).

If user hasn't specified Confluence details yet, ask:

• "Would you like me to publish this report to Confluence?"
• "Which Confluence space should I use?"
• "Should this be nested under a specific parent page?"

Use the createConfluencePage tool to publish the report.

Page creation:

createConfluencePage(
    cloudId="[obtained from getConfluenceSpaces or URL]",
    spaceId="[numerical space ID]",
    title="[Project Name] - Status Report - [Date]",
    body="[formatted report in Markdown]",
    contentFormat="markdown",
    parentId="[optional - parent page ID if nesting under another page]"
)

Title format examples:

• "Project Phoenix - Weekly Status - Dec 3, 2025"
• "Engineering Sprint 23 - Status Report"
• "Q4 Initiatives - Status Update - Week 49"

Body formatting: Write the report content in Markdown. The tool will convert it to Confluence format. Use:

• Headers (#, ##, ###) for structure
• Bullet points for lists
• Bold (**text**) for emphasis
• Tables for metrics if needed
• Links to Jira issues: [PROJ-123](https://yourinstance.atlassian.net/browse/PROJ-123)

Best practices:

• Include the report date prominently
• Link directly to relevant Jira issues
• Use consistent naming conventions for recurring reports
• Consider creating under a "Status Reports" parent page for organization

Finding the Right Space

If the user doesn't specify a Confluence space:

1. Use getConfluenceSpaces to list available spaces
2. Look for spaces related to the project (matching project name or key)
3. If unsure, ask the user which space to use
4. Default to creating in the most relevant team or project space

Updating Existing Reports

If updating an existing page instead of creating new:

1. Get the current page content:

getConfluencePage(
    cloudId="...",
    pageId="123456",
    contentFormat="markdown"
)

2. Update the page with new content:

updateConfluencePage(
    cloudId="...",
    pageId="123456",
    body="[updated report content]",
    contentFormat="markdown",
    versionMessage="Updated with latest status - Dec 8, 2025"
)

Complete Example Workflow

User request: "Generate a status report for Project Phoenix and publish it to Confluence"

Step 1 - Identify scope:

• Project: Phoenix (need to find project key)
• Time period: Last week (default)
• Audience: Not specified, assume executive level
• Destination: Confluence, need to find appropriate space

Step 2 - Query Jira:

# Find project key first
searchJiraIssuesUsingJql(
    cloudId="...",
    jql='project = "PHOENIX" OR project = "PHX"',
    maxResults=1
)

# Query completed issues
searchJiraIssuesUsingJql(
    cloudId="...",
    jql='project = "PHX" AND status = Done AND resolved >= -7d',
    maxResults=50
)

# Query blocked issues
searchJiraIssuesUsingJql(
    cloudId="...",
    jql='project = "PHX" AND status = Blocked',
    maxResults=50
)

# Query in-progress high priority
searchJiraIssuesUsingJql(
    cloudId="...",
    jql='project = "PHX" AND status IN ("In Progress", "In Review") AND priority IN (Highest, High)',
    maxResults=50
)

Step 3 - Analyze:

• 15 issues completed (metrics)
• 3 critical blockers (key insight)
• Major accomplishment: API integration completed (highlight)

Step 4 - Format: Use Executive Summary Format from templates. Create concise report with metrics, highlights, and blockers.

Step 5 - Publish:

# Find appropriate space
getConfluenceSpaces(cloudId="...")

# Create page
createConfluencePage(
    cloudId="...",
    spaceId="12345",
    title="Project Phoenix - Weekly Status - Dec 3, 2025",
    body="[formatted markdown report]",
    contentFormat="markdown"
)

Tips for Quality Reports

Be data-driven:

• Include specific numbers and metrics
• Reference issue keys directly
• Show trends when possible (e.g., "completed 15 vs 12 last week")

Highlight what matters:

• Lead with the most important information
• Flag blockers prominently
• Celebrate significant wins

Make it actionable:

• For blockers, state what action is needed and from whom
• For risks, provide mitigation options
• For priorities, be specific about next steps

Keep it consistent:

• Use the same format for recurring reports
• Maintain predictable structure
• Include comparable metrics week-over-week

Provide context:

• Link to Jira for details
• Explain the impact of blockers
• Connect work to business objectives when possible

Resources

scripts/jql_builder.py

Python utility for programmatically building JQL queries. Use this when you need to construct complex or dynamic queries. Import and use the helper functions rather than manually concatenating JQL strings.

references/jql-patterns.md

Quick reference of common JQL query patterns for status reports. Use this for standard queries or as a starting point for custom queries.

references/report-templates.md

Detailed templates for different report types and audiences. Reference this to select the appropriate format and structure for your report.

Base44 CLI

Create and manage Base44 apps (projects) using the Base44 CLI tool.

⚡ IMMEDIATE ACTION REQUIRED - Read This First

This skill activates on ANY mention of "base44" or when a base44/ folder exists. DO NOT read documentation files or search the web before acting.

Your first action MUST be:

1. Check if base44/config.jsonc exists in the current directory
2. If NO (new project scenario):
   • This skill (base44-cli) handles the request
   • Guide user through project initialization
   • Do NOT activate base44-sdk yet
3. If YES (existing project scenario):
   • Transfer to base44-sdk skill for implementation
   • This skill only handles CLI commands (login, deploy, entities push)

Critical: Local Installation Only

NEVER call base44 directly. The CLI is installed locally as a dev dependency and must be accessed via a package manager:

• npx base44 <command> (npm - recommended)
• yarn base44 <command> (yarn)
• pnpm base44 <command> (pnpm)

WRONG: base44 login RIGHT: npx base44 login

MANDATORY: Authentication Check at Session Start

CRITICAL: At the very start of every AI session when this skill is activated, you MUST:

1. Check authentication status by running:

   npx base44 whoami
   

2. If the user is logged in (command succeeds and shows an email):

   • Continue with the requested task

3. If the user is NOT logged in (command fails or shows an error):

   • STOP immediately
   • DO NOT proceed with any CLI operations
   • Ask the user to login manually by running:

     npx base44 login
     

   - Wait for the user to confirm they have logged in before continuing
   
   

This check is mandatory and must happen before executing any other Base44 CLI commands.

Overview

The Base44 CLI provides command-line tools for authentication, creating projects, managing entities, and deploying Base44 applications. It is framework-agnostic and works with popular frontend frameworks like Vite, Next.js, and Create React App, Svelte, Vue, and more.

When to Use This Skill vs base44-sdk

Use base44-cli when:

• Creating a NEW Base44 project from scratch
• Initializing a project in an empty directory
• Directory is missing base44/config.jsonc
• User mentions: "create a new project", "initialize project", "setup a project", "start a new Base44 app"
• Deploying, pushing entities, or authenticating via CLI
• Working with CLI commands (npx base44 ...)

Use base44-sdk when:

• Building features in an EXISTING Base44 project
• base44/config.jsonc already exists
• Writing JavaScript/TypeScript code using Base44 SDK
• Implementing functionality, components, or features
• User mentions: "implement", "build a feature", "add functionality", "write code"

Skill Dependencies:

• base44-cli is a prerequisite for base44-sdk in new projects
• If user wants to "create an app" and no Base44 project exists, use base44-cli first
• base44-sdk assumes a Base44 project is already initialized

State Check Logic: Before selecting a skill, check:

• IF (user mentions "create/build app" OR "make a project"):
  • IF (directory is empty OR no base44/config.jsonc exists): → Use base44-cli (project initialization needed)
  • ELSE: → Use base44-sdk (project exists, build features)

Project Structure

A Base44 project combines a standard frontend project with a base44/ configuration folder:

my-app/
├── base44/                      # Base44 configuration (created by CLI)
│   ├── config.jsonc             # Project settings, site config
│   ├── .types/                  # Auto-generated TypeScript types (created by `types generate`)
│   │   └── types.d.ts           # Module augmentation for @base44/sdk
│   ├── entities/                # Entity schema definitions
│   │   ├── task.jsonc
│   │   └── board.jsonc
│   ├── functions/               # Backend functions (optional); automations live in function.jsonc
│   │   └── my-function/
│   │       ├── function.jsonc
│   │       └── index.ts
│   ├── agents/                  # Agent configurations (optional)
│   │   └── support_agent.jsonc
│   └── connectors/              # OAuth connector configurations (optional)
│       └── googlecalendar.jsonc
├── src/                         # Frontend source code
│   ├── api/
│   │   └── base44Client.js      # Base44 SDK client
│   ├── pages/
│   ├── components/
│   └── main.jsx
├── index.html                   # SPA entry point
├── package.json
└── vite.config.js               # Or your framework's config

Key files:

• base44/config.jsonc - Project name, description, site build settings
• base44/entities/*.jsonc - Data model schemas (see Entity Schema section)
• base44/functions/*/function.jsonc - Function config and optional automations (CRON, simple triggers, entity hooks)
• base44/agents/*.jsonc - Agent configurations (optional)
• base44/.types/types.d.ts - Auto-generated TypeScript types for entities, functions, and agents (created by npx base44 types generate)
• base44/connectors/*.jsonc - OAuth connector configurations (optional)
• src/api/base44Client.js - Pre-configured SDK client for frontend use

config.jsonc example:

{
  "name": "My App",                    // Required: project name
  "description": "App description",    // Optional: project description
  "entitiesDir": "./entities",         // Optional: default "entities"
  "functionsDir": "./functions",       // Optional: default "functions"
  "agentsDir": "./agents",             // Optional: default "agents"
  "connectorsDir": "./connectors",     // Optional: default "connectors"
  "site": {                            // Optional: site deployment config
    "installCommand": "npm install",   // Optional: install dependencies
    "buildCommand": "npm run build",   // Optional: build command
    "serveCommand": "npm run dev",     // Optional: local dev server
    "outputDirectory": "./dist"        // Optional: build output directory
  }
}

Config properties:

Installation

Install the Base44 CLI as a dev dependency in your project:

npm install --save-dev base44

Important: Never assume or hardcode the base44 package version. Always install without a version specifier to get the latest version.

Then run commands using npx:

npx base44 <command>

Note: All commands in this documentation use npx base44. You can also use yarn base44, or pnpm base44 if preferred.

Available Commands

Authentication

Project Management

Deployment

Entity Management

Entity Schema (Quick Reference)

ALWAYS follow this exact structure when creating entity files:

File naming: base44/entities/{kebab-case-name}.jsonc (e.g., team-member.jsonc for TeamMember)

Schema template:

{
  "name": "EntityName",
  "type": "object",
  "properties": {
    "field_name": {
      "type": "string",
      "description": "Field description"
    }
  },
  "required": ["field_name"]
}

Field types: string, number, integer, boolean, array, object, binary String formats: date, date-time, time, email, uri, hostname, ipv4, ipv6, uuid, file, regex, richtext For enums: Add "enum": ["value1", "value2"] and optionally "default": "value1" Entity names: Must be alphanumeric only (pattern: /^[a-zA-Z0-9]+$/)

For complete documentation, see entities-create.md.

Function Management

Agent Management

Agents are conversational AI assistants that can interact with users, access your app's entities, and call backend functions. Use these commands to manage agent configurations.

Note: Agent commands perform full synchronization - pushing replaces all remote agents with local ones, and pulling replaces all local agents with remote ones.

Agent Schema (Quick Reference)

File naming: base44/agents/{agent_name}.jsonc (e.g., support_agent.jsonc)

Schema template:

{
  "name": "agent_name",
  "description": "Brief description of what this agent does",
  "instructions": "Detailed instructions for the agent's behavior",
  "tool_configs": [
    // Entity tool - gives agent access to entity operations
    { "entity_name": "tasks", "allowed_operations": ["read", "create", "update", "delete"] },
    // Backend function tool - gives agent access to a function
    { "function_name": "send_email", "description": "Send an email notification" }
  ],
  "whatsapp_greeting": "Hello! How can I help you today?"
}

Naming rules:

• Agent names must match pattern: /^[a-z0-9_]+$/ (lowercase alphanumeric with underscores, 1-100 chars)
• Valid: support_agent, order_bot
• Invalid: Support-Agent, OrderBot

Required fields: name, description, instructions Optional fields: tool_configs (defaults to []), whatsapp_greeting

Tool config types:

• Entity tools: entity_name + allowed_operations (array of: read, create, update, delete)
• Backend function tools: function_name + description

Connector Management

Connectors let your app connect to external services (Google Calendar, Slack, Stripe, etc.). Most connectors use OAuth to provide access tokens for backend functions to call external APIs. Stripe is the exception — it is provisioned automatically on the server side with no OAuth browser flow.

Note: Connector commands perform full synchronization - pushing replaces all remote connectors with local ones (and triggers OAuth for new OAuth connectors), and pulling replaces all local connectors with remote ones.

Connector Schema (Quick Reference)

File naming: base44/connectors/{type}.jsonc (e.g., googlecalendar.jsonc, slack.jsonc)

Schema template:

{
  "type": "googlecalendar",
  "scopes": [
    "https://www.googleapis.com/auth/calendar.readonly",
    "https://www.googleapis.com/auth/calendar.events"
  ]
}

Required fields: type Optional fields: scopes (defaults to [])

Available connector types: Run npx base44 connectors list-available to see all supported integration types.

Note: stripe is also a valid connector type but is not returned by list-available. Treat it as a supported type — it is provisioned automatically by Base44 with no OAuth browser flow. See connectors-create.md for details.

For complete documentation, see connectors-create.md.

Automation Quick Reference

Automations are triggers defined in the automations array inside function.jsonc. They deploy with the function via base44 functions deploy. Four types:

Common fields (all types): name (required), description, function_args, is_active (default: true)

Scheduled One-Time: type: "scheduled", schedule_mode: "one-time", one_time_date (ISO string)

Scheduled CRON: type: "scheduled", schedule_mode: "recurring", schedule_type: "cron", cron_expression, optional ends_type / ends_on_date / ends_after_count

Scheduled Simple: type: "scheduled", schedule_mode: "recurring", schedule_type: "simple", repeat_unit ("minutes" | "hours" | "days" | "weeks" | "months"), optional repeat_interval, start_time, repeat_on_days (0–6), repeat_on_day_of_month (1–31), ends_type / ends_on_date / ends_after_count

Entity Hook: type: "entity", entity_name (matches entity schema name), event_types: array of "create" | "update" | "delete" (at least one)

For full schemas and examples, see automations.md.

Auth Configuration

Manage your app's authentication settings (e.g., username & password login). Auth config is stored in base44/auth/ and synced with Base44 via auth push/auth pull.

Note: Auth config is also deployed as part of base44 deploy.

Secrets Management

Manage project secrets (environment variables stored securely in Base44). These commands are hidden from --help output but are fully functional.

Script Execution

Run one-off scripts against your app with the Base44 SDK pre-authenticated. Use it to perform CRUD operations on entities (base44.entities.MyEntity.list/create/update/delete), call backend functions (base44.functions.invoke("myFunction", args)), invoke agents, or access any other resource exposed by the SDK — without deploying a full function. Useful for data migrations, bulk operations, debugging, and automation scripts.

Type Generation

Output: base44/.types/types.d.ts — augments @base44/sdk module with typed registries (EntityTypeRegistry, FunctionNameRegistry, AgentNameRegistry, ConnectorTypeRegistry).

No authentication required. Runs entirely locally. Automatically updates tsconfig.json to include the generated types.

Site Management

SPA only: Base44 hosting supports Single Page Applications with a single index.html entry point. All routes are served from index.html (client-side routing).

Quick Start

1. Install the CLI in your project:

   npm install --save-dev base44
   

2. Authenticate with Base44:

   npx base44 login
   

3. Create a new project (ALWAYS provide name and --path flag):

   npx base44 create my-app -p .
   

4. Build and deploy everything:

   npm run build
   npx base44 deploy -y
   

Or deploy individual resources:

• npx base44 entities push - Push entities only
• npx base44 functions deploy - Deploy functions only
• npx base44 functions delete <name> - Delete a deployed function
• npx base44 functions list - List all deployed functions
• npx base44 functions pull - Pull deployed functions to local files
• npx base44 agents push - Push agents only
• npx base44 connectors pull - Pull connectors from Base44
• npx base44 connectors push - Push connectors only
• npx base44 auth pull - Pull auth config from Base44
• npx base44 auth push - Push auth config only
• npx base44 site deploy -y - Deploy site only

Common Workflows

Creating a New Project

⚠️ MANDATORY: Before running base44 create, you MUST read create.md for:

• Template selection - Choose the correct template (backend-and-client vs backend-only)
• Correct workflow - Different templates require different setup steps
• Common pitfalls - Avoid folder creation errors that cause failures

Failure to follow the create.md instructions will result in broken project scaffolding.

Linking an Existing Project

# If you have base44/config.jsonc but no .app.jsonc
npx base44 link --create --name my-app

Deploying All Changes

# Generate types (optional, for TypeScript projects)
npx base44 types generate

# Build your project first
npm run build

# Deploy everything (entities, functions, and site)
npx base44 deploy -y

Generating TypeScript Types

# Generate types from entities, functions, agents, and connectors
npx base44 types generate

This creates base44/.types/types.d.ts with typed registries for the @base44/sdk module. Run this after changing entities, functions, agents, or connectors to keep your types in sync. No authentication required.

Deploying Individual Resources

# Push only entities
npx base44 entities push

# Deploy only functions (all)
npx base44 functions deploy
# Deploy specific functions
npx base44 functions deploy my-function other-function
# Deploy and prune removed functions
npx base44 functions deploy --force

# Push only agents
npx base44 agents push

# Pull connectors from Base44
npx base44 connectors pull

# Push only connectors
npx base44 connectors push

# Deploy only site
npx base44 site deploy -y

Opening the Dashboard

# Open app dashboard in browser
npx base44 dashboard

Authentication

Most commands require authentication. If you're not logged in, the CLI will automatically prompt you to login. Your session is stored locally and persists across CLI sessions.

Troubleshooting

Base44 Coder

Build apps on the Base44 platform using the Base44 JavaScript SDK.

⚡ IMMEDIATE ACTION REQUIRED - Read This First

This skill activates on ANY mention of "base44" or when a base44/ folder exists. DO NOT read documentation files or search the web before acting.

Your first action MUST be:

1. Check if base44/config.jsonc exists in the current directory
2. If YES (existing project scenario):
   • This skill (base44-sdk) handles the request
   • Implement features using Base44 SDK
   • Do NOT use base44-cli unless user explicitly requests CLI commands
3. If NO (new project scenario):
   • Transfer to base44-cli skill for project initialization
   • This skill cannot help until project is initialized

When to Use This Skill vs base44-cli

Use base44-sdk when:

• Building features in an EXISTING Base44 project
• base44/config.jsonc already exists in the project
• Base44 SDK imports are present (@base44/sdk)
• Writing JavaScript/TypeScript code using Base44 SDK modules
• Implementing functionality, components, or features
• User mentions: "implement", "build a feature", "add functionality", "write code for"
• User says "create a [type] app" and a Base44 project already exists

DO NOT USE base44-sdk for:

• ❌ Initializing new Base44 projects (use base44-cli instead)
• ❌ Empty directories without Base44 configuration
• ❌ When user says "create a new Base44 project/app/site" and no project exists
• ❌ CLI commands like npx base44 create, npx base44 deploy, npx base44 login (use base44-cli)

Skill Dependencies:

• base44-sdk assumes a Base44 project is already initialized
• base44-cli is a prerequisite for base44-sdk in new projects
• If user wants to "create an app" and no Base44 project exists, use base44-cli first

State Check Logic: Before selecting this skill, verify:

• IF (user mentions "create/build app" OR "make a project"):
  • IF (directory is empty OR no base44/config.jsonc exists): → Use base44-cli (project initialization needed)
  • ELSE: → Use base44-sdk (project exists, build features)

Quick Start

// In Base44-generated apps, base44 client is pre-configured and available

// CRUD operations
const task = await base44.entities.Task.create({ title: "New task", status: "pending" });
const tasks = await base44.entities.Task.list();
await base44.entities.Task.update(task.id, { status: "done" });

// Get current user
const user = await base44.auth.me();

// External apps
import { createClient } from "@base44/sdk";

// IMPORTANT: Use 'appId' (NOT 'clientId' or 'id')
const base44 = createClient({ appId: "your-app-id" });
await base44.auth.loginViaEmailPassword("user@example.com", "password");

⚠️ CRITICAL: Do Not Hallucinate APIs

Before writing ANY Base44 code, verify method names against this table or QUICK_REFERENCE.md.

Base44 SDK has unique method names. Do NOT assume patterns from Firebase, Supabase, or other SDKs.

Authentication - WRONG vs CORRECT

Functions - WRONG vs CORRECT

Integrations - WRONG vs CORRECT

Entities - WRONG vs CORRECT

SDK Modules

For client setup and authentication modes, see client.md.

TypeScript and type registries

Each reference file includes a "Type Definitions" section with TypeScript interfaces and types for the module's methods, parameters, and return values.

Getting typed entities, functions, and agents: The Base44 CLI generates types from your project resources (entities, functions, agents), including augmentations to EntityTypeRegistry, FunctionNameRegistry, and AgentNameRegistry, and wires them into your project so you get autocomplete and type checking without manual setup. For how to generate types, use the base44-cli skill.

Manual augmentation: You can instead augment the registries yourself in a .d.ts file; see the Type Definitions sections in entities.md, functions.md, and base44-agents.md.

Installation

Install the Base44 SDK:

npm install @base44/sdk

Important: Never assume or hardcode the @base44/sdk package version. Always install without a version specifier to get the latest version.

Creating a Client (External Apps)

When creating a client in external apps, ALWAYS use appId as the parameter name:

import { createClient } from "@base44/sdk";

// ✅ CORRECT
const base44 = createClient({ appId: "your-app-id" });

// ❌ WRONG - Do NOT use these:
// const base44 = createClient({ clientId: "your-app-id" });  // WRONG
// const base44 = createClient({ id: "your-app-id" });        // WRONG

Required parameter: appId (string) - Your Base44 application ID

Optional parameters:

• token (string) - Pre-authenticated user token
• options (object) - Configuration options
  • options.onError (function) - Global error handler

Example with error handler:

const base44 = createClient({
  appId: "your-app-id",
  options: {
    onError: (error) => {
      console.error("Base44 error:", error);
    }
  }
});

Module Selection

Working with app data?

• Create/read/update/delete records → entities
• Import data from file → entities.importEntities()
• Realtime updates → entities.EntityName.subscribe()

User management?

• Login/register/logout → auth
• Get current user → auth.me()
• Update user profile → auth.updateMe()
• Invite users → users.inviteUser()

AI features?

• Chat with AI agents → agents (requires logged-in user)
• Create new conversation → agents.createConversation()
• Manage conversations → agents.getConversations()
• Generate text/JSON with AI → integrations.Core.InvokeLLM()
• Generate images → integrations.Core.GenerateImage()

Custom backend logic?

• Run server-side code → functions.invoke()
• Need admin access → base44.asServiceRole.functions.invoke()

External services?

• Send emails → integrations.Core.SendEmail()
• Upload files → integrations.Core.UploadFile()
• Custom APIs → integrations.custom.call()
• App-scoped OAuth (app builder's account) → asServiceRole.connectors.getConnection() (backend only)

Tracking and analytics?

• Track custom events → analytics.track()
• Log page views/activity → appLogs.logUserInApp()

Common Patterns

Filter and Sort Data

const pendingTasks = await base44.entities.Task.filter(
  { status: "pending", assignedTo: userId },  // query
  "-created_date",                             // sort (descending)
  10,                                          // limit
  0                                            // skip
);

Protected Routes (check auth)

const user = await base44.auth.me();
if (!user) {
  // Navigate to your custom login page
  navigate('/login', { state: { returnTo: window.location.pathname } });
  return;
}

Backend Function Call

// Frontend
const result = await base44.functions.invoke("processOrder", {
  orderId: "123",
  action: "ship"
});

// Backend function (Deno)
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const { orderId, action } = await req.json();
  // Process with service role for admin access
  const order = await base44.asServiceRole.entities.Orders.get(orderId);
  return Response.json({ success: true });
});

Service Role Access

Use asServiceRole in backend functions for admin-level operations:

// User mode - respects permissions
const myTasks = await base44.entities.Task.list();

// Service role - full access (backend only)
const allTasks = await base44.asServiceRole.entities.Task.list();
const token = await base44.asServiceRole.connectors.getAccessToken("slack");

Frontend vs Backend

Backend functions use Deno.serve() and createClientFromRequest(req) to get a properly authenticated client.

Troubleshoot Production Issues

Prerequisites

Verify authentication before fetching logs:

npx base44 whoami

If not authenticated or token expired, instruct user to run npx base44 login.

Must be run from the project directory (where base44/.app.jsonc exists):

cat base44/.app.jsonc

Available Commands

Troubleshooting Flow

1. Check Recent Errors

Start by pulling the latest errors across all functions:

npx base44 logs --level error

2. Drill Into a Specific Function

If you know which function is failing:

npx base44 logs --function <function_name> --level error

3. Inspect a Time Range

Correlate with user-reported issue timestamps:

npx base44 logs --function <function_name> --since <start_time> --until <end_time>

4. Analyze the Logs

• Look for stack traces and error messages in the output
• Check timestamps to correlate with user-reported issues
• Use --limit to fetch more entries if the default 50 isn't enough

Workflow

If boltz-api is missing from PATH, use boltz-cli-setup for install/update guidance before retrying. If a command reports missing or expired authentication, use boltz-cli-setup to start boltz-api auth login --device-code before retrying; do not ask permission first. If the agent host sandbox blocks boltz-api install/auth/API calls, use boltz-cli-setup to request the host sandbox bypass/escalation needed for user-wide CLI install, browser login, credential storage, temp files, or API access before retrying.

Use this skill to recover state across sessions and to inspect or download results for prior Boltz jobs. No payload authoring — this skill only calls list / retrieve / download-results / download-status.

Use four modes:

1. Local progress: if the user knows the run name / run dir, prefer download-status before remote API calls.
2. List recent jobs: enumerate all six resources, merge, and sort by created_at descending.
3. Retrieve one job: use the job ID prefix when known; otherwise probe resources until one succeeds.
4. Resume/download results: run download-results with the original run name when possible. Never run start again to resume.

ADME jobs use the prefix adme_pred_* and show up in Modes 1-2 (list / retrieve) like the others. ADME has no download-results/archive step, so Modes 3-4 don't apply — recover its scores by re-running retrieve (read output.molecules[]) or from the local run.json.

Read references/resume.md before recovering a dropped session, mapping job ID prefixes, or choosing a run name for download-results. Read references/api.md for per-resource list columns, retrieve fields, and result semantics.

Command Pattern

# Replace placeholders with concrete absolute paths before running.

# Local helper: inspect local checkpoint state without API calls.
boltz-api --format json download-status \
  --name "<run-name>" \
  --root-dir "/absolute/path/boltz-experiments"

# Mode 1: list recent jobs across all 6 resources.
# Note: the CLI emits one JSON object per record (streamed, no {data:[]} wrapper).
# --limit is per-page and the CLI auto-paginates, so cap each explicit command with head.
boltz-api predictions:structure-and-binding list --limit 20 --format jsonl | head -20
boltz-api predictions:adme list --limit 20 --format jsonl | head -20
boltz-api small-molecule:library-screen list --limit 20 --format jsonl | head -20
boltz-api small-molecule:design list --limit 20 --format jsonl | head -20
boltz-api protein:library-screen list --limit 20 --format jsonl | head -20
boltz-api protein:design list --limit 20 --format jsonl | head -20

# Mode 2: retrieve by ID. Pick the resource from the ID prefix in the workflow
# notes above. If the prefix is unknown, run these one at a time until one succeeds.
boltz-api predictions:structure-and-binding retrieve --id "<job-id>" --format json
boltz-api predictions:adme retrieve --id "<job-id>" --format json
boltz-api small-molecule:library-screen retrieve --id "<job-id>" --format json
boltz-api small-molecule:design retrieve --id "<job-id>" --format json
boltz-api protein:library-screen retrieve --id "<job-id>" --format json
boltz-api protein:design retrieve --id "<job-id>" --format json

# Mode 3: resume download. Use the agent runtime's managed long-running command mode.
boltz-api download-results \
  --id "<job-id>" --name "<run-name>" \
  --root-dir "/absolute/path/boltz-experiments" \
  --poll-interval-seconds 30

Always Do This

• If the user has a run name / slug or run dir and only wants local downloader state, prefer download-status before retrieve.
• Use an absolute output root and keep passing it through --root-dir. Do not cd into the run directory; that makes later relative paths point at the run directory instead of the user's workspace.
• On an unfamiliar job ID, run Mode 2 (retrieve) before Mode 3 (download) so you capture idempotency_key.
• Prefer the original run-name slug over the job ID as --name — it resumes into the existing dir with cursor.
• In permission-gated agents such as Claude Code, keep each Boltz call as a top-level command that starts with boltz-api. Prefer running the six list / retrieve commands explicitly over generating them from a shell loop; a fixed | head -20 cap is okay when listing to avoid runaway streamed output.
• Prefer the agent runtime's background/non-blocking command mode for download-results. In Codex specifically, keep download-results in the foreground and set the shell tool yield to 1000 ms; Codex will return a session_id if the command is still running. Do not append & or use nohup in Codex because the tool runner may clean up shell-backgrounded descendants before .boltz-run.json is fully written.
• After the background/session starts, do not manually wait on it or run ad hoc polling loops. In Codex app/desktop runtimes with same-thread heartbeat automation support, schedule a heartbeat that checks download-status periodically, posts only material status changes or terminal completion/failure, and stops once terminal. If the current host has no heartbeat automation support, do not claim an automatic next check; report the job ID, run name, output directory, and the command needed to check download-status.
• download-results now emits machine-readable JSONL progress on stderr by default. Add --progress-format text --verbose only when you explicitly want human-readable logs.
• Prefer download-status for local checkpoint state. In Codex hosts with heartbeat automation support, use it for automatic follow-up and poll the saved session with an empty write_stdin only for interactive, user-requested progress checks. Don't loop retrieve unless the user wants fresh remote status.
• If retrieve surfaces only {"code":"VALIDATION_ERROR","message":"Request validation failed"} with no details, that's expected for predictions:structure-and-binding failures — other endpoints include field paths.
• Never run start again on a failed or interrupted job. Fix the payload and submit with a new idempotency-key, or just resume with download-results.

Escape Hatch

• Python SDK reference (per-resource list / retrieve methods): https://api.boltz.bio/docs/api/python
• CLI flag names: boltz-api <resource> list --help, boltz-api <resource> retrieve --help, boltz-api download-results --help, boltz-api download-status --help

Outputs

• Local helper / Mode 1 / Mode 2 print structured data to stdout; present as a table.
• Mode 3 writes recovered artifacts under <output-root>/<run-name>/ — same layout as a fresh run. Read references/resume.md for resume behavior.

Boltz CLI Setup

Use this skill for boltz-api installation, version, PATH, and authentication issues. The workflow skills assume boltz-api is already installed.

Verify Installation

Check that the CLI is available:

boltz-api --version

If boltz-api is missing or too old, prefer a version-pinned release artifact whose checksum or signature can be verified. If Boltz does not publish one for the user's platform, its official installer is the fallback.

Before downloading or running either installer, show the exact platform command and obtain the user's explicit confirmation. Explain that the command downloads mutable remote code, executes it as the user outside the sandbox, and therefore trusts install.boltz.bio at execution time. A general request to use or install Boltz is not confirmation for this specific risk.

macOS and Linux:

curl -fsSL https://install.boltz.bio/boltz-api/install.sh | sh

Windows PowerShell:

irm https://install.boltz.bio/boltz-api/install.ps1 | iex

The installer updates an existing boltz-api on PATH. If no binary is found, it installs to a user-local bin directory. Add the installed binary to PATH if boltz-api --version is still not found after install.

The sandbox can block browser login, OAuth callbacks, temp files, credential storage, and user-wide install paths. Request the host sandbox bypass/escalation needed for installation only after the installer confirmation above. The host approval must cover the exact command; do not treat an ordinary setup request as authorization to execute mutable remote code outside the sandbox.

Read references/sandbox.md when an agent sandbox blocks the installer, browser auto-open, OAuth callback, credential storage, temp files, or global install path.

Authenticate

Check the current auth state with:

boltz-api auth status

If auth status reports unauthenticated, or any Boltz command fails because authentication is missing or expired, start device-code login on the user's behalf before retrying:

boltz-api auth login --device-code

Do not ask the user for permission before starting device-code login; relaying the login URL/code and waiting for the CLI to complete is part of auth recovery. When sharing the authentication login URL/code, tell the user to use exactly boltz-api auth login --device-code.

For auth recovery, assume the CLI can auto-open the browser and run the exact command above. In sandboxed environments, request the host sandbox bypass/escalation needed for browser auto-open, OAuth callbacks, credential storage, or temp files.

For automation, an API key is still supported when it is already provisioned in the environment:

test -n "${BOLTZ_API_KEY:+configured}" && echo "BOLTZ_API_KEY is configured"

Never ask the user to paste an API key into chat or a command, and never print, log, or persist it in shell history or generated files. If the variable is not already provisioned, direct the user to their host's secret-management facility.

Version Checks

Do not hard-code expected commands or minimum versions in this skill. Treat the CLI's own update check as the source of truth.

When boltz-api reports that an update is available or required, relay that message and the install command it provides. The CLI may get this from a Boltz-hosted version metadata endpoint such as /cli/version, returning latest version, minimum supported version, whether an update is required, and platform-appropriate install instructions.

If a user asks why the CLI thinks it is stale, explain the split:

• GitHub Releases define which CLI binaries are available to install.
• The Boltz version endpoint defines API compatibility, including the minimum supported CLI version.

Respect user or CI opt-outs such as BOLTZ_API_NO_UPDATE_CHECK=1; do not force update checks when the environment disables them.

Workflow

If boltz-api is missing from PATH, use boltz-cli-setup for install/update guidance before retrying. If a command reports missing or expired authentication, use boltz-cli-setup to start boltz-api auth login --device-code before retrying; do not ask permission first. If the agent host sandbox blocks boltz-api install/auth/API calls, use boltz-cli-setup to request the host sandbox bypass/escalation needed for user-wide CLI install, browser login, credential storage, temp files, or API access before retrying.

Use this skill when the user wants de novo protein / peptide / antibody / nanobody binders.

1. Decide on target exploration first (new targets). For a new target where the user hasn't already fixed the binding site and crop, your first action — before authoring a payload, normalizing the target, or running estimate-cost — is to raise the choice between a target-exploration pass and designing directly, with a recommendation for this target:

   • Unknown site, or a multi-domain / large target → recommend exploration (it scouts different input configurations for generation, ≈50 designs each, and finds the best before a full run).
   • A well-characterized site → it's fine to recommend going (mostly) direct, perhaps with a quick check of whether conditioning on the epitope beats letting the model find its own spot. State this plainly, as part of a conversation with the user about their target and goals, and let them choose.

   Phrase it as a question that works with the user (they may know their target's biology), e.g.:

   "This is a fresh target — I'd suggest a quick exploration pass that scouts a few framings and picks the best before a full run. Or, if you already know the site and crop, we can design directly. Which would you like?"

   Do not mention a campaign size or tier here — not even folded into this opening approach question. The full-run size is settled later, after the scouting runs pick a winner (its yield informs the tier), so don't ask it up front when exploration is on the table. If the user opts into exploration — or has already said they want to explore / let the design find its own epitope — read references/target-exploration.md, follow it, then resume at step 8 with the chosen framing and recommended num_proteins. If they want to design directly, continue below.

2. Normalize the target (same shape as protein-screen): structure_template if a CIF/PDB is available, else no_template.

3. Pick the binder_specification variant. Supported variants include:

   • boltz_curated — recommended default for antibody and nanobody design. Boltz selects from maintained scaffold/template lists (binder: boltz_antibody or boltz_nanobody).
   • structure_template — redesign motifs in an existing binder scaffold (CIF + design_motifs with replacement / insertion segments).
   • no_template — generate from the sequence DSL (fixed residues + designed segments like 5..10 or 8).

4. For antibody or nanobody requests, ask before authoring the payload: "I recommend Boltz's curated antibody/nanobody scaffolds for this. Do you want the curated default, or do you have custom scaffold structures/CDR motifs to use?" If the user picks curated, use type: boltz_curated; if they want custom scaffold control, use type: structure_template.

5. Pick modality: peptide, antibody, nanobody, or custom_protein for structure_template and no_template (use custom_protein for a "miniprotein" or generic "protein binder"). If the user already named the modality, take it as given — don't ask again. Do not include modality on boltz_curated; use binder instead.

6. Pick num_proteins — see Run sizing. Valid range is 10 to 1,000,000 (server rejects outside it); 10 is the hard floor but it is a test size, not a campaign. When the user has not given a count, propose a campaign tier (default 50,000), not the floor.

7. Supported optional features include rules such as excluded amino acids, excluded sequence motifs with X wildcards, and max hydrophobic fraction. Add rules only on request; read references/api.md for exact shapes and examples.

8. Author the payload YAML or JSON, then run estimate-cost and apply the spending gate (Always Do This) before start. (Cost model — tiered by total complex length, estimate-cost is the only source: see ## Cost in api.md.)

9. start to submit. Capture the ID.

10. Launch download-results with the agent runtime's background/non-blocking command facility. In Claude Code, use Bash with run_in_background: true. In Codex, run download-results as a foreground shell command with yield_time_ms: 1000; if Codex returns a session_id, keep it for optional same-thread polling, but treat download-status plus the run directory as the durable source of truth. In Codex app/desktop runtimes that expose same-thread heartbeat automations, create a heartbeat that checks download-status periodically and posts a concise completion or failure update when the download reaches a terminal state. After launching the downloader, always report the job ID, run name, and output directory. Include the next check cadence if the heartbeat was created; otherwise include the download-status command.

11. Rank from <output-root>/<run-name>/results/index.jsonl by binding_confidence descending. Use iptm and min_interaction_pae as tiebreakers. optimization_score is not emitted for this endpoint. Read references/results.md for output layout and metric details.

Run sizing

De novo design is a generate-and-filter campaign: you make many binders and keep the rare good ones, so a real run is large. Do not anchor on the num_proteins floor of 10 — that is only useful for a quick setup test. When the user names a count, honor it (≥10). When they do not, explain the tiers and propose one:

Present the tiers as design counts, not dollars: don't put a price next to a tier unless estimate-cost returned it — run estimate-cost on the tier the user leans toward and show that figure, and never extrapolate one estimate across the others. Then apply the spending gate (Always Do This) before submitting. If the setup is unproven, suggest a small test run (tens of designs) or the full target-exploration pass first.

Command Pattern

# Replace placeholders with concrete absolute paths before running.
# Use a short descriptive run name, for example: protein-design-<modality>-<target>-v1

boltz-api protein:design estimate-cost \
  --input @yaml:///absolute/path/payload.yaml

boltz-api protein:design start \
       --idempotency-key "<run-name>" \
       --input @yaml:///absolute/path/payload.yaml \
       --raw-output --transform id

# Copy the printed job ID into this command, then launch it in the agent
# runtime's background/non-blocking mode.
# Claude Code: Bash with run_in_background=true.
# Codex: foreground shell command with yield_time_ms=1000; keep the returned session_id if one is provided.
# Do not append "&" or use nohup in Codex.
boltz-api download-results \
  --id "<job-id-from-start>" --name "<run-name>" \
  --root-dir "/absolute/path/boltz-experiments" \
  --poll-interval-seconds 60

Payload keys are num_proteins, target, binder_specification — API body field names.

Always Do This

• For a new target, your first move is the step-1 conversation — never jump straight to a payload. Establish what the binder is for and whether the user has already fixed the binding site/crop, then recommend a target-exploration pass vs. designing directly and let them choose (step 1). Only normalize the target and author a payload after that. If they've already fixed the site/crop or explicitly want to design directly, proceed.
• Enforce 10 <= num_proteins <= 1,000,000 before calling estimate-cost (server rejects outside that range), but 10 is the floor, not a campaign — see Run sizing and propose a tier (default 50,000) when the user gives no count.
• Spending gate — explicit go-ahead before every start. start spends real money. A plan you already described, an earlier phase's approval, or a cost that looks "trivial" are not authorization — even a cheap run needs a fresh yes. Run estimate-cost, show the estimated_cost_usd it returns (summed for a batch), and wait for the user to say go. This holds even when tool calls are pre-approved (accept-edits / auto-accept / bypass modes) — there you are the only cost gate. Never quote or assume a dollar figure you didn't get from estimate-cost (cost model: ## Cost in api.md).
• For antibody or nanobody design, recommend binder_specification.type: boltz_curated and ask the user to confirm they do not want custom scaffold/CDR control before building the payload. Use binder: boltz_antibody for antibody/Fab requests and binder: boltz_nanobody for nanobody/VHH requests.
• Residue indices are 0-based everywhere (design_motifs.start_index/end_index, after_residue_index, epitope_residues, flexible_residues, bonds, constraints).
• For CIF/PDB bytes, use @data:///abs/path/file.cif inside structure.data. Don't use bare @path.
• Sequence DSL for designed_protein.value: uppercase letters = fixed residues; integer N = exactly N designed residues; MIN..MAX = variable-length designed segment. Examples: "20", "5..10", "ACDE8GHI", "MKTAYI5..10VKSHFSRQ".
• Keep payload field names exactly as the API body names shown in references/api.md.
• Use absolute paths for the output root, payload files, and embedded target files. Do not cd into the run directory for follow-up commands; pass the same --root-dir and use absolute paths so later relative paths do not drift.
• Prefer one merged top-level payload via --input @yaml:///absolute/path/payload.yaml or @json:///absolute/path/payload.json for estimate-cost and start. Keep --idempotency-key and --workspace-id top-level; if they also appear inside --input, the top-level flags win.
• Direct object flags still work as overrides, such as --target @yaml:///absolute/path/target.yaml or --binder-specification @json:///absolute/path/binder.json. Piped YAML / JSON on stdin also works, but it must use API body field names. Use the same slug for both --idempotency-key and --name.
• In permission-gated agents such as Claude Code, keep each Boltz call as a top-level command that starts with boltz-api. Prefer concrete arguments over sh -c, inline environment assignments, aliases, wrapper scripts, loops, or pipelines around the boltz-api invocation unless the user already allowed that exact command form. Use --raw-output --transform id, read the printed ID, then paste that literal ID into the next download-results command.
• Prefer the agent runtime's background/non-blocking command mode for download-results. In Codex specifically, keep download-results in the foreground and set the shell tool yield to 1000 ms; Codex will return a session_id if the command is still running. Do not append & or use nohup in Codex because the tool runner may clean up shell-backgrounded descendants before .boltz-run.json is fully written.
• After the background/session starts, do not manually wait on it or run ad hoc polling loops. Wall-clock time scales roughly with num_proteins: under 100 often finishes in a few minutes, 100-1,000 may take several minutes to tens of minutes, and larger runs can take longer or hours depending on inputs and system load. Don't quote a fixed duration. --poll-interval-seconds 60 is a sensible downloader default. download-results emits JSONL progress on stderr by default; add --progress-format text --verbose only when you explicitly want human-readable logs.
• In Codex app/desktop runtimes with same-thread heartbeat automation support, schedule a heartbeat after launching download-results. The heartbeat should run boltz-api --format json download-status --name "<run-name>" --root-dir "/absolute/path/boltz-experiments" and stop once terminal. Choose cadence by num_proteins: under 100 -> every 1-2 minutes; 100-1,000 -> every 5 minutes; over 1,000 -> every 15 minutes. Post only material status changes or terminal completion/failure. Poll the saved session_id with an empty write_stdin only for interactive, user-requested progress checks. Never run a manual poll loop in the current turn.
• If the current host has no heartbeat automation support, do not claim an automatic next check. Report the job ID, run name, output directory, and the command needed to check download-status.
• If detached download needs to be restarted, re-run boltz-api download-results with the same --name "<run-name>" and the same --root-dir.
• Only add rules on explicit user request.

Escape Hatch

• Payload reference: https://api.boltz.bio/docs/api/resources/protein/subresources/design/methods/start/
• CLI flag names: boltz-api protein:design start --help

Read references/api.md for all binder_specification variants, motif shapes, sequence DSL, rules, modalities, and target variants. Read references/results.md after download when ranking designed binders or explaining outputs.

Outputs

Rank from results/index.jsonl after download-results; use references/results.md for local file layout, metric meanings, and the designed-binder entity type gotcha.

Workflow

If boltz-api is missing from PATH, use boltz-cli-setup for install/update guidance before retrying. If a command reports missing or expired authentication, use boltz-cli-setup to start boltz-api auth login --device-code before retrying; do not ask permission first. If the agent host sandbox blocks boltz-api install/auth/API calls, use boltz-cli-setup to request the host sandbox bypass/escalation needed for user-wide CLI install, browser login, credential storage, temp files, or API access before retrying.

Use this skill when the user already has candidate proteins / peptides / antibodies / nanobodies.

1. Normalize the binder library into proteins — a list of candidate complexes. For a simple sequence library each entry has one protein entity; multi-chain candidates (antibody heavy+light) are also allowed.
2. Pick the target variant:
   • structure_template — user has a CIF/PDB file or URL; select which chains are polymer vs ligand, which residues to keep (crop_residues), and optionally epitope_residues / flexible_residues.
   • no_template — user has only sequences; pass them as target.entities plus optional epitope_residues.
3. Don't add bonds / constraints unless the user asks for geometry constraints.
4. Author the payload YAML or JSON, run estimate-cost, show the USD cost, wait for explicit confirmation.
5. start to submit. Capture the ID.
6. Launch download-results with the agent runtime's background/non-blocking command facility. In Claude Code, use Bash with run_in_background: true. In Codex, run download-results as a foreground shell command with yield_time_ms: 1000; if Codex returns a session_id, keep it for optional same-thread polling, but treat download-status plus the run directory as the durable source of truth. In Codex app/desktop runtimes that expose same-thread heartbeat automations, create a heartbeat that checks download-status periodically and posts a concise completion or failure update when the download reaches a terminal state. After launching the downloader, always report the job ID, run name, and output directory. Include the next check cadence if the heartbeat was created; otherwise include the download-status command.
7. Rank hits from <output-root>/<run-name>/results/index.jsonl by binding_confidence descending. Use iptm and min_interaction_pae as tiebreakers. optimization_score is not emitted for this endpoint. Read references/results.md for output layout and metric details.

Command Pattern

# Replace placeholders with concrete absolute paths before running.
# Use a short descriptive run name, for example: protein-screen-<target>-<library>-v1

boltz-api protein:library-screen estimate-cost \
  --input @yaml:///absolute/path/payload.yaml

boltz-api protein:library-screen start \
       --idempotency-key "<run-name>" \
       --input @yaml:///absolute/path/payload.yaml \
       --raw-output --transform id

# Copy the printed job ID into this command, then launch it in the agent
# runtime's background/non-blocking mode.
# Claude Code: Bash with run_in_background=true.
# Codex: foreground shell command with yield_time_ms=1000; keep the returned session_id if one is provided.
# Do not append "&" or use nohup in Codex.
boltz-api download-results \
  --id "<job-id-from-start>" --name "<run-name>" \
  --root-dir "/absolute/path/boltz-experiments" \
  --poll-interval-seconds 30

Payload keys are proteins, target — API body field names.

Always Do This

• For structure_template, embed CIF/PDB bytes with @data:///abs/path/target.cif inside the structure.data field. Don't use bare @path (automatic file-type detection once sent CIF as plain text into a base64 field and broke the server parser).
• Residue indices are 0-based. epitope_residues and flexible_residues must be subsets of crop_residues.
• Keep payload field names exactly as the API body names shown in references/api.md.
• Use absolute paths for the output root, payload files, and embedded target files. Do not cd into the run directory for follow-up commands; pass the same --root-dir and use absolute paths so later relative paths do not drift.
• Prefer one merged top-level payload via --input @yaml:///absolute/path/payload.yaml or @json:///absolute/path/payload.json for estimate-cost and start. Keep --idempotency-key and --workspace-id top-level; if they also appear inside --input, the top-level flags win.
• Direct object flags still work as overrides, such as --target @yaml:///absolute/path/target.yaml or repeated --protein @json:///absolute/path/protein-1.json entries. Piped YAML / JSON on stdin also works, but it must use API body field names. Never use @file:// or @./.
• Use the same slug as both --idempotency-key and --name.
• In permission-gated agents such as Claude Code, keep each Boltz call as a top-level command that starts with boltz-api. Prefer concrete arguments over sh -c, inline environment assignments, aliases, wrapper scripts, loops, or pipelines around the boltz-api invocation unless the user already allowed that exact command form. Use --raw-output --transform id, read the printed ID, then paste that literal ID into the next download-results command.
• Prefer the agent runtime's background/non-blocking command mode for download-results. In Codex specifically, keep download-results in the foreground and set the shell tool yield to 1000 ms; Codex will return a session_id if the command is still running. Do not append & or use nohup in Codex because the tool runner may clean up shell-backgrounded descendants before .boltz-run.json is fully written.
• After the background/session starts, do not manually wait on it or run ad hoc polling loops. Wall-clock time scales roughly with the number of candidates in the library: under 100 often finishes in a few minutes, 100-1,000 may take several minutes to tens of minutes, and larger screens can take longer or hours depending on inputs and system load. Don't quote a fixed duration. --poll-interval-seconds 30 is a reasonable downloader default. download-results emits JSONL progress on stderr by default; add --progress-format text --verbose only when you explicitly want human-readable logs.
• In Codex app/desktop runtimes with same-thread heartbeat automation support, schedule a heartbeat after launching download-results. The heartbeat should run boltz-api --format json download-status --name "<run-name>" --root-dir "/absolute/path/boltz-experiments" and stop once terminal. Choose cadence by candidate count: under 100 -> every 1-2 minutes; 100-1,000 -> every 5 minutes; over 1,000 -> every 15 minutes. Post only material status changes or terminal completion/failure. Poll the saved session_id with an empty write_stdin only for interactive, user-requested progress checks. Never run a manual poll loop in the current turn.
• If the current host has no heartbeat automation support, do not claim an automatic next check. Report the job ID, run name, output directory, and the command needed to check download-status.
• If detached download needs to be restarted, re-run boltz-api download-results with the same --name "<run-name>" and the same --root-dir.
• Cost is tiered by total complex length (target + candidate); the combined length sets the tier. Do not state or estimate a dollar figure yourself — to say anything about cost, run estimate-cost and quote only the number it returns.

Escape Hatch

• Payload reference: https://api.boltz.bio/docs/api/python/resources/protein/subresources/library_screen/methods/start
• CLI flag names: boltz-api protein:library-screen start --help

Read references/api.md for the proteins list shape and both target variants (structure_template with chain_selection, and no_template with epitope hints). Read references/results.md after download when ranking screened binders or explaining outputs.

Outputs

Rank from results/index.jsonl after download-results; use references/results.md for local file layout and metric meanings.

Workflow

If boltz-api is missing from PATH, use boltz-cli-setup for install/update guidance before retrying. If a command reports missing or expired authentication, use boltz-cli-setup to start boltz-api auth login --device-code before retrying; do not ask permission first. If the agent host sandbox blocks boltz-api install/auth/API calls, use boltz-cli-setup to request the host sandbox bypass/escalation needed for user-wide CLI install, browser login, credential storage, temp files, or API access before retrying.

Use this skill for standalone ADME triage on SMILES the user already has. No protein target is involved. If the user is also screening or docking those molecules against a target, prefer boltz-small-molecule-screen — it returns the same ADME block free as part of the screen.

1. Normalize the molecules from raw SMILES, a CSV (auto-detect the SMILES column), .smi, or .txt into the molecules list. Each entry is {smiles, id?}; the optional id is echoed back as external_id on each result so you can map results to inputs.
2. Hard cap: 128 molecules per request. If the list exceeds 128, split into batches of ≤128 and submit one request per batch (suffix the run name, for example -b1, -b2), then merge results. Never send more than 128 in one call — the API rejects it with VALIDATION_ERROR: input.molecules must contain at most 128 items.
3. Author the payload YAML or JSON, run estimate-cost, show the USD cost, wait for explicit confirmation. ADME is priced at $0.01 per molecule (size-independent); estimate-cost returns the authoritative total — always quote it.
4. run to submit and wait — ADME finishes in seconds, so it is synchronous and needs no background polling. run persists results locally under --root-dir/<run-name>/.
5. Report from <output-root>/<run-name>/run.json → output.molecules[]. For each molecule show external_id (or smiles), solubility, permeability, and lipophilicity. The three values live under each molecule's adme object. Call out any molecule with status: failed and its error (an object {code, message}, e.g. code adme_enumeration_failed, message Invalid SMILES) — adme is null there; one bad SMILES fails only that molecule, not the batch. Read references/results.md for the output layout and references/api.md for the payload and batching details.

ADME values are approximate estimates for triage and ranking, not absolute measurements.

Command Pattern

# Replace placeholders with concrete absolute paths before running.
# Use a short descriptive run name, for example: adme-<library>-v1

boltz-api predictions:adme estimate-cost \
  --model adme-v1 --input @yaml:///absolute/path/payload.yaml

# `run` is synchronous (submit + wait + persist) and finishes in seconds — no background mode needed.
# Claude Code: run as a normal Bash command. Codex: run as a foreground shell command; if Codex
# returns a session_id because it is still running, poll it. Do not append "&" or use nohup in Codex.
boltz-api predictions:adme run \
  --model adme-v1 \
  --idempotency-key "<run-name>" \
  --input @yaml:///absolute/path/payload.yaml \
  --name "<run-name>" \
  --root-dir "/absolute/path/boltz-experiments" \
  --poll-interval-seconds 5
# -> /absolute/path/boltz-experiments/<run-name>/run.json  (output.molecules[].adme)

Payload is just a molecules list — the API body field name, not the direct CLI flag. --model adme-v1 is required.

Always Do This

• Keep payload field names exactly as the API body names shown in references/api.md (molecules, each {smiles, id?}).
• Pass --model adme-v1 on every estimate-cost, run, and start.
• Enforce the 128-molecule-per-request cap. Chunk larger libraries into ≤128 batches and submit each as its own run; merge the per-batch run.json outputs when reporting.
• Use absolute paths for the output root and payload files. Do not cd into the run directory; pass the same --root-dir and use absolute paths so later relative paths do not drift.
• Prefer one merged top-level payload via --input @yaml:///absolute/path/payload.yaml or @json:///absolute/path/payload.json. Keep --model, --idempotency-key, and --workspace-id top-level. Never use @file:// or @./.
• Run estimate-cost and show the USD total before submitting. ADME is $0.01/molecule (size-independent); estimate-cost returns the authoritative total — always use it.
• Use the same slug as both --idempotency-key and --name so re-runs resume via .boltz-run.json.
• In permission-gated agents such as Claude Code, keep each Boltz call as a top-level command that starts with boltz-api. Prefer concrete arguments over sh -c, inline environment assignments, aliases, wrapper scripts, loops, or pipelines unless the user already allowed that exact command form.
• ADME run is synchronous and finishes in seconds, so unlike the screen/design endpoints it needs no background/non-blocking mode. In Claude Code, run it as a normal Bash call. In Codex, run it as a foreground shell command; if Codex returns a session_id because the command is still running, poll it. Do not append & or use nohup in Codex.
• Do not require or accept a protein target — ADME is structure-free. If the user wants ADME and binding against a target, redirect to boltz-small-molecule-screen.

Escape Hatch

• Payload reference: https://api.boltz.bio/docs/api/resources/predictions/subresources/adme/methods/start/
• Guide: https://api.boltz.bio/docs/guides/small-molecule-adme/
• CLI flag names: boltz-api predictions:adme run --help

Read references/api.md for the molecules payload shape, the per-molecule output fields, the 128-molecule cap, and error handling.

Outputs

Read <output-root>/<run-name>/run.json and report output.molecules[]. There are no structure files — ADME returns scalar/categorical values only. Read references/results.md for the local layout and per-molecule output fields; references/api.md has the full request/response schema.

Workflow

If boltz-api is missing from PATH, use boltz-cli-setup for install/update guidance before retrying. If a command reports missing or expired authentication, use boltz-cli-setup to start boltz-api auth login --device-code before retrying; do not ask permission first. If the agent host sandbox blocks boltz-api install/auth/API calls, use boltz-cli-setup to request the host sandbox bypass/escalation needed for user-wide CLI install, browser login, credential storage, temp files, or API access before retrying.

Use this skill when the user wants de novo small-molecule binders (no existing library).

1. Normalize the target: one or more protein sequences into target.entities, plus optional pocket_residues (0-based) and/or reference_ligands (known binders to help locate the pocket).
2. Pick num_molecules — valid range 10 to 1,000,000 (server rejects outside it). If the user says fewer than 10, explain the floor and propose 10.
3. Only add chemical_space (e.g. "enamine_real") if the user explicitly wants generation restricted to synthesizable molecules within that library.
4. Supported optional features include chemical_space and molecule_filters; only add them on explicit request. Read references/api.md for exact shapes and filter options.
5. Author the payload YAML or JSON, run estimate-cost, show the USD cost, wait for explicit confirmation. Cost is a flat $0.025 per molecule (size-independent); still quote estimated_cost_usd from the response as the authoritative total.
6. start to submit (synchronous). Capture the ID.
7. Launch download-results with the agent runtime's background/non-blocking command facility; it polls, paginates, downloads per-hit structures, and exits when terminal. In Claude Code, use Bash with run_in_background: true. In Codex, run download-results as a foreground shell command with yield_time_ms: 1000; if Codex returns a session_id, keep it for optional same-thread polling, but treat download-status plus the run directory as the durable source of truth. In Codex app/desktop runtimes that expose same-thread heartbeat automations, create a heartbeat that checks download-status periodically and posts a concise completion or failure update when the download reaches a terminal state. After launching the downloader, always report the job ID, run name, and output directory. Include the next check cadence if the heartbeat was created; otherwise include the download-status command.
8. Rank hits from <output-root>/<run-name>/results/index.jsonl by binding_confidence for hit discovery or optimization_score for lead optimization. Each generated molecule also carries a free adme block (solubility, permeability, lipophilicity) — surface it for developability triage when the user cares about ADME, or when a top hit looks risky. Read references/results.md for output layout and metric details.

Command Pattern

# Replace placeholders with concrete absolute paths before running.
# Use a short descriptive run name, for example: sm-design-<target>-<batch>-v1

boltz-api small-molecule:design estimate-cost \
  --input @yaml:///absolute/path/payload.yaml

boltz-api small-molecule:design start \
       --idempotency-key "<run-name>" \
       --input @yaml:///absolute/path/payload.yaml \
       --raw-output --transform id

# Copy the printed job ID into this command, then launch it in the agent
# runtime's background/non-blocking mode.
# Claude Code: Bash with run_in_background=true.
# Codex: foreground shell command with yield_time_ms=1000; keep the returned session_id if one is provided.
# Do not append "&" or use nohup in Codex.
boltz-api download-results \
  --id "<job-id-from-start>" --name "<run-name>" \
  --root-dir "/absolute/path/boltz-experiments" \
  --poll-interval-seconds 60
# -> /absolute/path/boltz-experiments/<run-name>/results/<pres_*>/...

Payload keys are num_molecules, target, chemical_space, molecule_filters — the API body field names.

Always Do This

• Enforce 10 <= num_molecules <= 1,000,000 before calling estimate-cost. The server rejects values outside that range.
• Cost is a flat $0.025 per molecule (size-independent). estimate-cost returns the authoritative total.
• Treat pocket residue indices as 0-based.
• Keep payload field names exactly as the API body names shown in references/api.md.
• Use absolute paths for the output root, payload files, and embedded target files. Do not cd into the run directory for follow-up commands; pass the same --root-dir and use absolute paths so later relative paths do not drift.
• Prefer one merged top-level payload via --input @yaml:///absolute/path/payload.yaml or @json:///absolute/path/payload.json for estimate-cost and start. Keep --idempotency-key and --workspace-id top-level; if they also appear inside --input, the top-level flags win.
• Direct object flags still work as overrides: for example --target @yaml:///absolute/path/target.yaml or --molecule-filters @json:///absolute/path/filters.json. Piped YAML / JSON on stdin also works, but it must use API body field names. Never use @file://.
• Use the same slug as both --idempotency-key at submit and --name on download-results.
• In permission-gated agents such as Claude Code, keep each Boltz call as a top-level command that starts with boltz-api. Prefer concrete arguments over sh -c, inline environment assignments, aliases, wrapper scripts, loops, or pipelines around the boltz-api invocation unless the user already allowed that exact command form. Use --raw-output --transform id, read the printed ID, then paste that literal ID into the next download-results command.
• Prefer the agent runtime's background/non-blocking command mode for download-results. In Codex specifically, keep download-results in the foreground and set the shell tool yield to 1000 ms; Codex will return a session_id if the command is still running. Do not append & or use nohup in Codex because the tool runner may clean up shell-backgrounded descendants before .boltz-run.json is fully written.
• After the background/session starts, do not manually wait on it or run ad hoc polling loops. Wall-clock time scales roughly with num_molecules: under 100 often finishes in a few minutes, 100-1,000 may take several minutes to tens of minutes, and larger runs can take longer or hours depending on inputs and system load. Don't quote a fixed duration. --poll-interval-seconds 60 is a sensible default for the downloader. download-results emits JSONL progress on stderr by default; add --progress-format text --verbose only when you explicitly want human-readable logs.
• In Codex app/desktop runtimes with same-thread heartbeat automation support, schedule a heartbeat after launching download-results. The heartbeat should run boltz-api --format json download-status --name "<run-name>" --root-dir "/absolute/path/boltz-experiments" and stop once terminal. Choose cadence by num_molecules: under 100 -> every 1-2 minutes; 100-1,000 -> every 5 minutes; over 1,000 -> every 15 minutes. Post only material status changes or terminal completion/failure. Poll the saved session_id with an empty write_stdin only for interactive, user-requested progress checks. Never run a manual poll loop in the current turn.
• If the current host has no heartbeat automation support, do not claim an automatic next check. Report the job ID, run name, output directory, and the command needed to check download-status.
• If detached download needs to be restarted, re-run boltz-api download-results with the same --name "<run-name>" and the same --root-dir.
• Do not invent filters; only add molecule_filters on user request.

Escape Hatch

• Payload reference: https://api.boltz.bio/docs/api/python/resources/small_molecule/subresources/design/methods/start
• CLI flag names: boltz-api small-molecule:design start --help

Read references/api.md for the target, chemical_space, and molecule_filters shapes (filter catalog matches the screen endpoint). Read references/results.md after download when ranking generated molecules or explaining outputs.

Outputs

Rank from results/index.jsonl after download-results; use references/results.md for local file layout and metric meanings.

Workflow

If boltz-api is missing from PATH, use boltz-cli-setup for install/update guidance before retrying. If a command reports missing or expired authentication, use boltz-cli-setup to start boltz-api auth login --device-code before retrying; do not ask permission first. If the agent host sandbox blocks boltz-api install/auth/API calls, use boltz-cli-setup to request the host sandbox bypass/escalation needed for user-wide CLI install, browser login, credential storage, temp files, or API access before retrying.

Use this skill when the user already has candidate molecules.

1. Normalize the library from raw SMILES, a CSV (auto-detect the SMILES column), .smi, or .txt into the molecules list. Each entry is {smiles, id?}; the optional id is echoed back as external_id on each result.
2. Normalize the target: one or more protein sequences into target.entities, plus optional pocket_residues (0-based) and/or reference_ligands (SMILES of known binders to help locate the pocket).
3. Keep default server-side filtering unless the user asks for custom filters — only add molecule_filters on explicit request.
4. Author the payload YAML or JSON, run estimate-cost, show the USD cost, wait for explicit confirmation.
5. start to submit (synchronous). Capture the ID.
6. Launch download-results with the agent runtime's background/non-blocking command facility — it polls, paginates list-results, downloads every per-hit structure, and exits when terminal. In Claude Code, use Bash with run_in_background: true. In Codex, run download-results as a foreground shell command with yield_time_ms: 1000; if Codex returns a session_id, keep it for optional same-thread polling, but treat download-status plus the run directory as the durable source of truth. In Codex app/desktop runtimes that expose same-thread heartbeat automations, create a heartbeat that checks download-status periodically and posts a concise completion or failure update when the download reaches a terminal state. After launching the downloader, always report the job ID, run name, and output directory. Include the next check cadence if the heartbeat was created; otherwise include the download-status command.
7. When done, rank from <output-root>/<run-name>/results/index.jsonl. Sort by binding_confidence for hit discovery or optimization_score for lead optimization; these are parallel intents, not a fallback hierarchy. Report the top 5-10 hits with smiles, the chosen ranking metric, key confidence metrics, and structure path. Each result also carries a free adme block (solubility, permeability, lipophilicity) — include it for developability triage when the user cares about ADME, or when a top hit looks risky. Read references/results.md for output layout, metrics, ADME, and filtered-input accounting.

Command Pattern

# Replace placeholders with concrete absolute paths before running.
# Use a short descriptive run name, for example: sm-screen-<target>-<library>-v1

boltz-api small-molecule:library-screen estimate-cost \
  --input @yaml:///absolute/path/payload.yaml

boltz-api small-molecule:library-screen start \
       --idempotency-key "<run-name>" \
       --input @yaml:///absolute/path/payload.yaml \
       --raw-output --transform id

# Copy the printed job ID into this command, then launch it in the agent
# runtime's background/non-blocking mode.
# Claude Code: Bash with run_in_background=true.
# Codex: foreground shell command with yield_time_ms=1000; keep the returned session_id if one is provided.
# Do not append "&" or use nohup in Codex.
boltz-api download-results \
  --id "<job-id-from-start>" --name "<run-name>" \
  --root-dir "/absolute/path/boltz-experiments" \
  --poll-interval-seconds 30
# -> /absolute/path/boltz-experiments/<run-name>/results/<pres_*>/...

Payload keys are molecules, target, molecule_filters — the API body field names, not the direct CLI flag names --molecule / --target / --molecule-filters.

Always Do This

• Keep payload field names exactly as the API body names shown in references/api.md.
• Use absolute paths for the output root, payload files, and embedded target files. Do not cd into the run directory for follow-up commands; pass the same --root-dir and use absolute paths so later relative paths do not drift.
• Prefer one merged top-level payload via --input @yaml:///absolute/path/payload.yaml or @json:///absolute/path/payload.json for estimate-cost and start. Keep --idempotency-key and --workspace-id top-level; if they also appear inside --input, the top-level flags win.
• Direct object flags still work as overrides, such as --target @yaml:///absolute/path/target.yaml, --molecule-filters @json:///absolute/path/filters.json, or repeated --molecule @json:///absolute/path/mol-1.json entries. Piped YAML / JSON on stdin also works, but it must use API body field names. Never use @file:// or @./.
• Treat pocket residue indices as 0-based.
• Do not invent medicinal-chemistry filters. Only add molecule_filters if the user asks; mention the catalog as an option.
• Use the same slug as both --idempotency-key at submit and --name on download-results so re-runs resume via .boltz-run.json.
• In permission-gated agents such as Claude Code, keep each Boltz call as a top-level command that starts with boltz-api. Prefer concrete arguments over sh -c, inline environment assignments, aliases, wrapper scripts, loops, or pipelines around the boltz-api invocation unless the user already allowed that exact command form. Use --raw-output --transform id, read the printed ID, then paste that literal ID into the next download-results command.
• Prefer the agent runtime's background/non-blocking command mode for download-results. In Codex specifically, keep download-results in the foreground and set the shell tool yield to 1000 ms; Codex will return a session_id if the command is still running. Do not append & or use nohup in Codex because the tool runner may clean up shell-backgrounded descendants before .boltz-run.json is fully written.
• After the background/session starts, do not manually wait on it or run ad hoc polling loops. download-results emits JSONL progress on stderr by default; add --progress-format text --verbose only when you explicitly want human-readable logs.
• In Codex app/desktop runtimes with same-thread heartbeat automation support, schedule a heartbeat after launching download-results. The heartbeat should run boltz-api --format json download-status --name "<run-name>" --root-dir "/absolute/path/boltz-experiments" and stop once terminal. Choose cadence by molecule count: under 100 -> every 1-2 minutes; 100-1,000 -> every 5 minutes; over 1,000 -> every 15 minutes. Post only material status changes or terminal completion/failure. Poll the saved session_id with an empty write_stdin only for interactive, user-requested progress checks. Never run a manual poll loop in the current turn.
• If the current host has no heartbeat automation support, do not claim an automatic next check. Report the job ID, run name, output directory, and the command needed to check download-status.
• If detached download needs to be restarted, re-run boltz-api download-results with the same --name "<run-name>" and the same --root-dir.
• Cost is a flat $0.025 per molecule (size-independent). estimate-cost returns the authoritative total — always use it.
• Poll interval: --poll-interval-seconds 30 is a reasonable downloader default. Wall-clock time scales roughly with the number of molecules: under 100 often finishes in a few minutes, 100-1,000 may take several minutes to tens of minutes, and larger screens can take longer or hours depending on inputs and system load. Don't quote a fixed duration, and never tell the user a 10-candidate screen will take 30 minutes or hours.

Escape Hatch

• Payload reference: https://api.boltz.bio/docs/api/python/resources/small_molecule/subresources/library_screen/methods/start
• CLI flag names: boltz-api small-molecule:library-screen start --help

Read references/api.md for the molecules, target, and molecule_filters shapes, including the built-in SMARTS filters and RDKit descriptor ranges. Read references/results.md after download when ranking hits or explaining missing/filtered inputs.

Outputs

Rank from results/index.jsonl after download-results; use references/results.md for the local file layout, metric meanings, and filtered-input accounting.

Workflow

If boltz-api is missing from PATH, use boltz-cli-setup for install/update guidance before retrying. If a command reports missing or expired authentication, use boltz-cli-setup to start boltz-api auth login --device-code before retrying; do not ask permission first. If the agent host sandbox blocks boltz-api install/auth/API calls, use boltz-cli-setup to request the host sandbox bypass/escalation needed for user-wide CLI install, browser login, credential storage, temp files, or API access before retrying.

Use this skill for one defined complex, not a library workflow.

1. Normalize the inputs into entities. Each entity is {type, chain_ids, value} — note plural chain_ids (an array, even for one chain) and the field is value, not sequence:

   {"entities": [{"type": "protein", "chain_ids": ["A"], "value": "MKTAYIAKQRQISFVKSHFSRQ"}]}
   

   type is one of protein | rna | dna | ligand_smiles | ligand_ccd. Chain IDs go in entity order (A, B, C, …) unless the user specifies otherwise. Read references/api.md for per-type field variants (cyclic, modifications, ligand CCD codes, etc.) before authoring your first payload — agent guesses like sequence: or chain_id: "A" (singular) fail with unclear 400 errors.

2. If the user wants binding metrics, add a flat binding block with an explicit type field. For ligand-protein binding use:

   binding:
     type: ligand_protein_binding
     binder_chain_id: B
   

   For protein-protein binding use:

   binding:
     type: protein_protein_binding
     binder_chain_ids: [B]
   

   Do not nest the variant name under binding (for example, no binding.ligand_protein_binding object).

3. Supported optional features include constraints, bonds, modifications, model_options, and binding metrics; only add them if the user asks. Read references/api.md for exact shapes and examples.

4. Author the payload YAML or JSON, run estimate-cost, show the USD cost, wait for explicit confirmation.

5. start to submit (synchronous). Capture the ID.

6. Launch download-results with the agent runtime's background/non-blocking command facility so polling + download continue without blocking the agent session. In Claude Code, use Bash with run_in_background: true. In Codex, run download-results as a foreground shell command with yield_time_ms: 1000; if Codex returns a session_id, keep it for optional same-thread polling, but treat download-status plus the run directory as the durable source of truth. In Codex app/desktop runtimes that expose same-thread heartbeat automations, create a heartbeat that checks download-status periodically and posts a concise completion or failure update when the download reaches a terminal state. After launching the downloader, always report the job ID, run name, and output directory. Include the next check cadence if the heartbeat was created; otherwise include the download-status command.

Command Pattern

# Replace placeholders with concrete absolute paths before running.
# Use a short descriptive run name, for example: sab-<target>-<ligand>-v1

# 1. estimate
boltz-api predictions:structure-and-binding estimate-cost \
  --model boltz-2.1 \
  --input @yaml:///absolute/path/payload.yaml

# 2. confirm with user, then submit
boltz-api predictions:structure-and-binding start \
       --model boltz-2.1 \
       --idempotency-key "<run-name>" \
       --input @yaml:///absolute/path/payload.yaml \
       --raw-output --transform id

# 3. Copy the printed job ID into this command, then launch it in the agent
# runtime's background/non-blocking mode.
# Claude Code: Bash with run_in_background=true.
# Codex: foreground shell command with yield_time_ms=1000; keep the returned session_id if one is provided.
# Do not append "&" or use nohup in Codex.
boltz-api download-results \
  --id "<job-id-from-start>" --name "<run-name>" \
  --root-dir "/absolute/path/boltz-experiments" \
  --poll-interval-seconds 10
# -> /absolute/path/boltz-experiments/<run-name>/outputs/archive.tar.gz, .boltz-run.json

Always Do This

• Keep payload field names exactly as the API body names shown in references/api.md; then pass the merged payload with --input @yaml:///absolute/path/payload.yaml or @json:///absolute/path/payload.json. Never use @./payload.yaml or @file:// for object-typed payloads.
• Use absolute paths for the output root, payload files, and embedded structure files. Do not cd into the run directory for follow-up commands; pass the same --root-dir and use absolute paths so later relative paths do not drift.
• Residue indices are 0-based wherever the payload asks for residue positions (constraints, modifications, contact tokens).
• For CIF/PDB bytes embedded in --target / structure.data, use @data:///absolute/path/file.cif — it detects binary and base64-encodes. Don't use bare @path for binary data.
• Use the same slug as both --idempotency-key at submit time and --name at download time so re-runs are idempotent and resume from .boltz-run.json.
• In permission-gated agents such as Claude Code, keep each Boltz call as a top-level command that starts with boltz-api. Prefer concrete arguments over sh -c, inline environment assignments, aliases, wrapper scripts, loops, or pipelines around the boltz-api invocation unless the user already allowed that exact command form. Use --raw-output --transform id, read the printed ID, then paste that literal ID into the next download-results command.
• Prefer the agent runtime's background/non-blocking command mode for download-results. In Codex specifically, keep download-results in the foreground and set the shell tool yield to 1000 ms; Codex will return a session_id if the command is still running. Do not append & or use nohup in Codex because the tool runner may clean up shell-backgrounded descendants before .boltz-run.json is fully written.
• After the background/session starts, do not manually wait on it or run ad hoc polling loops. download-results emits JSONL progress on stderr by default; add --progress-format text --verbose only when you explicitly want human-readable logs.
• In Codex app/desktop runtimes with same-thread heartbeat automation support, schedule a heartbeat after launching download-results. The heartbeat should run boltz-api --format json download-status --name "<run-name>" --root-dir "/absolute/path/boltz-experiments" on a sensible cadence, post only material status changes or terminal completion/failure, and stop once terminal. Poll the saved session_id with an empty write_stdin only for interactive, user-requested progress checks. Do not loop retrieve yourself.
• If the current host has no heartbeat automation support, do not claim an automatic next check. Report the job ID, run name, output directory, and the command needed to check download-status.
• If detached download needs to be restarted, re-run boltz-api download-results with the same --name "<run-name>" and the same --root-dir.
• Poll interval: keep --poll-interval-seconds 10 for SAB — predictions usually finish in under a few minutes.
• Cost: there is no published per-unit rate to cite for SAB — run estimate-cost and state only the figure it returns. Don't estimate or comment on cost.

Escape Hatch

For anything not covered in references/api.md:

• Payload reference: https://api.boltz.bio/docs/api/python/resources/predictions/subresources/structure_and_binding/methods/start
• CLI flag names: boltz-api predictions:structure-and-binding start --help (schema details aren't there — just flag names and types)

Read references/api.md for entity shapes, binding variants, bonds, constraints, model options, and input examples. Read references/results.md when summarizing downloaded outputs, metrics, or validation quirks.

Outputs

Summarize metrics.json and point the user at the downloaded CIF path. Read references/results.md for the local layout, nested metrics, binding metric variants, and SAB validation quirks.

SAB 400 validation quirk

If the server rejects a payload with only {"code":"VALIDATION_ERROR","message":"Request validation failed"}, inspect entities, binding, and constraints; read references/results.md for details.

Box Content API

Overview

Implement Box content workflows in application code. Reuse the repository's existing auth and HTTP or SDK stack whenever possible, identify the acting Box identity before coding, and make the smallest end-to-end path work before layering on sharing, metadata, webhooks, or AI.

Route The Request

Workflow

Follow these steps in order when coding against Box.

1. Inspect the repository for existing Box auth, SDK or HTTP client, env vars, webhook handlers, Box ID persistence, and tests.
2. Determine the acting identity before choosing endpoints: connected user, enterprise service account, app user, or platform-provided token.
3. Identify the primary Box object and choose the matching reference from the routing table above.
4. Confirm whether the task changes access or data exposure. Shared links, collaborations, auth changes, large-scale downloads, and broad AI retrieval all need explicit user confirmation before widening access or scope.
5. Read only the matching reference files:
   • Auth setup, actor selection, SDK vs REST: references/auth-and-setup.md
   • Box CLI local verification: references/box-cli.md
   • Workflow router: references/workflows.md
   • Content operations: references/content-workflows.md
   • Bulk file organization, batch moves, folder restructuring: references/bulk-operations.md
   • Webhooks and events: references/webhooks-and-events.md
   • AI and retrieval: references/ai-and-retrieval.md
   • Debugging and failure modes: references/troubleshooting.md
6. Implement the smallest end-to-end flow that proves the integration works.
7. Add a runnable verification step. Prefer the repository's tests first; otherwise use scripts/box_cli_smoke.py when Box CLI is available and authenticated, and scripts/box_rest.py as a fallback.
8. Summarize the deliverable with auth context, Box IDs, env vars or config, and the exact verification command or test.

Guardrails

• Preserve the existing Box auth model unless the user explicitly asks to change it.
• Check the current official Box docs before introducing a new auth path, changing auth scope, or changing Box AI behavior.
• Prefer an official Box SDK when the codebase already uses one or the target language has a maintained SDK. Otherwise use direct REST calls with explicit request and response handling.
• Keep access tokens, client secrets, private keys, and webhook secrets in env vars or the project's secret manager.
• Distinguish file IDs, folder IDs, shared links, metadata template identifiers, and collaboration IDs.
• Treat shared links, collaborations, and metadata writes as permission-sensitive changes. Confirm audience, scope, and least privilege before coding or applying them.
• Require explicit confirmation before widening external access, switching the acting identity, or retrieving more document content than the task truly needs.
• When a task requires understanding document content — classification, extraction, categorization — use Box AI (Q&A, extract) as the first method attempted. Box AI operates server-side and does not require downloading file bodies. Fall back to metadata inspection, previews, or local analysis only if Box AI is unavailable, not authorized, or returns an error on the first attempt.
• Pace Box AI calls at least 1–2 seconds apart. For content-based classification of many files, classify a small sample first to validate the prompt and discover whether cheaper signals (filename, extension, metadata) can sort the remaining files without additional AI calls.
• Avoid downloading file bodies or routing content through external AI pipelines when Box-native methods (Box AI, search, metadata, previews) can answer the question server-side.
• Connected Box tool availability can vary by account. If a Box MCP call returns Tool <name> not found, treat that tool as unavailable for the rest of the current task. Do not retry it with different arguments or call it again later; switch to an available fallback.
• For connected Box app or MCP text reads, use get_file_content or Deep Research fetch only when the file is likely to have markdown or extracted-text content. If Box says markdown or text representation is unavailable, do not retry the same text read; switch to preview, metadata, or the next scoped fallback.
• For connected Box previews, avoid get_file_preview for files known to exceed 3 MB. Reuse size from existing search, listing, or details results when it is already available.
• Request only the fields the application actually needs, and persist returned Box IDs instead of reconstructing paths later.
• Run Box CLI commands strictly one at a time. The CLI does not support concurrent invocations and parallel calls cause auth conflicts and dropped operations. For bulk work (organizing, batch moves, batch metadata), default to REST over CLI.
• Make webhook and event consumers idempotent. Box delivery and retry paths can produce duplicates.
• Keep AI retrieval narrow for search and Q&A tasks. Search and filter first, then retrieve only the files needed for the answer. This does not apply to Box AI classification — when classifying documents, Box AI should be tried first per the content-understanding guardrail above.
• Do not use box configure:environments:get --current as a routine auth check because it can print sensitive environment details.

Verification

• Prefer the repository's existing tests, scripts, or app flows when they already cover the changed Box behavior.
• If no better verification path exists, prefer scripts/box_cli_smoke.py when box is installed and authenticated. Fall back to scripts/box_rest.py with BOX_ACCESS_TOKEN when CLI auth is unavailable or the task specifically needs direct bearer-token verification.
• Confirm CLI auth with box users:get me --json or scripts/box_cli_smoke.py check-auth.
• Verify mutations with a read-after-write call using the same actor, and record the object ID.
• For webhooks, test the minimal happy path, duplicate delivery, and signature failure handling.
• For AI flows, test retrieval quality separately from answer formatting.

Example smoke checks:

python3 scripts/box_cli_smoke.py check-auth
python3 scripts/box_cli_smoke.py get-folder 0 --fields id name item_collection
python3 scripts/box_cli_smoke.py list-folder-items 0 --max-items 20
python3 scripts/box_cli_smoke.py search "invoice" --limit 10
python3 scripts/box_rest.py get-item --item-type folder --item-id 0 --fields id name item_collection

Deliverable

The final answer should include:

• Acting auth context used for the change
• Box object type and IDs touched
• Env vars, secrets, or config expected by the integration
• Files or endpoints added or changed
• Exact verification command, script, or test path
• Any permission-sensitive assumptions that still need confirmation

References

• references/auth-and-setup.md: auth path selection, SDK vs REST choice, existing-codebase inspection, and current Box doc anchors
• references/box-cli.md: CLI-first local auth, smoke-test commands, and safe verification patterns
• references/workflows.md: quick workflow router when the task is ambiguous
• references/content-workflows.md: uploads, folders, listings, downloads, shared links, collaborations, metadata, and file moves
• references/bulk-operations.md: organizing files at scale, batch moves, folder hierarchy creation, serial execution, and rate-limit handling
• references/webhooks-and-events.md: webhook setup, event-feed usage, idempotency, and verification
• references/ai-and-retrieval.md: search-first retrieval, Box AI usage, and external AI guardrails
• references/troubleshooting.md: common failure modes and a debugging checklist
• examples/box-content-api-prompts.md: example prompts for realistic use cases

BrightHire

Use BrightHire tools when the user asks for information stored in BrightHire or asks Codex to reason about interview intelligence from BrightHire data.

Good fits include:

• Finding calls, interviews, candidates, roles, interviewers, scorecards, or transcripts.
• Summarizing interview context for a hiring decision.
• Looking up evidence from BrightHire before answering questions about a candidate or role.
• Comparing interview feedback, themes, concerns, or evidence across calls.

Before using BrightHire data, identify what entity the user means: candidate, role, organization, call, interviewer, or date range. If the request is ambiguous and multiple BrightHire records may match, ask a concise clarifying question or search broadly and present the likely matches.

Treat BrightHire content as sensitive customer data. Do not expose more candidate, interviewer, or organization information than the user asked for. Prefer concise summaries with links or identifiers when available, and avoid copying long transcript passages unless the user explicitly needs exact evidence.

If a BrightHire tool fails because authentication is missing or expired, tell the user they need to connect or re-authenticate the BrightHire plugin. Do not ask for raw API tokens in chat.

iOS App Intents

Overview

Expose the smallest useful action and entity surface to the system. Start with the verbs and objects people would actually want outside the app, then implement a narrow App Intents layer that can deep-link or hand off cleanly into the main app when needed.

Read these references as needed:

• references/first-pass-checklist.md for choosing the first intent and entity surface
• references/example-patterns.md for concrete example shapes to copy and adapt
• references/code-templates.md for generalized App Intents code templates
• references/system-surfaces.md for how to think about Shortcuts, Siri, Spotlight, widgets, and other system entry points

Core workflow

1) Start with actions, not screens

• Identify the 1-3 highest-value actions that should work outside the app UI.
• Prefer verbs like compose, open, find, filter, continue, inspect, or start.
• Do not mirror the entire app navigation tree as intents.

2) Define a small entity surface

• Add AppEntity types only for the objects the system needs to understand or route.
• Keep the entity shape narrower than the app's persistence model.
• Add EntityQuery or other query types only where disambiguation or suggestions are genuinely useful.

3) Decide whether the action completes in place or opens the app

• Use non-opening intents for actions that can complete directly from the system surface.
• Use openAppWhenRun or open-style intents when the user should land in a specific in-app workflow.
• When the app must react inside the main scene, add one clear runtime handoff path instead of scattering ad hoc routing logic.
• If the action can work in both modes, consider shipping both an inline version and an open-app version rather than forcing one compromise.

4) Make the actions discoverable

• Add AppShortcutsProvider entries for the first set of high-value intents.
• Choose titles, phrases, and symbols that make sense in Shortcuts, Siri, and Spotlight.
• Keep shortcut phrases direct and task-oriented.
• Reuse the same action model for widgets and controls when a widget configuration or intent-driven control already needs the same parameters.

5) Validate the runtime handoff

• Build the app and confirm the intents target compiles cleanly.
• Verify the app opens or routes to the expected place when an intent runs.
• Summarize which actions are now exposed, which entities back them, and how the app handles invocation.

Strong defaults

• Prefer a dedicated intents target or module for the system-facing layer.
• Keep intent types thin; business logic should stay in app services or domain models.
• Keep app entities small and display-friendly.
• Use AppEnum for fixed app choices such as tabs, modes, or visibility levels before reaching for a full entity type.
• Prefer one predictable app-intent routing surface in the main app scene or root router.
• Treat App Intents as system integration infrastructure, not only as a Shortcuts feature.

Anti-patterns

• Exposing every screen or tab as its own intent without a real user value.
• Mirroring the entire model graph as AppEntity types.
• Hiding runtime handoff in global side effects with no clear app entry path.
• Adding App Shortcuts with vague phrases or generic titles.
• Treating the first App Intents pass as a broad taxonomy project instead of a small useful release.

Notes

• Apple documentation to use as primary references:
  • https://developer.apple.com/documentation/appintents/making-actions-and-content-discoverable-and-widely-available
  • https://developer.apple.com/documentation/appintents/creating-your-first-app-intent
  • https://developer.apple.com/documentation/appintents/adopting-app-intents-to-support-system-experiences
• In addition to the links above, use web search to consult current Apple Developer documentation when App Intents APIs or platform behavior may have changed.
• A good first pass often includes one open-app intent, one action intent, one or two entity types, and a small AppShortcutsProvider.
• Good example families to cover are:
  • open a destination or editor in the app
  • perform a lightweight action inline without opening the app
  • choose from a fixed enum such as a tab or mode
  • resolve one or more entities through EntityQuery
  • power widget configuration or controls from the same entity surface

iOS Debugger Agent

Overview

Use XcodeBuildMCP to build and run the current project scheme on a booted iOS simulator, interact with the UI, and capture logs. Prefer the MCP tools for simulator control, logs, and view inspection.

Core Workflow

Follow this sequence unless the user asks for a narrower action.

1) Discover the booted simulator

• Call mcp__XcodeBuildMCP__list_sims and select the simulator with state Booted.
• If none are booted, ask the user to boot one (do not boot automatically unless asked).

2) Set session defaults

• Call mcp__XcodeBuildMCP__session-set-defaults with:
  • projectPath or workspacePath (whichever the repo uses)
  • scheme for the current app
  • simulatorId from the booted device
  • Optional: configuration: "Debug", useLatestOS: true

3) Build + run (when requested)

• Call mcp__XcodeBuildMCP__build_run_sim.
• If the build fails, check the error output and retry (optionally with preferXcodebuild: true) or escalate to the user before attempting any UI interaction.
• After a successful build, verify the app launched by calling mcp__XcodeBuildMCP__describe_ui or mcp__XcodeBuildMCP__screenshot before proceeding to UI interaction.
• If the app is already built and only launch is requested, use mcp__XcodeBuildMCP__launch_app_sim.
• If bundle id is unknown:
  1. mcp__XcodeBuildMCP__get_sim_app_path
  2. mcp__XcodeBuildMCP__get_app_bundle_id

UI Interaction & Debugging

Use these when asked to inspect or interact with the running app.

• Describe UI: mcp__XcodeBuildMCP__describe_ui before tapping or swiping.
• Tap: mcp__XcodeBuildMCP__tap (prefer id or label; use coordinates only if needed).
• Type: mcp__XcodeBuildMCP__type_text after focusing a field.
• Gestures: mcp__XcodeBuildMCP__gesture for common scrolls and edge swipes.
• Screenshot: mcp__XcodeBuildMCP__screenshot for visual confirmation.

Logs & Console Output

• Start logs: mcp__XcodeBuildMCP__start_sim_log_cap with the app bundle id.
• Stop logs: mcp__XcodeBuildMCP__stop_sim_log_cap and summarize important lines.
• For console output, set captureConsole: true and relaunch if required.

Troubleshooting

• If build fails, ask whether to retry with preferXcodebuild: true.
• If the wrong app launches, confirm the scheme and bundle id.
• If UI elements are not hittable, re-run describe_ui after layout changes.

iOS ETTrace Performance

Use this skill to capture a focused, symbolicated ETTrace profile from an iOS simulator app. Pair it with ../ios-debugger-agent/SKILL.md when the task also needs simulator build, install, launch, UI driving, logs, or screenshots.

Core Workflow

1. Pick one focused flow and write down the expected start and stop points.
2. Build the exact simulator app that will be installed and profiled.
3. Temporarily link ETTrace into that app target for simulator/debug profiling.
4. Collect UUID-matched dSYMs for the app executable and embedded dynamic frameworks.
5. Capture one launch or runtime trace.
6. Preserve the processed flamegraph JSON immediately after the run.
7. Analyze only the processed JSON and report the flow, artifacts, hotspots, and caveats.

Avoid broad "use the app for a while" captures. One trace should correspond to one user-visible flow.

Setup

Use a writable run folder for each profiling session:

if [ -z "${RUN_DIR:-}" ]; then
  RUN_DIR="$(mktemp -d "${TMPDIR:-/tmp}/codex-ios-ettrace.XXXXXX")"
fi
mkdir -p "$RUN_DIR"

Install the ETTrace runner CLI if it is not already available:

brew install emergetools/homebrew-tap/ettrace

ettrace is the host-side macOS runner. The app must also link an ETTrace.xcframework for the iOS Simulator architecture. This workflow is validated for ETTrace v1.1.0 processed output_<thread>.json files with top-level nodes.

Link ETTrace Into The App

Wire ETTrace into the exact app target being profiled. Keep the integration in a clearly temporary patch and remove it when the profiling task is done unless the user explicitly asks to keep it.

Preferred options:

• Reuse an existing simulator-compatible ETTrace.xcframework if the repo already vendors one.
• If none exists, build a simulator-only copy into RUN_DIR from the upstream ETTrace package.
• Link the framework directly into the app target, not only into tests, resources, data files, or a nested launcher target.
• Confirm launch logs print Starting ETTrace.
• Profile only one ETTrace-instrumented simulator app at a time because simulator mode listens on a fixed localhost port.

Build a simulator framework when needed:

ETTRACE_TAG="${ETTRACE_TAG:-v1.1.0}" # Override to match the installed runner when Homebrew updates.
ETTRACE_SRC="$RUN_DIR/ETTrace-src"
if [ ! -d "$ETTRACE_SRC" ]; then
  git clone --depth 1 --branch "$ETTRACE_TAG" https://github.com/EmergeTools/ETTrace "$ETTRACE_SRC"
fi

rm -rf "$RUN_DIR/ETTrace-iphonesimulator.xcarchive" "$RUN_DIR/ETTrace.xcframework"
pushd "$ETTRACE_SRC" >/dev/null
xcodebuild archive \
  -scheme ETTrace \
  -archivePath "$RUN_DIR/ETTrace-iphonesimulator.xcarchive" \
  -sdk iphonesimulator \
  -destination 'generic/platform=iOS Simulator' \
  BUILD_LIBRARY_FOR_DISTRIBUTION=YES \
  INSTALL_PATH='Library/Frameworks' \
  SKIP_INSTALL=NO \
  CLANG_CXX_LANGUAGE_STANDARD=c++17

xcodebuild -create-xcframework \
  -framework "$RUN_DIR/ETTrace-iphonesimulator.xcarchive/Products/Library/Frameworks/ETTrace.framework" \
  -output "$RUN_DIR/ETTrace.xcframework"
popd >/dev/null

For Bazel apps, a temporary import usually looks like:

load("@rules_apple//apple:apple.bzl", "apple_dynamic_xcframework_import")

package(default_visibility = ["//visibility:public"])

apple_dynamic_xcframework_import(
    name = "ETTrace",
    xcframework_imports = glob(["ETTrace.xcframework/**"]),
)

For Xcode projects, temporarily add the simulator ETTrace.xcframework to the app target's Link Binary With Libraries / Embed Frameworks phases for the debug simulator build you are profiling, then remove that wiring after profiling.

Symbolication Gate

Do not draw conclusions from an unsymbolicated flamegraph. Before every capture, prepare a dSYM folder that includes the app dSYM and any embedded first-party dynamic framework dSYMs.

Collect dSYMs after the final build that produced the installed app:

SKILL_DIR="<absolute path to this loaded skill folder>"
APP="<path-to-built-simulator-App.app>"
DSYMS="$RUN_DIR/dsyms"

"$SKILL_DIR/scripts/collect_ios_dsyms.sh" \
  --app "$APP" \
  --out-dir "$DSYMS" \
  --search-root "$(dirname "$APP")" \
  --search-root "$PWD" \
  --extra-dsym "$RUN_DIR/ETTrace-iphonesimulator.xcarchive/dSYMs/ETTrace.framework.dSYM"

Add --require-framework <FrameworkName> for app-owned dynamic frameworks that must symbolicate; use --require-all-frameworks only when every embedded framework is app-owned or expected to have symbols. If the helper reports a missing required app or framework dSYM, rebuild the exact simulator app with dSYM generation before tracing, or add the build output directory that contains those dSYMs as another --search-root.

Verify important UUIDs before tracing when the report looks suspicious:

dwarfdump --uuid "$APP/$(/usr/libexec/PlistBuddy -c 'Print :CFBundleExecutable' "$APP/Info.plist")"
find "$DSYMS" -maxdepth 1 -type d -name '*.dSYM' -print -exec dwarfdump --uuid {} \;

After ETTrace exits, read its symbolication summary. Treat meaningful first-party "have library but no symbol" lines as a failed trace unless they are tiny noise. Unsymbolicated system-framework or ETTrace internal buckets are usually acceptable.

Capture

For launch traces:

cd "$RUN_DIR"
CAPTURE_MARKER="$RUN_DIR/.ettrace-capture-start"
: > "$CAPTURE_MARKER"
find "$RUN_DIR" -maxdepth 1 \( -name 'output.json' -o -name 'output_*.json' \) -delete
ettrace --simulator --launch --verbose --dsyms "$DSYMS"

Use --launch only when measuring startup or first render. The first launch connection can force quit the app; relaunch from the simulator home screen rather than Xcode if prompted. For first-launch-after-install traces, temporarily set ETTraceRunAtStartup=YES in the app Info.plist, then run ettrace --simulator and launch from the home screen.

For runtime flow traces:

cd "$RUN_DIR"
CAPTURE_MARKER="$RUN_DIR/.ettrace-capture-start"
: > "$CAPTURE_MARKER"
find "$RUN_DIR" -maxdepth 1 \( -name 'output.json' -o -name 'output_*.json' \) -delete
ettrace --simulator --verbose --dsyms "$DSYMS"

Start from a stable screen, start ETTrace, perform exactly one focused flow, wait until visible work is complete, then stop the runner. For wider attribution, add --multi-thread; otherwise start with the main thread.

In Codex, run ettrace with a TTY and answer prompts with write_stdin. Without a TTY, the runner can exit without a useful trace.

Preserve Outputs

The next ETTrace run can overwrite processed flamegraph files, so preserve fresh output_<thread-id>.json files immediately. Do not analyze a saved output.json; ETTrace also serves a viewer route with that name, and raw emerge-output/output.json files are not the processed flamegraph artifacts this workflow expects.

PRESERVED_DIR="$(mktemp -d "$RUN_DIR/run-$(date +%Y%m%d-%H%M%S).XXXXXX")"
: > "$PRESERVED_DIR/summary.txt"
if [ ! -e "$CAPTURE_MARKER" ]; then
  echo "error: capture marker missing; start a fresh ETTrace capture before preserving outputs" >&2
  exit 1
fi
find "$RUN_DIR" -maxdepth 1 -name 'output_*.json' -newer "$CAPTURE_MARKER" -print | while IFS= read -r json; do
  preserved="$PRESERVED_DIR/${json##*/}"
  cp "$json" "$preserved"
  {
    echo "## ${preserved##*/}"
    python3 "$SKILL_DIR/scripts/analyze_flamegraph_json.py" "$preserved"
  } >> "$PRESERVED_DIR/summary.txt"
done
if [ ! -s "$PRESERVED_DIR/summary.txt" ]; then
  echo "error: no fresh processed ETTrace output JSON found in $RUN_DIR" >&2
  exit 1
fi

Analyze only processed output_*.json files in RUN_DIR. Ignore output.json and raw emerge-output/output.json files unless debugging ETTrace itself. If the analyzer rejects the JSON shape, capture again with the Homebrew ETTrace runner and matching app-side ETTrace.xcframework tag instead of trying to interpret the rejected file.

Read The Profile

Start from run-*/summary.txt, then inspect processed JSON directly if needed.

Report:

• exact flow, app build, simulator model/runtime, and run count
• processed flamegraph JSON paths
• top active leaves and inclusive first-party stacks with sample weights or percentages
• whether symbols were complete for app-owned binaries
• caveats such as first-run setup, simulator-only cost, network variance, or low sample count
• before/after deltas only when the same flow was captured with comparable setup

Cleanup

Remove temporary ETTrace app wiring when profiling is complete unless the user asked to keep it. Keep or discard run artifacts based on the active task.

iOS Memgraph Leaks

Use this skill to prove iOS leaks from a live simulator process or an existing .memgraph. Pair it with ../ios-debugger-agent/SKILL.md when the task also needs simulator build, install, launch, UI driving, logs, or screenshots.

Core Workflow

1. Build, launch, and drive the exact flow that should release objects.
2. Capture a memgraph from the running simulator process with scripts/capture_sim_memgraph.sh.
3. Summarize leaks with scripts/summarize_memgraph_leaks.py.
4. For each app-owned leaked type, inspect ownership with leaks --traceTree=<address> <file.memgraph> and grouped leak evidence.
5. Make the smallest root-cause patch, then recapture the same flow on the same simulator when possible.
6. Report proof: before/after leak counts, disappeared root types, remaining leaks, memgraph paths, and test/build results.

Do not claim a leak fix from a smaller memgraph alone. A credible fix explains the ownership path that kept the object alive and shows that the same path or type disappears after the patch.

Capture

Prefer capturing from the simulator already used for the reproduction. Resolve the simulator UDID and app bundle identifier, then capture the running app:

SKILL_DIR="<absolute path to this loaded skill folder>"
SIM="<simulator-udid>"
BUNDLE_ID="<app.bundle.identifier>"
MEMGRAPH_DIR="$(mktemp -d "${TMPDIR:-/tmp}/codex-ios-memgraph.XXXXXX")"

"$SKILL_DIR/scripts/capture_sim_memgraph.sh" \
  --udid "$SIM" \
  --bundle-id "$BUNDLE_ID" \
  --out-dir "$MEMGRAPH_DIR"

Do not derive SKILL_DIR from the target app repo's pwd; installed plugins usually live outside the app being debugged. Store captures in a run-specific temp or user-chosen folder, not under SKILL_DIR.

If the process cannot be found, confirm the bundle identifier and use xcrun simctl spawn "$SIM" launchctl list to inspect running labels.

Summarize

Summarize an existing memgraph:

"$SKILL_DIR/scripts/summarize_memgraph_leaks.py" \
  /path/to/app.memgraph \
  --trace-limit 5 \
  --out /path/to/leak-summary.md

Use --trace-limit sparingly. Trace trees are useful root-cause evidence, but large memgraphs can produce noisy output. If a trace tree says Found 0 roots referencing, treat it as an unreachable/self-retained leak candidate and use the summary's grouped leak tree or leaks --groupByType <file.memgraph> to identify the retained fields and payload chain.

Root Cause Rules

• Identify the first app-owned leaked type in the leak output or trace.
• Determine the intended lifetime: process, session, account, view, request, or task.
• Treat lazy or deferred allocation as a scope reduction, not a leak fix, unless the original eager allocation itself violated the intended lifetime.
• Prove retain-cycle claims with either a traceTree ownership path or an isolated reproduction.
• For unreachable/self-cycle leaks, traceTree may have no root path; use leaks --groupByType plus source verification to find the self-retaining edge.
• Do not claim success just because total leak count went down; prove the specific type or path disappeared.
• Separate real root-cause branches from candidate/noise branches.
• Prefer deleting the retaining edge over adding broad cleanup code.

Report

A useful leak report includes:

• the exact flow and simulator/app build
• the memgraph and summary paths
• app-owned leaked types and counts
• at least one ownership path, or grouped leak tree evidence when the object is unreachable from roots
• the smallest proposed or applied retaining-edge fix
• before/after evidence when a fix was made

If the memgraph shows only framework/runtime noise, say that and recommend the next narrower capture rather than inventing an app leak.

iOS Simulator Browser

Browser Workflow

1. Obtain an explicit Simulator UDID from the existing iOS build/run workflow or from xcrun simctl list devices available.

2. Start serve-sim in a long-running terminal pinned to that simulator. Clean up any tracked stale helper for this simulator before starting, and install a trap so the helper is cleaned up when this terminal exits:

   SIM="<simulator-udid>"
   cleanup_serve_sim() {
     npx --yes serve-sim@latest --kill "$SIM" >/dev/null 2>&1 || true
   }
   trap cleanup_serve_sim EXIT INT TERM HUP
   cleanup_serve_sim
   npx --yes serve-sim@latest "$SIM"
   

3. Open the exact local preview URL printed by serve-sim in the Codex in-app browser.

4. Verify that a real frame is rendering before reporting success. A loaded page alone is not proof that the simulator stream is healthy.

• Keep the terminal alive while the browser mirror is in use. When finished, stop the terminal and wait for it to exit so the trap runs.
• If the terminal disappeared or did not exit cleanly, run npx --yes serve-sim@latest --kill "$SIM" before starting another mirror for that simulator.
• Never run an unscoped serve-sim --kill; another thread may own a different simulator mirror.

SwiftUI Preview Workflow

Use the bundled launcher when the requested previews live in an importable Swift package. Point it at the package manifest and select the target whose previews should be displayed. It generates a disposable host project outside the user's source tree, installs and launches that host in Simulator, and watches the package for edits.

node <skill-root>/scripts/swiftui-preview-browser.mjs \
  /absolute/path/to/Package.swift \
  --package-target "<target>" \
  --device "<simulator-udid>"

• Watch mode is enabled by default. On a Swift package source edit, the launcher rebuilds a generated dylib and hot-swaps it into the running host without relaunching the app.
• The generated host shows every preview variant discovered in the selected Swift Package target with in-simulator page controls. To show a subset instead, pass --preview-filter <regex[, ...]>; it matches display names and code identifiers such as StatusRowView_Previews.
• Once the launcher prints the selected Simulator UDID, start serve-sim for that same UDID and open its printed URL in the in-app browser.

Support Boundary

• Support Swift Package-backed PreviewProvider and #Preview declarations through the generated host.
• Do not edit the user's .xcodeproj, .xcworkspace, Package.swift, schemes, or build settings to force preview support.

Proof

For browser or preview QA, capture a browser screenshot showing the simulator frame. For hot reload QA, also report the launcher's hot reloaded package preview ... in pid ... output and show the changed frame after editing.

SwiftUI Liquid Glass

Overview

Use this skill to build or review SwiftUI features that fully align with the iOS 26+ Liquid Glass API. Prioritize native APIs (glassEffect, GlassEffectContainer, glass button styles) and Apple design guidance. Keep usage consistent, interactive where needed, and performance aware.

Workflow Decision Tree

Choose the path that matches the request:

1) Review an existing feature

• Inspect where Liquid Glass should be used and where it should not.
• Verify correct modifier order, shape usage, and container placement.
• Check for iOS 26+ availability handling and sensible fallbacks.

2) Improve a feature using Liquid Glass

• Identify target components for glass treatment (surfaces, chips, buttons, cards).
• Refactor to use GlassEffectContainer where multiple glass elements appear.
• Introduce interactive glass only for tappable or focusable elements.

3) Implement a new feature using Liquid Glass

• Design the glass surfaces and interactions first (shape, prominence, grouping).
• Add glass modifiers after layout/appearance modifiers.
• Add morphing transitions only when the view hierarchy changes with animation.

Core Guidelines

• Prefer native Liquid Glass APIs over custom blurs.
• Use GlassEffectContainer when multiple glass elements coexist.
• Apply .glassEffect(...) after layout and visual modifiers.
• Use .interactive() for elements that respond to touch/pointer.
• Keep shapes consistent across related elements for a cohesive look.
• Gate with #available(iOS 26, *) and provide a non-glass fallback.

Review Checklist

• Availability: #available(iOS 26, *) present with fallback UI.
• Composition: Multiple glass views wrapped in GlassEffectContainer.
• Modifier order: glassEffect applied after layout/appearance modifiers.
• Interactivity: interactive() only where user interaction exists.
• Transitions: glassEffectID used with @Namespace for morphing.
• Consistency: Shapes, tinting, and spacing align across the feature.

Implementation Checklist

• Define target elements and desired glass prominence.
• Wrap grouped glass elements in GlassEffectContainer and tune spacing.
• Use .glassEffect(.regular.tint(...).interactive(), in: .rect(cornerRadius: ...)) as needed.
• Use .buttonStyle(.glass) / .buttonStyle(.glassProminent) for actions.
• Add morphing transitions with glassEffectID when hierarchy changes.
• Provide fallback materials and visuals for earlier iOS versions.

Quick Snippets

Use these patterns directly and tailor shapes/tints/spacing.

if #available(iOS 26, *) {
    Text("Hello")
        .padding()
        .glassEffect(.regular.interactive(), in: .rect(cornerRadius: 16))
} else {
    Text("Hello")
        .padding()
        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
}

GlassEffectContainer(spacing: 24) {
    HStack(spacing: 24) {
        Image(systemName: "scribble.variable")
            .frame(width: 72, height: 72)
            .font(.system(size: 32))
            .glassEffect()
        Image(systemName: "eraser.fill")
            .frame(width: 72, height: 72)
            .font(.system(size: 32))
            .glassEffect()
    }
}

Button("Confirm") { }
    .buttonStyle(.glassProminent)

Resources

• Reference guide: references/liquid-glass.md
• Prefer Apple docs for up-to-date API details, and use web search to consult current Apple Developer documentation in addition to the references above.

SwiftUI Performance Audit

Quick start

Use this skill to diagnose SwiftUI performance issues from code first, then request profiling evidence when code review alone cannot explain the symptoms.

Workflow

1. Classify the symptom: slow rendering, janky scrolling, high CPU, memory growth, hangs, or excessive view updates.
2. If code is available, start with a code-first review using references/code-smells.md.
3. If code is not available, ask for the smallest useful slice: target view, data flow, reproduction steps, and deployment target.
4. If code review is inconclusive or runtime evidence is required, guide the user through profiling with references/profiling-intake.md.
5. Summarize likely causes, evidence, remediation, and validation steps using references/report-template.md.

1. Intake

Collect:

• Target view or feature code.
• Symptoms and exact reproduction steps.
• Data flow: @State, @Binding, environment dependencies, and observable models.
• Whether the issue shows up on device or simulator, and whether it was observed in Debug or Release.

Ask the user to classify the issue if possible:

• CPU spike or battery drain
• Janky scrolling or dropped frames
• High memory or image pressure
• Hangs or unresponsive interactions
• Excessive or unexpectedly broad view updates

For the full profiling intake checklist, read references/profiling-intake.md.

2. Code-First Review

Focus on:

• Invalidation storms from broad observation or environment reads.
• Unstable identity in lists and ForEach.
• Heavy derived work in body or view builders.
• Layout thrash from complex hierarchies, GeometryReader, or preference chains.
• Large image decode or resize work on the main thread.
• Animation or transition work applied too broadly.

Use references/code-smells.md for the detailed smell catalog and fix guidance.

Provide:

• Likely root causes with code references.
• Suggested fixes and refactors.
• If needed, a minimal repro or instrumentation suggestion.

3. Guide the User to Profile

If code review does not explain the issue, ask for runtime evidence:

• A trace export or screenshots of the SwiftUI timeline and Time Profiler call tree.
• Device/OS/build configuration.
• The exact interaction being profiled.
• Before/after metrics if the user is comparing a change.

Use references/profiling-intake.md for the exact checklist and collection steps.

4. Analyze and Diagnose

• Map the evidence to the most likely category: invalidation, identity churn, layout thrash, main-thread work, image cost, or animation cost.
• Prioritize problems by impact, not by how easy they are to explain.
• Distinguish code-level suspicion from trace-backed evidence.
• Call out when profiling is still insufficient and what additional evidence would reduce uncertainty.

5. Remediate

Apply targeted fixes:

• Narrow state scope and reduce broad observation fan-out.
• Stabilize identities for ForEach and lists.
• Move heavy work out of body into derived state updated from inputs, model-layer precomputation, memoized helpers, or background preprocessing. Use @State only for view-owned state, not as an ad hoc cache for arbitrary computation.
• Use equatable() only when equality is cheaper than recomputing the subtree and the inputs are truly value-semantic.
• Downsample images before rendering.
• Reduce layout complexity or use fixed sizing where possible.

Use references/code-smells.md for examples, Observation-specific fan-out guidance, and remediation patterns.

6. Verify

Ask the user to re-run the same capture and compare with baseline metrics. Summarize the delta (CPU, frame drops, memory peak) if provided.

Outputs

Provide:

• A short metrics table (before/after if available).
• Top issues (ordered by impact).
• Proposed fixes with estimated effort.

Use references/report-template.md when formatting the final audit.

References

• Profiling intake and collection checklist: references/profiling-intake.md
• Common code smells and remediation patterns: references/code-smells.md
• Audit output template: references/report-template.md
• Add Apple documentation and WWDC resources under references/ as they are supplied by the user.
• Optimizing SwiftUI performance with Instruments: references/optimizing-swiftui-performance-instruments.md
• Understanding and improving SwiftUI performance: references/understanding-improving-swiftui-performance.md
• Understanding hangs in your app: references/understanding-hangs-in-your-app.md
• Demystify SwiftUI performance (WWDC23): references/demystify-swiftui-performance-wwdc23.md
• In addition to the references above, use web search to consult current Apple Developer documentation when Instruments workflows or SwiftUI performance guidance may have changed.

SwiftUI UI Patterns

Quick start

Choose a track based on your goal:

Existing project

• Identify the feature or screen and the primary interaction model (list, detail, editor, settings, tabbed).
• Find a nearby example in the repo with rg "TabView\(" or similar, then read the closest SwiftUI view.
• Apply local conventions: prefer SwiftUI-native state, keep state local when possible, and use environment injection for shared dependencies.
• Choose the relevant component reference from references/components-index.md and follow its guidance.
• If the interaction reveals secondary content by dragging or scrolling the primary content away, read references/scroll-reveal.md before implementing gestures manually.
• Build the view with small, focused subviews and SwiftUI-native data flow.

New project scaffolding

• Start with references/app-wiring.md to wire TabView + NavigationStack + sheets.
• Add a minimal AppTab and RouterPath based on the provided skeletons.
• Choose the next component reference based on the UI you need first (TabView, NavigationStack, Sheets).
• Expand the route and sheet enums as new screens are added.

General rules to follow

• Use modern SwiftUI state (@State, @Binding, @Observable, @Environment) and avoid unnecessary view models.
• If the deployment target includes iOS 16 or earlier and cannot use the Observation API introduced in iOS 17, fall back to ObservableObject with @StateObject for root ownership, @ObservedObject for injected observation, and @EnvironmentObject only for truly shared app-level state.
• Prefer composition; keep views small and focused.
• Use async/await with .task and explicit loading/error states. For restart, cancellation, and debouncing guidance, read references/async-state.md.
• Keep shared app services in @Environment, but prefer explicit initializer injection for feature-local dependencies and models. For root wiring patterns, read references/app-wiring.md.
• Prefer the newest SwiftUI API that fits the deployment target and call out the minimum OS whenever a pattern depends on it.
• Maintain existing legacy patterns only when editing legacy files.
• Follow the project's formatter and style guide.
• Sheets: Prefer .sheet(item:) over .sheet(isPresented:) when state represents a selected model. Avoid if let inside a sheet body. Sheets should own their actions and call dismiss() internally instead of forwarding onCancel/onConfirm closures.
• Scroll-driven reveals: Prefer deriving a normalized progress value from scroll offset and driving the visual state from that single source of truth. Avoid parallel gesture state machines unless scroll alone cannot express the interaction.

State ownership summary

Use the narrowest state tool that matches the ownership model:

Choose the ownership location first, then pick the wrapper. Do not introduce a reference model when plain value state is enough.

Cross-cutting references

• In addition to the references below, use web search to consult current Apple Developer documentation when SwiftUI APIs, availability, or platform guidance may have changed.
• references/navigationstack.md: navigation ownership, per-tab history, and enum routing.
• references/sheets.md: centralized modal presentation and enum-driven sheets.
• references/deeplinks.md: URL handling and routing external links into app destinations.
• references/app-wiring.md: root dependency graph, environment usage, and app shell wiring.
• references/async-state.md: .task, .task(id:), cancellation, debouncing, and async UI state.
• references/previews.md: #Preview, fixtures, mock environments, and isolated preview setup.
• references/performance.md: stable identity, observation scope, lazy containers, and render-cost guardrails.

Anti-patterns

• Giant views that mix layout, business logic, networking, routing, and formatting in one file.
• Multiple boolean flags for mutually exclusive sheets, alerts, or navigation destinations.
• Live service calls directly inside body-driven code paths instead of view lifecycle hooks or injected models/services.
• Reaching for AnyView to work around type mismatches that should be solved with better composition.
• Defaulting every shared dependency to @EnvironmentObject or a global router without a clear ownership reason.

Workflow for a new SwiftUI view

1. Define the view's state, ownership location, and minimum OS assumptions before writing UI code.
2. Identify which dependencies belong in @Environment and which should stay as explicit initializer inputs.
3. Sketch the view hierarchy, routing model, and presentation points; extract repeated parts into subviews. For complex navigation, read references/navigationstack.md, references/sheets.md, or references/deeplinks.md. Build and verify no compiler errors before proceeding.
4. Implement async loading with .task or .task(id:), plus explicit loading and error states when needed. Read references/async-state.md when the work depends on changing inputs or cancellation.
5. Add previews for the primary and secondary states, then add accessibility labels or identifiers when the UI is interactive. Read references/previews.md when the view needs fixtures or injected mock dependencies.
6. Validate with a build: confirm no compiler errors, check that previews render without crashing, ensure state changes propagate correctly, and sanity-check that list identity and observation scope will not cause avoidable re-renders. Read references/performance.md if the screen is large, scroll-heavy, or frequently updated. For common SwiftUI compilation errors — missing @State annotations, ambiguous ViewBuilder closures, or mismatched generic types — resolve them before updating callsites. If the build fails: read the error message carefully, fix the identified issue, then rebuild before proceeding to the next step. If a preview crashes, isolate the offending subview, confirm its state initialisation is valid, and re-run the preview before continuing.

Component references

Use references/components-index.md as the entry point. Each component reference should include:

• Intent and best-fit scenarios.
• Minimal usage pattern with local conventions.
• Pitfalls and performance notes.
• Paths to existing examples in the current repo.

Adding a new component reference

• Create references/<component>.md.
• Keep it short and actionable; link to concrete files in the current repo.
• Update references/components-index.md with the new entry.

SwiftUI View Refactor

Overview

Refactor SwiftUI views toward small, explicit, stable view types. Default to vanilla SwiftUI: local state in the view, shared dependencies in the environment, business logic in services/models, and view models only when the request or existing code clearly requires one.

Core Guidelines

1) View ordering (top → bottom)

• Enforce this ordering unless the existing file has a stronger local convention you must preserve.
• Environment
• private/public let
• @State / other stored properties
• computed var (non-view)
• init
• body
• computed view builders / other view helpers
• helper / async functions

2) Default to MV, not MVVM

• Views should be lightweight state expressions and orchestration points, not containers for business logic.
• Favor @State, @Environment, @Query, .task, .task(id:), and onChange before reaching for a view model.
• Inject services and shared models via @Environment; keep domain logic in services/models, not in the view body.
• Do not introduce a view model just to mirror local view state or wrap environment dependencies.
• If a screen is getting large, split the UI into subviews before inventing a new view model layer.

3) Strongly prefer dedicated subview types over computed some View helpers

• Flag body properties that are longer than roughly one screen or contain multiple logical sections.
• Prefer extracting dedicated View types for non-trivial sections, especially when they have state, async work, branching, or deserve their own preview.
• Keep computed some View helpers rare and small. Do not build an entire screen out of private var header: some View-style fragments.
• Pass small, explicit inputs (data, bindings, callbacks) into extracted subviews instead of handing down the entire parent state.
• If an extracted subview becomes reusable or independently meaningful, move it to its own file.

Prefer:

var body: some View {
    List {
        HeaderSection(title: title, subtitle: subtitle)
        FilterSection(
            filterOptions: filterOptions,
            selectedFilter: $selectedFilter
        )
        ResultsSection(items: filteredItems)
        FooterSection()
    }
}

private struct HeaderSection: View {
    let title: String
    let subtitle: String

    var body: some View {
        VStack(alignment: .leading, spacing: 6) {
            Text(title).font(.title2)
            Text(subtitle).font(.subheadline)
        }
    }
}

private struct FilterSection: View {
    let filterOptions: [FilterOption]
    @Binding var selectedFilter: FilterOption

    var body: some View {
        ScrollView(.horizontal, showsIndicators: false) {
            HStack {
                ForEach(filterOptions, id: \.self) { option in
                    FilterChip(option: option, isSelected: option == selectedFilter)
                        .onTapGesture { selectedFilter = option }
                }
            }
        }
    }
}

Avoid:

var body: some View {
    List {
        header
        filters
        results
        footer
    }
}

private var header: some View {
    VStack(alignment: .leading, spacing: 6) {
        Text(title).font(.title2)
        Text(subtitle).font(.subheadline)
    }
}

3b) Extract actions and side effects out of body

• Do not keep non-trivial button actions inline in the view body.
• Do not bury business logic inside .task, .onAppear, .onChange, or .refreshable.
• Prefer calling small private methods from the view, and move real business logic into services/models.
• The body should read like UI, not like a view controller.

Button("Save", action: save)
    .disabled(isSaving)

.task(id: searchText) {
    await reload(for: searchText)
}

private func save() {
    Task { await saveAsync() }
}

private func reload(for searchText: String) async {
    guard !searchText.isEmpty else {
        results = []
        return
    }
    await searchService.search(searchText)
}

4) Keep a stable view tree (avoid top-level conditional view swapping)

• Avoid body or computed views that return completely different root branches via if/else.
• Prefer a single stable base view with conditions inside sections/modifiers (overlay, opacity, disabled, toolbar, etc.).
• Root-level branch swapping causes identity churn, broader invalidation, and extra recomputation.

Prefer:

var body: some View {
    List {
        documentsListContent
    }
    .toolbar {
        if canEdit {
            editToolbar
        }
    }
}

Avoid:

var documentsListView: some View {
    if canEdit {
        editableDocumentsList
    } else {
        readOnlyDocumentsList
    }
}

5) View model handling (only if already present or explicitly requested)

• Treat view models as a legacy or explicit-need pattern, not the default.
• Do not introduce a view model unless the request or existing code clearly calls for one.
• If a view model exists, make it non-optional when possible.
• Pass dependencies to the view via init, then create the view model in the view's init.
• Avoid bootstrapIfNeeded patterns and other delayed setup workarounds.

Example (Observation-based):

@State private var viewModel: SomeViewModel

init(dependency: Dependency) {
    _viewModel = State(initialValue: SomeViewModel(dependency: dependency))
}

6) Observation usage

• For @Observable reference types on iOS 17+, store them as @State in the owning view.
• Pass observables down explicitly; avoid optional state unless the UI genuinely needs it.
• If the deployment target includes iOS 16 or earlier, use @StateObject at the owner and @ObservedObject when injecting legacy observable models.

Workflow

1. Reorder the view to match the ordering rules.
2. Remove inline actions and side effects from body; move business logic into services/models and keep only thin orchestration in the view.
3. Shorten long bodies by extracting dedicated subview types; avoid rebuilding the screen out of many computed some View helpers.
4. Ensure stable view structure: avoid top-level if-based branch swapping; move conditions to localized sections/modifiers.
5. If a view model exists or is explicitly required, replace optional view models with a non-optional @State view model initialized in init.
6. Confirm Observation usage: @State for root @Observable models on iOS 17+, legacy wrappers only when the deployment target requires them.
7. Keep behavior intact: do not change layout or business logic unless requested.

Notes

• Prefer small, explicit view types over large conditional blocks and large computed some View properties.
• Keep computed view builders below body and non-view computed vars above init.
• A good SwiftUI refactor should make the view read top-to-bottom as data flow plus layout, not as mixed layout and imperative logic.
• For MV-first guidance and rationale, see references/mv-patterns.md.
• In addition to the references above, use web search to consult current Apple Developer documentation when SwiftUI APIs, Observation behavior, or platform guidance may have changed.

Large-view handling

When a SwiftUI view file exceeds ~300 lines, split it aggressively. Extract meaningful sections into dedicated View types instead of hiding complexity in many computed properties. Use private extensions with // MARK: - comments for actions and helpers, but do not treat extensions as a substitute for breaking a giant screen into smaller view types. If an extracted subview is reused or independently meaningful, move it into its own file.

AppKit Interop

Quick Start

Use this skill when SwiftUI is close but not quite enough for native macOS behavior. Keep the bridge as small and explicit as possible. SwiftUI should usually remain the source of truth, while AppKit handles the imperative edge.

Choose The Smallest Bridge

• Use pure SwiftUI when the required behavior already exists in scenes, toolbars, commands, inspectors, or standard controls.
• Use NSViewRepresentable when you need a specific AppKit view with lightweight lifecycle needs.
• Use NSViewControllerRepresentable when you need controller lifecycle, delegation, or presentation coordination.
• Use direct AppKit window or app hooks when you need NSWindow, responder-chain, menu validation, panels, or app-level behavior.

Workflow

1. Name the capability gap precisely.

   • Window behavior
   • Text system behavior
   • Menu validation
   • Drag and drop
   • File open/save panels
   • First responder control

2. Pick the smallest boundary that solves it.

   • Avoid porting a whole screen to AppKit when one wrapped control or coordinator would do.

3. Keep ownership explicit.

   • SwiftUI owns value state, selection, and observable models.
   • AppKit objects stay inside the representable, coordinator, or bridge object.

4. Expose a narrow interface back to SwiftUI.

   • Bindings for editable state
   • Small callbacks for events
   • Focused bridge services only when necessary

5. Validate lifecycle assumptions.

   • SwiftUI may recreate representables.
   • Coordinators exist to hold delegate and target-action glue, not as a second app architecture.

References

• references/representables.md: choosing between view and view-controller wrappers, plus coordinator patterns.
• references/window-panels.md: window access, utility windows, and open/save panels.
• references/responder-menus.md: first responder, command routing, and menu validation.
• references/drag-drop-pasteboard.md: pasteboard, file URLs, and desktop drag/drop edges.

Guardrails

• Do not duplicate the source of truth between SwiftUI and AppKit.
• Do not let Coordinator become an unstructured dumping ground.
• Do not store long-lived NSView or NSWindow instances globally without a strong ownership reason.
• Prefer a tiny tested bridge over rewriting the feature in raw AppKit.
• If a pattern can remain entirely in swiftui-patterns, keep it there.

Output Expectations

Provide:

• the exact SwiftUI limitation being crossed
• the smallest recommended bridge type
• the data-flow boundary between SwiftUI and AppKit
• the lifecycle or validation risks to watch

Build / Run / Debug

Quick Start

Use this skill to set up one project-local script/build_and_run.sh entrypoint, wire .codex/environments/environment.toml so the Codex app shows a Run button, then use that script as the default build/run path.

Prefer shell-first workflows:

• ./script/build_and_run.sh as the single kill + build + run entrypoint once it exists
• xcodebuild for Xcode workspaces or projects
• swift build plus raw executable launch inside that script for true SwiftPM command-line tools
• swift build plus project-local .app bundle staging and /usr/bin/open -n launch for SwiftPM AppKit/SwiftUI GUI apps
• optional script flags for lldb, log stream, telemetry verification, or post-launch process checks

Do not assume simulators, touch interaction, or mobile-specific tooling.

If an Xcode-aware MCP surface is already available and the user explicitly wants it, use it only where it fits. Keep that usage narrow and honest: prefer it for Xcode-oriented discovery, logging, or debugging support, and do not force simulator-specific workflows onto pure macOS tasks.

Workflow

1. Discover the project shape.

   • Check whether the workspace is already inside a git repo with git rev-parse --is-inside-work-tree.
   • If no git repo is present, run git init at the project/workspace root before building so Codex app git-backed features are available. Never run git init inside a nested subdirectory when the current workspace already belongs to a parent repo.
   • Look for .xcworkspace, .xcodeproj, and Package.swift.
   • If more than one candidate exists, explain the default choice and the ambiguity.

2. Resolve the runnable target and process name.

   • For Xcode, list schemes and prefer the app-producing scheme unless the user names another one.
   • For SwiftPM, identify executable products when possible.
   • Split SwiftPM launch handling by product type:
     • use raw executable launch only for true command-line tools,
     • use a generated project-local .app bundle for AppKit/SwiftUI GUI apps.
   • Determine the app/process name to kill before relaunching.

3. Create or update script/build_and_run.sh.

   • Make the script project-specific and executable.
   • It should always:
     1. stop the existing running app/process if present,
     2. build the macOS target,
     3. launch the freshly built app or executable.
   • Add optional flags for debugging/log inspection:
     • --debug to launch under lldb or attach the debugger
     • --logs to stream process logs after launch
     • --telemetry to stream unified logs filtered to the app subsystem/category
     • --verify to launch the app and confirm the process exists with pgrep -x <AppName>
   • Keep the default no-flag path simple: kill, build, run.
   • Prefer writing one script that owns this workflow instead of repeatedly asking the agent to manually run swift build, locate the artifact, then invoke an ad hoc run command.
   • For SwiftPM GUI apps, make the script build the product, create dist/<AppName>.app, copy the binary to Contents/MacOS/<AppName>, generate a minimal Contents/Info.plist with CFBundlePackageType=APPL, CFBundleExecutable, CFBundleIdentifier, CFBundleName, LSMinimumSystemVersion, and NSPrincipalClass=NSApplication, then launch with /usr/bin/open -n <bundle>.
   • For SwiftPM GUI --logs and --telemetry, launch the bundle with /usr/bin/open -n first, then stream unified logs with /usr/bin/log stream --info ....
   • Do not recommend direct SwiftPM executable launch for AppKit/SwiftUI GUI apps.
   • Use references/run-button-bootstrap.md as the canonical source for the script shape and exact environment file format. Do not fork a second authoritative snippet in another skill or command.
   • Keep the run script outside app source. It belongs in script/build_and_run.sh, not in App/, Views/, Models/, Stores/, Services/, or Support/.

4. Write .codex/environments/environment.toml at the project root once the script exists.

   • Use this exact placement: .codex/environments/environment.toml.
   • Use the exact action shape in references/run-button-bootstrap.md.
   • This file is what gives the user a Codex app Run button wired to the script.
   • If the project already has this file, update the Run action command to point at ./script/build_and_run.sh instead of creating a duplicate action.
   • Keep this Codex environment config separate from Swift app source files.

5. Build and run through the script.

   • Default to ./script/build_and_run.sh.
   • Use ./script/build_and_run.sh --debug, --logs, --telemetry, or --verify when the user asks for debugger/log/telemetry/process verification support.

6. Summarize failures correctly.

   • Classify the blocker as compiler, linker, signing, build settings, missing SDK/toolchain, script bug, or runtime launch.
   • Quote the smallest useful error snippet and explain what it means.

7. Debug the right way.

   • Use the script's --logs or --telemetry mode for config, entitlement, sandbox, and action-event verification.
   • For SwiftPM GUI apps, if the app bundle launches but its window still does not come forward, check whether the entrypoint needs NSApp.setActivationPolicy(.regular) and NSApp.activate(ignoringOtherApps: true).
   • Use the script's --debug mode or direct lldb if symbolized crash debugging is needed.
   • If the user needs to instrument and verify specific window, sidebar, menu, or menu bar actions, switch to telemetry.
   • Keep evidence tight and user-facing.

8. Use Xcode-aware MCP tooling only when it helps.

   • If the user explicitly asks for XcodeBuildMCP and it is already available, prefer it over ad hoc setup.
   • Use the MCP for Xcode-aware discovery or debug/logging workflows when the available tool surface clearly matches the task.
   • Fall back to shell commands immediately when the MCP does not provide a clean macOS path.

Preferred Commands

• Project discovery:
  • find . -name '*.xcworkspace' -o -name '*.xcodeproj' -o -name 'Package.swift'
• Scheme discovery:
  • xcodebuild -list -workspace <workspace>
  • xcodebuild -list -project <project>
• Build/run:
  • ./script/build_and_run.sh
  • ./script/build_and_run.sh --debug
  • ./script/build_and_run.sh --logs
  • ./script/build_and_run.sh --telemetry
  • ./script/build_and_run.sh --verify

References

• references/run-button-bootstrap.md: canonical build_and_run.sh and .codex/environments/environment.toml contract.

Guardrails

• Prefer the narrowest command that proves or disproves the current theory.
• Do not leave the user with a one-off manual command chain once a stable build_and_run.sh script can own the workflow.
• Do not write .codex/environments/environment.toml before the run script exists, and do not point the Run action at a stale script path.
• Do not launch a SwiftUI/AppKit SwiftPM GUI app as a raw executable unless the user explicitly wants to diagnose that failure mode: it can produce no Dock icon, no foreground activation, and missing bundle identifier warnings. Keep raw executable launch only for true command-line tools.
• Do not claim UI state you cannot inspect directly.
• Do not describe mobile or simulator workflows as if they apply to macOS.
• If build output is huge, summarize the first real blocker and point to follow-up commands.

Output Expectations

Provide:

• the detected project type
• the script path and Codex environment action you configured, if applicable
• the command you ran
• whether build and launch succeeded
• the top blocker if they failed
• the smallest sensible next action

Liquid Glass

Overview

Use this skill to bring a macOS SwiftUI app into the modern macOS design system with the least custom chrome possible. Start with standard app structure, toolbars, search placement, sheets, and controls, then add custom Liquid Glass only where the app needs a distinctive surface.

Prefer system-provided glass and adaptive materials over bespoke blur, opaque backgrounds, or custom toolbar/sidebar skins. Audit existing UI for extra fills, scrims, and clipping before adding more effects.

Workflow

1. Read the relevant scene or root view and identify the structural pattern: NavigationSplitView, TabView, sheet presentation, detail/inspector layout, toolbar, or custom floating controls.
2. Remove custom backgrounds or darkening layers behind system sheets, sidebars, and toolbars unless the product explicitly needs them. These can obscure Liquid Glass and interfere with the automatic scroll-edge effect.
3. Update standard SwiftUI structure and controls first.
4. Add custom glassEffect surfaces only for app-specific UI that standard controls do not cover.
5. Validate that glass grouping, transitions, icon treatment, and foreground activation are visually coherent and still usable with pointer and keyboard.
6. If the UI change also affects launch behavior for a SwiftPM GUI app, use build-run-debug so the app runs as a foreground .app bundle rather than as a raw executable.

App Structure

• Prefer NavigationSplitView for hierarchy-driven macOS layouts. Let the sidebar use the system Liquid Glass material instead of painting over it.
• For hero artwork or large media adjacent to a floating sidebar, use backgroundExtensionEffect so the visual can extend beyond the safe area without clipping the subject.
• Keep inspectors visually associated with the current selection and avoid giving them a heavier custom background than the content they inspect.
• If the app uses tabs, keep TabView for persistent top-level sections and preserve each tab's local navigation state.
• Do not force iPhone-only tab bar minimize/accessory behavior onto a Mac app. On macOS, prefer a conventional top toolbar and native tab/search placement.
• If a sheet already uses presentationBackground purely to imitate frosted material, consider removing it and letting the system's new material render.
• For sheet transitions that should visually originate from a toolbar button, make the presenting item the source of a navigation zoom transition and mark the sheet content as the destination.

Toolbars

• Assume toolbar items are rendered on a floating Liquid Glass surface and are grouped automatically.
• Use ToolbarSpacer to communicate grouping:
  • fixed spacing to split related actions into a distinct group,
  • flexible spacing to push a leading action away from a trailing group.
• Use sharedBackgroundVisibility when an item should stand alone without the shared glass background, for example a profile/avatar item.
• Add badge to toolbar item content for notification or status indicators.
• Expect monochrome icon rendering in more toolbar contexts. Use tint only to convey semantic meaning such as a primary action or alert state, not as pure decoration.
• If content underneath a toolbar has extra darkening, blur, or custom background layers, remove them before judging the new automatic scroll-edge effect.
• For dense windows with many floating elements, tune the content's scroll-edge treatment with scrollEdgeEffectStyle instead of building a custom bar background.

Search

• For a search field that applies across a whole split-view hierarchy, attach searchable to the NavigationSplitView, not to just one column.
• When search is secondary and a compact affordance is better, use searchToolbarBehavior instead of hand-rolling a toolbar button and a separate field.
• For a dedicated search page in a multi-tab app, assign the search role to one tab and place searchable on the TabView.
• Make most of the app's content discoverable from search when the field lives in the top-trailing toolbar location.
• On iPad and Mac, expect the dedicated search tab to show a centered field above browsing suggestions rather than a bottom search bar.

Controls

• Prefer standard SwiftUI controls before creating custom glass components.
• Expect bordered buttons to default to a capsule shape at larger sizes. On macOS, mini/small/medium controls preserve a rounded-rectangle shape for denser layouts.
• Use buttonBorderShape when a button shape needs to be explicit.
• Use controlSize to preserve density in inspectors and popovers, and reserve extra-large sizing for truly prominent actions.
• Use the system glass and glass-prominent button styles for primary actions instead of recreating a translucent button background by hand.
• For sliders with discrete values, pass step to get automatic tick marks or provide specific ticks in a ticks closure.
• For sliders that should expand left and right around a baseline, set neutralValue.
• Use Label or standard control initializers for menu items so icons are consistently placed on the leading edge across platforms.
• For custom shapes that must align concentrically with a sheet, card, or window corner, use a concentric rectangle shape with the containerConcentric corner configuration instead of guessing a radius.

Custom Liquid Glass

• Use glassEffect for custom glass surfaces. The default shape is capsule-like and text foregrounds are automatically made vibrant and legible against changing content underneath.
• Pass an explicit shape to glassEffect when a capsule is not the right fit.
• Add tint only when color carries meaning, such as a status or call to action.
• Use glassEffect(... .interactive()) for custom controls or containers with interactive elements so they scale, bounce, and shimmer like system glass.
• Wrap nearby custom glass elements in one GlassEffectContainer. This is a visual correctness rule, not just organization: separate containers cannot sample each other's glass and can produce inconsistent refraction.
• Use glassEffectID with a local @Namespace when matching glass elements should morph between collapsed and expanded states.

Review Checklist

• Standard structures and controls were updated first before adding custom glass.
• Opaque backgrounds, dark scrims, and custom toolbar/sheet fills that fight the system material were removed unless intentionally required.
• searchable is attached at the correct container level for the intended search scope.
• Toolbar grouping uses ToolbarSpacer, sharedBackgroundVisibility, and badge instead of one-off hand-built chrome.
• Icon tint is semantic, not decorative.
• Custom glass elements that sit near each other share a GlassEffectContainer.
• Morphing glass transitions use glassEffectID with a namespace and stable identity.
• Any SwiftPM GUI app used to test the result is launched as a .app bundle, not as a raw executable.

Guardrails

• Do not rebuild system sidebars, toolbars, sheets, or controls from scratch if standard SwiftUI APIs already provide the modern macOS behavior.
• Do not apply custom opaque backgrounds behind a NavigationSplitView sidebar, system toolbar, or sheet just because an older version needed one.
• Do not scatter related glass elements across multiple GlassEffectContainers.
• Do not tint every icon or glass surface for visual variety alone.
• Do not assume an iPhone tab/search behavior is the right answer on macOS. Prefer desktop-native toolbar, split-view, and inspector placement.
• Do not leave a GUI SwiftPM app launching as a bare executable when reviewing Liquid Glass behavior; missing foreground activation can make a design bug look like a rendering bug.

When To Use Other Skills

• Use swiftui-patterns when the main question is scene architecture, sidebar/detail layout, commands, or settings rather than Liquid Glass-specific treatment.
• Use view-refactor when the main issue is file structure, state ownership, and extracting large views before design changes.
• Use appkit-interop when the design requires window, panel, responder-chain, or AppKit-only control behavior.
• Use build-run-debug when you need to launch, verify, or inspect logs for the app after the visual update.

Packaging & Notarization

Quick Start

Use this skill when the work is about shipping the app rather than merely running it locally: archives, exported app bundles, notarization readiness, hardened runtime, or distribution validation.

Workflow

1. Confirm the distribution goal.

   • Local archive validation
   • Signed distributable app
   • Notarization troubleshooting

2. Inspect the artifact.

   • Validate app bundle structure.
   • Check nested frameworks, helper tools, and entitlements.

3. Inspect signing and runtime prerequisites.

   • Hardened runtime
   • Signing identity
   • Nested code signatures
   • Required entitlements

4. Explain notarization readiness or failure.

   • Separate packaging issues from trust-policy symptoms.
   • Point to the minimum follow-up validation commands.

Guardrails

• Do not present notarization as required for ordinary local debug runs.
• Call out when you lack the actual exported artifact and are inferring from project settings.
• Keep advice concrete and verifiable.

Output Expectations

Provide:

• what artifact or settings were inspected
• whether the app looks distribution-ready
• the top missing prerequisite or failure mode
• the next validation or repair step

Signing & Entitlements

Quick Start

Use this skill when the failure smells like codesigning rather than compilation: launch refusal, missing entitlement, invalid signature, sandbox mismatch, hardened runtime confusion, or trust-policy rejection.

Workflow

1. Inspect the bundle or binary.

   • Locate the .app or executable.
   • Identify the main binary inside Contents/MacOS/.

2. Read signing details.

   • Use codesign -dvvv --entitlements :- <path>.
   • Use spctl -a -vv <path> when Gatekeeper behavior matters.
   • Use plutil -p for entitlements or Info.plist inspection.

3. Classify the failure.

   • Unsigned or ad hoc signed
   • Wrong identity
   • Entitlement mismatch
   • Hardened runtime issue
   • App Sandbox issue
   • Nested code signing issue
   • Distribution/notarization prerequisite issue

4. Explain the minimum fix path.

   • Say exactly what is wrong.
   • Show the shortest set of validation or repair commands.
   • Distinguish local development problems from distribution problems.

Useful Commands

• codesign -dvvv --entitlements :- <app-or-binary>
• spctl -a -vv <app-or-binary>
• security find-identity -p codesigning -v
• plutil -p <path-to-entitlements-or-plist>

Guardrails

• Never invent missing entitlements.
• Do not conflate notarization with local debug signing.
• If the real issue is a build setting or provisioning profile, say so directly.

Output Expectations

Provide:

• what artifact was inspected
• what signing state it is in
• the exact failure class
• the minimum fix or validation sequence

SwiftPM for macOS

Quick Start

Use this skill when Package.swift is the primary entrypoint or when SwiftPM is the fastest path to a reproducible result.

Workflow

1. Inspect the package.

   • Read Package.swift.
   • Identify executable, library, and test products.

2. Build with SwiftPM.

   • Use swift build by default.
   • Use release mode only when the user explicitly needs it.

3. Run the right product.

   • Use swift run <product> when an executable exists.
   • If multiple executables exist, explain the default choice.

4. Test narrowly.

   • Use swift test.
   • Apply filters when a specific test target or case is known.

5. Summarize failures.

   • Module/import resolution
   • Package graph or dependency issue
   • Linker failure
   • Runtime failure
   • Test regression

Guardrails

• Prefer SwiftPM over Xcode when both exist and the package path is clearly simpler.
• Do not assume an app bundle exists in a pure package workflow.
• Explain when the package is library-only and therefore not directly runnable.

Output Expectations

Provide:

• the package products you found
• the command you ran
• whether build, run, or test succeeded
• the top blocker if not

SwiftUI Patterns

Quick Start

Choose a track based on your goal:

Existing project

• Identify the feature or scene and the primary interaction model: document, editor, sidebar-detail, utility window, settings, or menu bar extra.
• Read the nearest existing scene or root view before inventing a new desktop structure.
• Choose the relevant reference from references/components-index.md.
• If SwiftUI cannot express the required platform behavior cleanly, use the appkit-interop skill rather than forcing a shaky workaround.

New app scaffolding

• Choose the scene model first: WindowGroup, Window, Settings, MenuBarExtra, or DocumentGroup.
• If the app combines a normal main window and a MenuBarExtra, use WindowGroup(..., id:) for the primary window when it should appear at launch. Treat Window(...) as a better fit for auxiliary/on-demand singleton windows; in menu-bar-heavy apps, a Window(...) scene may not present the main window automatically at launch.
• Before creating the scaffold, check whether the workspace is already inside a git repo with git rev-parse --is-inside-work-tree. If not, run git init at the project root so Codex app git-backed features are available from the start. Do not initialize a nested repo inside an existing parent checkout.
• For a new app scaffold, also create one project-local script/build_and_run.sh and .codex/environments/environment.toml so the Codex app Run button works immediately. Use the exact bootstrap contract from build-run-debug and its references/run-button-bootstrap.md file rather than inventing a second variant here.
• Decide which state is app-wide, scene-scoped, or window-scoped before writing views.
• Sketch file and module boundaries before writing the full UI. For any non-trivial app, create the folder structure first and split files by responsibility from the start.
• Use a single Swift file only for tiny throwaway examples or snippets: roughly under 50 lines, one screen, no persistence, no networking/process client, and no reusable models. Anything beyond that should be multi-file immediately.
• Use system-adaptive colors and materials by default (Color.primary, Color.secondary, semantic foreground styles, .regularMaterial, etc.) so the app follows Light/Dark mode automatically. Do not hardcode white or light backgrounds unless the user explicitly asks for a fixed theme, and do not reach for opaque windowBackgroundColor fills for root panes by default.
• Pick the references for the first feature surface you need: windowing, commands, split layouts, or settings.

New App File Structure

For any non-trivial macOS app, start with this shape instead of putting the app, all views, models, stores, services, and helpers in one Swift file:

• App/<AppName>App.swift: the @main app type and AppDelegate only.
• Views/ContentView.swift: root layout and high-level composition only.
• Views/SidebarView.swift, Views/DetailView.swift, Views/ComposerView.swift, etc.: feature views named after their primary type.
• Models/*.swift: value models, identifiers, and selection enums.
• Stores/*.swift: persistence and state stores.
• Services/*.swift: app-server, network, process, or platform clients.
• Support/*.swift: small formatters, resolvers, extensions, and glue helpers.

Keep files small and named after the primary type they contain. If a file starts collecting unrelated views, models, stores, networking clients, and helper extensions, split it before adding more behavior.

Pre-Edit Checklist For New App Scaffolds

Before writing the full UI:

1. Choose the scene model.
2. Choose state ownership: app-wide, scene-scoped, window-scoped, or view-local.
3. Sketch file and module boundaries.
4. Create the folder structure before filling in the UI.
5. Keep script/build_and_run.sh and .codex/environments/environment.toml separate from app source.

General Rules To Follow

• Design for pointer, keyboard, menus, and multiple windows.
• Keep scenes explicit. A separate settings window, utility window, or menu bar extra should be modeled as its own scene, not hidden inside one monolithic ContentView.
• Prefer system desktop affordances: commands, toolbars, sidebars, inspectors, contextual menus, and searchable.
• For menu bar apps, keep MenuBarExtra item titles and action labels short and scannable. Cap visible menu item text at 30 characters; if source content is longer, truncate or summarize it before rendering and open the full content in a dedicated window or detail surface.
• If a MenuBarExtra app should still behave like a regular Dock app with a visible main window/process, install an NSApplicationDelegate via @NSApplicationDelegateAdaptor, call NSApp.setActivationPolicy(.regular) during launch, and activate the app with NSApp.activate(ignoringOtherApps: true). If the app is intentionally menu-bar-only, document that .accessory / no-Dock behavior is a deliberate product choice.
• Prefer system-adaptive colors, materials, and semantic foreground styles. Avoid fixed white/light backgrounds in scaffolding and examples unless the requested design explicitly calls for a custom non-adaptive theme.
• Do not paint NavigationSplitView sidebars or root window panes with opaque custom Color(...) or Color(nsColor: .windowBackgroundColor) fills by default. Prefer native macOS sidebar/window materials and system-provided backgrounds unless the user explicitly asks for a custom opaque surface. In sidebar-detail-inspector layouts, let the sidebar keep the standard source-list/material appearance and reserve custom backgrounds for detail or inspector content cards where needed.
• Use @SceneStorage for per-window ephemeral state and @AppStorage for durable user preferences.
• Keep selection state explicit and stable. macOS layouts often pivot around sidebar selection rather than push navigation.
• Prefer NavigationSplitView or a deliberate manual split layout over iOS-style stacked flows when the app benefits from always-visible structure.
• For List(...).listStyle(.sidebar) and NavigationSplitView sidebars, prefer flat native rows with standard system selection/highlight behavior. Keep rows visually lightweight and Mail-like: at most one leading icon, one strong title line, and one optional secondary detail line in .secondary. Avoid stacked metadata rows, repeated inline utility icons, or dense multi-column status text in the sidebar. Reserve card-style and metadata-heavy surfaces for detail or inspector panes unless the user explicitly asks for a highly custom sidebar treatment.
• Keep primary actions discoverable from both UI chrome and keyboard shortcuts when appropriate.
• Use SwiftUI-native scenes and views first. If you need low-level window, responder-chain, text system, or panel control, switch to appkit-interop.

For concrete sidebar row and split-view background examples, read references/split-inspectors.md.

State Ownership Summary

Use the narrowest state tool that matches the ownership model:

Choose the ownership location first, then the wrapper. Do not turn simple desktop state into a view model by reflex.

Cross-Cutting References

• references/components-index.md: entry point for scene and component guidance.
• references/windowing.md: choosing between WindowGroup, Window, DocumentGroup, and window-opening patterns.
• references/settings.md: dedicated settings scenes, SettingsLink, and preference layouts.
• references/commands-menus.md: command menus, keyboard shortcuts, focused values, and desktop action routing.
• references/split-inspectors.md: sidebars, split views, selection-driven layout, and inspectors.
• references/menu-bar-extra.md: menu bar extra structure and when it fits.

Anti-Patterns

• One huge ContentView pretending the whole app is a single screen.
• A single Swift file containing the @main app, all views, models, stores, networking/process clients, formatters, and extensions. This is acceptable only for tiny throwaway snippets under the new-app threshold above.
• Touch-first interaction models ported directly from iOS without desktop affordances.
• Hiding core actions behind gestures with no menu, toolbar, or keyboard path.
• Building a menu-bar-plus-window app around only a Window(...) scene and then expecting the main window to appear at launch. Use WindowGroup(..., id:) for the primary launch window and reserve Window(...) for auxiliary/on-demand windows.
• Rendering full unbounded document titles, prompts, or message text directly inside a menu bar extra. Menu item labels should stay at or below 30 characters, with longer content moved into a dedicated window or detail view.
• Treating settings as another navigation destination in the main content window.
• Hardcoding .background(.white), Color.white, or a fixed light palette in a brand-new scaffold without an explicit design requirement.
• Wrapping each sidebar item in large rounded custom cards inside a .sidebar list, which fights native source-list density, alignment, and selection behavior unless the user explicitly asked for a bespoke visual sidebar.
• Building sidebar rows with multiple repeated icons, three or more text lines, or a dense strip of inline metadata counters/timestamps/models. Keep the sidebar row to one icon and one or two text lines, then move richer metadata into the detail pane.
• Painting NavigationSplitView sidebars or root window panes with opaque custom color fills by default, instead of letting the sidebar use native source-list/material appearance and reserving custom backgrounds for actual content cards.
• Using push navigation for layouts that want stable sidebar selection and detail panes.
• Reaching for AppKit before the SwiftUI scene and command APIs have been used properly.

Workflow For A New macOS Scene Or View

1. Define the scene type and ownership model before writing child views.
2. Decide which actions live in content, toolbars, commands, inspectors, or settings.
3. Sketch the selection model and layout: sidebar-detail, editor-inspector, document window, or utility window.
4. Create the file/folder structure for app entrypoint, root layout, feature views, models, stores, services, and support helpers.
5. Build with small, focused subviews and explicit inputs rather than giant computed fragments.
6. Add keyboard shortcuts and menu or toolbar exposure for actions that matter on desktop.
7. Validate the flow with a build and a quick usability pass: multiwindow assumptions, settings entry points, and selection stability.

Component References

Use references/components-index.md as the entry point. Each component reference should include:

• intent and best-fit scenarios
• minimal usage pattern with desktop conventions
• pitfalls and discoverability notes
• when to fall back to appkit-interop

Telemetry

Quick Start

Use this skill to add lightweight app instrumentation that helps debug behavior without turning the codebase into a logging landfill. Prefer Apple's unified logging APIs and verify the events after a build/run loop.

Core Guidelines

• Prefer Logger from the OSLog framework for structured app logs.
• Give each feature a clear subsystem/category pair so runtime filtering stays easy.
• Log meaningful user and app lifecycle events: window opening, sidebar selection changes, menu commands, menu bar extra actions, sync/load milestones, and unexpected fallback paths.
• Keep info logs concise and stable. Use debug logs for noisy state details.
• Do not log secrets, auth tokens, personal data, or raw document contents.
• Add signposts only when measuring timing or performance spans; do not overinstrument by default.

Minimal Logger Pattern

import OSLog

private let logger = Logger(
  subsystem: Bundle.main.bundleIdentifier ?? "SampleApp",
  category: "Sidebar"
)

@MainActor
func selectItem(_ item: SidebarItem) {
  logger.info("Selected sidebar item: \(item.id, privacy: .public)")
  selection = item.id
}

Use feature-specific categories like Windowing, Commands, MenuBar, Sidebar, Sync, or Import so logs can be filtered quickly.

Workflow

1. Identify the behavior that needs observability.

   • Window open/close
   • Sidebar or inspector selection changes
   • Menu or keyboard command actions
   • Menu bar extra actions
   • Background load/sync/import events
   • Error and recovery paths

2. Add the smallest useful instrumentation.

   • Create one Logger per feature area or type.
   • Log action boundaries and key state transitions.
   • Prefer one high-signal line per user action over noisy value dumps.

3. Build and run the app.

   • Use build-run-debug for the build/run loop.
   • If script/build_and_run.sh exists, prefer ./script/build_and_run.sh --telemetry for live telemetry checks or ./script/build_and_run.sh --logs for broader process logs.
   • Exercise the UI or command path that should emit telemetry.

4. Read runtime logs and verify the event fired.

   • Use Console.app with a process/subsystem filter when that is the fastest manual check.
   • Use log stream --style compact --predicate 'process == "AppName"' for live terminal verification.
   • Prefer tighter predicates when you know the subsystem/category: log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'

5. Tighten or remove instrumentation.

   • If the event fires, keep only the logs that remain useful for future debugging.
   • If it does not fire, move the log closer to the suspected control path and rerun.

Verification Checklist

• The app builds after telemetry changes.
• The relevant action emits exactly one clear log line or a small bounded sequence.
• The log can be filtered by process, subsystem, or category.
• No sensitive payloads are written to unified logs.
• Noisy temporary debug logs are removed or demoted before finishing.

Guardrails

• Do not use print as the primary app telemetry mechanism for macOS app code.
• Do not leave a dense trail of permanent debug logs around every state mutation.
• Do not claim an event is wired correctly until you have a concrete verification path through Console, log stream, or captured process output.
• If the debugging task is mostly about crash/backtrace analysis rather than action telemetry, switch to build-run-debug.

Test Triage

Quick Start

Use this skill to run the smallest meaningful test scope first, classify failures precisely, and avoid treating every test failure like a product bug.

Workflow

1. Detect the test harness.

   • Use xcodebuild test for Xcode-based projects.
   • Use swift test for SwiftPM packages.

2. Narrow the scope.

   • If the user gave a target, product, or test filter, use it.
   • If not, prefer the smallest likely failing target before a full suite.

3. Classify the result.

   • Build failure
   • Assertion failure
   • Crash or signal
   • Async timing or flake
   • Environment or fixture setup issue
   • Missing entitlement or host app issue

4. Rerun intelligently.

   • Use focused reruns when a specific case fails.
   • Avoid burning time on full-suite reruns without new information.

5. Summarize clearly.

   • What command ran
   • Which tests failed
   • What kind of failure it was
   • The best next proof step or fix path

Guardrails

• Distinguish compilation failures from test execution failures.
• Call out when a test appears to assume iOS-only or simulator-only behavior.
• Mark likely flakes as such instead of overstating confidence.

Output Expectations

Provide:

• the command used
• the smallest failing scope
• the top failure category
• a concise explanation of the likely cause
• the next rerun or fix step

View Refactor

Overview

Refactor macOS views toward small, explicit, stable scene and view types. Default to native SwiftUI for layout, selection, commands, and settings. Reach for AppKit only at the narrow edges where desktop behavior truly requires it.

Core Guidelines

1) Model scenes explicitly

• Break the app into meaningful scene roots: main window, settings, utility windows, inspectors, or menu bar extras.
• Do not let one giant root view silently own every desktop surface.

2) Keep a predictable file shape

• Follow this ordering unless the file already has a stronger local convention:
• Environment
• private/public let
• @State / other stored properties
• computed var (non-view)
• init
• body
• computed view builders / other view helpers
• helper / async functions

2b) Split files by responsibility

• For non-trivial apps, do not keep the full app, all views, models, stores, networking clients, process clients, and helpers in one Swift file.
• Accept a single Swift file only for tiny throwaway examples or snippets: roughly under 50 lines, one screen, no persistence, no networking/process client, and no reusable models.
• Use App/<AppName>App.swift for the @main app and AppDelegate only.
• Keep Views/ContentView.swift focused on root layout and composition; move feature UI into files such as Views/SidebarView.swift, Views/DetailView.swift, and Views/ComposerView.swift.
• Move value types and selection enums into Models/*.swift, stores into Stores/*.swift, app-server/network/process clients into Services/*.swift, and small formatters/resolvers/extensions into Support/*.swift.
• Keep files small and named after the primary type they contain.

3) Prefer dedicated subview types over many computed some View fragments

• Extract meaningful desktop sections like sidebar rows, detail panels, inspectors, or toolbar content into focused subviews.
• Keep computed some View helpers small and rare.
• Pass explicit data, bindings, and actions into subviews instead of handing down the whole scene model.

4) Keep selection and layout stable

• Prefer one stable split or window layout with local conditionals inside it.
• Avoid top-level branch swapping between radically different roots when selection changes.
• Let the layout be constant; let state drive the content inside it.

5) Extract commands, toolbars, and actions out of body

• Do not bury non-trivial button logic inline.
• Do not mix command routing, menu state, and layout in the same block if they can be named clearly.
• Keep body readable as UI, not as a desktop view controller.

6) Use scene and app storage intentionally

• Use @SceneStorage for per-window ephemeral state when it truly helps restore the scene.
• Use @AppStorage for durable preferences, not transient UI toggles that only matter in one window.
• Keep scene-owned state close to the scene root.

7) Keep AppKit escape hatches narrow

• If a representable or NSWindow bridge exists, isolate it behind a small wrapper or helper.
• Do not let AppKit references spread through unrelated SwiftUI views.
• If the bridge starts owning the feature, re-evaluate the architecture.

8) Observation usage

• For @Observable reference types on modern macOS targets, store them as @State in the owning view.
• Pass observables explicitly to children.
• On older deployment targets, fall back to @StateObject and @ObservedObject where needed.

Workflow

1. Identify the current scene boundary and whether the file is trying to do too much.
2. Reorder the file into a predictable top-to-bottom structure.
3. Extract desktop-specific sections into dedicated subview types.
4. Stabilize the root layout around selection, scenes, and commands rather than top-level branching.
5. Move action logic, command routing, and toolbar behavior into named helpers or separate types.
6. Tighten any AppKit bridge so the imperative edge is small and explicit.
7. Keep behavior intact unless the request explicitly asks for structural and behavioral changes together.

Refactor Checklist

• Split oversized view files before adding more UI.
• Move pure models, identifiers, and selection enums out of view files.
• Move Process, URLSession, app-server, and platform client code out of SwiftUI views into Services/.
• Keep AppDelegate and the @main app entrypoint minimal.
• Build after each major split so compile errors stay local.

Common Smells

• A root view that mixes window scaffolding, settings, toolbar code, command handling, and detail layout.
• A single app file that mixes app entrypoint, root layout, feature views, models, stores, service clients, and support extensions.
• iOS-style push navigation forced into a Mac sidebar-detail problem.
• Several booleans for mutually exclusive inspectors, sheets, or utility windows.
• AppKit objects passed through many SwiftUI layers without a clear ownership reason.
• Large computed view fragments standing in for real subviews.

Notes

• A good macOS refactor should make scene structure, selection flow, and command ownership obvious.
• When the problem is fundamentally a missing desktop pattern, use swiftui-patterns.
• When the problem is fundamentally a boundary with AppKit, use appkit-interop.

Window Management

Overview

Use this skill to tailor each SwiftUI window to its job. Start by identifying which scene owns the window (Window, WindowGroup, or a dedicated utility scene), then customize the toolbar/title area, background material, resize and restoration behavior, and initial or zoomed placement.

Prefer scene and window modifiers over ad hoc AppKit bridges when SwiftUI offers the behavior directly. Keep each window purpose-built: a main browser window, an About window, and a media player window usually want different chrome, resizability, restoration, and placement rules.

These APIs are macOS 15+ SwiftUI window/scene customizations. For older deployment targets, expect to use more AppKit bridging or availability guards.

Workflow

1. Inspect the relevant scene declaration and classify the window role: main app navigation, inspector/detail utility, About/support window, media playback window, welcome window, or a borderless custom surface.
2. Adjust toolbar and title presentation to match the content.
3. If the toolbar background or entire toolbar is hidden, make sure the window still has a usable drag region.
4. Refine window behavior for that role: minimize availability, restoration, resize expectations, and whether the window should appear at launch.
5. Set default placement for newly opened windows and ideal placement for zoom behavior when content and display size matter.
6. Build and launch the app with build-run-debug to verify the result in a real foreground .app bundle.
7. If SwiftUI scene/window modifiers are not enough, switch to appkit-interop for a narrow NSWindow bridge rather than spreading AppKit through the view tree.

Toolbar And Title

• Use .toolbar(removing: .title) when the window title should stay associated with the window for accessibility and menus, but not be visibly drawn in the title bar.
• Use .toolbarBackgroundVisibility(.hidden, for: .windowToolbar) when large media or hero content should visually extend to the top edge of the window.
• If the window still needs close/minimize/full-screen controls, remove only the title and toolbar background. If the toolbar should disappear entirely, use .toolbarVisibility(.hidden, for: .windowToolbar) instead.
• Remove custom toolbar backgrounds and manually painted titlebar fills before layering new SwiftUI toolbar APIs on top.
• Keep the window's logical title meaningful even if hidden; the system can still use it for accessibility and menu items. These are visual changes only.

Drag Regions

• If a toolbar background is hidden or the toolbar is removed entirely, use WindowDragGesture() to extend the draggable area into your content.
• Attach the gesture to a transparent overlay or non-interactive header region that does not steal gestures from real controls.
• For a media player with custom playback controls, insert the drag overlay between the video content and the controls so AVKit or transport controls keep receiving input.
• Pair the drag gesture with .allowsWindowActivationEvents(true) so clicking and immediately dragging a background window still activates and moves it.

Background And Materials

• Use .containerBackground(.thickMaterial, for: .window) when a utility window or About window should replace the default window background with a subtle frosted material.
• Prefer system materials for stylized windows instead of hardcoded translucent colors.
• Use this especially for fixed-content utility windows where a softer backdrop is part of the design.

Window Behavior

• Use .windowMinimizeBehavior(.disabled) for always-reachable utility windows such as a custom About window where minimizing adds little value.
• Disable the green zoom control through fixed sizing or window constraints when the window's content has one intended size.
• Use .restorationBehavior(.disabled) for windows that should not reopen on next launch, such as About panels, transient support/info windows, or first-run welcome surfaces.
• Keep state restoration enabled for primary document or navigation windows when reopening prior size and position is desirable.
• By default, SwiftUI respects the user's system-wide macOS state restoration setting. Use restorationBehavior(...) only when a specific window should intentionally opt into or out of that system behavior.
• Use .defaultLaunchBehavior(.presented) for windows that should appear first on launch, such as a welcome window, and choose that behavior intentionally rather than relying on side effects from scene creation order.

Window Placement

• Use .defaultWindowPlacement { content, context in ... } to control the initial size and optional position of newly opened windows.
• Inside the placement closure, call content.sizeThatFits(.unspecified) to get the content's ideal size.
• Read context.defaultDisplay.visibleRect to get the display's usable region after accounting for the menu bar and Dock.
• Return WindowPlacement(size: size) with a size clamped to the visible rect when media or document content may be larger than the display. If no position is provided, the window is centered by default.
• Use .windowIdealPlacement { content, context in ... } to control what happens when the user chooses Zoom from the Window menu or Option-clicks the green toolbar button. For media windows, preserve aspect ratio and grow to the largest size that fits the display.
• Treat default placement and ideal placement as separate policies:
  • default placement controls where a new window first appears,
  • ideal placement controls how large a zoomed window should become.
• Always consider external displays and rotated/narrow screens when sizing player windows or document windows from content dimensions.

Borderless And Specialized Windows

• Use .windowStyle(.plain) for borderless or highly custom chrome windows, but make sure the content still provides a clear drag/move affordance and visible context.
• For a borderless player, HUD, or welcome window, decide upfront whether losing standard titlebar affordances is worth the custom presentation.
• Keep one clear path back to regular window management if the plain style makes the window feel invisible or hard to move.

For concrete window modifier examples, read references/api-snippets.md.

Review Checklist

• The scene type matches the window's role and lifecycle.
• Hidden titles still leave a meaningful logical title for accessibility and menus.
• Toolbar background removal is intentional and does not hurt titlebar legibility or window control placement.
• Windows with hidden or removed toolbars still have a reliable drag region and support click-then-drag activation from the background.
• Utility windows have restoration/minimize behavior that matches their purpose.
• Restoration overrides are used only when a scene should intentionally differ from the user's system-wide setting.
• Default and ideal placement use content.sizeThatFits(.unspecified) and context.defaultDisplay.visibleRect when content/display size matters.
• Media windows preserve aspect ratio and fit on small or rotated displays.
• Borderless windows still have a usable move/drag affordance.

Guardrails

• Do not use .toolbar(removing: .title) just to hide a title you forgot to set. Keep the underlying window title meaningful.
• Do not hide the toolbar background or the whole toolbar without replacing the lost drag affordance.
• Do not disable restoration on the main document/navigation window unless the user explicitly wants a fresh-start app every launch.
• Do not hardcode one monitor size or assume a single-display setup when sizing player windows.
• Do not reach for NSWindow mutation before checking whether .windowMinimizeBehavior, .restorationBehavior, .defaultWindowPlacement, .windowIdealPlacement, .windowStyle, or .defaultLaunchBehavior already solve the problem.
• Do not leave a plain borderless window without any obvious drag or close path.

When To Use Other Skills

• Use swiftui-patterns for broader scene, commands, settings, sidebar, and inspector architecture.
• Use liquid-glass when the main question is modern macOS visual treatment, Liquid Glass, or system material adoption.
• Use appkit-interop if a custom window behavior truly requires NSWindow, NSPanel, or responder-chain control.
• Use build-run-debug to launch and verify the resulting windows.

Frontend App Builder

Use this skill to create polished frontend apps, dashboards, games, creative websites, hero sections, redesigns, and other visually driven UI. Act first as a senior front-end designer, then as an engineer implementing an approved design spec.

Core Standard

The two priorities of this skill outrank everything else:

1. Create enough great-looking Image Gen design first: clean, airy, distinctive, complete, readable, section-specific when needed, and not repetitive by default.
2. Do not stop until the accepted design and browser implementation match 10/10. Keep fixing visual, interaction, responsive, asset, and typography mismatches until view_image comparison would pass agency sign-off.

Hard Rules

1. Use Image Gen for the visual concept unless the user explicitly opts out or the task is a small UI fix inside an existing design system.
2. Design the complete requested surface before coding. For a full page, app, dashboard, game, or product interface, a header or hero concept is not enough. For multi-section websites and long landing pages, prefer coordinated section-by-section concepts, plus an optional overview for rhythm, over one tall image that loses detail. For apps, dashboards, games, or compact product surfaces, generate the full primary screen plus any needed state, responsive, or asset concepts first.
3. Inside Codex, default multi-section website concepting to one fresh, large, readable Image Gen screenshot per major section. If the request has 1-10 sections, expect roughly 1-10 primary section images. Generate additional section/detail screenshots whenever text, buttons, card anatomy, typography, spacing, or colors are too small to extract. Do not crop or zoom an old full-page image as the main reference; regenerate a fresh standalone section or detail image that preserves the same design system.
4. In Plan mode, generate the design first, then use request_user_input to get design approval before planning implementation details.
5. Once accepted, the concept is a production design spec. No creative liberties during implementation: do not reinterpret layout, visible copy, hierarchy, container model, styling, imagery, density, or sections unless the user approves it or a concrete blocker requires it. General design heuristics never override the accepted concept.
6. The completion bar is agency-signoff faithful implementation: 10/10 fidelity to the accepted spec plus production-quality code. If the browser-rendered UI would receive design-review comments, keep fixing it.
7. Before coding, build a small design system from the accepted image: tokens, typography, component families, variants, spacing, icon treatment, and container rules. Include both content typography and UI chrome typography for tools, editors, and dashboards. Implement from that system so repeated elements stay consistent.
8. For new complex app UIs such as dashboards, admin tools, editors, data-heavy tools, and multi-panel product surfaces, default to React + Vite unless the user specifies another framework, the existing repo already dictates one, or the task is explicitly a single-file/static deliverable.
9. Hero eyebrow, kicker, pretitle, badge, or pill labels above the main heading are prohibited by default. Use one only when the user explicitly requested it or the accepted/reference design already contains it.
10. Verify in the Browser plugin / built-in browser first. Use Playwright Chromium only when Browser/IAB is unavailable or unreliable, and state the fallback reason.
11. Final handoff is blocked until you use view_image on both the accepted concept and the latest browser screenshot. This cannot be skipped or replaced with browser inspection alone. Judge the pair directly: is this agency-signoff faithfully implemented, and would a great, highly skilled design agency sign off on this exact implementation of the accepted design? If not, keep fixing.
12. Remove temporary QA artifacts before handoff unless the user or task explicitly asks to keep them.

Coordinate With Other Installed Skills

This skill owns visual concepting and faithful frontend implementation. Use other installed skills when the app needs capabilities outside frontend design. Provider setup should not block Image Gen concepting, static UI work, or design review that does not exercise provider-backed behavior, but implementation and verification of provider-backed behavior should coordinate through the installed skill for that capability. Avoid placeholder setup instructions when another installed skill covers that setup.

For AI/model-generated output, use openai-developers:openai-platform-api-key when available unless the user names another provider or explicitly says not to use OpenAI. When that skill is available, always use its credential flow instead of fake keys, placeholder env vars, or manual API-key setup instructions.

Image Gen Workflow

Read and follow the installed @imagegen skill. For website-specific briefing guidance, use references/imagegen-website-concepts.md.

Before calling Image Gen:

• Copy the user's concrete requirements into the brief: product/page purpose, audience, required sections or states, workflow, supplied copy, nav labels, CTA labels, data fields, required media, responsive needs, and implementation constraints.
• Ask for the complete requested surface: full page, app screen, dashboard, game screen, or coordinated section/state set. If the deliverable is more than a hero, say the concept must include downstream sections, states, or responsive continuation. If the section count is known or implied, name each section/state that needs its own concept screenshot.
• Repeat the implementation constraints: code-native app UI text and controls, fully rendered product/background assets with their own text and branding when appropriate, separable assets, reusable component families, intentional container model, no default card grids, no invented hero eyebrows/kickers/badges/pills, and practical HTML/CSS/component implementation.
• Preserve information architecture from user content, screenshots, or existing apps. Do not let Image Gen invent unrelated sections, fake metrics, new product claims, extra dashboards, new navigation, or a different product story.
• For multi-section websites or long landing pages, default to one coordinated concept image per major section. Use an optional overview only for structure and rhythm; never rely on one giant compressed board when it makes text, button details, card structure, spacing, or typography hard to analyze.
• For dense apps, dashboards, editors, product surfaces, and complex sections, generate separate state or detail concepts for the areas that would become unreadable in a single full-screen image: tables, sidebars, inspectors, modals, toolbars, charts, forms, cards, pricing blocks, testimonials, or media modules.
• If any concept screenshot is too small, blurry, cropped, crowded, or ambiguous for implementation, generate a fresh standalone section/state/detail screenshot before coding. Keep the same palette, typography mood, component family, asset treatment, density, and section order. Do not crop, slice, zoom, or reuse a tiny part of an earlier image as the source of truth.
• For games, plan a dedicated Image Gen asset pass in addition to the concept: transparent character/state sprites or sprite sheet, terrain/platform tiles, collectibles, hazards, goal/checkpoint objects, props, and 2-3 parallax/background layers when the environment has depth. HUD text, scoring, controls, physics, and collision remain code-native.

Reject or iterate on concepts that are header-only for a full-surface ask, cluttered, generic, repetitive, under-specified, unreadable, over-decorated, off-spec with hero eyebrows/kickers/badges/pills not explicitly requested or present in the reference, or not practical to implement faithfully.

Design Quality Bar

The concept should look like a professional product mockup by a senior product designer:

• One clear creative idea or visual point of view.
• Strong first viewport with clear offer, product signal, and primary action.
• Full-page rhythm: sections, states, transitions, and mobile views feel designed as one system, without repetitive card stacks or repeated section formulas.
• Cohesive section-to-section flow: connect sections with shared spacing, palette, type rhythm, media treatment, and subtle transitions, not by inventing major new UI components.
• Excellent typography: clear hierarchy, scale, weight, line height, label treatment, and control/chrome text that never falls back to browser-default sizing.
• Intentional whitespace and density; no filler cards, hero eyebrow/kicker labels, pills, badges, fake metrics, or icon rows unless explicitly requested or present in the accepted design.
• Simpler by default: use fewer, stronger visual elements instead of filling the page with illustrations, iconography, decorative widgets, or complex UI chrome.
• Coherent visual system: palette, spacing, radius, borders, shadows, gradients, icon style, imagery, and component geometry.
• Icon fidelity matters when icons are present. Match the accepted design's icon metaphor, stroke weight, fill style, corner shape, size, color, alignment, and spacing instead of swapping in generic nearby icons.
• Color fidelity is mandatory. Match the accepted design's actual background, surface, text, border, shadow, and accent colors; if the design uses a white background, use white rather than cream, ivory, beige, warm gray, or any softened off-white substitute.
• Hero media treatment must match the accepted design. If the hero image has no color overlay or tint in the concept, the implementation must not add one. Use edge fades, masks, or background gradients only to blend image edges into the page; do not wash the image with a color overlay.
• High-quality generated assets for logos, brand marks, hero imagery, product renders, background scenes, illustrations, textures, posters, avatars, empty states, and game sprites/tiles/background layers. Product/background assets should be fully rendered with consistent branding and in-image text when that text belongs to the asset.
• Purposeful motion that clarifies hierarchy, reveals state, or makes the product feel tangible.
• Specific, non-generic copy when the user has not provided exact copy.

Default to clean, airy, tasteful 7/10 creativity: distinctive enough to feel designed, restrained enough to build, and not repetitive. Interpret "clean" as edited and legible, not empty or sterile.

Visual Direction Defaults

Use these defaults when the user has not given stronger art direction. Adapt them to the product type instead of forcing every app into a marketing-site style.

• Baseline: roughly 7/10 creativity, low-to-medium density, generous spacing, high implementation clarity, high typography discipline, and image-led moments when the domain benefits from real visuals.
• Before generating concepts, choose a coherent visual direction: one theme paradigm, background character, typography character, hero or primary-screen architecture, section/app rhythm, 2-4 signature component motifs, and 1-2 motion cues. Commit to the combination so the design feels intentional instead of a generic template.
• Hero or first viewport: keep one obvious focal point, a short readable headline or primary task, restrained supporting copy, a visible primary action, and enough negative space to work on a small laptop. Do not overcrowd the opening view with stats, chips, badges, fake controls, or competing mini-panels.
• Header simplicity: default to a clean brand mark, essential navigation, and one primary action or control. Avoid icon-heavy nav, extra buttons, search bars, status widgets, segmented controls, decorative illustrations, or dense product chrome in the header unless the user explicitly asks for them or the product workflow requires them.
• Visual economy: prefer one or two high-quality image or illustration moments over many small decorative visuals. Use iconography only where it clarifies navigation, controls, or product meaning.
• Container discipline: avoid nested cards, giant rounded wrappers around every section, default bento/card grids, and over-framed dashboards unless the concept or product type truly needs them. Prefer open layouts, bands, rails, lists, tables, canvases, or a single purposeful framing move.
• Section rhythm: long pages should vary density, image-to-text ratio, alignment, scale, whitespace, and visual tempo while keeping one coherent brand system. Do not repeat the same centered block or left-text/right-card formula through the whole page.
• Section continuity: when multiple section concepts need to become one page, use connective tissue from the existing design system: gutters, bands, alignment, repeated typography, recurring media frames, color rhythm, and small transitional spacing shifts. Do not invent major new carousels, accordions, pricing cards, dashboards, forms, nav systems, feature grids, or other component families unless the user requested them or the accepted concepts show them.
• Media framing: generated imagery should usually sit in clear, implementation-friendly frames with stable aspect ratios, consistent crop logic, radius, shadows, and spacing. Avoid random image sizes or collage chaos unless the user explicitly asks for that direction.
• UI restraints: small labels, utility pills, pseudo-system markers, fake metrics, and decorative dashboard jargon are allowed only when they clarify the product. If they are just visual filler, remove them before acceptance.

Concept Review Mode

Use only when the user asks to generate concepts first, review options, or wait for approval.

• Generate and show the concept.
• Iterate until the user approves.
• Do not implement while the user is still reviewing.
• Once approved, treat the concept as the active spec and follow the fidelity workflow below.

Before Coding

Turn the accepted concept into a design system and implementation inventory before coding:

• Exact visible copy, nav items, CTA labels, section headings, proof points, data labels, and important UI text.
• Per-section/state image inventory: source concept screenshot, native aspect, visual priority, readable text, typography relationships, spacing, button/control styling, component/container rules, dominant colors, and any unresolved details that required a fresh extraction screenshot.
• Allowed above-the-fold copy list: every visible hero, nav, eyebrow/kicker/pretitle, badge/pill, CTA, label, and proof string allowed from the accepted concept or user-provided copy.
• First viewport composition, section order, downstream states, responsive continuation, and next-section preview.
• Section continuity plan: how adjacent sections connect using the accepted design system, and which major component families are allowed. Treat unshown major components as prohibited unless the user requested them or a required workflow cannot function without them.
• Brand mark, imagery roles, product mockups, dashboards, tables, charts, maps, media rails, forms, HUDs, or other visual artifacts.
• Hero/media treatment inventory: whether each image has no overlay, a color overlay, a gradient overlay, edge fade, mask, transparent background, or matching background color. Record this explicitly before coding.
• Standalone asset needs: if the concept includes a logo, brand mark, product label, packaging, poster, sign, product render, or branded background object, create matching standalone assets with Image Gen editing before implementation so branding stays coherent.
• Game asset needs: if the concept is a game, create matching production art assets with Image Gen before implementation. Include transparent sprite/state assets, tiles/platforms, collectibles, hazards, goal objects, props, and parallax/background layers as needed; use code for collision boxes and game state, not as a substitute for visible art.
• Design tokens sampled or approximated from the image: background, surface, text, muted text, border, shadow, accent, semantic colors, radii, elevation, spacing scale, and motion timing.
• Color lock: explicitly identify whether the concept background is true white, off-white, cream, gray, dark, or tinted, then implement that exact choice. Do not warm up, cool down, mute, or otherwise "tastefully" reinterpret the palette.
• Typography system: font family/fallback, type scale, weights, line heights, tracking, label treatment, heading/body/caption styles, control text styles, and responsive type behavior.
• Icon inventory: every visible icon, glyph, chevron, logo-like mark, toolbar symbol, status symbol, and empty-state symbol; record meaning, source family, outline vs filled style, stroke width, size, color, container, alignment, spacing, and selected/hover/disabled treatment.
• Component families and variants: buttons, navigation, rows, panels, media frames, product mockups, cards only where present, tables, forms, chips, icons, empty states, responsive variants, hover/focus/selected states.
• Component architecture plan for complex app UIs: app shell, navigation, major feature regions, reusable UI primitives, data/state helpers, chart/table/form modules, asset modules, and responsive layout boundaries. A great front-end implementation should have clear component ownership, not one giant App component or one-off copied markup.
• Container model: cards, panels, rails, bands, lists, tables, canvases, drawers, sidebars, modals, or full-bleed sections.
• Core workflow: controls that must respond, selected states, filters, tabs, edits, creation flow, success state, playback, game controls, or generated-result demo.

If the concept omits required downstream sections, states, mobile views, or readable detail for a complex area, generate matching section/state/detail concepts when visual consistency or extraction is uncertain. Otherwise extend in the exact same visual system.

Implementation

• Build the real usable surface first, not a marketing wrapper around a future app.
• Follow the repo's framework, routing, component, styling, state, accessibility, and asset conventions.
• When creating a new complex app UI without an existing framework constraint, use React + Vite by default. Structure it like a senior front-end engineer would: small focused components, a clear app shell, reusable primitives for repeated controls, feature-specific modules for dashboards/tables/charts/forms, separated sample data and state helpers, and shared tokens/styles. Keep App as composition glue instead of a monolithic screen implementation.
• Implement through the design system extracted from the image. Similar elements must use the same component or shared style primitive; differences should be explicit variants, not one-off copied CSS.
• Implement the accepted concept exactly. Preserve copy, hierarchy, section order, density, colors, typography, spacing, radii, borders, shadows, asset framing, and interaction model.
• For multi-section pages, implement in slices that match the accepted section concepts. Start with the first viewport, compare its browser screenshot to the section concept, fix visible drift, then continue section by section. Do not defer all visual comparison until the whole page is coded, and do not merge or simplify section-specific design decisions just because a broad overview image is easier to follow.
• Connect sections into one cohesive page without adding unapproved major UI components. Use spacing, background bands, alignment, typography rhythm, repeated motifs, and media framing to bridge gaps. Do not invent new carousels, accordions, pricing blocks, dashboards, forms, tab systems, feature-card grids, or other large components to make the page feel complete unless they appear in the accepted concept, were requested by the user, or are recorded as a concrete functional necessity.
• Do not add new visible above-the-fold copy, hero eyebrows/kickers, explanatory labels, subtitles, or category text after concept acceptance unless it appears in the accepted concept, came from the user, or is recorded as an intentional deviation. If semantic HTML, SEO, or accessibility requires changing an H1 or heading level, change the element semantics first; do not invent compensating visible copy.
• Do not add decorative hero eyebrow labels, pills, badges, gradients, glows, or overlays that were not in the accepted design. Do not substitute a gradient treatment unless it matches the concept's palette, direction, intensity, and placement. If the accepted hero image has no color overlay, do not add a translucent tint, wash, or colored layer over it. If the image needs help blending into a non-matching page background, use a matching asset, transparent cutout, edge fade, mask, or background gradient around the image rather than a color overlay on top of the image. Do not replace white backgrounds with cream/off-white or otherwise shift the accepted color temperature.
• Define typography on controls deliberately. Do not rely on browser defaults or inherited 16px sizing for buttons, tabs, inputs, toolbars, sidebars, inspector panels, layer rows, status bars, command palettes, or export/share controls.
• Preserve the container model. Do not add cards, bordered panels, floating containers, tiles, or card grids where the spec uses open whitespace, bands, rails, lists, tables, canvases, or full-bleed composition.
• Keep real interactive app UI text, navigation, buttons, forms, tables, controls, and labels code-native. This does not apply to text and branding that belong inside product images, posters, packaging, signs, background scenes, hero photos, or other raster assets. Do not ship a static screenshot as UI.
• Use Image Gen for central non-icon assets. Render product images and background assets completely with the needed text, logos, marks, labels, packaging, signage, and branding. When the asset must layer into the UI, request a transparent background or clean cutout. Quote exact asset text and require verbatim rendering when text matters.
• If the accepted design includes branded product imagery, use Image Gen editing to create standalone versions of the logo/product/packaging/signage assets from the concept or a matching asset pass. Include transparent-background variants when those assets need to layer into the UI. Do not rebuild branded raster assets from generic CSS, mismatched fonts, or approximate labels.
• For games, use Image Gen for visible production art: character/state sprites or sprite sheets, terrain/platform tiles, collectibles, hazards, goals/checkpoints, foreground props, and parallax/background layers. Do not fall back to canvas-drawn shapes because collision, scaling, or animation is simpler. Keep HUD text, score, controls, hit boxes, physics, and game state code-native, and tune collision geometry to the rendered assets. Any code-drawn or vector game art must be listed as an intentional deviation or concrete blocker.
• Do not replace concept assets with rough CSS drawings, generic gradients, placeholder SVGs, or stock-like crops. Images must sit naturally in the composition: background color, lighting, edges, crop, shadow, and transparency should blend with the surrounding design. SVG is fine for faithful icons and directional glyphs.
• Use SVG/icon components for arrows, chevrons, carets, disclosure indicators, pagination arrows, and carousel arrows; do not use plain text glyphs unless the concept intentionally does.
• Implement icons as faithfully as other visual elements. Prefer the repo's existing icon set or lucide only when it matches the accepted design's style; otherwise create a small custom SVG/icon variant that matches the concept. Custom SVG icons must be production-quality vector assets: clear viewBox, clean geometry, consistent stroke widths, aligned joins/caps, balanced negative space, optical centering, scalable paths, no jagged or placeholder-looking shapes, and currentColor or explicit fills only when they match the design system. Do not replace filled icons with outline icons, rounded icons with sharp icons, thick strokes with thin strokes, or specific metaphors with generic symbols. Keep icon color, optical size, baseline alignment, padding, and interactive states consistent with the extracted icon inventory.
• Make app interfaces experiential: local state, meaningful selected states, working filters/tabs/forms, editable or creatable items, success states, playback controls, game controls, or simulated generated output where appropriate.
• Use interactive UI inside a hero only when it genuinely fits: SaaS/software product previews, product demos, or purposeful interactive animation. Do not force fake interactive chrome into a branded, editorial, product, venue, food, consumer, or background-led hero. Faithful implementation and consistent branding are more important than adding interactivity.
• Add motion only where it supports the design. Respect accessibility and prefers-reduced-motion.
• Keep implementation production-oriented: semantic markup, stable responsive dimensions, no fragile hardcoded hacks, and type/lint/test checks when the repo supports them.

Verification

Run the app and verify the visible product, not just the build.

1. Use Browser/IAB first. Load the app, inspect the first viewport, scroll, and click through the core workflow.
2. Check desktop, current browser viewport, and a mobile-sized viewport.
3. Capture or locate the accepted concept and the latest implementation screenshot. Use view_image on both in the same QA pass before final handoff; do not skip this step or substitute a browser glance for it.
4. Capture the implementation at the accepted concept's native dimensions when practical. If not practical, record the blocker and also verify the current browser viewport.
5. Write a fidelity ledger before final: mismatch, concept evidence, render evidence, and fix made or reason not fixed. For multi-section or multi-state specs, include evidence from the relevant section/state concept screenshots, not only the overview. Inspect at least five concrete comparison points covering copy, layout, typography, palette/gradients, asset treatment, spacing/container model, responsive behavior, or motion.
6. Compare side by side for copy, nav, CTA labels, section order, first-viewport balance, next-section visibility, palette, gradient treatment, font personality, type scale, spacing, borders, radii, container model, asset/background blending, motion, and simulated interactions.
7. Run an above-the-fold copy diff against the allowed copy list. Added, removed, renamed, or reordered visible copy must be fixed or listed as an intentional deviation; unapproved additions fail fidelity.
8. Audit typography everywhere, not just the hero or main canvas. Check headings, body, captions, labels, toolbar controls, sidebar rows, tabs, inputs, inspector fields, status bars, command palettes, export/share buttons, table cells, chart labels, and mobile line breaks. Use computed CSS sizes/weights/line-heights when the screenshot suggests drift.
9. Audit icons wherever they appear: nav, buttons, cards, toolbar controls, sidebars, tables, status indicators, empty states, pagination, carousels, and mobile controls. Check metaphor, stroke/fill style, size, color, alignment, optical weight, spacing, and state changes against the accepted concept.
10. For canvas/editor apps, audit app chrome separately from canvas/document text. Default zoom and pan are part of the spec; persisted local state must not hide seed, scale, or typography fixes during verification.
11. Ask explicitly: is this agency-signoff faithfully implemented, and would a great, highly skilled design agency sign off on this exact implementation of the accepted design? If anything would get a design-review comment, write a concrete repair checklist and keep editing. Do not final-answer with fixable visual issues.
12. Verify generated assets load, are framed correctly, and do not obscure text or controls.
13. Verify the core workflow updates real local UI state. Do not ship inert controls, fake media progress, hidden required media, or placeholder interactions.

Functional QA does not count as fidelity QA. Passing build checks, clicking controls, or verifying local state cannot replace the concept-to-screenshot comparison, native-size check, and written mismatch ledger.

Hard stops: clipped primary content, accidental wrapping, prototype-looking layout, rough seeded data, placeholder boxes, generic stock-like assets, unfinished cards, code-drawn game placeholders replacing concept art, invented visible copy, invented hero eyebrows/kickers/pills/badges, mismatched colors or gradients, white backgrounds changed to cream/off-white, unapproved hero image color overlays or tints, missing or generic substituted icons, mismatched icon style or stroke weight, images that do not blend with the background, stale debug artifacts, unreadable text, type-scale drift, browser-default control typography, mobile overflow, unprofessional responsive collapse, or any visible drift from the accepted spec.

Surface Gates

• Landing/company sites: preserve first viewport, hero role, brand/nav/CTA labels, section order, next-section preview, and signature imagery.
• Product/SaaS pages: preserve product mockups, workflow diagrams, feature strips, proof elements, and brand treatment.
• Dashboards/tools: preserve density, sidebars, headers, tables, tabs, timelines, charts, maps, row counts, and selected/detail behavior. Do not turn table-driven concepts into card grids.
• Canvas/editor tools: preserve default zoom/pan, canvas/document text scale, chrome density, toolbars, sidebars, inspector controls, layer rows, status bars, command surfaces, and autosaved/seed-state behavior.
• Timeline/planning tools: preserve grid/time-axis anatomy, row spans, event density, status rails, and command-center fit.
• Clone-like interfaces: preserve the recognizable skeleton before adding polish. Do not add marketing heroes or custom navigation that breaks the product type.
• Games: preserve the art direction with Image Gen assets for sprites, tiles/platforms, collectibles, hazards, goals/checkpoints, props, and background/parallax layers. Verify assets load, scale, animate or swap state correctly, align with collision geometry, and support movement, action/jump/drag behavior, scoring, hazards, and restart.
• Media surfaces: verify real media load, duration, play/pause, seek/progress, and visible frame changes.
• Forms/booking/purchase/restaurant flows: verify the main transaction path and confirmation state.

Final Response

Include the accepted concept path, rendered screenshot method, Browser/IAB verification method or Playwright fallback reason, view_image inspection of the accepted concept and latest implementation screenshot, native-size viewport checked or blocker, at least five inspected comparison points, above-the-fold copy diff result, remaining intentional deviations, and an explicit statement that the implementation was faithfully verified against the accepted design. Also include material mismatches fixed and core interaction path verified. If no material mismatches remain, say so directly.

Frontend Testing Debugging

Invocation Contract

This skill should work from normal user prompts. Do not require the user to spell out Browser routing, screenshots, report shape, or fallback policy.

Use this skill when the user asks to use the Build Web Apps plugin, web dev plugin, frontend dev plugin, or frontend testing/debugging skill for a rendered frontend change, test, or bug investigation.

Examples that should trigger this full workflow:

• please make an improvement to the web dashboard transaction search area and use the web dev plugin
• use the frontend dev plugin to polish this dashboard
• debug this UI with the Build Web Apps plugin
• test this localhost app and fix the broken interaction

From a brief prompt, infer the target surface from the repo, currently open app/browser URL, nearby files, or running dev server. If the target URL is unclear, inspect the repo scripts and running local ports before asking the user.

For any code change to a rendered frontend surface, do the validation loop by default:

1. Identify the target flow.
2. Choose the Browser path below.
3. Make the smallest useful edit.
4. Validate the rendered behavior.
5. Reply with the QA final response report.

Choose The Browser Path

First classify Browser availability:

• Available: the Browser plugin and its browser skill are listed in the session. Read and follow that skill before any browser action.
• Absent: the Browser plugin or browser skill is not listed. Use regular Playwright and record Browser plugin not available.
• Invocation failed: Browser appears available, but the skill/runtime, Node REPL JavaScript setup, tab acquisition, or navigation fails. Treat this as a Browser-path blocker.

Do not use regular Playwright, external Chrome, or shell open first when Browser is available.

Only switch from a failed Browser invocation to regular Playwright if the user already allowed fallback or the task explicitly permits non-Browser validation. In that case, report the exact Browser failure and the fallback decision.

Target Flow

Before browser validation, define the target flow in one sentence:

The flow under test is: [entry route] -> [user action or state] -> [expected rendered result].

If the user asked for general smoke testing, use:

The flow under test is: app loads -> first meaningful screen renders -> primary visible controls respond without runtime errors.

Browser Plugin Loop

Run Browser commands through the Node REPL JavaScript tool described by the Browser skill. Do not invent a separate browser setup path. Keep using the same tab binding unless the Browser skill says otherwise.

Required sequence:

1. Load the Browser runtime exactly as the Browser skill instructs.
2. Name the session with agent.browser.nameSession("...").
3. Acquire a tab with agent.browser.tabs.selected() or agent.browser.tabs.new().
4. Navigate with tab.goto(url).
5. Run the required checks below.
6. Interact with scoped tab.playwright locators or Browser skill interaction APIs.
7. After edits, call await tab.reload(), then repeat the checks and the failing interaction.

For each UI-changing action, collect the cheapest proof that the next state is correct: fresh DOM snapshot, visible text/state, URL change, focused control, toast, modal, screenshot, or console log.

Required Browser Checks

Run these checks before claiming the rendered app works:

1. Page identity: await tab.url() and await tab.title() match the intended page.
2. Not blank: await tab.playwright.domSnapshot() contains meaningful app content, not an empty shell.
3. No framework overlay: the snapshot or screenshot does not show a Next.js, Vite, Webpack, or framework error overlay.
4. Console health: await tab.dev.logs({ levels: ["error", "warn"], limit: 50 }) has no relevant app errors, or each relevant error is explained.
5. Screenshot evidence: await display(await tab.playwright.screenshot({ fullPage: false })) supports visual claims.
6. Interaction proof: at least one target-flow interaction is exercised and followed by a state check.

For visual work, add desktop plus one mobile-sized viewport when practical. For reference-driven work, keep a short mismatch ledger: reference evidence, rendered evidence, fix or intentional deviation.

Playwright Loop

Use this branch when Browser is not available, or when the user has allowed fallback after a Browser invocation failure.

Use this order:

1. Find scripts in package.json.
2. Start the app with the repo's package manager and keep the requested host exact.
3. Prefer the repo's e2e script if present.
4. Otherwise run pnpm exec playwright test or the package-manager equivalent when Playwright is configured.
5. If there is no project Playwright workflow, verify Playwright with pnpm exec playwright --version, then capture a screenshot with pnpm exec playwright screenshot <url> /tmp/frontend-check.png.
6. For deeper debugging, create a small temporary Playwright script outside committed source that opens the URL, captures console errors, screenshots, and runs the target interaction.
7. After edits, rerun the same command or script.

Do not install new browser dependencies unless the task requires it and the user has allowed dependency changes.

Validation Checklist

• Keep the requested host exact.
• Verify controls update real UI state.
• Check the first viewport before scrolling, plus desktop and one mobile-sized viewport when practical.
• Look for clipping, overlap, unreadable text, wrapping, layout shift, missing assets, z-index issues, scroll traps, stale loading, and broken states.
• For reference-driven work, compare the rendered screenshot against the reference and keep a short mismatch ledger.
• A passing build is not enough when rendered validation was requested.

QA Final Response Report

For any non-trivial rendered UI validation run, write the final response like a QA engineer verifying a code change. The response should make it easy for the user or PR reviewer to understand what changed, what was tested, what evidence proves it, and what remains untested.

Use this shape:

• Summary: one or two bullets explaining the user-visible change and whether QA passed.
• Environment: URL, viewport(s), Browser availability classification, and fallback reason if Playwright was used.
• Changes Verified: files or surfaces changed, plus the specific user-facing behavior expected.
• Checks: a pass/fail table for page identity, blank-page check, framework overlay check, console health, screenshot evidence, and interaction proof.
• Interaction Loop: exact interaction path tested, including the control or workflow exercised and the observed state change.
• Evidence: describe the screenshot evidence in the QA sections, then place the actual screenshots together at the end of the response as consecutive images. Include as many screenshots as are useful to prove the relevant before, after, interaction, responsive, error, or fixed states.
• Commands / Browser APIs: list the key command and Browser API sequence used, without dumping noisy logs.
• Remaining Risk: untested viewports, flows, browsers, data states, or known limitations.

If issues were found, lead with Findings before the summary. Each finding should include what the user sees, reproduction steps, screenshot/DOM/console evidence, likely owner or file when known, and the fix made or remaining blocker.

When using Browser screenshots that should be shown to the user, emit or display the screenshot through the Browser runtime so it can be referenced in chat. When using Playwright screenshots, save them outside the repo and reference them in chat. Include multiple screenshots when they help verify distinct states or flows.

Do not interleave screenshots throughout the written report. Put a short Screenshots section at the very end, and make it a consecutive image gallery with one image per line. Add short labels only when they clarify the state, for example Before, After, Filtered results, Empty state, or Mobile.

Do not create separate HTML reports by default. Only create a standalone report file when the user explicitly asks for one, and write it outside the repo unless the user explicitly asks for committed artifacts.

Do not write reports, screenshots, traces, or temporary scripts into the repo unless the user explicitly asks for committed artifacts.

Related Skills

• Use frontend-app-builder when the task is design creation, redesign, or fidelity to an accepted concept.
• Use react-best-practices after meaningful React/Next.js component edits.
• Do not invoke Image Gen for ordinary debugging. Use it only when the task requires creating or revising visual assets, or when frontend-app-builder is already driving a concept-to-implementation fidelity loop.

Final Response

Use the QA final response report format above. Keep it concise, but include enough concrete evidence that a PR reviewer can trust the validation without rerunning it immediately.

If Browser was absent and Playwright was used, end by suggesting that the user install the Browser plugin for a better frontend development experience with in-app navigation, screenshots, DOM snapshots, console logs, and interaction validation.

Vercel React Best Practices

Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 64 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new React components or Next.js pages
• Implementing data fetching (client or server-side)
• Reviewing code for performance issues
• Refactoring existing React/Next.js code
• Optimizing bundle size or load times

Rule Categories by Priority

Quick Reference

1. Eliminating Waterfalls (CRITICAL)

• async-defer-await - Move await into branches where actually used
• async-parallel - Use Promise.all() for independent operations
• async-dependencies - Use better-all for partial dependencies
• async-api-routes - Start promises early, await late in API routes
• async-suspense-boundaries - Use Suspense to stream content

2. Bundle Size Optimization (CRITICAL)

• bundle-barrel-imports - Import directly, avoid barrel files
• bundle-dynamic-imports - Use next/dynamic for heavy components
• bundle-defer-third-party - Load analytics/logging after hydration
• bundle-conditional - Load modules only when feature is activated
• bundle-preload - Preload on hover/focus for perceived speed

3. Server-Side Performance (HIGH)

• server-auth-actions - Authenticate server actions like API routes
• server-cache-react - Use React.cache() for per-request deduplication
• server-cache-lru - Use LRU cache for cross-request caching
• server-dedup-props - Avoid duplicate serialization in RSC props
• server-hoist-static-io - Hoist static I/O (fonts, logos) to module level
• server-serialization - Minimize data passed to client components
• server-parallel-fetching - Restructure components to parallelize fetches
• server-after-nonblocking - Use after() for non-blocking operations

4. Client-Side Data Fetching (MEDIUM-HIGH)

• client-swr-dedup - Use SWR for automatic request deduplication
• client-event-listeners - Deduplicate global event listeners
• client-passive-event-listeners - Use passive listeners for scroll
• client-localstorage-schema - Version and minimize localStorage data

5. Re-render Optimization (MEDIUM)

• rerender-defer-reads - Don't subscribe to state only used in callbacks
• rerender-memo - Extract expensive work into memoized components
• rerender-memo-with-default-value - Hoist default non-primitive props
• rerender-dependencies - Use primitive dependencies in effects
• rerender-derived-state - Subscribe to derived booleans, not raw values
• rerender-derived-state-no-effect - Derive state during render, not effects
• rerender-functional-setstate - Use functional setState for stable callbacks
• rerender-lazy-state-init - Pass function to useState for expensive values
• rerender-simple-expression-in-memo - Avoid memo for simple primitives
• rerender-split-combined-hooks - Split hooks with independent dependencies
• rerender-move-effect-to-event - Put interaction logic in event handlers
• rerender-transitions - Use startTransition for non-urgent updates
• rerender-use-deferred-value - Defer expensive renders to keep input responsive
• rerender-use-ref-transient-values - Use refs for transient frequent values
• rerender-no-inline-components - Don't define components inside components

6. Rendering Performance (MEDIUM)

• rendering-animate-svg-wrapper - Animate div wrapper, not SVG element
• rendering-content-visibility - Use content-visibility for long lists
• rendering-hoist-jsx - Extract static JSX outside components
• rendering-svg-precision - Reduce SVG coordinate precision
• rendering-hydration-no-flicker - Use inline script for client-only data
• rendering-hydration-suppress-warning - Suppress expected mismatches
• rendering-activity - Use Activity component for show/hide
• rendering-conditional-render - Use ternary, not && for conditionals
• rendering-usetransition-loading - Prefer useTransition for loading state
• rendering-resource-hints - Use React DOM resource hints for preloading
• rendering-script-defer-async - Use defer or async on script tags

7. JavaScript Performance (LOW-MEDIUM)

• js-batch-dom-css - Group CSS changes via classes or cssText
• js-index-maps - Build Map for repeated lookups
• js-cache-property-access - Cache object properties in loops
• js-cache-function-results - Cache function results in module-level Map
• js-cache-storage - Cache localStorage/sessionStorage reads
• js-combine-iterations - Combine multiple filter/map into one loop
• js-length-check-first - Check array length before expensive comparison
• js-early-exit - Return early from functions
• js-hoist-regexp - Hoist RegExp creation outside loops
• js-min-max-loop - Use loop for min/max instead of sort
• js-set-map-lookups - Use Set/Map for O(1) lookups
• js-tosorted-immutable - Use toSorted() for immutability
• js-flatmap-filter - Use flatMap to map and filter in one pass

8. Advanced Patterns (LOW)

• advanced-event-handler-refs - Store event handlers in refs
• advanced-init-once - Initialize app once per app load
• advanced-use-latest - useLatest for stable callback refs

How to Use

Read individual rule files for detailed explanations and code examples:

rules/async-parallel.md
rules/bundle-barrel-imports.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

shadcn/ui

A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.

IMPORTANT: Run all CLI commands using the project's package runner: npx shadcn@latest, pnpm dlx shadcn@latest, or bunx --bun shadcn@latest — based on the project's packageManager. Examples below use npx shadcn@latest but substitute the correct runner for the project.

Current Project Context

!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "No shadcn project found. Run shadcn init first."}'`

The JSON above contains the project config and installed components. Use npx shadcn@latest docs <component> to get documentation and example URLs for any component.

Principles

1. Use existing components first. Use npx shadcn@latest search to check registries before writing custom UI. Check community registries too.
2. Compose, don't reinvent. Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
3. Use built-in variants before custom styles. variant="outline", size="sm", etc.
4. Use semantic colors. bg-primary, text-muted-foreground — never raw values like bg-blue-500.

Critical Rules

These rules are always enforced. Each links to a file with Incorrect/Correct code pairs.

Styling & Tailwind → styling.md

• className for layout, not styling. Never override component colors or typography.
• No space-x-* or space-y-*. Use flex with gap-*. For vertical stacks, flex flex-col gap-*.
• Use size-* when width and height are equal. size-10 not w-10 h-10.
• Use truncate shorthand. Not overflow-hidden text-ellipsis whitespace-nowrap.
• No manual dark: color overrides. Use semantic tokens (bg-background, text-muted-foreground).
• Use cn() for conditional classes. Don't write manual template literal ternaries.
• No manual z-index on overlay components. Dialog, Sheet, Popover, etc. handle their own stacking.

Forms & Inputs → forms.md

• Forms use FieldGroup + Field. Never use raw div with space-y-* or grid gap-* for form layout.
• InputGroup uses InputGroupInput/InputGroupTextarea. Never raw Input/Textarea inside InputGroup.
• Buttons inside inputs use InputGroup + InputGroupAddon.
• Option sets (2–7 choices) use ToggleGroup. Don't loop Button with manual active state.
• FieldSet + FieldLegend for grouping related checkboxes/radios. Don't use a div with a heading.
• Field validation uses data-invalid + aria-invalid. data-invalid on Field, aria-invalid on the control. For disabled: data-disabled on Field, disabled on the control.

Component Structure → composition.md

• Items always inside their Group. SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.
• Use asChild (radix) or render (base) for custom triggers. Check base field from npx shadcn@latest info. → base-vs-radix.md
• Dialog, Sheet, and Drawer always need a Title. DialogTitle, SheetTitle, DrawerTitle required for accessibility. Use className="sr-only" if visually hidden.
• Use full Card composition. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Don't dump everything in CardContent.
• Button has no isPending/isLoading. Compose with Spinner + data-icon + disabled.
• TabsTrigger must be inside TabsList. Never render triggers directly in Tabs.
• Avatar always needs AvatarFallback. For when the image fails to load.

Use Components, Not Custom Markup → composition.md

• Use existing components before custom markup. Check if a component exists before writing a styled div.
• Callouts use Alert. Don't build custom styled divs.
• Empty states use Empty. Don't build custom empty state markup.
• Toast via sonner. Use toast() from sonner.
• Use Separator instead of <hr> or <div className="border-t">.
• Use Skeleton for loading placeholders. No custom animate-pulse divs.
• Use Badge instead of custom styled spans.

Icons → icons.md

• Icons in Button use data-icon. data-icon="inline-start" or data-icon="inline-end" on the icon.
• No sizing classes on icons inside components. Components handle icon sizing via CSS. No size-4 or w-4 h-4.
• Pass icons as objects, not string keys. icon={CheckIcon}, not a string lookup.

CLI

• Never decode or fetch preset codes manually. Pass them directly to npx shadcn@latest init --preset <code>.

Key Patterns

These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above.

// Form layout: FieldGroup + Field, not div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validation: data-invalid on Field, aria-invalid on the control.
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Invalid email.</FieldDescription>
</Field>

// Icons in buttons: data-icon, no sizing classes.
<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>

// Spacing: gap-*, not space-y-*.
<div className="flex flex-col gap-4">  // correct
<div className="space-y-4">           // wrong

// Equal dimensions: size-*, not w-* h-*.
<Avatar className="size-10">   // correct
<Avatar className="w-10 h-10"> // wrong

// Status colors: Badge variants or semantic tokens, not raw colors.
<Badge variant="secondary">+20.1%</Badge>    // correct
<span className="text-emerald-600">+20.1%</span> // wrong

Component Selection

Key Fields

The injected project context contains these key fields:

• aliases → use the actual alias prefix for imports (e.g. @/, ~/), never hardcode.
• isRSC → when true, components using useState, useEffect, event handlers, or browser APIs need "use client" at the top of the file. Always reference this field when advising on the directive.
• tailwindVersion → "v4" uses @theme inline blocks; "v3" uses tailwind.config.js.
• tailwindCssFile → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
• style → component visual treatment (e.g. nova, vega).
• base → primitive library (radix or base). Affects component APIs and available props.
• iconLibrary → determines icon imports. Use lucide-react for lucide, @tabler/icons-react for tabler, etc. Never assume lucide-react.
• resolvedPaths → exact file-system destinations for components, utils, hooks, etc.
• framework → routing and file conventions (e.g. Next.js App Router vs Vite SPA).
• packageManager → use this for any non-shadcn dependency installs (e.g. pnpm add date-fns vs npm install date-fns).