Market Skill
Thin wrapper that routes market sizing research requests to the market-agent.
IMPORTANT: This skill implements the skill-internal postflight pattern. After the subagent returns,
this skill handles all postflight operations (status update, artifact linking, git commit) before returning.
Context Pointers
Reference (do not load eagerly):
- Path:
.claude/context/core/formats/subagent-return.md
- Purpose: Return validation
- Load at: Subagent execution only
Note: This skill is a thin wrapper. Context is loaded by the delegated agent, not this skill.
Trigger Conditions
This skill activates when:
Direct Invocation
- User explicitly runs
/market command
- User requests market sizing in conversation
Implicit Invocation (during task implementation)
When an implementing agent encounters any of these patterns:
Plan step language patterns:
- "Analyze market size"
- "Calculate TAM/SAM/SOM"
- "Market sizing analysis"
- "Estimate addressable market"
Target mentions:
- "TAM", "SAM", "SOM"
- "total addressable market"
- "market opportunity"
- "market sizing"
When NOT to trigger
Do not invoke for:
- Competitive analysis (use skill-analyze)
- GTM strategy (use skill-strategy)
- General business research (use skill-researcher)
- Revenue projections (not market sizing)
Execution Flow
Validate required inputs:
task_number - Must be provided and exist in state.jsonindustry - Optional, stringsegment - Optional, stringmode - Optional, one of: VALIDATE, SIZE, SEGMENT, DEFEND
bash
1# Lookup task
2task_data=$(jq -r --argjson num "$task_number" \
3 '.active_projects[] | select(.project_number == $num)' \
4 specs/state.json)
5
6# Validate exists
7if [ -z "$task_data" ]; then
8 return error "Task $task_number not found"
9fi
10
11# Extract fields
12language=$(echo "$task_data" | jq -r '.language // "founder"')
13status=$(echo "$task_data" | jq -r '.status')
14project_name=$(echo "$task_data" | jq -r '.project_name')
15description=$(echo "$task_data" | jq -r '.description // ""')
16
17# Validate mode if provided
18if [ -n "$mode" ]; then
19 case "$mode" in
20 VALIDATE|SIZE|SEGMENT|DEFEND) ;;
21 *) return error "Invalid mode: $mode. Must be VALIDATE, SIZE, SEGMENT, or DEFEND" ;;
22 esac
23fi
Stage 2: Preflight Status Update
Update task status to "researching" BEFORE invoking subagent.
Update state.json:
bash
1jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
2 --arg status "researching" \
3 --arg sid "$session_id" \
4 '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
5 status: $status,
6 last_updated: $ts,
7 session_id: $sid
8 }' specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json
Update TODO.md: Use Edit tool to change status marker to [RESEARCHING].
Stage 3: Create Postflight Marker
bash
1padded_num=$(printf "%03d" "$task_number")
2mkdir -p "specs/${padded_num}_${project_name}"
3
4cat > "specs/${padded_num}_${project_name}/.postflight-pending" << EOF
5{
6 "session_id": "${session_id}",
7 "skill": "skill-market",
8 "task_number": ${task_number},
9 "operation": "research",
10 "reason": "Postflight pending: status update, artifact linking, git commit",
11 "created": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
12}
13EOF
Stage 4: Prepare Delegation Context
json
1{
2 "task_context": {
3 "task_number": N,
4 "project_name": "{project_name}",
5 "description": "{description}",
6 "language": "founder"
7 },
8 "industry": "optional industry hint",
9 "segment": "optional segment hint",
10 "mode": "VALIDATE|SIZE|SEGMENT|DEFEND or null",
11 "metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json",
12 "metadata": {
13 "session_id": "sess_{timestamp}_{random}",
14 "delegation_depth": 1,
15 "delegation_path": ["orchestrator", "market", "skill-market"]
16 }
17}
Stage 5: Invoke Agent
CRITICAL: You MUST use the Task tool to spawn the agent.
Required Tool Invocation:
Tool: Task (NOT Skill)
Parameters:
- subagent_type: "market-agent"
- prompt: [Include task_context, industry, segment, mode, metadata_file_path, metadata]
- description: "Market sizing research with TAM/SAM/SOM"
The agent will:
- Present mode selection if not pre-selected
- Use forcing questions to gather market data
- Create research report at specs/{NNN}_{SLUG}/reports/
- Write metadata file
- Return brief text summary
Stage 6: Parse Subagent Return
bash
1padded_num=$(printf "%03d" "$task_number")
2metadata_file="specs/${padded_num}_${project_name}/.return-meta.json"
3
4if [ -f "$metadata_file" ] && jq empty "$metadata_file" 2>/dev/null; then
5 status=$(jq -r '.status' "$metadata_file")
6 artifact_path=$(jq -r '.artifacts[0].path // ""' "$metadata_file")
7 artifact_type=$(jq -r '.artifacts[0].type // ""' "$metadata_file")
8 artifact_summary=$(jq -r '.artifacts[0].summary // ""' "$metadata_file")
9else
10 status="failed"
11fi
Stage 7: Update Task Status (Postflight)
If status is "researched", update state.json and TODO.md.
Update state.json:
bash
1jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
2 --arg status "researched" \
3 '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
4 status: $status,
5 last_updated: $ts
6 }' specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json
Update TODO.md: Use Edit tool to change status marker to [RESEARCHED].
Stage 8: Link Artifacts
Add artifact to state.json with summary.
IMPORTANT: Use two-step jq pattern to avoid escaping issues.
bash
1if [ -n "$artifact_path" ]; then
2 # Step 1: Filter out existing research artifacts (use "| not" pattern)
3 jq '(.active_projects[] | select(.project_number == '$task_number')).artifacts =
4 [(.active_projects[] | select(.project_number == '$task_number')).artifacts // [] | .[] | select(.type == "research" | not)]' \
5 specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json
6
7 # Step 2: Add new research artifact
8 jq --arg path "$artifact_path" \
9 --arg type "$artifact_type" \
10 --arg summary "$artifact_summary" \
11 '(.active_projects[] | select(.project_number == '$task_number')).artifacts += [{"path": $path, "type": $type, "summary": $summary}]' \
12 specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json
13fi
Update TODO.md: Add research artifact link using count-aware format.
Strip specs/ prefix for TODO.md (TODO.md is inside specs/): todo_link_path="${artifact_path#specs/}"
Use count-aware artifact linking format per .claude/rules/state-management.md "Artifact Linking Format".
Stage 9: Git Commit
bash
1git add -A
2git commit -m "task ${task_number}: complete research
3
4Session: ${session_id}
5
6Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
Stage 10: Cleanup
bash
1rm -f "specs/${padded_num}_${project_name}/.postflight-pending"
2rm -f "specs/${padded_num}_${project_name}/.postflight-loop-guard"
3rm -f "specs/${padded_num}_${project_name}/.return-meta.json"
Stage 11: Return Brief Summary
Market sizing research completed for task {N}:
- Mode: {mode}, {questions_asked} forcing questions completed
- Problem: {brief problem statement}
- Entity count: {value} from {source}
- Research report: specs/{NNN}_{SLUG}/reports/01_{short-slug}.md
- Status updated to [RESEARCHED]
- Changes committed
- Next: Run /plan {N} to create implementation plan
Brief text summary (NOT JSON).
Expected successful return:
Market sizing research completed for task 234:
- Mode: SIZE, 8 forcing questions completed
- Problem: Streamline deploy coordination for mid-market SaaS
- Entity count: 500,000 mid-market SaaS companies globally (Gartner)
- Research report: specs/234_market_sizing_fintech/reports/01_market-sizing.md
- Status updated to [RESEARCHED]
- Changes committed with session sess_1736700000_abc123
- Next: Run /plan 234 to create implementation plan
Error Handling
Return immediately if task not found.
Keep status as "researching" for resume.
User Abandonment
Return partial status with progress made.
Git Commit Failure
Non-blocking: Log failure but continue.
