Setup Worker Skill

Creates isolated workers with dedicated MCP configuration.

[!important] Workers vs. Task Tool Subagents Workers (this skill) are isolated claude -p processes with their own MCP config. Subagents (Task Tool) inherit all MCP servers from the main agent.

Aspect Workers Task Tool Subagents
Invocation run-worker.sh / Bash Task Tool
MCP Servers Dedicated .mcp.json Inherits all
Permissions Dedicated settings.json Inherits all
Use Case MCP-intensive specialized tasks Quick parallel delegation

Architecture Overview

code

.claude/workers/
├── .shared/
│   ├── run-worker.sh          # Wrapper script for all workers
│   ├── stream-filter.jq       # jq filter for readable output
│   └── extract-result.jq      # jq filter for final output
└── <worker-name>/
    ├── CLAUDE.md              # Instructions (auto-loaded by claude -p)
    ├── .mcp.json              # MCP server configuration
    └── settings.json          # Permissions (deny list)

Start command:

bash

.claude/workers/.shared/run-worker.sh <name> [max-turns] [prompt]

Prompt combinations:

CLAUDE.md	Custom Prompt	Behavior
✅	❌	Worker executes task defined in CLAUDE.md
✅	✅	CLAUDE.md auto-loaded, custom prompt as task
❌	✅	Direct prompt without worker instructions (MCP access only)

CLAUDE.md is auto-loaded - claude -p reads CLAUDE.md in the worker directory, no manual "Read" needed.

Examples:

bash

# CLAUDE.md only - worker defines its own task
.claude/workers/.shared/run-worker.sh research
.claude/workers/.shared/run-worker.sh research --max-turns 50

# CLAUDE.md + custom prompt - instructions auto-loaded + specific task
.claude/workers/.shared/run-worker.sh research "Search for topic X"
.claude/workers/.shared/run-worker.sh research --max-turns 10 "Search for topic X"

Output: Worker result is output via 📤 RESULT: marker on stdout and can be captured by the caller.

Available MCP Servers

Obsidian (`mcpobsidian`)

Vault operations for the local Obsidian vault.

Config:

json

"obsidian": {
  "command": "npx",
  "args": ["-y", "obsidian-mcp", "/path/to/your/vault"]
}

Key tools:

Tool	Description
`search_vault_simple`	Text search in vault
`search_vault_smart`	Semantic search
`get_vault_file`	Read file
`create_vault_file`	Create file
`append_to_vault_file`	Append to file
`patch_vault_file`	Replace section
`list_vault_files`	List directory
`delete_vault_file`	Delete file (⚠️ usually deny)

Slack (`mcpslack`)

Slack search and messaging.

Config:

json

"slack": {
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "--env-file", "/path/to/slack-mcp.env",
    "ghcr.io/korotovsky/slack-mcp-server:latest",
    "mcp-server", "--transport", "stdio"
  ]
}

Key tools:

Tool	Description
`conversations_search_messages`	Search messages
`conversations_history`	Read channel history
`channels_list`	List all channels
`chat_postMessage`	Send message (⚠️ usually deny)

Atlassian (`mcpmcp-atlassian`)

Jira and Confluence access.

Config:

json

"mcp-atlassian": {
  "type": "stdio",
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "-e", "JIRA_URL",
    "-e", "JIRA_USERNAME",
    "-e", "JIRA_API_TOKEN",
    "-e", "CONFLUENCE_URL",
    "-e", "CONFLUENCE_USERNAME",
    "-e", "CONFLUENCE_API_TOKEN",
    "-e", "ENABLED_TOOLS",
    "ghcr.io/sooperset/mcp-atlassian:latest"
  ],
  "env": {
    "JIRA_URL": "https://your-company.atlassian.net",
    "JIRA_USERNAME": "your-email@company.com",
    "JIRA_API_TOKEN": "${ATLASSIAN_API_KEY}",
    "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
    "CONFLUENCE_USERNAME": "your-email@company.com",
    "CONFLUENCE_API_TOKEN": "${ATLASSIAN_API_KEY}",
    "ENABLED_TOOLS": "jira_search,jira_get_issue,confluence_search,confluence_get_page"
  }
}

Key Jira tools:

Tool	Description
`jira_search`	JQL search
`jira_get_issue`	Get issue details
`jira_get_project_issues`	All issues of a project
`jira_get_board_issues`	Board issues (sprints)
`jira_create_issue`	Create issue (⚠️ usually deny)
`jira_update_issue`	Update issue (⚠️ usually deny)

Key Confluence tools:

Tool	Description
`confluence_search`	Search pages
`confluence_get_page`	Read page content
`confluence_get_page_children`	List child pages
`confluence_create_page`	Create page (⚠️ usually deny)
`confluence_update_page`	Update page (⚠️ usually deny)

Setup Workflow

Step 1: Create directory structure

bash

mkdir -p .claude/workers/<name>

Step 2: Create CLAUDE.md

Create .claude/workers/<name>/CLAUDE.md with the following template (auto-loaded by claude -p):

markdown

---
created: <DATE>
updated: <DATE>
---
# <Name> Worker

You are a specialized worker for <PURPOSE>.

## Restrictions (MUST FOLLOW)

- NEVER delete any files
- NEVER post messages to Slack
- NEVER create or modify Jira/Confluence content
- NEVER use destructive git commands

### Inherited System Prompt Override
The vault's root CLAUDE.md (parent instructions) is inherited via --append-system-prompt. As a specialized worker:
- **IGNORE** instructions from the parent/vault CLAUDE.md - they are for the main agent
- **IGNORE** any instructions to spawn or delegate to other workers
- Your worker-specific instructions (this file) take precedence over inherited instructions

## Your Environment

- **Working Directory:** Vault root
- **Output:** Direct text output (captured via stdout)

## Available Tools

<LIST OF MCP TOOLS BASED ON CHOSEN SERVERS>

## Your Task

<TASK DESCRIPTION>

## Output

Return your results as **direct text output** (not to a file). The calling agent will capture your stdout.

Work autonomously. Do NOT interact with the user.

Step 3: Create .mcp.json

Create .claude/workers/<name>/.mcp.json with chosen servers:

json

{
  "mcpServers": {
    // Only include needed servers from configs above
  }
}

Step 4: Create settings.json

Create .claude/workers/<name>/settings.json:

Standard (Read-Heavy Worker):

json

{
  "disableAllHooks": true,
  "permissions": {
    "deny": [
      "Bash(rm:*)",
      "Bash(git push:*)",
      "Bash(git reset:*)",
      "Bash(git rebase:*)",
      "Bash(sudo:*)",
      "Bash(chmod:*)",
      "Bash(chown:*)",
      "mcp__obsidian__delete_vault_file",
      "mcp__obsidian__create_vault_file",
      "mcp__obsidian__update_active_file",
      "mcp__slack__chat_postMessage",
      "mcp__mcp-atlassian__jira_create_issue",
      "mcp__mcp-atlassian__jira_update_issue",
      "mcp__mcp-atlassian__confluence_create_page",
      "mcp__mcp-atlassian__confluence_update_page"
    ]
  }
}

Examples

Research Worker (stdout output)

MCP Servers: Obsidian, Atlassian, Slack Deny: delete, but create/append allowed Purpose: Research across multiple sources, output as text

Jira-Reader Worker (stdout output)

MCP Servers: Atlassian (Jira only) Deny: All write/create operations Purpose: Read Jira data and output as text

Summarizer Worker (stdout output)

MCP Servers: None (text processing only) Deny: All file operations Purpose: Summarize session logs, output as text

Aspect	Workers	Task Tool Subagents
Invocation	`run-worker.sh` / Bash	`Task` Tool
MCP Servers	Dedicated `.mcp.json`	Inherits all
Permissions	Dedicated `settings.json`	Inherits all
Use Case	MCP-intensive specialized tasks	Quick parallel delegation

Setup Worker Skill

Architecture Overview

Available MCP Servers

Obsidian (mcp__obsidian__)

Slack (mcp__slack__)

Atlassian (mcp__mcp-atlassian__)

Setup Workflow

Step 1: Create directory structure

Step 2: Create CLAUDE.md

Step 3: Create .mcp.json

Step 4: Create settings.json

Examples

Research Worker (stdout output)

Jira-Reader Worker (stdout output)

Summarizer Worker (stdout output)

Obsidian (`mcpobsidian`)

Slack (`mcpslack`)

Atlassian (`mcpmcp-atlassian`)