git:20260423.d345582 to git:20260428.35e38bf

- description: Protocol for interacting with the OntoSkills MCP server to discover, evaluate, and compose skills from the compiled knowledge graph.

- ## OVERVIEW

-

- The OntoSkills MCP server exposes a knowledge graph of compiled skills. This document teaches you how to use its 4 tools effectively to find, evaluate, and compose skills for any task.

-

- ## AVAILABLE MCP TOOLS

-

- ### 1. search({ query: string }) -> Vec<SkillSearchResult>

-

- Search across all compiled skills by keyword (BM25), alias, or structured filters. Returns matching skills with relevance indicators.

-

- **When to use:** When you need to find skills that address a user's intent or task requirement.

-

- **Best practices:**

- - Use natural language queries that describe the GOAL, not the tool name

- - Example: "create a presentation from data" is better than "pptx"

- - If results are sparse, try synonyms or broader terms

- - Call this FIRST before any other MCP tool

-

- ### 2. get_skill_context({ skill_id: string, include_inherited_knowledge: bool = true }) -> SkillContextResult

-

- Returns full details for a specific skill: metadata, all operational knowledge (procedures, code patterns, constraints, heuristics, anti-patterns, etc.), state transitions, dependencies, and section titles (table of contents).

-

- **When to use:** After search identified candidate skills, to evaluate fitness and access all the knowledge needed to execute the skill.

-

- **Best practices:**

- - The response includes all operational knowledge nodes — read them carefully before executing

- - Set `include_inherited_knowledge=false` to exclude knowledge from extended skills

- - Always check requiresState before attempting execution

- - Read ALL knowledge nodes with severity CRITICAL or HIGH before proceeding

-

- **Response structure:**

- - `skill`: skill metadata (name, description, category, intents, aliases)

- - `payload`: executor type and code (for executable skills)

- - `knowledge_nodes`: epistemic rules — all operational knowledge including standards, anti-patterns, constraints, heuristics, procedures, code patterns, etc.

- - `sections`: table of contents — list of section titles with levels and hierarchy

- - `include_inherited_knowledge`: whether inherited knowledge from extended skills was included

-

- ### 3. evaluate_execution_plan({ plan: ExecutionPlan }) -> ExecutionPlanEvaluation

-

- Validates a proposed execution plan against the skill knowledge graph. Checks state chains, dependencies, and identifies missing prerequisites.

-

- **When to use:** Before executing a multi-skill workflow, to verify the plan is sound.

-

- **Best practices:**

- - Include ALL skills in the plan, even "obvious" ones

- - Check the `applicable` field — if false, review `missing_states` and `warnings`

- - Pay attention to `recommended_skill` — the graph may suggest a better alternative

- - Review `plan_steps` for the correct execution order

-

- **Plan structure:**

- ```json

- {

- "steps": [

- {"skill_id": "skill-name", "description": "what this step accomplishes"},

- ...

- ]

- }

- ```

-

- ### 4. query_epistemic_rules({ context: string, kind: string = None, severity: string = None }) -> Vec<KnowledgeNodeInfo>

-

- Queries knowledge rules across all skills, optionally filtered by type and severity.

-

- **When to use:** When you need best practices, constraints, or warnings for a specific domain/context.

-

- **Best practices:**

- - Use specific context strings: "when modifying Excel files" is better than "excel"

- - Filter by severity="CRITICAL" first to catch hard constraints

- - Filter by kind to get specific rule types: "AntiPattern", "Constraint", "SecurityImplication"

- - This tool searches ACROSS skills — it finds rules from any skill that matches the context

-

- ## WORKFLOW

- ### Discovery Phase

- 1. Call `search` with the user's intent

- 2. For each match (up to 5), call `get_skill_context({ skill_id })` to see knowledge nodes and requirements

- 3. Evaluate: check intents alignment, requiresState preconditions, category relevance

- 4. Select the best 1-3 candidates

- ### Planning Phase

- 5. Build an execution plan with selected skills

- 6. Call `evaluate_execution_plan` to validate

- 7. If `executable=false`: address missing_states, resolve warnings, re-evaluate

- 8. For CRITICAL/HIGH knowledge nodes: internalize the rules before proceeding

- ### Execution Phase

- 9. Follow ordered procedures (stepOrder) if present

- 10. Respect all knowledge nodes — especially AntiPatterns and Constraints

- 11. After execution, verify yieldsState matches expected outcomes

- ## COMMON MISTAKES TO AVOID

- - **Skipping search:** Don't guess skill names. Always search first.

- - **Ignoring requiresState:** Executing a skill without its preconditions leads to failures.

- - **Overlooking CRITICAL knowledge nodes:** These are hard constraints, not suggestions.

- - **Not validating plans:** Multi-skill workflows can have broken state chains.

- - **Assuming skill availability:** Search results only include compiled and enabled skills.

- ## STATE TRANSITION SEMANTICS

- Skills form a state machine via requiresState/yieldsState:

- - `requiresState`: What MUST be true before execution (preconditions)

- - `yieldsState`: What BECOMES true after successful execution (outcomes)

- - `handlesFailure`: What states indicate execution failure

- State chaining: Skill A's yieldsState should match Skill B's requiresState for valid sequencing.

- If evaluate_execution_plan reports `missing_states`, you need to find or ensure skills that yield those states.