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

> Learn to define inputs and outputs for a Claude skill using a Markdown manifest. Composio MCP handles JSON Schema validation and result formatting automatically.

- Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills)
- Tags: how-to-guide
- Published: 2026-07-23

---

**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.

```markdown
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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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:

```markdown
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`.

```markdown
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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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.

```markdown
---
name: my-sample-skill
---

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

```

### OpenAI Automation Skill

The [`composio-skills/openai-automation/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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.

```markdown
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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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.

```typescript
{
  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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/template-skill/SKILL.md) for templates and [`composio-skills/openai-automation/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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.