From 25272bf6b14b3e973ff62df7e39012926aa0a086 Mon Sep 17 00:00:00 2001 From: Mike Date: Thu, 4 Jun 2026 15:15:27 -0600 Subject: [PATCH] v2.1.163 (+5,630 tokens) --- README.md | 24 +- .../data-cowork-plugin-component-schemas.md | 401 ++++++++++++++++++ system-prompts/data-cowork-plugin-examples.md | 357 ++++++++++++++++ ...ork-plugin-mcp-discovery-and-connection.md | 142 +++++++ .../data-knowledge-mcp-search-strategies.md | 56 +++ .../data-token-counting-reference.md | 61 +++ ...l-build-with-claude-api-reference-guide.md | 5 +- ...ng-llm-powered-applications-with-claude.md | 6 +- .../skill-cowork-plugin-authoring.md | 370 ++++++++++++++++ .../skill-design-sync-package-source-shape.md | 12 +- .../skill-design-sync-slash-command.md | 4 +- ...kill-design-sync-storybook-source-shape.md | 222 ++-------- ...rompt-outcome-first-communication-style.md | 17 + .../tool-description-bash-sandbox-tmpdir.md | 4 +- .../tool-description-browser-file-upload.md | 6 + system-prompts/tool-description-workflow.md | 4 +- 16 files changed, 1490 insertions(+), 201 deletions(-) create mode 100644 system-prompts/data-cowork-plugin-component-schemas.md create mode 100644 system-prompts/data-cowork-plugin-examples.md create mode 100644 system-prompts/data-cowork-plugin-mcp-discovery-and-connection.md create mode 100644 system-prompts/data-knowledge-mcp-search-strategies.md create mode 100644 system-prompts/data-token-counting-reference.md create mode 100644 system-prompts/skill-cowork-plugin-authoring.md create mode 100644 system-prompts/system-prompt-outcome-first-communication-style.md create mode 100644 system-prompts/tool-description-browser-file-upload.md diff --git a/README.md b/README.md index bb261c2..1c4b4d1 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ Download it and try it out for free! **https://piebald.ai/** > [!important] > **NEW (January 23, 2026): We've added all of Claude Code's ~40 system reminders to this list—see [System Reminders](#system-reminders).** -This repository contains an up-to-date list of all Claude Code's various system prompts and their associated token counts as of **[Claude Code v2.1.162](https://www.npmjs.com/package/@anthropic-ai/claude-code/v/2.1.162) (June 3rd, 2026).** It also contains a [**CHANGELOG.md**](./CHANGELOG.md) for the system prompts across 197 versions since v2.0.14. From the team behind [ **Piebald.**](https://piebald.ai/) +This repository contains an up-to-date list of all Claude Code's various system prompts and their associated token counts as of **[Claude Code v2.1.163](https://www.npmjs.com/package/@anthropic-ai/claude-code/v/2.1.163) (June 4th, 2026).** It also contains a [**CHANGELOG.md**](./CHANGELOG.md) for the system prompts across 198 versions since v2.0.14. From the team behind [ **Piebald.**](https://piebald.ai/) **This repository is updated within minutes of each Claude Code release. See the [changelog](./CHANGELOG.md), and follow [@PiebaldAI](https://x.com/PiebaldAI) on X for a summary of the system prompt changes in each release.** @@ -151,11 +151,15 @@ The content of various template files embedded in Claude Code. - [Data: Claude Code recent changes reference](./system-prompts/data-claude-code-recent-changes-reference.md) (**528** tks) - Reference mapping of recently removed or renamed Claude Code commands, flags, and terms to their current replacements. - [Data: Claude Platform on AWS reference](./system-prompts/data-claude-platform-on-aws-reference.md) (**1158** tks) - Reference documentation for using the Claude Developer Platform through AWS infrastructure, including AnthropicAWS clients, required region and workspace configuration, SigV4 authentication, and short-term API keys. - [Data: Claude model catalog](./system-prompts/data-claude-model-catalog.md) (**2507** tks) - Catalog of current and legacy Claude models with exact model IDs, aliases, context windows, and pricing. +- [Data: Cowork plugin MCP discovery and connection](./system-prompts/data-cowork-plugin-mcp-discovery-and-connection.md) (**1338** tks) - Reference guidance for finding MCP connectors during plugin customization, using search and suggestion tools, mapping categories to keywords, and writing .mcp.json entries. +- [Data: Cowork plugin component schemas](./system-prompts/data-cowork-plugin-component-schemas.md) (**3109** tks) - Reference documentation for Cowork plugin component formats, including skills, agents, hooks, MCP servers, legacy commands, CONNECTORS.md, and README.md. +- [Data: Cowork plugin examples](./system-prompts/data-cowork-plugin-examples.md) (**2323** tks) - Reference examples of minimal, medium, and complex Cowork plugin structures with plugin metadata, skills, agents, hooks, MCP config, README, and connectors. - [Data: Files API reference — Python](./system-prompts/data-files-api-reference-python.md) (**1360** tks) - Python Files API reference including file upload, listing, deletion, and usage in messages. - [Data: Files API reference — TypeScript](./system-prompts/data-files-api-reference-typescript.md) (**797** tks) - TypeScript Files API reference including file upload, listing, deletion, and usage in messages. - [Data: GitHub Actions workflow for @claude mentions](./system-prompts/data-github-actions-workflow-for-claude-mentions.md) (**525** tks) - GitHub Actions workflow template for triggering Claude Code via @claude mentions. - [Data: GitHub App installation PR description](./system-prompts/data-github-app-installation-pr-description.md) (**409** tks) - Template for PR description when installing Claude Code GitHub App integration. - [Data: HTTP error codes reference](./system-prompts/data-http-error-codes-reference.md) (**2508** tks) - Reference for HTTP error codes returned by the Claude API with common causes and handling strategies. +- [Data: Knowledge MCP search strategies](./system-prompts/data-knowledge-mcp-search-strategies.md) (**447** tks) - Reference query patterns for using knowledge MCPs to discover organization-specific tool names, project identifiers, team names, and workflow details during plugin customization. - [Data: Live documentation sources](./system-prompts/data-live-documentation-sources.md) (**4075** tks) - WebFetch URLs for fetching current Claude API and Agent SDK documentation from official sources. - [Data: Managed Agents client patterns](./system-prompts/data-managed-agents-client-patterns.md) (**2685** tks) - Reference guide of common client-side patterns for driving Managed Agent sessions, including stream reconnection, idle-break gating, tool confirmations, interrupts, and custom tools. - [Data: Managed Agents core concepts](./system-prompts/data-managed-agents-core-concepts.md) (**3988** tks) - Reference documentation for the Managed Agents API covering core concepts (Agents, Sessions, Environments, Containers), lifecycle, versioning, endpoints, and usage patterns. @@ -176,6 +180,7 @@ The content of various template files embedded in Claude Code. - [Data: Prompt Caching — Design & Optimization](./system-prompts/data-prompt-caching-design-optimization.md) (**3914** tks) - Document on how to design prompt-building code for effective caching, including placement patterns and anti-patterns. - [Data: Streaming reference — Python](./system-prompts/data-streaming-reference-python.md) (**1668** tks) - Python streaming reference including sync/async streaming and handling different content types. - [Data: Streaming reference — TypeScript](./system-prompts/data-streaming-reference-typescript.md) (**1620** tks) - TypeScript streaming reference including basic streaming and handling different content types. +- [Data: Token counting reference](./system-prompts/data-token-counting-reference.md) (**486** tks) - Reference documentation for counting Claude model tokens with the Messages count_tokens endpoint and Anthropic SDK or CLI examples, including warnings against OpenAI tokenizers. - [Data: Tool use concepts](./system-prompts/data-tool-use-concepts.md) (**4431** tks) - Conceptual foundations of tool use with the Claude API including tool definitions, tool choice, and best practices. - [Data: Tool use reference — Python](./system-prompts/data-tool-use-reference-python.md) (**5106** tks) - Python tool use reference including tool runner, manual agentic loop, code execution, and structured outputs. - [Data: Tool use reference — TypeScript](./system-prompts/data-tool-use-reference-typescript.md) (**5033** tks) - TypeScript tool use reference including tool runner, manual agentic loop, code execution, and structured outputs. @@ -239,6 +244,7 @@ Parts of the main system prompt. - [System Prompt: Minimal mode](./system-prompts/system-prompt-minimal-mode.md) (**164** tks) - Describes the behavior and constraints of minimal mode, which skips hooks, LSP, plugins, auto-memory, and other features while requiring explicit context via CLI flags. - [System Prompt: One of six rules for using sleep command](./system-prompts/system-prompt-one-of-six-rules-for-using-sleep-command.md) (**23** tks) - One of the six rules for using the sleep command. - [System Prompt: Option previewer](./system-prompts/system-prompt-option-previewer.md) (**151** tks) - System prompt for previewing UI options in a side-by-side layout. +- [System Prompt: Outcome-first communication style](./system-prompts/system-prompt-outcome-first-communication-style.md) (**460** tks) - Instructs Claude to keep user-facing updates readable and outcome-first, answer directly after work completes, match response format to task complexity, and limit code comments to non-obvious constraints. - [System Prompt: Parallel tool call note (part of "Tool usage policy")](./system-prompts/system-prompt-parallel-tool-call-note-part-of-tool-usage-policy.md) (**102** tks) - System prompt for telling Claude to using parallel tool calls. - [System Prompt: Partial compaction instructions](./system-prompts/system-prompt-partial-compaction-instructions.md) (**805** tks) - Instructions on how to compact when the user decided to compact only a portion of the conversation, with a structured summary format and analysis process. - [System Prompt: Phase four of plan mode](./system-prompts/system-prompt-phase-four-of-plan-mode.md) (**187** tks) - Phase four of plan mode. @@ -309,6 +315,7 @@ Text for large system reminders. ### Builtin Tool Descriptions - [Tool Description: AskUserQuestion](./system-prompts/tool-description-askuserquestion.md) (**220** tks) - Tool description for asking user questions. +- [Tool Description: Browser file upload](./system-prompts/tool-description-browser-file-upload.md) (**130** tks) - Describes the browser file upload tool, which uploads shared files directly to a page file input by element ref and enforces the 10 MB combined size limit. - [Tool Description: BrowserBatch](./system-prompts/tool-description-browserbatch.md) (**159** tks) - Tool description for BrowserBatch, which executes multiple browser tool calls sequentially in one round trip. - [Tool Description: Computer](./system-prompts/tool-description-computer.md) (**161** tks) - Main description for the Chrome browser computer automation tool. - [Tool Description: CronCreate](./system-prompts/tool-description-croncreate.md) (**850** tks) - Describes the CronCreate tool for enqueuing one-shot or recurring cron-based jobs with jitter and off-minute scheduling guidance. @@ -335,7 +342,7 @@ Text for large system reminders. - [Tool Description: TodoWrite](./system-prompts/tool-description-todowrite.md) (**2037** tks) - Tool description for creating and managing task lists. - [Tool Description: WebFetch](./system-prompts/tool-description-webfetch.md) (**297** tks) - Tool description for web fetch functionality. - [Tool Description: WebSearch](./system-prompts/tool-description-websearch.md) (**319** tks) - Tool description for web search functionality. -- [Tool Description: Workflow](./system-prompts/tool-description-workflow.md) (**4793** tks) - Describes the Workflow tool for running deterministic multi-subagent orchestration scripts, including opt-in requirements, script metadata, agent hooks, concurrency, budgeting, quality patterns, and resume behavior. +- [Tool Description: Workflow](./system-prompts/tool-description-workflow.md) (**4823** tks) - Describes the Workflow tool for running deterministic multi-subagent orchestration scripts, including opt-in requirements, script metadata, agent hooks, concurrency, budgeting, quality patterns, and resume behavior. - [Tool Description: Write](./system-prompts/tool-description-write.md) (**129** tks) - Tool for writing files to the local filesystem. **Additional notes for some Tool Descriptions** @@ -377,7 +384,7 @@ Text for large system reminders. - [Tool Description: Bash (sandbox — per-command)](./system-prompts/tool-description-bash-sandbox-per-command.md) (**52** tks) - Treat each command individually; default to sandbox for future commands. - [Tool Description: Bash (sandbox — response header)](./system-prompts/tool-description-bash-sandbox-response-header.md) (**17** tks) - Header for how to respond when seeing sandbox-caused failures. - [Tool Description: Bash (sandbox — retry without sandbox)](./system-prompts/tool-description-bash-sandbox-retry-without-sandbox.md) (**33** tks) - Immediately retry with dangerouslyDisableSandbox on sandbox failure. -- [Tool Description: Bash (sandbox — tmpdir)](./system-prompts/tool-description-bash-sandbox-tmpdir.md) (**65** tks) - Use $TMPDIR for temporary files in sandbox mode. +- [Tool Description: Bash (sandbox — tmpdir)](./system-prompts/tool-description-bash-sandbox-tmpdir.md) (**58** tks) - Use $TMPDIR for temporary files in sandbox mode. - [Tool Description: Bash (sandbox — user permission prompt)](./system-prompts/tool-description-bash-sandbox-user-permission-prompt.md) (**14** tks) - Note that disabling sandbox will prompt user for permission. - [Tool Description: Bash (semicolon usage)](./system-prompts/tool-description-bash-semicolon-usage.md) (**29** tks) - Bash tool instruction: use semicolons when sequential order matters but failure does not. - [Tool Description: Bash (sequential commands)](./system-prompts/tool-description-bash-sequential-commands.md) (**42** tks) - Bash tool instruction: chain dependent commands with &&. @@ -401,9 +408,9 @@ Text for large system reminders. Built-in skill prompts for specialized tasks. - [Skill: /catch-up periodic heartbeat](./system-prompts/skill-catch-up-periodic-heartbeat.md) (**1591** tks) - Skill definition for the /catch-up periodic heartbeat that scans current priorities, triages actionable changes, reports a short digest, and updates catch-up state. -- [Skill: /design-sync Storybook source shape](./system-prompts/skill-design-sync-storybook-source-shape.md) (**9705** tks) - Shape-specific /design-sync instructions for syncing a React design system from Storybook stories and built package output. -- [Skill: /design-sync package source shape](./system-prompts/skill-design-sync-package-source-shape.md) (**8928** tks) - Shape-specific /design-sync instructions for syncing a React design system from a built package without Storybook. -- [Skill: /design-sync slash command](./system-prompts/skill-design-sync-slash-command.md) (**1154** tks) - Skill definition for syncing a React design system to claude.ai/design, including project selection, source-shape detection, converter configuration, validation, upload planning, and self-check behavior. +- [Skill: /design-sync Storybook source shape](./system-prompts/skill-design-sync-storybook-source-shape.md) (**1646** tks) - Shape-specific /design-sync instructions for syncing a React design system from Storybook output, including build steps, converter configuration, validation fixes, and DesignSync upload. +- [Skill: /design-sync package source shape](./system-prompts/skill-design-sync-package-source-shape.md) (**9368** tks) - Shape-specific /design-sync instructions for syncing a React design system from a built package without Storybook. +- [Skill: /design-sync slash command](./system-prompts/skill-design-sync-slash-command.md) (**1179** tks) - Skill definition for syncing a React design system to claude.ai/design, including project selection, source-shape detection, converter configuration, validation, upload planning, and self-check behavior. - [Skill: /dream memory consolidation](./system-prompts/skill-dream-memory-consolidation.md) (**512** tks) - Skill definition for the /dream nightly housekeeping job that consolidates recent logs and transcripts into persistent memory topics, learnings, and a pruned MEMORY.md index. - [Skill: /init CLAUDE.md and skill setup (new version)](./system-prompts/skill-init-claudemd-and-skill-setup-new-version.md) (**5412** tks) - A comprehensive onboarding flow for setting up CLAUDE.md and related skills/hooks in the current repository, including codebase exploration, user interviews, and iterative proposal refinement. - [Skill: /insights report output](./system-prompts/skill-insights-report-output.md) (**182** tks) - Formats and displays the insights usage report results after the user runs the /insights slash command. @@ -415,10 +422,11 @@ Built-in skill prompts for specialized tasks. - [Skill: /pre-meeting-checkin event brief](./system-prompts/skill-pre-meeting-checkin-event-brief.md) (**491** tks) - Skill definition for the /pre-meeting-checkin task that gathers event materials, recent thread context, open questions, and a concise meeting brief. - [Skill: /stuck slash command](./system-prompts/skill-stuck-slash-command.md) (**964** tks) - Diagnozse frozen or slow Claude Code sessions. - [Skill: Agent Design Patterns](./system-prompts/skill-agent-design-patterns.md) (**2029** tks) - Reference guide covering decision heuristics for building agents on the Claude API, including tool surface design, context management, caching strategies, and composing tool calls. -- [Skill: Build with Claude API (reference guide)](./system-prompts/skill-build-with-claude-api-reference-guide.md) (**655** tks) - Template for presenting language-specific reference documentation with quick task navigation. -- [Skill: Building LLM-powered applications with Claude](./system-prompts/skill-building-llm-powered-applications-with-claude.md) (**9298** tks) - Guides Claude in building LLM-powered applications using the Anthropic SDK, covering language detection, API surface selection (Claude API vs Managed Agents), model defaults, thinking/effort configuration, and language-specific documentation reading. +- [Skill: Build with Claude API (reference guide)](./system-prompts/skill-build-with-claude-api-reference-guide.md) (**703** tks) - Template for presenting language-specific reference documentation with quick task navigation. +- [Skill: Building LLM-powered applications with Claude](./system-prompts/skill-building-llm-powered-applications-with-claude.md) (**9367** tks) - Guides Claude in building LLM-powered applications using the Anthropic SDK, covering language detection, API surface selection (Claude API vs Managed Agents), model defaults, thinking/effort configuration, and language-specific documentation reading. - [Skill: Claude Code configuration guide](./system-prompts/skill-claude-code-configuration-guide.md) (**975** tks) - Skill instructions for answering Claude Code configuration questions by checking the running build, bundled references, and current documentation. - [Skill: Computer Use MCP](./system-prompts/skill-computer-use-mcp.md) (**1206** tks) - Instructions for using computer-use MCP tools including tool selection tiers, app access tiers, link safety, and financial action restrictions. +- [Skill: Cowork plugin authoring](./system-prompts/skill-cowork-plugin-authoring.md) (**4791** tks) - Skill instructions for creating or customizing Cowork plugins, including mode selection, research, implementation, packaging, connector replacement, and plugin delivery. - [Skill: Create verifier skills](./system-prompts/skill-create-verifier-skills.md) (**2580** tks) - Prompt for creating verifier skills for the Verify agent to automatically verify code changes. - [Skill: Debugging](./system-prompts/skill-debugging.md) (**417** tks) - Instructions for debugging an issue that the user is encountering in the Claude Code session. - [Skill: Dynamic pacing loop execution](./system-prompts/skill-dynamic-pacing-loop-execution.md) (**598** tks) - Step-by-step instructions for executing a dynamic pacing loop that runs tasks, arms persistent monitors for event-gated waits, schedules fallback heartbeat ticks, and handles task notifications. diff --git a/system-prompts/data-cowork-plugin-component-schemas.md b/system-prompts/data-cowork-plugin-component-schemas.md new file mode 100644 index 0000000..ad126d1 --- /dev/null +++ b/system-prompts/data-cowork-plugin-component-schemas.md @@ -0,0 +1,401 @@ + +# Component Schemas + +Detailed format specifications for every plugin component type. Reference this when implementing components in Phase 4. + +## Skills + +**Location**: `skills/skill-name/SKILL.md` +**Format**: Markdown with YAML frontmatter + +### Frontmatter Fields + +| Field | Required | Type | Description | +| ------------- | -------- | ------ | ------------------------------------------------------- | +| `name` | Yes | String | Skill identifier (lowercase, hyphens; matches dir name) | +| `description` | Yes | String | Third-person description with trigger phrases | +| `metadata` | No | Map | Arbitrary key-value pairs (e.g., `version`, `author`) | + +### Example Skill + +```yaml +--- +name: api-design +description: > + This skill should be used when the user asks to "design an API", + "create API endpoints", "review API structure", or needs guidance + on REST API best practices, endpoint naming, or request/response design. +metadata: + version: "0.1.0" +--- +``` + +### Writing Style Rules + +- **Frontmatter description**: Third-person ("This skill should be used when..."), with specific trigger phrases in quotes. +- **Body**: Imperative/infinitive form ("Parse the config file," not "You should parse the config file"). +- **Length**: Keep SKILL.md body under 3,000 words (ideally 1,500-2,000). Move detailed content to `references/`. + +### Skill Directory Structure + +``` +skill-name/ +├── SKILL.md # Core knowledge (required) +├── references/ # Detailed docs loaded on demand +│ ├── patterns.md +│ └── advanced.md +├── examples/ # Working code examples +│ └── sample-config.json +└── scripts/ # Utility scripts + └── validate.sh +``` + +### Progressive Disclosure Levels + +1. **Metadata** (always in context): name + description (~100 words) +2. **SKILL.md body** (when skill triggers): core knowledge (<5k words) +3. **Bundled resources** (as needed): references, examples, scripts (unlimited) + +## Agents + +**Location**: `agents/agent-name.md` +**Format**: Markdown with YAML frontmatter + +### Frontmatter Fields + +| Field | Required | Type | Description | +| ------------- | -------- | ------ | --------------------------------------------------- | +| `name` | Yes | String | Lowercase, hyphens, 3-50 chars | +| `description` | Yes | String | Triggering conditions with `` blocks | +| `model` | Yes | String | `inherit`, `sonnet`, `opus`, or `haiku` | +| `color` | Yes | String | `blue`, `cyan`, `green`, `yellow`, `magenta`, `red` | +| `tools` | No | Array | Restrict to specific tools | + +### Example Agent + +```markdown +--- +name: code-reviewer +description: Use this agent when the user asks for a thorough code review or wants detailed analysis of code quality, security, and best practices. + + +Context: User has just written a new module +user: "Can you do a deep review of this code?" +assistant: "I'll use the code-reviewer agent to provide a thorough analysis." + +User explicitly requested a detailed review, which matches this agent's specialty. + + + + +Context: User is about to merge a PR +user: "Review this before I merge" +assistant: "Let me run a comprehensive review using the code-reviewer agent." + +Pre-merge review benefits from the agent's structured analysis process. + + + +model: inherit +color: blue +tools: ["Read", "Grep", "Glob"] +--- + +You are a code review specialist focused on identifying issues across security, performance, maintainability, and correctness. + +**Your Core Responsibilities:** + +1. Analyze code structure and organization +2. Identify security vulnerabilities +3. Flag performance concerns +4. Check adherence to best practices + +**Analysis Process:** + +1. Read all files in scope +2. Identify patterns and anti-patterns +3. Categorize findings by severity +4. Provide specific remediation suggestions + +**Output Format:** +Present findings grouped by severity (Critical, Warning, Info) with: + +- File path and line number +- Description of the issue +- Suggested fix +``` + +### Agent Naming Rules + +- 3-50 characters +- Lowercase letters, numbers, hyphens only +- Must start and end with alphanumeric +- No underscores, spaces, or special characters + +### Color Guidelines + +- Blue/Cyan: Analysis, review +- Green: Success-oriented tasks +- Yellow: Caution, validation +- Red: Critical, security +- Magenta: Creative, generation + +## Hooks + +**Location**: `hooks/hooks.json` +**Format**: JSON + +### Available Events + +| Event | When it fires | +| ------------------ | ------------------------------- | +| `PreToolUse` | Before a tool call executes | +| `PostToolUse` | After a tool call completes | +| `Stop` | When Claude finishes a response | +| `SubagentStop` | When a subagent finishes | +| `SessionStart` | When a session begins | +| `SessionEnd` | When a session ends | +| `UserPromptSubmit` | When the user sends a message | +| `PreCompact` | Before context compaction | +| `Notification` | When a notification fires | + +### Hook Types + +**Prompt-based** (recommended for complex logic): + +```json +{ + "type": "prompt", + "prompt": "Evaluate whether this file write follows project conventions: $TOOL_INPUT", + "timeout": 30 +} +``` + +Supported events: Stop, SubagentStop, UserPromptSubmit, PreToolUse. + +**Command-based** (deterministic checks): + +```json +{ + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh", + "timeout": 60 +} +``` + +### Example hooks.json + +```json +{ + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "prompt", + "prompt": "Check that this file write follows project coding standards. If it violates standards, explain why and block.", + "timeout": 30 + } + ] + } + ], + "SessionStart": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "cat ${CLAUDE_PLUGIN_ROOT}/context/project-context.md", + "timeout": 10 + } + ] + } + ] +} +``` + +### Hook Output Format (Command Hooks) + +Command hooks return JSON to stdout: + +```json +{ + "decision": "block", + "reason": "File write violates naming convention" +} +``` + +Decisions: `approve`, `block`, `ask_user` (ask for confirmation). + +## MCP Servers + +**Location**: `.mcp.json` at plugin root +**Format**: JSON + +### Server Types + +**stdio** (local process): + +```json +{ + "mcpServers": { + "my-server": { + "command": "node", + "args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"], + "env": { + "API_KEY": "${API_KEY}" + } + } + } +} +``` + +**SSE** (remote server, server-sent events transport): + +```json +{ + "mcpServers": { + "asana": { + "type": "sse", + "url": "https://mcp.asana.com/sse" + } + } +} +``` + +**HTTP** (remote server, streamable HTTP transport): + +```json +{ + "mcpServers": { + "api-service": { + "type": "http", + "url": "https://api.example.com/mcp", + "headers": { + "Authorization": "Bearer ${API_TOKEN}" + } + } + } +} +``` + +### Environment Variable Expansion + +All MCP configs support `${VAR_NAME}` substitution: + +- `${CLAUDE_PLUGIN_ROOT}` — plugin directory (always use for portability) +- `${ANY_ENV_VAR}` — user environment variables + +Document all required environment variables in the plugin README. + +### Directory Servers Without a URL + +Some MCP directory entries have no `url` because the endpoint is dynamic. Plugins can reference these servers by **name** instead — if the server name in the plugin's MCP config matches the directory entry name, it is treated the same as a URL match. + +## Commands (Legacy) + +> **Prefer `skills/*/SKILL.md` for new plugins.** The Cowork UI now presents commands and skills as a single "Skills" concept. The `commands/` format still works, but only use it if you specifically need the single-file format with `$ARGUMENTS`/`$1` substitution and inline bash execution. + +**Location**: `commands/command-name.md` +**Format**: Markdown with optional YAML frontmatter + +### Frontmatter Fields + +| Field | Required | Type | Description | +| --------------- | -------- | --------------- | --------------------------------------------------- | +| `description` | No | String | Brief description shown in `/help` (under 60 chars) | +| `allowed-tools` | No | String or Array | Tools the command can use | +| `model` | No | String | Model override: `sonnet`, `opus`, `haiku` | +| `argument-hint` | No | String | Documents expected arguments for autocomplete | + +### Example Command + +```markdown +--- +description: Review code for security issues +allowed-tools: Read, Grep, Bash(git:*) +argument-hint: [file-path] +--- + +Review @$1 for security vulnerabilities including: + +- SQL injection +- XSS attacks +- Authentication bypass +- Insecure data handling + +Provide specific line numbers, severity ratings, and remediation suggestions. +``` + +### Key Rules + +- Commands are instructions FOR Claude, not messages for the user. Write them as directives. +- `$ARGUMENTS` captures all arguments as a single string; `$1`, `$2`, `$3` capture positional arguments. +- `@path` syntax includes file contents in the command context. +- `!` backtick syntax executes bash inline for dynamic context (e.g., `` !`git diff --name-only` ``). +- Use `${CLAUDE_PLUGIN_ROOT}` to reference plugin files portably. + +### allowed-tools Patterns + +```yaml +# Specific tools +allowed-tools: Read, Write, Edit, Bash(git:*) + +# Bash with specific commands only +allowed-tools: Bash(npm:*), Read + +# MCP tools (specific) +allowed-tools: ["mcp__plugin_name_server__tool_name"] +``` + +## CONNECTORS.md + +**Location**: Plugin root +**When to create**: When the plugin references external tools by category rather than specific product + +### Format + +```markdown +# Connectors + +## How tool references work + +Plugin files use `~~category` as a placeholder for whatever tool the user +connects in that category. For example, `~~project tracker` might mean +Asana, Linear, Jira, or any other project tracker with an MCP server. + +Plugins are tool-agnostic — they describe workflows in terms of categories +rather than specific products. + +## Connectors for this plugin + +| Category | Placeholder | Included servers | Other options | +| --------------- | ------------------- | ---------------- | ------------------------ | +| Chat | `~~chat` | Slack | Microsoft Teams, Discord | +| Project tracker | `~~project tracker` | Linear | Asana, Jira, Monday | +``` + +### Using ~~ Placeholders + +In plugin files (skills, agents), reference tools generically: + +```markdown +Check ~~project tracker for open tickets assigned to the user. +Post a summary to ~~chat in the team channel. +``` + +During customization (via the cowork-plugin-customizer skill), these get replaced with specific tool names. + +## README.md + +Every plugin should include a README with: + +1. **Overview** — what the plugin does +2. **Components** — list of skills, agents, hooks, MCP servers +3. **Setup** — any required environment variables or configuration +4. **Usage** — how to trigger each skill +5. **Customization** — if CONNECTORS.md exists, mention it diff --git a/system-prompts/data-cowork-plugin-examples.md b/system-prompts/data-cowork-plugin-examples.md new file mode 100644 index 0000000..b519172 --- /dev/null +++ b/system-prompts/data-cowork-plugin-examples.md @@ -0,0 +1,357 @@ + +# Example Plugins + +Three complete plugin structures at different complexity levels. Use these as templates when implementing in Phase 4. + +## Minimal Plugin: Single Skill + +A simple plugin with one skill and no other components. + +### Structure + +``` +meeting-notes/ +├── .claude-plugin/ +│ └── plugin.json +├── skills/ +│ └── meeting-notes/ +│ └── SKILL.md +└── README.md +``` + +### plugin.json + +```json +{ + "name": "meeting-notes", + "version": "0.1.0", + "description": "Generate structured meeting notes from transcripts", + "author": { + "name": "User" + } +} +``` + +### skills/meeting-notes/SKILL.md + +```markdown +--- +name: meeting-notes +description: > + Generate structured meeting notes from a transcript. Use when the user asks + to "summarize this meeting", "create meeting notes", "extract action items + from this transcript", or provides a meeting transcript file. +--- + +Read the transcript file the user provided and generate structured meeting notes. + +Include these sections: + +1. **Attendees** — list all participants mentioned +2. **Summary** — 2-3 sentence overview of the meeting +3. **Key Decisions** — numbered list of decisions made +4. **Action Items** — table with columns: Owner, Task, Due Date +5. **Open Questions** — anything unresolved + +Write the notes to a new file named after the transcript with `-notes` appended. +``` + +--- + +## Standard Plugin: Skills + MCP + +A plugin that combines domain knowledge, user-initiated actions, and external service integration. + +### Structure + +``` +code-quality/ +├── .claude-plugin/ +│ └── plugin.json +├── skills/ +│ ├── coding-standards/ +│ │ ├── SKILL.md +│ │ └── references/ +│ │ └── style-rules.md +│ ├── review-changes/ +│ │ └── SKILL.md +│ └── fix-lint/ +│ └── SKILL.md +├── .mcp.json +└── README.md +``` + +### plugin.json + +```json +{ + "name": "code-quality", + "version": "0.1.0", + "description": "Enforce coding standards with reviews, linting, and style guidance", + "author": { + "name": "User" + } +} +``` + +### skills/review-changes/SKILL.md + +```markdown +--- +name: review-changes +description: > + Review code changes for style and quality issues. Use when the user asks to + "review my changes", "check this diff", "review for style violations", or + wants a code quality pass on uncommitted work. +--- + +Run `git diff --name-only` to get the list of changed files. + +For each changed file: + +1. Read the file +2. Check against the coding-standards skill for style violations +3. Identify potential bugs or anti-patterns +4. Flag any security concerns + +Present a summary with: + +- File path +- Issue severity (Error, Warning, Info) +- Description and suggested fix +``` + +### skills/fix-lint/SKILL.md + +```markdown +--- +name: fix-lint +description: > + Auto-fix linting issues in changed files. Use when the user asks to + "fix lint errors", "clean up linting", or "auto-fix my lint issues". +--- + +Run the linter: `npm run lint -- --format json 2>&1` + +Parse the linter output and fix each issue: + +- For auto-fixable issues, apply the fix directly +- For manual-fix issues, make the correction following project conventions +- Skip issues that require architectural changes + +After all fixes, run the linter again to confirm clean output. +``` + +### skills/coding-standards/SKILL.md + +```yaml +--- +name: coding-standards +description: > + This skill should be used when the user asks about "coding standards", + "style guide", "naming conventions", "code formatting rules", or needs + guidance on project-specific code quality expectations. +metadata: + version: "0.1.0" +--- +``` + +```markdown +# Coding Standards + +Project coding standards and conventions for consistent, high-quality code. + +## Core Rules + +- Use camelCase for variables and functions +- Use PascalCase for classes and types +- Prefer const over let; avoid var +- Maximum line length: 100 characters +- Use explicit return types on all exported functions + +## Import Order + +1. External packages +2. Internal packages (aliased with @/) +3. Relative imports +4. Type-only imports last + +## Additional Resources + +- **`references/style-rules.md`** — complete style rules by language +``` + +### .mcp.json + +```json +{ + "mcpServers": { + "github": { + "type": "http", + "url": "https://api.githubcopilot.com/mcp/" + } + } +} +``` + +--- + +## Full-Featured Plugin: All Component Types + +A plugin using skills, agents, hooks, and MCP integration with tool-agnostic connectors. + +### Structure + +``` +engineering-workflow/ +├── .claude-plugin/ +│ └── plugin.json +├── skills/ +│ ├── team-processes/ +│ │ ├── SKILL.md +│ │ └── references/ +│ │ └── workflow-guide.md +│ ├── standup-prep/ +│ │ └── SKILL.md +│ └── create-ticket/ +│ └── SKILL.md +├── agents/ +│ └── ticket-analyzer.md +├── hooks/ +│ └── hooks.json +├── .mcp.json +├── CONNECTORS.md +└── README.md +``` + +### plugin.json + +```json +{ + "name": "engineering-workflow", + "version": "0.1.0", + "description": "Streamline engineering workflows: standup prep, ticket management, and code quality", + "author": { + "name": "User" + }, + "keywords": ["engineering", "workflow", "tickets", "standup"] +} +``` + +### agents/ticket-analyzer.md + +```markdown +--- +name: ticket-analyzer +description: Use this agent when the user needs to analyze tickets, triage incoming issues, or prioritize a backlog. + + +Context: User is preparing for sprint planning +user: "Help me triage these new tickets" +assistant: "I'll use the ticket-analyzer agent to review and categorize the tickets." + +Ticket triage requires systematic analysis across multiple dimensions, making the agent appropriate. + + + + +Context: User has a large backlog +user: "Prioritize my backlog for next sprint" +assistant: "Let me analyze the backlog using the ticket-analyzer agent to recommend priorities." + +Backlog prioritization is a multi-step autonomous task well-suited for the agent. + + + +model: inherit +color: cyan +tools: ["Read", "Grep"] +--- + +You are a ticket analysis specialist. Analyze tickets for priority, effort, and dependencies. + +**Your Core Responsibilities:** + +1. Categorize tickets by type (bug, feature, tech debt, improvement) +2. Estimate relative effort (S, M, L, XL) +3. Identify dependencies between tickets +4. Recommend priority ordering + +**Analysis Process:** + +1. Read all ticket descriptions +2. Categorize each by type +3. Estimate effort based on scope +4. Map dependencies +5. Rank by impact-to-effort ratio + +**Output Format:** +| Ticket | Type | Effort | Dependencies | Priority | +|--------|------|--------|-------------|----------| +| ... | ... | ... | ... | ... | + +Followed by a brief rationale for the top 5 priorities. +``` + +### hooks/hooks.json + +```json +{ + "SessionStart": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "echo '## Team Context\n\nSprint cycle: 2 weeks. Standup: daily at 9:30 AM. Use ~~project tracker for ticket management.'", + "timeout": 5 + } + ] + } + ] +} +``` + +### CONNECTORS.md + +```markdown +# Connectors + +## How tool references work + +Plugin files use `~~category` as a placeholder for whatever tool the user +connects in that category. Plugins are tool-agnostic. + +## Connectors for this plugin + +| Category | Placeholder | Included servers | Other options | +| --------------- | ------------------- | ---------------- | ------------------- | +| Project tracker | `~~project tracker` | Linear | Asana, Jira, Monday | +| Chat | `~~chat` | Slack | Microsoft Teams | +| Source control | `~~source control` | GitHub | GitLab, Bitbucket | +``` + +### .mcp.json + +```json +{ + "mcpServers": { + "linear": { + "type": "sse", + "url": "https://mcp.linear.app/sse" + }, + "github": { + "type": "http", + "url": "https://api.githubcopilot.com/mcp/" + }, + "slack": { + "type": "http", + "url": "https://slack.mcp.claude.com/mcp" + } + } +} +``` diff --git a/system-prompts/data-cowork-plugin-mcp-discovery-and-connection.md b/system-prompts/data-cowork-plugin-mcp-discovery-and-connection.md new file mode 100644 index 0000000..2b24a5f --- /dev/null +++ b/system-prompts/data-cowork-plugin-mcp-discovery-and-connection.md @@ -0,0 +1,142 @@ + +# MCP Discovery and Connection + +How to find and connect MCPs during plugin customization. + +## Available Tools + +### `search_mcp_registry` +Search the MCP directory for available connectors. + +**Input:** `{ "keywords": ["array", "of", "search", "terms"] }` + +**Output:** Up to 10 results, each with: +- `name`: MCP display name +- `description`: One-liner description +- `tools`: List of tool names the MCP provides +- `url`: MCP endpoint URL (use this in `.mcp.json`) +- `directoryUuid`: UUID for use with suggest_connectors +- `connected`: Boolean - whether user has this MCP connected + +### `suggest_connectors` +Display Connect buttons to let users install/connect MCPs. + +**Input:** `{ "directoryUuids": ["uuid1", "uuid2"] }` + +**Output:** Renders UI with Connect buttons for each MCP + +## Category-to-Keywords Mapping + +| Category | Search Keywords | +|----------|-----------------| +| `project-management` | `["asana", "jira", "linear", "monday", "tasks"]` | +| `software-coding` | `["github", "gitlab", "bitbucket", "code"]` | +| `chat` | `["slack", "teams", "discord"]` | +| `documents` | `["google docs", "notion", "confluence"]` | +| `calendar` | `["google calendar", "calendar"]` | +| `email` | `["gmail", "outlook", "email"]` | +| `design-graphics` | `["figma", "sketch", "design"]` | +| `analytics-bi` | `["datadog", "grafana", "analytics"]` | +| `crm` | `["salesforce", "hubspot", "crm"]` | +| `wiki-knowledge-base` | `["notion", "confluence", "outline", "wiki"]` | +| `data-warehouse` | `["bigquery", "snowflake", "redshift"]` | +| `conversation-intelligence` | `["gong", "chorus", "call recording"]` | + +## Workflow + +1. **Find customization point**: Look for `~~`-prefixed values (e.g., `~~Jira`) +2. **Check earlier phase findings**: Did you already learn which tool they use? + - **Yes**: Search for that specific tool to get its `url`, skip to step 5 + - **No**: Continue to step 3 +3. **Search**: Call `search_mcp_registry` with mapped keywords +4. **Present choices and ask user**: Show all results, ask which they use +5. **Connect if needed**: If not connected, call `suggest_connectors` +6. **Update MCP config**: Add config using the `url` from search results + +## Updating Plugin MCP Configuration + +### Finding the Config File + +1. **Check `plugin.json`** for an `mcpServers` field: + ```json + { + "name": "my-plugin", + "mcpServers": "./config/servers.json" + } + ``` + If present, edit the file at that path. + +2. **If no `mcpServers` field**, use `.mcp.json` at the plugin root (default). + +3. **If `mcpServers` points only to `.mcpb` files** (bundled servers), create a new `.mcp.json` at the plugin root. + +### Config File Format + +Both wrapped and unwrapped formats are supported: + +```json +{ + "mcpServers": { + "github": { + "type": "http", + "url": "https://api.githubcopilot.com/mcp/" + } + } +} +``` + +Use the `url` field from `search_mcp_registry` results. + +### Directory Entries Without a URL + +Some directory entries have no `url` because the endpoint is dynamic — the admin provides it when connecting the server. These servers can still be referenced in the plugin's MCP config by **name**: if the MCP server name in the config matches the directory entry name, it is treated the same as a URL match. + +## Example: Fully Configured `.mcp.json` + +```json +{ + "mcpServers": { + "github": { + "type": "http", + "url": "https://api.githubcopilot.com/mcp/", + "headers": { + "Authorization": "Bearer ${GITHUB_TOKEN}" + } + }, + "asana": { + "type": "sse", + "url": "https://mcp.asana.com/sse" + }, + "slack": { + "type": "http", + "url": "https://slack.mcp.claude.com/mcp" + }, + "figma": { + "type": "http", + "url": "https://mcp.figma.com/mcp" + }, + "datadog": { + "type": "http", + "url": "https://api.datadoghq.com/mcp", + "headers": { + "DD-API-KEY": "${DATADOG_API_KEY}", + "DD-APPLICATION-KEY": "${DATADOG_APP_KEY}" + } + } + }, + "recommendedCategories": [ + "source-control", + "project-management", + "chat", + "documents", + "wiki-knowledge-base", + "design-graphics", + "analytics-bi" + ] +} + +``` diff --git a/system-prompts/data-knowledge-mcp-search-strategies.md b/system-prompts/data-knowledge-mcp-search-strategies.md new file mode 100644 index 0000000..f85e666 --- /dev/null +++ b/system-prompts/data-knowledge-mcp-search-strategies.md @@ -0,0 +1,56 @@ + +# Knowledge MCP Search Strategies + +Query patterns for gathering organizational context during plugin customization. + +## Finding Tool Names + +**Source control:** +- Search: "GitHub" OR "GitLab" OR "Bitbucket" +- Search: "pull request" OR "merge request" +- Look for: repository links, CI/CD mentions + +**Project management:** +- Search: "Asana" OR "Jira" OR "Linear" OR "Monday" +- Search: "sprint" AND "tickets" +- Look for: task links, project board mentions + +**Chat:** +- Search: "Slack" OR "Teams" OR "Discord" +- Look for: channel mentions, integration discussions + +**Analytics:** +- Search: "Datadog" OR "Grafana" OR "Mixpanel" +- Search: "monitoring" OR "observability" +- Look for: dashboard links, alert configurations + +**Design:** +- Search: "Figma" OR "Sketch" OR "Adobe XD" +- Look for: design file links, handoff discussions + +**CRM:** +- Search: "Salesforce" OR "HubSpot" +- Look for: deal mentions, customer record links + +## Finding Organization Values + +**Workspace/project IDs:** +- Search for existing integrations or bookmarked links +- Look for admin/setup documentation + +**Team conventions:** +- Search: "story points" OR "estimation" +- Search: "workflow" OR "ticket status" +- Look for engineering process docs + +**Channel/team names:** +- Search: "standup" OR "engineering" OR "releases" +- Look for channel naming patterns + +## When Knowledge MCPs Are Unavailable + +If no knowledge MCPs are configured, skip automatic discovery and proceed directly to AskUserQuestion for all categories. Note: AskUserQuestion always includes a Skip button and a free-text input box for custom answers, so do not include `None` or `Other` as options. diff --git a/system-prompts/data-token-counting-reference.md b/system-prompts/data-token-counting-reference.md new file mode 100644 index 0000000..d8157c9 --- /dev/null +++ b/system-prompts/data-token-counting-reference.md @@ -0,0 +1,61 @@ + +# Token Counting + +Use the `count_tokens` endpoint (`POST /v1/messages/count_tokens`) for accurate +token counts against Claude models. Token counts are **model-specific** — pass +the same model ID you'll use for inference. + +**Do not use `tiktoken`.** It's OpenAI's tokenizer. It undercounts Claude +tokens by ~15–20% on typical text, and by much more on code or non-English +input. Any estimate from `tiktoken`, `gpt-tokenizer`, or similar is wrong for +Claude. + +## Count a file or string + +```python +from anthropic import Anthropic + +client = Anthropic() +resp = client.messages.count_tokens( + model="{{OPUS_ID}}", + messages=[{"role": "user", "content": open("CLAUDE.md").read()}], +) +print(resp.input_tokens) +``` + +TypeScript: `await client.messages.countTokens({model, messages})` → +`.input_tokens`. See `{lang}/claude-api/README.md` for other SDKs. + +## CLI + +```sh +ant messages count-tokens --model {{OPUS_ID}} \ + --message '{role: user, content: "@./CLAUDE.md"}' \ + --transform input_tokens -r +``` + +## Diffing a file across two versions + +The endpoint is stateless — count each version separately and subtract: + +```python +from anthropic import Anthropic +import subprocess + +client = Anthropic() +def count(text: str) -> int: + return client.messages.count_tokens( + model="{{OPUS_ID}}", + messages=[{"role": "user", "content": text}], + ).input_tokens + +before = subprocess.check_output(["git", "show", "HEAD:CLAUDE.md"], text=True) +after = open("CLAUDE.md").read() +print(count(after) - count(before)) +``` + +Full docs: see the Token Counting entry in `shared/live-sources.md`. diff --git a/system-prompts/skill-build-with-claude-api-reference-guide.md b/system-prompts/skill-build-with-claude-api-reference-guide.md index f25bb2d..93d5ef9 100644 --- a/system-prompts/skill-build-with-claude-api-reference-guide.md +++ b/system-prompts/skill-build-with-claude-api-reference-guide.md @@ -1,7 +1,7 @@ ## Reference Documentation @@ -24,6 +24,9 @@ The relevant documentation for your detected language is included below in ` # Building LLM-Powered Applications with Claude @@ -159,7 +159,7 @@ Everything goes through `POST /v1/messages`. Tools and output constraints are fe **Structured outputs** — Constrains the Messages API response format (`output_config.format`) and/or tool parameter validation (`strict: true`). The recommended approach is `client.messages.parse()` which validates responses against your schema automatically. Note: the old `output_format` parameter is deprecated; use `output_config: {format: {...}}` on `messages.create()`. -**Supporting endpoints** — Batches (`POST /v1/messages/batches`), Files (`POST /v1/files`), Token Counting, and Models (`GET /v1/models`, `GET /v1/models/{id}` — live capability/context-window discovery) feed into or support Messages API requests. +**Supporting endpoints** — Batches (`POST /v1/messages/batches`), Files (`POST /v1/files`), Token Counting (`POST /v1/messages/count_tokens` — see `shared/token-counting.md`), and Models (`GET /v1/models`, `GET /v1/models/{id}` — live capability/context-window discovery) feed into or support Messages API requests. --- @@ -265,6 +265,8 @@ After detecting the language, read the relevant files based on what the user nee → Read `shared/model-migration.md` **Prompt caching / optimize caching / "why is my cache hit rate low":** → Read `shared/prompt-caching.md` + `{lang}/claude-api/README.md` (Prompt Caching section) +**Count tokens in a file / prompt / diff ("how many tokens is X"):** +→ Read `shared/token-counting.md` — use `messages.count_tokens`, never `tiktoken` **Function calling / tool use / agents:** → Read `{lang}/claude-api/README.md` + `shared/tool-use-concepts.md` + `{lang}/claude-api/tool-use.md` diff --git a/system-prompts/skill-cowork-plugin-authoring.md b/system-prompts/skill-cowork-plugin-authoring.md new file mode 100644 index 0000000..87ac764 --- /dev/null +++ b/system-prompts/skill-cowork-plugin-authoring.md @@ -0,0 +1,370 @@ + +# Cowork Plugin Authoring + +Create a new Cowork plugin from scratch, or customize an existing one for a specific organization. Both paths deliver a ready-to-install `.plugin` file at the end. + +## Determining the Mode + +Decide from the user's request: + +- **Customize** — the user names an existing installed plugin ("customize the X plugin", "configure X for my company", "set up the X plugin", "update the X skill"). Follow **Customizing an Existing Plugin** below. +- **Create** — the user wants to build a plugin from scratch ("create a plugin for X", "make a new plugin", "build a plugin that does X"). Follow **Creating a New Plugin** below. + +> **Nontechnical output**: Keep all user-facing conversation in plain language. Never mention file paths, directory structures, schema fields, `~~` prefixes, or placeholders unless the user asks. Frame everything in terms of what the plugin will do. + +> **AskUserQuestion**: When you need input, use AskUserQuestion. Don't assume "industry standard" defaults are correct. AskUserQuestion always includes a Skip button and a free-text input box for custom answers, so do not include `None` or `Other` as options. + +## Plugin Architecture + +A plugin is a self-contained directory that extends Claude with skills, agents, hooks, and MCP server integrations. + +### Directory Structure + +``` +plugin-name/ +├── .claude-plugin/ +│ └── plugin.json # Required: plugin manifest +├── skills/ # Skills (subdirectories with SKILL.md) +│ └── skill-name/ +│ ├── SKILL.md +│ └── references/ +├── agents/ # Subagent definitions (.md files) +├── .mcp.json # MCP server definitions +└── README.md # Plugin documentation +``` + +> **Legacy `commands/` format**: Older plugins may include a `commands/` directory with single-file `.md` slash commands. This format still works, but new plugins should use `skills/*/SKILL.md` instead — the Cowork UI presents both as a single "Skills" concept, and the skills format supports progressive disclosure via `references/`. Treat `commands/*.md` files the same way you would `skills/*/SKILL.md` when customizing. + +**Rules:** + +- `.claude-plugin/plugin.json` is always required +- Component directories (`skills/`, `agents/`) go at the plugin root, not inside `.claude-plugin/` +- Only create directories for components the plugin actually uses +- Use kebab-case for all directory and file names + +### plugin.json Manifest + +Located at `.claude-plugin/plugin.json`. Minimal required field is `name`. + +```json +{ + "name": "plugin-name", + "version": "0.1.0", + "description": "Brief explanation of plugin purpose", + "author": { + "name": "Author Name" + } +} +``` + +**Name rules:** kebab-case, lowercase with hyphens, no spaces or special characters. +**Version:** semver format (MAJOR.MINOR.PATCH). Start at `0.1.0`. + +Optional fields: `homepage`, `repository`, `license`, `keywords`. + +Custom component paths can be specified (supplements, does not replace, auto-discovery): + +```json +{ + "commands": "./custom-commands", + "agents": ["./agents", "./specialized-agents"], + "hooks": "./config/hooks.json", + "mcpServers": "./.mcp.json" +} +``` + +### Component Summary + +Detailed schemas for each component type are in `references/component-schemas.md`. + +| Component | Location | Format | +| ---------------------------------- | ------------------- | --------------------------- | +| Skills | `skills/*/SKILL.md` | Markdown + YAML frontmatter | +| MCP Servers | `.mcp.json` | JSON | +| Agents (uncommonly used in Cowork) | `agents/*.md` | Markdown + YAML frontmatter | +| Hooks (rarely used in Cowork) | `hooks/hooks.json` | JSON | +| Commands (legacy) | `commands/*.md` | Markdown + YAML frontmatter | + +This schema is shared with Claude Code's plugin system, but you're building for Claude Cowork, a desktop app for knowledge work. Cowork users will usually find skills the most useful. **Scaffold new plugins with `skills/*/SKILL.md` — do not create `commands/` unless the user explicitly needs the legacy single-file format.** + +### Customizable plugins with `~~` placeholders + +> **Do not use or ask about this pattern by default.** Only introduce `~~` placeholders if the user explicitly says they want people outside their organization to use the plugin. You can mention it as an option if they want to distribute externally, but do not proactively ask with AskUserQuestion. + +When a plugin is intended to be shared outside the author's company, it might reference external tools by category rather than specific product (e.g., "project tracker" instead of "Jira"). Use generic language and mark these as requiring customization with two tilde characters: `create an issue in ~~project tracker`. + +If any tool categories are used, write a `CONNECTORS.md` file at the plugin root to explain: + +```markdown +# Connectors + +## How tool references work + +Plugin files use `~~category` as a placeholder for whatever tool the user +connects in that category. Plugins are tool-agnostic — they describe +workflows in terms of categories rather than specific products. + +## Connectors for this plugin + +| Category | Placeholder | Options | +| --------------- | ------------------- | ------------------------------- | +| Chat | `~~chat` | Slack, Microsoft Teams, Discord | +| Project tracker | `~~project tracker` | Linear, Asana, Jira | +``` + +### ${CLAUDE_PLUGIN_ROOT} Variable + +Use `${CLAUDE_PLUGIN_ROOT}` for all intra-plugin path references in hooks and MCP configs. Never hardcode absolute paths. + +## Creating a New Plugin + +Build from scratch through a five-phase guided conversation. + +### Phase 1: Discovery + +Understand what the user wants to build and why. Ask (only what is unclear — skip questions the user's initial request already answers): + +- What should this plugin do? What problem does it solve? +- Who will use it and in what context? +- Does it integrate with any external tools or services? +- Is there a similar plugin or workflow to reference? + +Summarize understanding and confirm before proceeding. + +### Phase 2: Component Planning + +Based on discovery, determine which component types are needed: + +- **Skills** — Specialized knowledge Claude loads on-demand, or user-initiated actions (domain expertise, reference schemas, workflow guides, deploy/configure/analyze/review actions) +- **MCP Servers** — External service integration (databases, APIs, SaaS tools) +- **Agents (uncommon)** — Autonomous multi-step tasks (validation, generation, analysis) +- **Hooks (rare)** — Automatic behavior on certain events (enforce policies, load context, validate operations) + +Present a component plan table including types you decided not to create: + +``` +| Component | Count | Purpose | +|-----------|-------|---------| +| Skills | 3 | Domain knowledge for X, /do-thing, /check-thing | +| Agents | 0 | Not needed | +| Hooks | 1 | Validate writes | +| MCP | 1 | Connect to service Y | +``` + +Get user confirmation before proceeding. + +### Phase 3: Design & Clarifying Questions + +Specify each component in detail. Resolve all ambiguities before implementation. Present questions grouped by component type and wait for answers. + +**Skills:** + +- What user queries should trigger this skill? +- What knowledge domains does it cover? +- Should it include reference files for detailed content? +- If it represents a user-initiated action: what arguments does it accept, and what tools does it need? (Read, Write, Bash, Grep, etc.) + +**Agents:** + +- Should it trigger proactively or only when requested? +- What tools does it need? +- What output format? + +**Hooks:** + +- Which events? (PreToolUse, PostToolUse, Stop, SessionStart, etc.) +- What behavior — validate, block, modify, add context? +- Prompt-based (LLM-driven) or command-based (deterministic script)? + +**MCP Servers:** + +- What server type? (stdio for local, SSE for hosted with OAuth, HTTP for REST APIs) +- What authentication method? +- What tools should be exposed? + +If the user says "whatever you think is best," provide specific recommendations and get explicit confirmation. + +### Phase 4: Implementation + +Create all plugin files following best practices. + +1. Create the plugin directory structure +2. Create `plugin.json` manifest +3. Create each component (see `references/component-schemas.md` for exact formats) +4. Create `README.md` documenting the plugin + +**Guidelines:** + +- **Skills** use progressive disclosure: lean SKILL.md body (under 3,000 words), detailed content in `references/`. Frontmatter description must be third-person with specific trigger phrases. Skill bodies are instructions FOR Claude, not messages to the user — write them as directives. +- **Agents** need a description with `` blocks showing triggering conditions, plus a system prompt in the markdown body. +- **Hooks** config goes in `hooks/hooks.json`. Use `${CLAUDE_PLUGIN_ROOT}` for script paths. Prefer prompt-based hooks for complex logic. +- **MCP configs** go in `.mcp.json` at plugin root. Use `${CLAUDE_PLUGIN_ROOT}` for local server paths. Document required env vars in README. + +### Phase 5: Review + +1. Summarize what was created — list each component and its purpose +2. Ask if the user wants any adjustments +3. Run `claude plugin validate ` to check the plugin structure. If this command is unavailable (e.g., when running inside Cowork), verify manually: + - `.claude-plugin/plugin.json` exists and contains valid JSON with at least a `name` field + - The `name` field is kebab-case (lowercase letters, numbers, and hyphens only) + - Any component directories referenced by the plugin (`commands/`, `skills/`, `agents/`, `hooks/`) actually exist and contain files in the expected formats — `.md` for commands/skills/agents, `.json` for hooks + - Each skill subdirectory contains a `SKILL.md` + - Report what passed and what didn't, the same way the CLI validator would + + Fix any errors, then proceed to **Packaging**. + +## Customizing an Existing Plugin + +Customize a plugin for a specific organization — either by setting up a generic plugin template for the first time, or by tweaking an already-configured plugin. + +### Finding the plugin + +Run `find mnt/.local-plugins mnt/.plugins ~/.claude/plugins/synced -type d -name "**" 2>/dev/null` to locate the plugin directory, then read its files to understand its structure before making changes. + +If you cannot find the plugin directory in any of those locations, let the user know: "I couldn't find an installed plugin named ''. If it's installed on your desktop, open this task from the Cowork desktop app so I can access it." + +### Determining the Customization Mode + +After locating the plugin, check for `~~`-prefixed placeholders: `grep -rn '~~\w' /path/to/plugin --include='*.md' --include='*.json'` + +> **Default rule**: If `~~` placeholders exist, default to **Generic plugin setup** unless the user explicitly asks to customize a specific part of the plugin. + +**1. Generic plugin setup** — The plugin contains `~~`-prefixed placeholders. These are customization points in a template that need to be replaced with real values (e.g., `~~Jira` → `Asana`, `~~your-team-channel` → `#engineering`). + +**2. Scoped customization** — No `~~` placeholders exist, and the user asked to customize a specific part of the plugin (e.g., "customize the connectors", "update the standup skill", "change the ticket tool"). Read the plugin files to find the relevant section(s) and focus only on those. Do not scan the entire plugin or present unrelated customization items. + +**3. General customization** — No `~~` placeholders exist, and the user wants to modify the plugin broadly. Read the plugin's files to understand its current configuration, then ask the user what they'd like to change. + +> **Important**: Never change the name of the plugin or skill being customized. Do not rename directories, files, or the plugin/skill name fields. + +### Customization Workflow + +#### Phase 0: Gather User Intent (scoped and general customization only) + +Check whether the user provided free-form context alongside their request (e.g., "customize the standup skill — we do async standups in #eng-updates every morning"). + +- **If the user provided context**: Record it and use it to pre-fill answers in Phase 3 — skip asking questions the user already answered here. +- **If the user did not provide context**: Ask a single open-ended question using AskUserQuestion before proceeding. Tailor it to what they asked to customize — e.g., "What changes do you have in mind for the brief skill?" or "What would you like to change about how this plugin works?" Keep it short and specific. + +#### Phase 1: Gather Context from Knowledge MCPs + +Use company-internal knowledge MCPs to collect information relevant to the customization scope. See `references/search-strategies.md` for detailed query patterns. + +**What to gather** (scope to what's relevant): + +- Tool names and services the organization uses +- Organizational processes and workflows +- Team conventions (naming, statuses, estimation scales) +- Configuration values (workspace IDs, project names, team identifiers) + +**Sources to search:** + +1. **Chat/Slack MCPs** — tool mentions, integrations, workflow discussions +2. **Document MCPs** — onboarding docs, tool guides, setup instructions +3. **Email MCPs** — license notifications, admin emails, setup invitations + +Record all findings for use in Phase 3. + +#### Phase 2: Create Todo List + +Build a todo list of changes to make, scoped appropriately: + +- **Scoped customization**: Only items related to the specific section the user asked about. +- **Generic plugin setup**: Run `grep -rn '~~\w' /path/to/plugin --include='*.md' --include='*.json'` to find all placeholder customization points. Group them by theme. +- **General customization**: Read the plugin files, understand the current config, and based on the user's request, identify what needs to change. + +Use user-friendly descriptions that focus on the plugin's purpose: + +- **Good**: "Learn how standup prep works at Company" +- **Bad**: "Replace placeholders in skills/standup-prep/SKILL.md" + +#### Phase 3: Complete Todo Items + +Work through each item using context from Phase 0 and Phase 1. + +**If the user's free-form input (Phase 0) or knowledge MCPs (Phase 1) provided a clear answer**: Apply directly without confirmation. + +**Otherwise**: Use AskUserQuestion. Don't assume "industry standard" defaults are correct — if neither the user's input nor knowledge MCPs provided a specific answer, ask. + +**Types of changes:** + +1. **Placeholder replacements** (generic setup): `~~Jira` → `Asana`, `~~your-org-channel` → `#engineering` +2. **Content updates**: Modifying instructions, skills, workflows, or references to match the organization +3. **URL pattern updates**: `tickets.example.com/your-team/123` → `app.asana.com/0/PROJECT_ID/TASK_ID` +4. **Configuration values**: Workspace IDs, project names, team identifiers + +If the user doesn't know or skips, leave the value unchanged (or the `~~`-prefixed placeholder, for generic setup). + +#### Phase 4: Search for Useful MCPs + +After customization items are resolved, connect MCPs for any tools that were identified or changed. See `references/mcp-servers.md` for the full workflow, category-to-keywords mapping, and config file format. + +For each tool identified during customization: + +1. Search the registry: `search_mcp_registry(keywords=[...])` using category keywords from `references/mcp-servers.md`, or search for the specific tool name if already known +2. If unconnected: `suggest_connectors(directoryUuids=["chosen-uuid"])` — user completes auth +3. Update the plugin's MCP config file (check `plugin.json` for custom location, otherwise `.mcp.json` at root) + +Collect all MCP results and present them together in the summary output — don't present MCPs one at a time during this phase. + +### Summary Output + +After customization, present the user with a summary of what was learned grouped by source. Always include the MCPs sections showing which were connected and which the user should still connect: + +```markdown +## From searching Slack + +- You use Asana for project management +- Sprint cycles are 2 weeks + +## From searching documents + +- Story points use T-shirt sizes + +## From your answers + +- Ticket statuses are: Backlog, In Progress, In Review, Done +``` + +Then present the MCPs that were connected during setup and any that the user should still connect, with instructions. + +If no knowledge MCPs were available in Phase 1, and the user had to answer at least one question manually, include a note at the end: + +> By the way, connecting sources like Slack or Microsoft Teams would let me find answers automatically next time you customize a plugin. + +Then proceed to **Packaging**. + +## Packaging + +After create or customize completes, package the plugin as a `.plugin` file and deliver it with the SendUserFile tool: + +1. Zip the plugin directory: + ```bash + cd /path/to/plugin-dir && zip -r /tmp/plugin-name.plugin . -x "setup/*" -x "*.DS_Store" + ``` +2. Call `SendUserFile` with `files: ["/tmp/plugin-name.plugin"]`, `status: "normal"`, and a short caption summarizing what was built or changed. + +The `.plugin` file will appear in the chat as a rich preview where the user can browse the files and accept the plugin by pressing a button. + +> **Naming**: Use the plugin name from `plugin.json` (for create) or the original plugin directory name (for customize) as the `.plugin` filename. Do not rename the plugin or its files during customization — only replace placeholder values and update content. + +## Best Practices + +- **Start small**: Begin with the minimum viable set of components. A plugin with one well-crafted skill is more useful than one with five half-baked components. +- **Progressive disclosure for skills**: Core knowledge in SKILL.md, detailed reference material in `references/`, working examples in `examples/`. +- **Clear trigger phrases**: Skill descriptions should include specific phrases users would say. Agent descriptions should include `` blocks. +- **Skills are for Claude**: Write skill body content as instructions for Claude to follow, not documentation for the user to read. +- **Imperative writing style**: Use verb-first instructions in skills ("Parse the config file," not "You should parse the config file"). +- **Portability**: Always use `${CLAUDE_PLUGIN_ROOT}` for intra-plugin paths, never hardcoded paths. +- **Security**: Use environment variables for credentials, HTTPS for remote servers, least-privilege tool access. + +## Additional Resources + +- **`references/component-schemas.md`** — Detailed format specifications for every component type (skills, agents, hooks, MCP, legacy commands, CONNECTORS.md) +- **`references/example-plugins.md`** — Three complete example plugin structures at different complexity levels +- **`references/mcp-servers.md`** — MCP discovery workflow, category-to-keywords mapping, config file locations, example `.mcp.json` +- **`references/search-strategies.md`** — Knowledge MCP query patterns for finding tool names and org values diff --git a/system-prompts/skill-design-sync-package-source-shape.md b/system-prompts/skill-design-sync-package-source-shape.md index 66c2165..fa65970 100644 --- a/system-prompts/skill-design-sync-package-source-shape.md +++ b/system-prompts/skill-design-sync-package-source-shape.md @@ -1,7 +1,7 @@ # Package source shape @@ -22,7 +22,7 @@ No Storybook — the component list comes from the package's shipped `.d.ts` exp |---|---| | `pkg` / `globalName` | package name and the `window.*` global to assign — required | | `shape` | `'storybook'` or `'package'` — pins the source shape (overrides auto-detection). Written on first run. | - | `buildCmd` | the discovered build command; re-sync re-runs it | + | `buildCmd` | the discovered build command — tells Claude what to re-run before the converter on re-sync | | `srcDir` | source root when not `src/`/`lib/`/`components/` | | `tsconfig` | path to `tsconfig.json` — esbuild reads `compilerOptions.paths` so `@/…` path aliases resolve in synth-entry mode | | `extraEntries` | package names to merge into `window.` alongside the DS entry (e.g. the DS's separate icon package). Sibling icon packages under the same scope are auto-detected (`[ICON_PKG]`). | @@ -37,7 +37,7 @@ No Storybook — the component list comes from the package's shipped `.d.ts` exp | `runtimeFontPrefixes` | string[] — family-name prefixes for fonts the host app serves at runtime from a font service (via a `