Search and reference knowledge from the knowledge base using full-text search and ontology tag search. Use when needing to find existing knowledge, lookup information, or reference KB content. Triggers on requests like "search knowledge base", "find in knowledge base", "what do we know about", "reference knowledge".
Search and reference knowledge from the knowledge base using full-text search and ontology tag search. Use when needing to find existing knowledge, lookup information, or reference KB content. Triggers on requests like "search knowledge base", "find in knowledge base", "what do we know about", "reference knowledge".
Task-Based Skill: Knowledge Referencer
Purpose
Search and reference knowledge from the knowledge base by:
Full-text search across KB markdown files (grep/glob)
Ontology entity/tag search via x-ipe-tool-reference-ontology (MANDATORY)
Optional user manual lookup via x-ipe-tool-reference-user-manual (when manual KB exists and query is about how-to/instructions)
Combining, deduplicating, ranking, and consolidating results into a unified answer
Important Notes
BLOCKING: Learn x-ipe-workflow-task-execution skill before executing this skill.
Note: If Agent does not have skill capability, go to .github/skills/ folder to learn skills. SKILL.md is the entry point.
Search Strategy:
x-ipe-tool-reference-ontology is MANDATORY — always called regardless of full-text results
x-ipe-tool-reference-user-manual is OPTIONAL — only called when a user manual KB exists AND the query is about how-to/instructions
Results are ranked by cross-method hit count: files found by more search methods rank higher
IMPORTANT: When process_preference.interaction_mode == "dao-represent-human-to-interact", NEVER stop to ask the human. Instead, call x-ipe-assistant-user-representative-Engineer to get the answer.
Input Parameters
input:task_id:"{TASK-XXX}"task_based_skill:"x-ipe-task-based-knowledge-referencer"execution_mode:"free-mode | workflow-mode"workflow:name:"N/A"category:"standalone"next_task_based_skill:"null"process_preference:interaction_mode:"interact-with-human | dao-represent-human-to-interact | dao-represent-human-to-interact-for-questions-in-skill"query:""# Natural language search query (required)kb_scope:"all"# "all" | specific KB folder pathinclude_user_manual:true# Whether to also search user manualsmax_results:20# Maximum results to return per search step
Input Initialization
<input_init><fieldname="task_id"source="x-ipe+all+task-board-management (auto-generated)" /><fieldname="execution_mode"source="x-ipe-workflow-task-execution (from --workflow-mode@{name})" /><fieldname="workflow.name"source="x-ipe-workflow-task-execution (from --workflow-mode@{name})" /><fieldname="process_preference.interaction_mode"source="from caller (x-ipe-workflow-task-execution) or default 'interact-with-human'" /><fieldname="query"source="from human input or calling skill" /><fieldname="kb_scope"source="from human input or default 'all'" /><fieldname="include_user_manual"source="from human input or default true" /><fieldname="max_results"source="from human input or default 20" /></input_init>
Definition of Ready
<definition_of_ready><checkpointrequired="true"><name>Query provided</name><verification>A non-empty natural language search query exists</verification></checkpoint><checkpointrequired="true"><name>KB path exists</name><verification>x-ipe-docs/knowledge-base/ directory exists and is not empty</verification></checkpoint><checkpointrequired="recommended"><name>KB scope valid</name><verification>If kb_scope is not "all", the specified folder path exists under knowledge-base/</verification></checkpoint></definition_of_ready>
Execution Flow
Phase
Step
Name
Action
Gate
1. 博学之
1.1
Gather Context
Read query, determine KB scope, check if user manual exists
context gathered
2. 审问之
—
SKIP
Input is fully specified by caller; no ambiguity to resolve
—
3. 慎思之
—
SKIP
No design decisions; procedural execution
—
4. 明辨之
—
SKIP
Single valid approach; no alternatives
—
5. 笃行之
5.1
Execute Full-Text Search
Grep/glob across KB markdown files for query terms
results collected
5.2
Execute Ontology Search
Load x-ipe-tool-reference-ontology, run search operation
ontology results collected
5.3
Execute User Manual Lookup
IF include_user_manual AND manual KB exists: load x-ipe-tool-reference-user-manual
manual results collected (or skipped)
5.4
Combine & Consolidate
Merge results, deduplicate, rank by relevance, produce summary
consolidated output
5.5
Complete
Verify DoD
DoD validated
6. 继续执行
6.1
Decide Next Action
DAO-assisted next task decision
Next action decided
6.2
Execute Next Action
Load skill, execute
Execution started
BLOCKING: Step 5.2 (ontology search) is MANDATORY — never skip it.
BLOCKING: Step 5.4 must not run until steps 5.1, 5.2, and 5.3 (if applicable) are complete.
Execution Procedure
<procedurename="knowledge-referencer"><execute_dor_checks_before_starting/><schedule_dod_checks_with_sub_agent_before_starting/><phase_1name="博学之（Gather）"><step_1_1><name>Gather Context</name><action>
1. Read the input query — this is the search term(s) for all search methods
2. Determine KB scope:
- IF kb_scope == "all": search_path = "x-ipe-docs/knowledge-base/"
- ELSE: search_path = "x-ipe-docs/knowledge-base/{kb_scope}/"
- Verify the search_path directory exists; if not, BLOCK with error
3. Check if a user manual KB exists at search_path:
- Look for 04-core-features/ directory OR 01-overview.md file
- Set has_user_manual = true if found, false otherwise
4. Determine if user manual lookup is applicable:
- user_manual_applicable = include_user_manual AND has_user_manual
</action><output>search_path, has_user_manual, user_manual_applicable established</output></step_1_1></phase_1><phase_2name="审问之（Inquire）">SKIP — Input is fully specified by caller; no ambiguity to resolve.</phase_2><phase_3name="慎思之（Analyze）">SKIP — No design decisions; procedural execution only.</phase_3><phase_4name="明辨之（Discern）">SKIP — Single valid approach; no alternatives to evaluate.</phase_4><phase_5name="笃行之（Execute）"><step_5_1><name>Execute Full-Text Search</name><action>
1. Use grep to search across all .md files under search_path for the query terms
2. Break query into individual keywords if multi-word; search for each
3. Collect results up to max_results:
- file_path: path to the matched file
- matched_lines: the line(s) containing the match
- context: 2-3 lines of surrounding context
4. Sort by number of keyword hits per file (descending)
</action><output>full_text_matches: [{file_path, matched_lines, context}]</output></step_5_1><step_5_2><name>Execute Ontology Search (MANDATORY)</name><action>
1. Load x-ipe-tool-reference-ontology skill
2. Call its search operation with the query
3. Collect entity matches up to max_results:
- entity_id: ontology entity identifier
- label: human-readable entity name
- node_type: entity type in ontology (concept, feature, component, etc.)
- source_files: KB files linked to this entity
- dimensions: ontology dimensions/tags associated
- relevance: match relevance score
4. This step is MANDATORY — always execute regardless of Step 5.1 results
</action><constraints>
- BLOCKING: This step MUST always execute — do NOT skip
</constraints><output>ontology_matches: [{entity_id, label, node_type, source_files, dimensions, relevance}]</output></step_5_2><step_5_3><name>Execute User Manual Lookup (OPTIONAL)</name><action>
1. IF user_manual_applicable == false: SKIP this step, set user_manual_matches = []
2. IF user_manual_applicable == true:
a. Load x-ipe-tool-reference-user-manual skill
b. Call its lookup_instruction operation with the query
c. Collect matches:
- file_path: path to the manual document
- title: section or document title
- relevance_score: how closely the manual entry matches the query
- interaction_pattern: the how-to/instruction content
</action><output>user_manual_matches: [{file_path, title, relevance_score, interaction_pattern}] (or empty)</output></step_5_3><step_5_4><name>Combine & Consolidate</name><action>
1. Collect all source file paths from all three result sets
2. Deduplicate by source file path — if the same file appears in multiple search results,
merge into a single entry noting which methods found it
3. Rank results by cross-method hit count:
- File found by 3 methods (full-text + ontology + manual) → highest relevance
- File found by 2 methods → medium relevance
- File found by 1 method → standard relevance
Within same hit count, sort by individual relevance scores
4. Produce a consolidated summary:
- List the top matches (up to max_results total) with source file and why they matched
- Synthesize a brief answer that addresses the original query using the found content
- Note which search methods contributed to each result
5. Compute total_results count (unique files across all methods)
</action><output>consolidated_results object with ranked matches and synthesized summary</output></step_5_4><step_5_5><name>Complete</name><action>
1. Verify all DoD checkpoints
2. Produce task_completion_output
</action><output>Task completed with consolidated knowledge reference output</output></step_5_5></phase_5><phase_6name="继续执行（Continue Execute）"><step_6_1><name>Decide Next Action</name><action>
Collect the full context and task_completion_output from this skill execution.
IF process_preference.interaction_mode == "dao-represent-human-to-interact":
→ Invoke x-ipe-assistant-user-representative-Engineer with:
type: "routing"
completed_skill_output: {full task_completion_output YAML from this skill}
next_task_based_skill: "{from output}"
context: "Skill completed. Study the context and full output to decide best next action."
→ DAO studies the complete context and decides the best next action
ELSE (interact-with-human):
→ Present results and next task suggestion to human and wait for instruction
</action><constraints>
- BLOCKING (interact-with-human): Human MUST confirm or redirect before proceeding
- BLOCKING (auto): Proceed after DoD verification; auto-select next task via DAO
</constraints><output>Next action decided with execution context</output></step_6_1><step_6_2><name>Execute Next Action</name><action>
Based on the decision from Step 6.1:
1. Load the target task-based skill's SKILL.md
2. Generate an execution plan from the skill's Execution Flow table
3. Start execution from the skill's first phase/step
</action><constraints>
- MUST load the skill before executing — do not skip skill loading
- Execution follows the target skill's procedure, not this skill's
</constraints><output>Next task execution started</output></step_6_2></phase_6></procedure>
CRITICAL: Use a sub-agent to validate DoD checkpoints independently.
<definition_of_done><checkpointrequired="true"><name>Full-text search executed</name><verification>Grep/glob search was run against KB markdown files under the determined scope</verification></checkpoint><checkpointrequired="true"><name>Ontology search executed</name><verification>x-ipe-tool-reference-ontology was loaded and its search operation was called</verification></checkpoint><checkpointrequired="true"><name>User manual lookup handled</name><verification>Either user manual lookup was executed (when applicable) or explicitly skipped with reason</verification></checkpoint><checkpointrequired="true"><name>Results deduplicated</name><verification>No duplicate source file paths appear in the final consolidated output</verification></checkpoint><checkpointrequired="true"><name>Results ranked</name><verification>Results are ordered by cross-method hit count and individual relevance</verification></checkpoint><checkpointrequired="true"><name>Summary synthesized</name><verification>A human-readable summary addressing the original query is present in output</verification></checkpoint><checkpointrequired="true"><name>Output structure complete</name><verification>task_completion_output contains all required fields including consolidated_results</verification></checkpoint></definition_of_done>
MANDATORY: After completing this skill, return to x-ipe-workflow-task-execution to continue the task execution flow.
Patterns & Anti-Patterns
Pattern: Multi-Method Search
When: Searching for knowledge in the KB
Then:
1. Run full-text grep across .md files
2. Run ontology entity search (MANDATORY)
3. Optionally run user manual lookup
4. Merge, deduplicate, rank by cross-method hits
5. Synthesize consolidated answer
Pattern: Scoped Search
When: User specifies a particular KB area
Then:
1. Validate kb_scope path exists under knowledge-base/
2. Limit all search methods to that path
3. Report scope in output so user knows search was limited
Pattern: Graceful Skip
When: User manual KB does not exist or is not relevant
Then:
1. Check for 04-core-features/ or 01-overview.md
2. If absent: set user_manual_matches = [], continue
3. Do NOT fail — proceed with full-text + ontology results only
