How to Define Inputs and Outputs for a Claude Skill: The Complete Manifest Guide

Define inputs and outputs for a Claude skill by creating a Markdown-based manifest with Inputs: and Outputs: sections, where the Composio MCP runtime automatically converts these lists into JSON Schema validation and result formatting.

Claude skills in the ComposioHQ/awesome-claude-skills repository use a declarative Markdown format to specify tool contracts. When you define inputs and outputs for a Claude skill, you create a machine-readable interface that the Model Context Protocol (MCP) runtime validates against JSON Schema before execution.

Understanding the Skill Manifest Structure

A Claude skill manifest is a .md file that describes one or more tools—discrete actions the skill can perform. The manifest follows a consistent pattern that the MCP compiler processes to generate server-side validation logic and client-side type hints.

Each tool definition requires three core components: a Tool header that declares the callable slug, an Inputs section that lists parameters with types and constraints, and an Outputs section (or workflow description) that documents the return shape.

Defining Tool Inputs

Inputs are declared under an Inputs: heading as a bullet list. Each entry follows the syntax name: type (required/optional) — description, which the runtime parses into formal JSON Schema properties.

Input Syntax and Types

The type system supports primitives (string, number, boolean), complex objects, and unions (using |). Descriptions help Claude understand semantic constraints beyond raw types.

Tool: ECHO_TEXT
Inputs:
  - message: string (required) — Text to echo back.
  - shout: boolean (optional) — If true, the response is upper-cased.
  - metadata: object (optional) — Additional context.

See the minimal example in template-skill/SKILL.md.

Required vs Optional Parameters

Mark parameters as (required) or (optional) to control the required array in the generated inputSchema. The MCP server rejects calls missing required fields before invoking your tool logic, enforcing type safety at the boundary.

For nested objects, indent child properties to create structured schemas. The OpenAI skill demonstrates this with its text.format configuration.

Specifying Tool Outputs

Output contracts describe what the tool returns after successful execution. While optional, explicit output documentation helps Claude interpret results correctly, especially for structured data extraction.

Explicit Output Blocks

Use an Outputs: section to enumerate return fields when the shape is predictable:

Outputs:
  - result: string — The echoed (or shouted) text.
  - timestamp: number — Unix epoch of the execution.

If omitted, the runtime infers the output type from the tool's "Core Workflow" description text.

Structured JSON Output

For programmatic consumption, specify JSON output using the text.format parameter with a json_schema definition. The runtime serializes the tool's return value to match this schema when response_format is set to json.

Inputs:
  - text: object (optional) — Structured output config.
    - format: { type: "json_schema", name: "response", schema: {...}, strict: true }
Outputs:
  - content: array — JSON object matching `text.format`.

Reference the structured output example in composio-skills/openai-automation/SKILL.md.

Real-World Examples from the Repository

The awesome-claude-skills repository provides canonical implementations demonstrating input-output patterns for production use cases.

Minimal Template Example

The template-skill/SKILL.md file provides a barebones skeleton showing proper placement of input and output declarations. This template validates against the MCP compiler and serves as the starting point for new skills.

---
name: my-sample-skill
---

Tool: ECHO_TEXT
Inputs:
  - message: string (required)
Outputs:
  - result: string

OpenAI Automation Skill

The composio-skills/openai-automation/SKILL.md demonstrates complex input validation with the OPENAI_CREATE_RESPONSE tool. It defines union types (string | array), constrained numbers (0‑2), and nested objects for structured generation.

Tool: OPENAI_CREATE_RESPONSE
Inputs:
  - model: string (required) — e.g., "gpt-4o"
  - input: string | array (required) — Prompt or messages.
  - temperature: number (optional) — 0‑2, not supported with reasoning models.
  - text: object (optional)
    - format: { type: "json_schema", name: "...", schema: {...}, strict: true }

This skill lacks an explicit Outputs: block but documents the JSON return shape in the "Structured output example" section, illustrating how workflow text can substitute for formal output declarations.

How the MCP Runtime Processes Schemas

When the MCP server loads your skill, it compiles the Markdown manifest into TypeScript tool definitions. The inputSchema property becomes a JSON Schema object generated from your Inputs: list, while the response_format flag determines whether the tool emits JSON or Markdown.

According to mcp-builder/reference/mcp_best_practices.md, the runtime validates all parameters against this schema before execution. Optional annotations like readOnlyHint or destructiveHint guide UI rendering but do not bypass validation.

{
  name: "calculate_sum",
  inputSchema: {
    type: "object",
    properties: {
      a: { type: "number" },
      b: { type: "number" }
    },
    required: ["a", "b"]
  }
}

The server implementation in mcp-builder/reference/python_mcp_server.md consumes these schemas to enforce contracts at runtime.

Summary

• Input declaration uses bullet lists under Inputs: with the syntax name: type (required/optional) — description.
• Type safety is enforced by the MCP runtime converting these lists into JSON Schema inputSchema definitions.
• Output specification can be explicit via Outputs: blocks or implicit through workflow documentation.
• Structured data requires setting text.format to a json_schema object for strict validation.
• Repository references include template-skill/SKILL.md for templates and composio-skills/openai-automation/SKILL.md for complex examples.

Frequently Asked Questions

What file format does Claude use for skill manifests?

Claude skills use Markdown (.md) files as manifests, typically named SKILL.md in the skill's root directory. The Composio MCP runtime parses these files to extract tool definitions, input schemas, and output contracts without requiring separate configuration files.

How does the MCP runtime handle optional input parameters?

The runtime parses (optional) markers in the Inputs: list to exclude those fields from the JSON Schema required array. When Claude calls the tool, the server validates that all (required) parameters are present, rejecting requests that omit mandatory fields before your tool logic executes.

Can I define complex nested objects as inputs?

Yes. Indent child properties under parent object parameters to create nested schemas. The OpenAI skill in composio-skills/openai-automation/SKILL.md demonstrates this pattern with the text.format configuration object, which accepts a json_schema definition for structured output validation.

What is the difference between JSON and Markdown output formats?

The response_format flag determines serialization: JSON returns machine-readable structured data matching your output schema, while Markdown returns human-readable formatted text. Set text.format to json_schema when you need strict type guarantees for downstream processing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}