Dev Skills & MCP Servers¶

Dev skills are modular commands that extend AI coding agents with specialized workflows for common development tasks. This page covers all available skills (internal and community-sourced) and the MCP servers integrated into the project.

How Skills Work¶

Skills live in .agents/skills/ and are agent-agnostic — any AI coding agent that supports the skill format can use them. For Claude Code specifically, .claude/skills/ is a symlink to .agents/skills/.

Each skill is a directory containing a SKILL.md file with YAML frontmatter (name, description, allowed-tools) and markdown instructions that teach the agent a specialized workflow.

Skill Sources¶

Source	Description	Examples
Internal	Built and maintained by the Rose team	`test-backend`, `pr-fix`, `rose-config-system`
Community	Downloaded from the internet (e.g. via `/find-skills`)	`supabase-security`, `visual-explainer`, `skill-creator`

Internal Skills¶

Skills built and maintained by the Rose team.

Testing & Quality¶

Skill	Command	Description	Status
Test	`/test`	Router that delegates to test-backend or test-frontend	Needs review
Test Backend	`/test-backend`	Run Python tests with pytest, parse failures, fix issues	Needs review
Test Frontend	`/test-frontend`	Run TypeScript tests with Vitest, parse failures, fix issues	Needs review
Test E2E	`/test-e2e`	End-to-end browser tests against local dev servers using agent-browser	Active
Mypy	`/mypy`	Run mypy type checking, parse errors, apply fixes. Auto-triggers after Python edits	Active
Smoke	`/smoke`	Run backend smoke tests	Active

Workflow & Git¶

Skill	Command	Description
PR Fix	`/pr-fix`	Address PR review comments, make fixes, reply, and resolve threads
Create PR	`/create-pr`	Push and create a PR with a title derived from actual changes
Commit	`/commit`	Generate and create a commit from current changes
Dependabot	`/dependabot`	Resolve Dependabot security alerts and PRs across the monorepo
Solve Linear Ticket	`/rose-solve-linear-ticket`	Implement Linear issues systematically with task tracking
Solve Chatbot Issues	`/rose-solve-chatbot-issues`	Batch-process [Chatbot] Linear issues: group by client, dispatch parallel subagents
Client-Facing Changelog	`/rose-client-changelog`	Generate changelog entries from recent git history for clients

Browser Integration¶

Skill	Command	Description
Agent Browser	`/agent-browser`	Browser automation CLI — navigate, snapshot, interact, screenshot pages
Browse Playground	`/rose-browse-playground`	Access preprod-ui via Playwright (port 3001)
Browse Demo Page	`/rose-browse-demo-page`	Access widget demo page via Playwright (port 8083)
Browse Backoffice	`/rose-browse-backoffice`	Access client-backoffice via Playwright (port 3002)

Agent Skills (Client Configuration)¶

Skill	Command	Description
Onboard Client	`/rose-onboard-client`	Full onboarding orchestrator: runs rose-create-client-config then rose-create-client-skills
Create Client Config	`/rose-create-client-config`	Create all Rose configs and curated content for a new client from their KB
Create Client Skills	`/rose-create-client-skills`	Onboard a new client: analyze needs, create skills, build eval dataset
Fix Client Skills	`/rose-fix-client-skills`	Diagnose and fix agent behavior for existing clients
Prompt Engineering	`/rose-prompt-engineering`	Systematic prompt fix workflow: reproduce, fix, verify, prevent regressions
Scrape Website	`/rose-scrape-website`	Scrape a website to clean markdown for RAG knowledge base ingestion
Feature Eval	`/rose-feature-eval`	Per-feature E2E evaluation dataset convention and workflow via Langfuse

Diagnostics & Config¶

Skill	Command	Description
Config System	(auto)	Unified config system workflow — add properties, create slugs, run codegen
Rose Config	`/rose-config`	Read and edit client config values in Supabase via CLI (questions, CTAs, taxonomy)
Form Tracking Diagnosis	`/rose-form-tracking-diagnosis`	Diagnose form detection issues: query config, inspect page, suggest strategy fixes
Widget Styling	(auto)	Rules for safely editing the Rose widget styling system — theme tokens, glass shell, CSS delivery
Chat Model Routing	(auto)	Guide for ixchat model/provider routing changes under the resolver-owned architecture
Debug GCloud	`/debug-gcloud`	Fetch and analyze Cloud Run production logs by session_id

Community Skills (Downloaded from Internet)¶

Skills installed from the open skill ecosystem via /find-skills or manual download. These are maintained by third-party authors.

Frontend & UI¶

Skill	Command	Description	Author
Baseline UI	`/baseline-ui`	Enforces typography, animation, accessibility, layout constraints in Tailwind	—
Fixing Motion Performance	`/fixing-motion-performance`	Fix animation jank, layout thrashing, compositor issues	—
Implement Design	`/implement-design`	Translate Figma designs into production code (requires Figma MCP)	—
Vercel React Best Practices	(auto)	React/Next.js performance optimization guidelines	Vercel
TanStack Query	`/tanstack-query`	TanStack Query v5 patterns, migration guide, SSR/hydration	—

Sentry Integration¶

Skill	Command	Description
Sentry Fix Issues	`/sentry-fix-issues`	Find and fix production issues using Sentry MCP
Sentry React Setup	`/sentry-react-setup`	Install and configure `@sentry/react`
Sentry Setup Logging	`/sentry-setup-logging`	Configure Sentry structured logging (JS, Python, Ruby)
Sentry Setup Tracing	`/sentry-setup-tracing`	Configure Sentry performance monitoring

Supabase¶

Skill	Command	Description	Author
Supabase Security	(auto)	RLS policies, auth hardening, API security, production checklist	Supabase
Supabase Postgres Best Practices	(auto)	Query optimization, schema design, connection management	Supabase

Observability¶

Skill	Command	Description	Author
Langfuse	`/langfuse`	Query/modify Langfuse data via CLI, look up docs, instrument applications	—

Meta & Tooling¶

Skill	Command	Description	Author
Create Skill	`/create-skill`	Guide for creating new skills with proper structure and validation	—
Find Skills	`/find-skills`	Discover and install skills from the open ecosystem	—
Visual Explainer	`/visual-explainer`	Generate self-contained HTML pages for diagrams and data tables	nicobailon
Architecture Review	`/architecture-review`	Review code against SOLID, DRY, KISS, coupling/cohesion	—
Claude MD Improver	`/claude-md-improver`	Audit and improve CLAUDE.md files across a repo	—

MCP Servers¶

MCP (Model Context Protocol) servers provide Claude with external tool integrations. They are configured in .mcp.json (project-level) and ~/.claude.json (global).

Active MCP Servers¶

Server	Type	Purpose	Configuration
Linear	HTTP	Issue tracking — read/create/update issues, comments, statuses	`https://mcp.linear.app/mcp`
Playwright	stdio	Browser automation — navigate, click, fill forms, screenshots, E2E testing	`npx @playwright/mcp@latest`
Sentry	HTTP	Error tracking — read issues, stack traces, breadcrumbs, traces	`https://mcp.sentry.dev/mcp`
Figma	HTTP	Design files — read Figma nodes, extract design tokens, inspect components	`https://mcp.figma.com/mcp`

Server Configuration¶

MCP servers are defined in two places:

Project-level (.mcp.json): Servers specific to this repo. Currently configures Linear, Figma, Sentry, Playwright, and Supabase.
Global (~/.claude.json): Servers available across all projects. Currently configures Linear globally.
Enabled servers (.claude/settings.json): The enabledMcpjsonServers array controls which .mcp.json servers are active. Currently: linear-server, figma.

How Skills Use MCPs¶

Several skills depend on MCP servers to function:

Skill	Required MCP	Usage
Solve Linear Ticket	Linear	Fetch issues, update status, add comments
Browse Playground/Demo/Backoffice	Playwright	Navigate browser, interact with UI, take screenshots
Sentry Fix Issues	Sentry	Read production errors, stack traces, breadcrumbs
Implement Design	Figma	Read design files, extract component specs

Adding a New MCP Server¶

Add the server config to .mcp.json:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

For stdio servers:

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["my-mcp-package"]
    }
  }
}

If the server should be active by default, add it to enabledMcpjsonServers in .claude/settings.json.

Detailed Skill Reference¶

PR Fix¶

Automates addressing pull request review feedback: analyze comments, make fixes, reply to explain changes, resolve threads, and commit.

Usage:

/pr-fix          # Auto-detect PR from current branch
/pr-fix 123      # Use specific PR number

What it does:

Fetches unresolved review threads via GitHub GraphQL API
Analyzes and categorizes each comment (code change, docs, question, disagree)
Reads relevant files and makes fixes
Replies to each comment explaining what was changed
Resolves the thread
Creates a single commit with all fixes

Notes:

Does NOT push automatically - review changes before pushing
Asks for user confirmation on disagreements (never auto-resolves)
Requires gh CLI to be authenticated

Test¶

Router skill that delegates to test-backend or test-frontend.

Usage:

/test backend          # Run backend tests
/test frontend         # Run frontend tests
/test unit             # Run backend unit tests (auto-routes)
/test smoke            # Run backend smoke tests (auto-routes)
/test coverage         # Run frontend tests with coverage (auto-routes)
/test path/to/test.py  # Run specific backend test (auto-routes)

If no arguments provided, asks which to run.

Test Backend¶

Run Python tests with pytest, parse failures, fix issues, and verify resolution.

Usage:

/test-backend              # Run unit tests (default)
/test-backend unit         # Run unit tests
/test-backend integration  # Run integration tests
/test-backend smoke        # Run smoke tests
/test-backend evaluation   # Run evaluation tests
/test-backend all          # Run all tests (excludes evaluation)
/test-backend path/to/test.py  # Run specific file

What it does:

Runs appropriate pytest command (just test, just unit, just smoke, etc.)
Parses failures (test name, error type, traceback)
Categorizes issues (mock, import, type, assertion, async, fixture)
Applies fixes based on confidence level
Re-runs individual tests to verify
Runs full suite for final verification

Critical rules enforced:

Uses mocker fixture, NEVER unittest.mock
Never skips tests - fixes the issue instead
All async tests must have @pytest.mark.asyncio

Test Frontend¶

Run TypeScript tests with Vitest, parse failures, fix issues, and verify resolution.

Usage:

/test-frontend              # Run all tests
/test-frontend coverage     # Run with coverage
/test-frontend watch        # Watch mode
/test-frontend e2e          # E2E tests with Playwright
/test-frontend path/to/file.test.ts  # Run specific file

What it does:

Runs appropriate vitest command (just test, etc.)
Parses failures (test name, error type, traceback)
Categorizes issues (import, type, assertion, mock, async)
Applies fixes based on confidence level
Re-runs individual tests to verify

Critical rules enforced:

Uses logger from shared utils, NEVER console.log
Tests use Vitest, NOT Jest
Run tests from frontend/ directory

Mypy (Typecheck Python)¶

Run mypy type checking on Python files, parse errors, apply fixes, and verify resolution.

Auto-triggers when:

User mentions "mypy" or "type error"
User asks to fix typing issues
Mypy output is pasted showing errors
After ANY edit to Python files (mandatory)

Usage:

/mypy                          # Fix errors in recently edited files
/mypy packages/ixchat          # Check a package
/mypy path/to/file.py          # Check specific file

Common fixes:

Missing Optional[] wrappers
Type narrowing with assert or if
Adding return type annotations
Import errors for known modules

Solve Linear Ticket¶

Systematically implement Linear issues by working through TODO subissues with structured task tracking.

Usage:

/rose-solve-linear-ticket IX-1151          # Use issue identifier
/rose-solve-linear-ticket https://linear.app/.../IX-1151  # Use full URL

What it does:

Fetches parent issue and all TODO subissues via Linear MCP
Creates hierarchical task structure with dependencies
For each subissue, executes 7 steps: fetch → analyze → impl → test → visual → commit → linear
Downloads attachments/images using linearis CLI
Commits changes with Linear issue reference
Updates Linear status to "In Review" and adds implementation comment
Creates summary of all completed work

Requirements:

Linear MCP server configured
linearis CLI installed (for attachments)
gh CLI authenticated (for commits)

Browse Skills (Playwright Integration)¶

Three skills for accessing different UIs via Playwright MCP. All require Playwright MCP server to be active.

Browse Playground¶

Access preprod-ui for testing widget changes.

/rose-browse-playground                 # Open localhost:3001
/rose-browse-playground /ai-sections-test  # Navigate to specific page
/rose-browse-playground chat "Hello"    # Type in chat widget
/rose-browse-playground screenshot      # Take screenshot

Port: 3001 | Start: cd frontend/preprod-ui && just dev

Browse Demo Page¶

Access widget demo page for testing widget builds.

/rose-browse-demo-page                  # Open localhost:8083/demo.html
/rose-browse-demo-page rebuild          # Rebuild widget + demo, then refresh
/rose-browse-demo-page rebuild-sections # Rebuild AI Sections only
/rose-browse-demo-page screenshot       # Take screenshot

Port: 8083 | Start: cd frontend/widget && just dev

Rebuild commands:

Scenario	Command
Any code change	`just rebuild` (server stays running)
AI Sections only	`npx vite build --config vite.sections.config.ts`
Server not running	`just dev` (builds + starts server)

Browse Backoffice¶

Access client-backoffice for admin panel testing.

/rose-browse-backoffice                 # Open localhost:3002
/rose-browse-backoffice /sites          # Navigate to sites list
/rose-browse-backoffice find "Edit"     # Find element on page
/rose-browse-backoffice screenshot      # Take screenshot

Port: 3002 | Start: cd frontend/client-backoffice && just dev

Config System¶

Auto-triggered skill that guides Claude through the unified config system workflow when editing schemas or working with ixconfig.

Auto-triggers when:

Editing JSON schema files in schemas/configs/
Working with the ixconfig package or ConfigResolver
Mentioning "config", "schema", "x-feature", "x-access", "codegen"

What it provides:

Workflow A — Add a property to an existing config (edit schema, codegen, mypy)
Workflow B — Create a new config slug (schema, validate, codegen, migration, check-slugs)
Schema template with all required fields
Key commands reference (just validate, just codegen, just list, just check-slugs)

Key rules enforced:

Never edit *_generated.py or *.generated.ts — run just codegen instead
Schema "$id" must match the filename stem
Schema "default" must be a JSON object
Always run just codegen then just mypy packages/ixconfig after schema edits

Related docs: Config System

Debug GCloud¶

Fetch and analyze Cloud Run production logs for a given session_id.

Usage:

/debug-gcloud session_pennylane.com_1771033548702_cy46t7

What it does:

Parses session_id from arguments
Queries GCloud Logging API for structured JSON logs filtered by session_id
Presents logs with timestamps, severity, and relevant context

Requirements:

gcloud CLI authenticated with access to the GCP project

Agent Browser¶

Browser automation CLI for AI agents. Wraps Playwright with an element-reference system (@e1, @e2, ...) designed for LLM interaction.

Usage:

agent-browser open https://example.com       # Navigate to URL
agent-browser snapshot -i                     # Interactive snapshot with element refs
agent-browser fill @e1 "user@example.com"     # Fill a form field by ref
agent-browser click @e3                       # Click a button by ref
agent-browser screenshot output.png           # Capture screenshot
agent-browser close                           # Close session (avoid daemon leaks)

What it does:

Opens a browser session and navigates to URLs
Takes interactive snapshots that assign @e1, @e2, ... refs to page elements
Supports fill, click, select, type, hover, scroll, drag interactions via refs
Captures screenshots, PDFs, and visual diffs
Supports parallel sessions (--session <name>), device emulation, and auth state persistence

Key rules:

After any navigation or form submission, re-snapshot — refs invalidate when the page changes
Use agent-browser close when done to avoid daemon leaks
Use --content-boundaries to wrap untrusted page content for LLM safety
For complex JavaScript, use --stdin or -b (base64) to avoid shell escaping issues

This skill underpins: Browse Playground, Browse Demo Page, Browse Backoffice, Test E2E, and Form Tracking Diagnosis.

Test E2E¶

Run end-to-end browser tests against local dev servers using agent-browser. Auto-discovers what changed on the branch and maps changes to test scenarios.

Usage:

/test-e2e      # Auto-discover changes and run matching tests

What it does:

Discovers changes: git log develop..HEAD and git diff develop..HEAD --stat
Maps schema/node changes to test scenarios from its built-in test catalog
For each scenario: opens backoffice, toggles a config, opens playground, verifies behavior
Restores original config values after each test
Reports results: PASS | FAIL | SKIP

Test catalog:

Config	Where	Test Action	Verification
`use_visitor_context`	Settings > Behavior	Toggle OFF/ON	Response references/ignores visitor industry
`suggested_answers.enabled`	Settings > Engagement	Toggle OFF/ON	Suggested answer buttons appear/disappear
`dynamic_questions.enabled`	Settings > Engagement	Toggle OFF/ON	Starter question buttons appear/disappear

Prerequisites:

Backend running on port 8080
Backoffice running on port 3002 (cd frontend/client-backoffice && just dev)
Playground running on port 3001 (cd frontend/preprod-ui && just dev)

Key rules:

Uses Cactus Inbound sandbox client only — always restores original values after tests
Playground must be configured with "Local" API endpoint before testing

Rose Config¶

Read and edit client config values in Supabase via the rose-config CLI. For schema changes (adding new properties or slugs), use the Config System skill instead.

Usage:

.venv/bin/rose-config list-configs --site acme.com                    # List configs + lock status
.venv/bin/rose-config get engagement --site acme.com --json           # Read current config
.venv/bin/rose-config set engagement --site acme.com -f /tmp/cfg.json --dry-run  # Preview
.venv/bin/rose-config set engagement --site acme.com -f /tmp/cfg.json --yes      # Write

Editable configs:

Slug	Key paths	Purpose
`identity`	`company_name`, `description`, `default_language`, `display_name`	Company info and language
`engagement`	`dynamic_questions.questions`, `suggested_answers`	Suggested questions and answers
`analytics`	`taxonomy.topics`	Taxonomy / intent classification
`ctas`	`ctas`	Call-to-action buttons
`qualification`	`interest_signals`	Buying intent signals

Key rules:

Always read before write — never blind-overwrite config
Check lock status first — if system.config_locked is true, the CLI refuses writes
All language variants must be filled when editing language-keyed fields
Use --dry-run before committing changes
KB dump mandatory when creating questions/taxonomy/CTAs from scratch

Form Tracking Diagnosis¶

Diagnose why form submissions aren't being detected for a client domain. Queries Supabase config, inspects the page with agent-browser, and maps to the correct detection strategy.

Usage:

/rose-form-tracking-diagnosis https://edusign.com/fr/contact/

What it does:

Queries Supabase for the domain's CTA URLs, form_tracking_pages, and thank_you_pages
Checks post_request_captures table for intercepted form data
Opens the page with agent-browser to detect form structure
Maps the page to one of 7 detection strategies (by priority):
- SuperformStrategy — Webflow Superform multi-step forms
- HubSpotFormStrategy — HubSpot React forms
- CTAPageFormStrategy — Standard <form> on CTA destination pages
- ThankYouPageStrategy — URL-based completion (no form needed)
- NetworkObserverStrategy — SPA pages with orphan inputs + backend POST
- DomObserverStrategy — SPA step transitions (disabled by default)
- PostMessageStrategy — Cross-origin iframe forms (Cal.com, HubSpot, Typeform)
Suggests config changes and guides validation

Key rules:

Strategies 1-6 only activate if the page matches CTA URL, form_tracking_pages, thank_you_pages, or post_request_capture.page_patterns
PostMessageStrategy (7) has no eligibility requirement — the iframe postMessage IS the signal
DomObserver is disabled by default — requires explicit toggle via form_detection_strategies.dom_observer: true

Solve Chatbot Issues¶

Batch-process [Chatbot] issues from Linear. Fetches all issues in Triage/Todo, groups by client domain, and dispatches parallel subagents to fix each client's issues.

Usage:

/rose-solve-chatbot-issues    # No arguments needed

What it does:

Fetches all [Chatbot] issues in Triage and Todo states via Linear MCP
Groups issues by client domain using scripts/group_issues.py
Presents a plan (table of clients + issue counts) for user confirmation
Creates a task hierarchy: main epic > per-client tasks > Linear update > summary
Dispatches all client subagents in parallel (one per domain) running /rose-fix-client-skills
Collects results and updates Linear issues to "In Review" with summaries
Generates results table with status (Fixed/Failed), commit hashes, and eval scores

Key rules:

All client subagents launch in a single message (parallel dispatch)
Linear updates are deferred until all client tasks complete
Each subagent runs the full /rose-fix-client-skills workflow for its domain's issues

Requirements:

Linear MCP server configured
gh CLI authenticated

Create Skill¶

Guide for creating or updating Claude Code skills with proper structure, progressive disclosure, and validation.

Usage:

/create-skill              # Guided skill creation workflow

What it does:

Understand the skill (collects examples, identifies use cases)
Plan contents (scripts vs references vs SKILL.md body)
Initialize directory: python3 scripts/init_skill.py <skill-name>
Implement scripts first (deterministic tools, stdlib-only Python)
Implement references second (domain knowledge, one topic per file)
Write SKILL.md last (lean workflow referencing scripts and references)
Validate: python3 scripts/validate_skill.py .agents/skills/<skill-name>

Key rules:

3-level progressive disclosure: metadata (always loaded) > SKILL.md body (on trigger) > scripts/references (on demand)
SKILL.md must stay under 500 lines
Scripts are executed, not loaded — only their output consumes tokens
The description field is the only trigger mechanism — be specific
Use imperative mood ("Query the database", not "You should query")

Adding New Skills¶

Installing from the Internet¶

Use /find-skills to discover community skills:

/find-skills supabase          # Search for Supabase-related skills
/find-skills "visual diagram"  # Search by description

Skills are installed into .agents/skills/<skill-name>/SKILL.md.

Creating Internal Skills¶

Each skill needs a SKILL.md file in .agents/skills/<skill-name>/:

---
name: my-skill
description: When to trigger this skill and what it does
allowed-tools:
  - "Bash(just test **)"
  - "Edit(backend/**/*.py)"
---

# My Skill

Instructions for the workflow...

Use /create-skill for guided skill creation. See the Prompt & Skill Workflow for the full development and testing process.

Dependabot¶

Resolve all open Dependabot security alerts and PRs across the entire monorepo — Python (Poetry), npm, and GitHub Actions.

Usage:

/dependabot          # Inventory, fix, and close all Dependabot alerts/PRs

What it does:

Lists all open Dependabot alerts and PRs via gh CLI
Categorizes each by ecosystem and fix strategy (direct bump, transitive override, major upgrade)
Fixes Python vulnerabilities — bumps constraints in pyproject.toml files, regenerates poetry.lock
Fixes npm vulnerabilities — checks all frontend apps (widget, preprod-ui, shared, chrome-plugin, client-backoffice, docs), applies direct bumps or npm overrides
Fixes GitHub Actions — bumps version tags in .github/workflows/*.yml
Commits fixes grouped by scope
Closes superseded Dependabot PRs with a comment linking to the fix
Reports remaining open alerts with reasons

Key rules enforced:

Always uses bounded version ranges (>=x,<y) — never unbounded >=
Checks all frontend apps for shared vulnerabilities (each has its own lockfile)
Only closes PRs that are fully addressed
Runs just mypy and just unit to verify Python changes