| name | consult-spec |
| description | TRIGGER CONDITIONS - invoke this skill when ANY of these apply:
User-triggered (explicit request):
- User mentions "specification", "SPEC", "SPEC.md", "spec requirements"
- User asks to "verify with spec", "confirm with specification", "check requirements"
- User requests "authoritative requirements" or "source of truth"
Agent self-triggered (during reasoning):
- Before implementing any feature or making code changes
- When verifying technical requirements or constraints
- When making architectural or design decisions
- When you need unbiased guidance not influenced by current implementation
- When encountering conflicting information and need ground truth
PURPOSE: Consults SPEC.md through an isolated subagent that ONLY reads the
specification, never implementation code. This ensures guidance is based on
authoritative requirements, not potentially incorrect existing code.
|
| user-invocable | false |
SPEC.md Consultation Skill
Before implementing any feature or making architectural decisions, consult SPEC.md through an isolated Explore agent to understand the authoritative requirements and design principles.
Purpose
This skill provides access to SPEC.md (the source of truth for architecture and requirements) through a dedicated subagent that ONLY reads the specification, never the implementation code. This ensures you receive unbiased, authoritative guidance based on requirements rather than potentially incorrect implementations.
When to Use This Skill
Use this proactively when you:
- Begin implementing any feature (check spec requirements first)
- Design API responses or data structures (verify against spec models)
- Make architectural decisions (consult spec design principles)
- Need to understand design rationale for existing patterns
- Encounter conflicting information (get the ground truth)
- Verify technical requirements or constraints
- Check pagination strategies, error handling patterns, or data processing rules
Do NOT use this when:
- You need to understand current implementation details (read code directly)
- You need to see how something is actually implemented (that's not the spec's job)
- You're just checking a simple constant or configuration value
Workflow
1. Formulate Your Question
Be specific about what you need from the spec:
Good questions:
- "What is the opaque cursor strategy for pagination?"
- "How should log data field truncation work?"
- "What are the design principles for response processing?"
- "What is the standardized ToolResponse model structure?"
Bad questions:
- "How is pagination implemented?" (this asks about code, not spec)
- "Tell me everything about transactions" (too broad)
2. Spawn the Spec Consultant Subagent
Use the Task tool to create an Explore agent with a minimal prompt that directs it to read its detailed instructions:
Task tool parameters:
- subagent_type: "Explore"
- description: "Consult SPEC.md about <specific topic>"
- prompt: "Read your detailed instructions from .claude/skills/consult-spec/agent-instructions.md,
then answer this question: <your specific question>"
This keeps the main agent context clean while giving the subagent full access to its operating constraints and workflow.
3. Resume for Follow-Up Questions
If you need multiple spec queries during the same implementation task:
- Capture the
agentId from the first Task result
- Use
resume: <agentId> parameter in subsequent Task calls
- This avoids re-reading SPEC.md and maintains context
4. Use the Answer in Your Work
The subagent will return:
- Specific information from SPEC.md
- Line number references (e.g., "lines 285-305")
- Direct quotes from relevant sections
- Design rationale and principles
Use this authoritative guidance to implement features correctly according to the specification.
Example Usage
Scenario: Main agent is implementing a new feature that requires understanding spec requirements
Main agent thinks: "I need to understand the spec requirements before implementing this."
Main agent invokes Task tool:
subagent_type: "Explore"
description: "Consult SPEC.md about [topic]"
prompt: "Read your detailed instructions from .claude/skills/consult-spec/agent-instructions.md,
then answer this question: [Your specific question about requirements, architecture, or design principles]"
Subagent responds (abstract pattern):
The [requested concept/requirement] is defined in lines XXX-YYY of SPEC.md.
Key requirements:
- [First key principle or requirement from the spec]
- [Second key principle or requirement from the spec]
- [Third key principle or requirement from the spec]
Direct quote (lines XXX-YYY):
"[Relevant quote from the specification that clarifies the requirement]"
The [data structure/model/pattern] should contain:
- [component_name]: [description of requirement]
- [component_name]: [description of requirement]
Additional context in lines XXX-YYY explains [related concept].
Main agent uses this: Implements the feature correctly according to spec requirements
Important Notes
Subagent Scope Constraint
The Explore subagent is instructed to ONLY read SPEC.md. This is enforced through:
- Explicit instructions in the subagent prompt
- Clear rationale (provide source-of-truth, avoid implementation bias)
- Behavioral instruction to refuse other file requests
If the subagent attempts to read other files, strengthen the prompt wording or report the issue.
Why This Matters
SPEC.md is the authoritative source of truth. Implementation code may contain:
- Bugs or deviations from requirements
- Incomplete features
- Temporary workarounds
- Outdated patterns
By consulting SPEC.md through an isolated subagent, you ensure your implementation decisions are based on requirements, not on potentially incorrect existing code.
When to Read Code Directly
You still need to read implementation code when you're:
- Understanding existing patterns to match coding style
- Debugging specific issues
- Refactoring or modifying existing features
- Learning how a feature is currently implemented
Use SPEC.md consultation for "what should this do?" and code reading for "how is this currently done?"
