Skill Definitions

Trovella's research system consists of four skills that work together. Each skill is a markdown file at .claude/skills/<name>/SKILL.md with YAML frontmatter (name, description) and structured instructions that the AI platform follows during execution.

Router Skill: /research

File: .claude/skills/research/SKILL.md

The router skill is the only skill the user invokes directly. It handles the interview phase, classifies the request, and delegates to either scan or deep mode. The user never sees the routing decision.

Responsibilities

1. Interview -- parse the user's message to extract eight elements: topic, researchType, scope, depthSignals, decisionContext, knownContext, outputMediaType, and outputFormattingInstructions
2. Clarification -- ask 0-2 follow-up questions when the topic is ambiguous or scope is unclear (never more than 2)
3. Route -- classify as scan or deep based on complexity, depth signals, and scope (see Routing Logic)
4. Initialize tracking -- call log_skill_execution with all extracted metadata
5. Delegate -- execute the scan or deep workflow inline (the router skill contains both execution paths)

Research Types

The router classifies every request into one of three types, which determines plan structure in both scan and deep modes:

Type	Trigger patterns	Example
general_topic	"What is X?", "Tell me about X", "Current state of X"	"Research the current state of WebAssembly adoption"
competitive_analysis	"Compare X and Y", "Who competes with X?", "Market for X"	"Give me a competitive analysis of AI code assistants"
decision_support	"Should I use X or Y?", "Pros and cons", "Which is better for..."	"Should I use Postgres or MongoDB for our new service?"

Output Media Types

The router extracts the user's preferred output format. If the prompt does not indicate a format, the router always asks:

conversation | markdown | html | word | excel | powerpoint

Scan Skill: /research-scan

File: .claude/skills/research-scan/SKILL.md

Fast, focused research producing key facts and a concise summary. Activated when the router classifies the request as simple or the user signals they want speed.

Plan Templates

Plans have 2-4 steps with no branching conditions and no checkpoints.

General topic (2-3 steps):

1. search -- gather key facts, statistics, and current state
2. analyze -- organize findings into themes, assess confidence
3. synthesize -- produce concise summary with key takeaways

Competitive analysis (3-4 steps):

1. search -- identify key players and positioning
2. extract -- structured per-competitor data
3. analyze -- compare across dimensions
4. synthesize -- comparison summary with positioning insights

Decision support (3 steps):

1. search -- research all options, gather evidence
2. analyze -- evaluate against criteria, weigh trade-offs
3. synthesize -- recommendation with confidence and key trade-offs

Plan naming convention: [Scan] <descriptive topic name>

Key Behaviors

• No branching conditions -- plans are always linear
• No checkpoint steps -- runs straight through
• Every step requires a stepExecutionReport documenting the AI platform's reasoning, web searches, web fetches, and tool calls
• Significant outputs are stored as research artifacts via store_research

Deep Skill: /research-deep

File: .claude/skills/research-deep/SKILL.md

Comprehensive, multi-perspective research with human checkpoints and adaptive branching. Activated when the router classifies the request as complex or the user signals they want depth.

Decomposition Phase

Before creating a plan, the deep skill decomposes the research question into:

1. Core question -- what the user ultimately needs to understand or decide
2. Known entities -- what is already established from the user's message
3. Unknown entities -- what needs to be discovered
4. Sub-questions (2-5) -- questions that, when answered, fully address the core question

This decomposition directly shapes the plan steps.

Plan Templates

Plans have 5-8+ steps, always including at least one checkpoint before synthesis.

General topic (5-7 steps):

1. search -- broad survey: concepts, history, current state, major players
2. search -- focused investigation of specific sub-questions
3. extract -- structure key data points, statistics, claims with sources
4. analyze -- cross-reference, patterns, contradictions, gaps
5. critique -- challenge the analysis: missing info, biases, confidence
6. checkpoint -- present interim findings for user review
7. synthesize -- final synthesis with user feedback incorporated

Competitive analysis (6-8 steps):

1. search -- identify all relevant competitors
2. search -- deep dive per competitor: product, positioning, strategy
3. extract -- structured per-competitor extraction (consistent schema via extract_data)
4. analyze -- comparative analysis across dimensions
5. critique -- gaps, biases, confidence per competitor
6. checkpoint -- present landscape for user review
7. synthesize -- final comparison with strategic insights
8. (Optional) custom -- follow up on user feedback from checkpoint

Decision support (6-7 steps):

1. search -- all options plus alternatives user may not have considered
2. search -- decision criteria: what factors matter for this type of decision
3. extract -- structured pros, cons, risks, costs per option
4. analyze -- multi-criteria scoring
5. critique -- sensitivity analysis: which assumptions matter most
6. checkpoint -- present analysis for user review
7. synthesize -- recommendation with confidence, trade-offs, and conditions

Plan naming convention: [Deep] <descriptive topic name>

Branching and Adaptation

Deep plans use branching conditions for quality gates. The primary pattern:

branchingConditions: [{
  afterStepOrder: <critique step>,
  conditionExpression: "confidence < 0.5",
  ifTrueAction: "fail"
}]

Additionally, the critique step instructions direct the AI platform to call modify_plan if confidence is below 0.6, adding targeted search steps to fill identified gaps. All modifications require a modificationRationale explaining why the change was needed.

Checkpoint Behavior

At checkpoint steps, the plan pauses via request_user_review and presents:

• A markdown summary of findings so far
• Specific questions for the user

User responses and their effects:

Decision	Effect
approve	Step marked completed, plan resumes
modify	Feedback appended to instructions, step returns to in_progress
skip	Step marked skipped, plan resumes
reject	Step and plan marked failed

Subagent Support

Deep dives can spawn subagents for parallel research across competitors or sub-topics. Each subagent calls submit_subagent_report to persist its execution report as a research artifact, returning a reportId that the parent includes in its own stepExecutionReport.subagents[] array.

Output Skill: /research-output

File: .claude/skills/research-output/SKILL.md

Generates and delivers the final research deliverable after a plan completes. Invoked automatically when get_next_step returns plan_complete, or manually by the user.

Responsibilities

1. Load context -- call get_research_context to load all step results, artifacts, and metadata
2. Generate deliverable -- format results according to the user's requested media type and formatting instructions
3. Store deliverable -- call store_research_output to persist the output for later retrieval
4. Present to user -- deliver the formatted output
5. Capture feedback -- collect initial feedback immediately, then closing feedback when the conversation shifts

Formatting Priority

When generating output, formatting instructions are applied in this priority order:

1. User's formatting instructions (outputFormattingInstructions) -- highest priority
2. Planning agent's notes (planFormattingNotes) -- structural guidance from plan creation
3. Step formatting notes (stepFormattingNotes) -- ideas discovered during execution
4. Output skill's judgment -- fills gaps based on what the research actually found

Feedback Capture

Two feedback moments ensure user satisfaction is always recorded:

Moment	Trigger	Tool call
Initial	Right after delivering results	submit_research_feedback({ feedbackType: "initial", ... })
Closing	When conversation shifts to another topic	submit_research_feedback({ feedbackType: "closing", ... })

If the user does not respond to the feedback prompt, the skill still records userSatisfaction: "none" with a note that the user did not respond.

Related Pages

• Execution Flow -- the end-to-end lifecycle these skills drive
• Routing Logic -- how the router decides between scan and deep
• Lifecycle Tracking -- how skill invocations are tracked
• Plan Orchestration -- the plan state machine and step types
• Reasoning -- the AI integration layer