AgentSkillsCN

consult-spec

触发条件——当以下任一情形适用时，即可调用此技能： 用户主动触发（显式请求）： - 用户提及“规格”、“SPEC”、“SPEC.md”、“规格需求” - 用户要求“对照规格核实”、“以规格确认”、“核对需求” - 用户请求“权威需求”或“事实依据” 代理自动触发（推理过程中）： - 在实施任何新功能或进行代码变更之前 - 在验证技术需求或约束条件时 - 在做出架构或设计决策时 - 当你需要不受当前实现影响的客观指导时 - 当遇到信息冲突、亟需还原事实真相时 用途：通过一个独立的子代理来查阅SPEC.md文件——该子代理仅读取规格文档，绝不接触实现代码。此举确保所给出的指导基于权威需求，而非可能存有偏差的现有代码。

SKILL.md
--- frontmatter
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:

plaintext
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:

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?"