# Consult Spec > 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. - Skill: `blockscout/consult-spec` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add blockscout/consult-spec` - Raw SKILL.md: https://api.skillmd.com/api/skills/blockscout/consult-spec/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: blockscout (https://skillmd.com/u/blockscout) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/blockscout/consult-spec --- # 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: ```plaintext Task tool parameters: - subagent_type: "Explore" - description: "Consult SPEC.md about " - prompt: "Read your detailed instructions from .claude/skills/consult-spec/agent-instructions.md, then answer this 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: ` 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**: ```plaintext 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): ```plaintext 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?"