Agent Skills: extract-knowledge

  <substep n="1a" title="Track Progress">
    <action if="first iteration">Create todo list from all instruction step titles (TodoWrite)</action>
    <action>Mark current step as in_progress (TodoWrite)</action>
  </substep>

  <substep n="1b" title="Handle Step Attributes">
    <check>If optional="true" and NOT YOLO -> Use Question tool to ask user whether to include (Yes/Skip)</check>
    <check>If if="condition" -> Evaluate condition</check>
    <check>If for-each="item" -> Repeat step for each item</check>
    <check>If repeat="n" -> Repeat step n times</check>
  </substep>

  <substep n="1c" title="Execute Step Content">
    <action>Process step instructions (markdown or XML tags)</action>
    <action>Replace {{variables}} with values (ask user if unknown)</action>
    <execute-tags>
      <tag>action -> Perform the action</tag>
      <tag>action type="script" -> Execute as shell command, capture output</tag>
      <tag>check if="condition" -> Conditional block wrapping actions (requires closing &lt;/check&gt;)</tag>
      <tag>ask -> Prompt user using Question tool and WAIT for response. When options exist, present them as selectable choices. For open-ended questions, provide helpful suggested options with custom input enabled</tag>
      <tag>invoke-skill name="skill-name" -> Execute another skill via OpenCode skill system</tag>
      <tag>invoke-agent name="subagent" prompt="task" -> Delegate to subagent via Task tool</tag>
      <tag>goto step="x" -> Jump to specified step (used for explicit loop-back in Q-R style flows)</tag>
    </execute-tags>
  </substep>

  <substep n="1d" title="Handle template-output Tags">
    <if tag="template-output">
      <mandate>Generate content for this section</mandate>
      <mandate>Save to file (Write first time, Edit subsequent)</mandate>
      <action>Display generated content</action>
      <action>Use Question tool to present checkpoint options. WAIT for response.
        <options>
          <option label="Continue" description="Approve this section and move to the next step" />
          <option label="Advanced Elicitation" description="Explore this section deeper before proceeding" />
          <option label="YOLO" description="Auto-complete the rest of this workflow without stopping" />
        </options>
        <if response="Advanced Elicitation">
          <action>Invoke advanced-elicitation skill</action>
        </if>
        <if response="Continue">
          <action>Continue to next step</action>
        </if>
        <if response="YOLO">
          <action>Enter YOLO mode for the rest of the workflow</action>
        </if>
      </action>
    </if>
  </substep>

  <substep n="1e" title="Step Completion">
    <action>Mark current step as completed (TodoWrite)</action>
    <check>If no special tags and NOT YOLO:</check>
    <action>Use Question tool to ask:
      <options>
        <option label="Continue" description="Proceed to the next step" />
        <option label="Edit" description="Revise this step before moving on" />
      </options>
    </action>
  </substep>
</step>

<step n="2" title="Completion">
  <check>Confirm all instruction steps have been executed</check>
  <output>Workflow complete.</output>
</step>

  Second mode — diagnose a design flaw in an existing agent or skill:
  not only spot the issue but localize WHERE in the source it lives and
  prescribe WHAT to change. Output is an actionable remediation (exact
  source files + changes); the researcher is dispatched to map the source
  precisely (step 2).
</purpose>

<output>
  A knowledge document under .vera/shared/references/{namespace}/ or
  under a specific skill's references/ directory (depending on scope —
  cross-skill references go to shared; skill-local references stay in
  the skill). The document captures extracted patterns, examples, and
  guidelines with rationale.
</output>

<key-responsibility>
  The critical skill is PATTERN RECOGNITION — identifying what's:

  1. REUSABLE — Patterns that apply beyond the source material
  2. ACTIONABLE — Concrete enough to guide future work
  3. STRUCTURED — Organized for easy reference and retrieval

  Good extracted knowledge captures the "why" behind patterns, not just
  the "what" — enabling adaptation, not just copying. Distinguish from
  a transcript dump: extraction is synthesis, not pasting.

  When fixing an existing agent/skill, two disciplines apply: (1) VERIFY a
  dispatched researcher's load-bearing claims with a cheap deterministic
  probe before acting — a finding is a hypothesis until confirmed, and
  attribution is often subtly wrong; (2) prefer PREVENTION over validation
  — eliminate the error class at its source (a script, a structural
  guarantee) rather than adding a downstream check.
</key-responsibility>

<type name="patterns">
  <description>Recurring solutions to common problems</description>
  <sources>Code, architecture docs, successful implementations</sources>
  <output>Pattern catalog with context, structure, examples</output>
  <example>Error handling patterns, API design patterns</example>
</type>

<type name="conventions">
  <description>Agreed standards and naming/formatting rules</description>
  <sources>Style guides, existing codebases, team practices</sources>
  <output>Convention reference with rules and examples</output>
  <example>Naming conventions, file organization, commit formats</example>
</type>

<type name="templates">
  <description>Reusable structures with fill-in-the-blank sections</description>
  <sources>Successful documents, repeated file structures</sources>
  <output>Template with placeholders and usage instructions</output>
  <example>PR template, agent config template, skill template</example>
</type>

<type name="guidelines">
  <description>Decision-making frameworks and best practices</description>
  <sources>Post-mortems, lessons learned, expert knowledge</sources>
  <output>Guideline document with rationale and examples</output>
  <example>When to use X vs Y, security guidelines</example>
</type>

<type name="vocabulary">
  <description>Domain terms, definitions, and relationships</description>
  <sources>Documentation, conversations, domain experts</sources>
  <output>Glossary or ontology with definitions</output>
  <example>Project-specific terms, API concepts</example>
</type>

<type name="remediation">
  <description>A precise fix for a design flaw in an existing agent/skill</description>
  <sources>A surfaced defect + the agent/skill's true source under .vera/</sources>
  <output>A remediation set: exact source files and the change to each</output>
  <example>A workflow that ships process notes inside its deliverable</example>
</type>

<step n="1" title="Discovery and Scoping">
  <action>Load and execute: references/steps/step-01-discovery.xml</action>
  <note>
    Identify what to extract from and what kind of knowledge we're
    after. Scope appropriately — too broad yields shallow results.
  </note>
</step>

<step n="2" title="Analysis and Pattern Recognition">
  <action>Load and execute: references/steps/step-02-analysis.xml</action>
  <note>
    THIS IS THE CORE STEP. Analyze source material for:
    - Recurring patterns
    - Implicit conventions
    - Decision rationales
    - Reusable structures
  </note>
</step>

<step n="3" title="Extraction and Structuring">
  <action>Load and execute: references/steps/step-03-extraction.xml</action>
  <note>
    Transform analysis into structured knowledge document. Include
    context, examples, and rationale — not just rules. Place output
    per dubstack convention: cross-skill knowledge under
    .vera/shared/references/{namespace}/; skill-local knowledge inside
    the owning skill's references/.
  </note>
</step>

<step n="4" title="Validate and Complete">
  <action>Load and execute: references/steps/step-04-validate.xml</action>
  <note>
    Verify extracted knowledge is accurate, actionable, and useful.
    Consider how it will be consumed by agents/skills.
  </note>
</step>

<next-steps>
  <step>Review and refine the extracted knowledge</step>
  <step>Add to skill references/ if skill-specific</step>
  <step>Add to .vera/shared/references/ if broadly applicable</step>
  <step>Update relevant skill.yaml attachments lists to consume the new reference</step>
</next-steps>