Authoring MCP Skills

Descriptor Surface

The source descriptor for this family is mskill.md. During preparation, the subsystem reads the descriptor through the generic skill document parser and then extracts three bounded section families: planning instructions, allowed tools, and an optional script. Several aliases are accepted. Instructions, Guidance, System-Prompt, Overview, and MCP-Guidance all map to the same instruction surface. Allowed-Tools, Tool-Allowlist, Tool-Allow-List, and Tools all map to the allowlist. Plan SOPlang, Script, and Plan-Script all map to the optional script section.

The practical role of these sections is narrower than general documentation prose might suggest. The instructions become planning guidance. The allowlist determines which MCP tools are admissible. The script section, when present, bypasses LLM planning and becomes the source of the plan itself. No broader hidden contract is inferred from the descriptor.

Tool names in the allowlist are normalized through the same name sanitization logic used elsewhere in the library. This means the descriptor should still use the real MCP tool names, but minor differences in punctuation or casing are normalized internally before matching.

Minimal Descriptor Example

A minimal LLM-planned MCP skill may look as follows.

# Inventory Data Retrieval

## Instructions

- Select tools that fetch stock or movement data.
- Avoid pricing or unrelated finance tools unless explicitly mentioned.
- Provide clear reasoning for each tool invocation.

## Allowed Tools

- inventoryLookup

This matches the fixture used in the repository tests. The descriptor does not force execution. It only constrains the planning surface to the allowed MCP tools and supplies the guidance used during plan generation.

Script-Based Variant

When the planning path should be explicit rather than LLM-derived, the descriptor may add a Plan SOPlang script section. In that case, the script becomes the source of the plan and the subsystem does not ask the LLM to propose tool steps.

# Metrics Retrieval

## Instructions

Use the declared MCP tools to collect the data required for downstream reporting.

## Allowed Tools

- metricScanner
- inventoryLookup

## Plan SOPlang
@prompt prompt
@scan metricScanner $prompt
@lookup inventoryLookup $prompt

This form is appropriate when the planning sequence should remain explicit and inspectable in the descriptor itself rather than being synthesized at runtime.