Feat kql expert (#137)

* feat: KQL expert skill with requires-mcp, trigger cleanup, syntax highlighting

- Add kql-expert skill (SKILL.md) with 35 triggers, requires-mcp: fabric-rti-mcp
- Add requires-mcp frontmatter support in skill-loader + approach-resolver
- Add MCP enrichment wiring in agent index.ts
- Add --mcp setup-fabric-rti CLI command
- Clean generic triggers across 7 skills to prevent false matches
- Add hljs-kql.ts grammar (derived from @kusto/monaco-kusto MIT)
- Register KQL/Kusto syntax highlighting in markdown-renderer via createRequire
- Add intent-matcher regression tests (27 tests: 22 positive + 5 guards)
- Add skill-loader tests (8 tests) and approach-resolver MCP tests (8 tests)

All 2396 tests pass. Typecheck clean. Fmt clean.

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

* fix: gate diagnostic output behind --verbose/--debug flags

- Rust: gate [hyperlight-analysis] eprintln! behind HYPERAGENT_VERBOSE/DEBUG env vars
- MCP: gate [mcp] Connected/Auth success messages behind isVerbose()
- MCP: pipe subprocess stderr when not verbose to suppress Python INFO logs
- KQL skill: remove azuremcpserver reference, add anti-pattern to use fabric-rti-mcp only

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

* docs: update skill tables and add requires-mcp documentation

- Add all 9 skills to tables in docs/SKILLS.md, README.md, skills/CLAUDE.md,
  and .github/instructions/skills.instructions.md (was missing kql-expert,
  xlsx-expert, mcp-services in various files)
- Document requires-mcp frontmatter field in docs/SKILLS.md
- Add requires-mcp to YAML examples in instruction files
- Alphabetise skill tables for consistency

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

* fix: address PR #137 review feedback (9 issues)

- Fix #2: Use MCP_SETUP_COMMANDS lookup for correct CLI setup hints
  (was generating 'setup-rti-mcp' instead of '--mcp-setup-fabric-rti')
- Fix #3: Show unconfigured status when mcpManager is null
- Fix #4: Update test assertion to match corrected setup command
- Fix #5: Add highlight.js ^10.7.3 as explicit dependency (was transitive)
- Fix #6: Validate Fabric RTI options — reject missing values & unknown flags
- Fix #7: Set HYPERAGENT_VERBOSE=1 from cli.verbose flag
- Fix #8: Update skill count from 9 to 10 in docs/SKILLS.md
- Fix #9: Use stderr 'ignore' instead of 'pipe' to avoid back-pressure
- Fix #10: Add CLI parser test for --mcp-setup-fabric-rti flag

Comment #1 (hljs types) is invalid — typecheck passes with /// <reference>.

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

---------

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

Author: simongdavies

.github/instructions/skills.instructions.md

@@ -28,6 +28,8 @@ antiPatterns:
   - "Don't do X"
 allowed-tools:
   - tool_name
+requires-mcp:
+  - mcp-server-name
 ---
 
 # Skill Title
@@ -39,13 +41,16 @@ Detailed instructions for the LLM when this skill is active.
 
 | Skill | Purpose |
 |-------|---------|
-| `pptx-expert` | PowerPoint presentation building |
+| `api-explorer` | API discovery, testing, and documentation |
+| `data-processor` | Data processing workflows |
+| `kql-expert` | KQL/Kusto queries via Fabric RTI MCP |
+| `mcp-services` | External MCP server integration |
 | `pdf-expert` | PDF document building |
+| `pptx-expert` | PowerPoint presentation building |
+| `report-builder` | Report and document generation |
 | `research-synthesiser` | Research and synthesis |
-| `data-processor` | Data processing workflows |
 | `web-scraper` | Web scraping |
-| `report-builder` | Report generation |
-| `api-explorer` | API exploration |
+| `xlsx-expert` | Excel workbook generation |
 
 ## Triggers
 

README.md

@@ -175,6 +175,7 @@ Useful skills include:
 | `pptx-expert`    | Professional PowerPoint decks                 |
 | `pdf-expert`     | Structured PDF reports                        |
 | `xlsx-expert`    | Excel workbook generation                     |
+| `kql-expert`     | Kusto queries via Fabric RTI MCP tools        |
 | `report-builder` | Multi-format reports and document output      |
 | `data-processor` | Data cleaning, joins, aggregation, and export |
 | `api-explorer`   | Understanding and calling APIs                |

docs/SKILLS.md

@@ -38,12 +38,16 @@ You: /skill pptx-expert
 
 | Skill | Description |
 |-------|-------------|
-| `pptx-expert` | Building professional PowerPoint presentations |
-| `web-scraper` | Extracting data from web pages |
-| `research-synthesiser` | Combining multiple sources into reports |
-| `data-processor` | Transforming and analyzing data |
-| `report-builder` | Creating structured reports |
-| `api-explorer` | Discovering and using APIs |
+| `api-explorer` | Discover, test, and document REST/GraphQL/JSON APIs |
+| `data-processor` | Transform, filter, and analyse data using sandbox handlers |
+| `kql-expert` | KQL expertise for Kusto queries via Fabric RTI MCP tools |
+| `mcp-services` | Connect and use external MCP servers (M365, GitHub, custom) |
+| `pdf-expert` | Professional PDF documents using sandbox modules |
+| `pptx-expert` | Professional PowerPoint presentations using sandbox modules |
+| `report-builder` | Generate documents, reports, and formatted output |
+| `research-synthesiser` | Multi-source research synthesised into structured reports |
+| `web-scraper` | Extract data from web pages using fetch plugin |
+| `xlsx-expert` | Excel XLSX workbooks using sandbox modules |
 
 ## Skill File Format
 
@@ -66,6 +70,8 @@ antiPatterns:
 allowed-tools:
   - register_handler
   - execute_javascript
+requires-mcp:
+  - mcp-server-name
 ---
 ```
 
@@ -104,6 +110,18 @@ and always produce high-quality Z.
 | `patterns` | No | Code patterns relevant to this skill |
 | `antiPatterns` | No | Common mistakes to avoid |
 | `allowed-tools` | No | Tools the LLM can use with this skill |
+| `requires-mcp` | No | MCP server names that must be connected for this skill |
+
+### MCP Server Dependencies
+
+If `requires-mcp` is specified, the skill declares which MCP servers it needs. The approach resolver checks whether required servers are connected and shows their status:
+
+```yaml
+requires-mcp:
+  - fabric-rti-mcp
+```
+
+When the skill is matched, the agent enriches the guidance with MCP connection status so the LLM knows whether to prompt the user to connect the server first.
 
 ### Tool Restrictions
 
@@ -218,9 +236,10 @@ Skills are discovered automatically from:
 List available skills:
 ```
 You: /skill list
-  📚 Available skills (6):
-     pptx-expert - Expert at building professional PowerPoint presentations
-     web-scraper - Extracting data from web pages
+  📚 Available skills (10):
+     api-explorer - Discover, test, and document REST/GraphQL/JSON APIs
+     data-processor - Transform, filter, and analyse data
+     kql-expert - KQL expertise for Kusto queries via Fabric RTI MCP
      ...
 ```
 

package-lock.json

@@ -35,6 +35,7 @@
     "@hyperlight/js-host-api": "file:deps/js-host-api",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "boxen": "^8.0.1",
+    "highlight.js": "^10.7.3",
     "hyperlight-analysis": "file:src/code-validator/guest",
     "marked": "^15.0.12",
     "marked-terminal": "^7.3.0",

package.json

@@ -24,6 +24,8 @@ antiPatterns:
   - "Don't do X"
 allowed-tools:
   - tool_name
+requires-mcp:
+  - mcp-server-name
 ---
 
 # Skill Title
@@ -35,13 +37,16 @@ Detailed instructions for the LLM when this skill is active.
 
 | Skill | Purpose |
 |-------|---------|
-| `pptx-expert` | PowerPoint presentation building |
+| `api-explorer` | API discovery, testing, and documentation |
+| `data-processor` | Data processing workflows |
+| `kql-expert` | KQL/Kusto queries via Fabric RTI MCP |
+| `mcp-services` | External MCP server integration |
 | `pdf-expert` | PDF document building |
+| `pptx-expert` | PowerPoint presentation building |
+| `report-builder` | Report and document generation |
 | `research-synthesiser` | Research and synthesis |
-| `data-processor` | Data processing workflows |
 | `web-scraper` | Web scraping |
-| `report-builder` | Report generation |
-| `api-explorer` | API exploration |
+| `xlsx-expert` | Excel workbook generation |
 
 ## Triggers
 

skills/CLAUDE.md

@@ -11,11 +11,12 @@ triggers:
   - API documentation
   - API reference
   - test endpoint
-  - request
-  - response
   - status code
   - rate limit
   - webhook
+  - API call
+  - REST API
+  - HTTP endpoint
 patterns:
   - fetch-and-process
   - data-extraction

skills/api-explorer/SKILL.md

@@ -4,16 +4,16 @@ description: Transform, filter, and analyse data using sandbox handlers
 triggers:
   - CSV
   - JSON
-  - transform
-  - convert
-  - process
-  - analyse
-  - analyze
-  - data
-  - filter
-  - aggregate
-  - sort
-  - parse
+  - TSV
+  - CSV to JSON
+  - JSON to CSV
+  - data pipeline
+  - ETL
+  - tabular data
+  - parse CSV
+  - parse JSON
+  - transform CSV
+  - transform JSON
 patterns:
   - data-transformation
   - two-handler-pipeline