Skills Input/Output Specification Design

An excellent Skill not only completes tasks, but also clearly defines "what it accepts" and "what it produces."

Good input/output specifications are the foundation for reliable Skill operation.

Why Define Input/Output Specifications

Skills face real user requests, and input formats vary endlessly.

Without clear specifications, Claude will guess the input intent on its own, leading to unstable behavior.

Specifications are not limitations, but clear action boundaries for Claude, reducing ambiguity and improving output consistency.

The Four Elements of Input Specifications

Element Description Example
Input Type Files, text, URLs, parameters, etc. PDF file uploaded by the user
Format Requirements File extension, encoding, structure .csv, UTF-8 encoding, first row is the header
Required/Optional Which inputs are required File path is required, column names are optional
Default Behavior How to handle when optional parameters are not provided Analyze all columns when column names are not specified

Defining Input Specifications in SKILL.md

Example

## Input Specifications

### Required Inputs

- **Data file**: User-uploaded`.csv`or`.xlsx`file
- Encoding: UTF-8(CSV) or standard Excel format
- The first row must be column headers
- File size must not exceed 50MB

### Optional Inputs

- **Target columns**: Specify which columns to analyze; by default, all numeric columns are analyzed
- **Output format**：`table`(table) or`text`(text summary), default`table`
- **Precision**: Number of decimal places to retain, default2bits

### Handling Missing Inputs

If no file is uploaded, inform the user:"Please upload the CSV or Excel file to be analyzed."
If the file format is not supported, inform the user and list the supported formats.

The Three Dimensions of Output Specifications

Dimension 1: Output Content

Clearly specify what content to output, avoiding omissions or excessive output.

Example

## Output Content

After the analysis is complete, provide the following:

1. **Statistical summary table**: Row count, mean, maximum for each column/Minimum value, count of null values
2. **Data quality report**: List issues found (e.g., too many null values, mixed data types)
3. **File path**: If output files are generated, provide download paths

Dimension 2: Output Format

Specify the format in which the output is presented and where it is stored.

Output destination Format Storage path
Display in conversation Markdown tables, code blocks No storage needed
Downloadable file .xlsx、.pdf、.html /mnt/user-data/outputs/
Intermediate result JSON、CSV /home/claude/(temporary)

Dimension 3: Output Timing

Specify when to output, whether to output everything at once or display it progressively in steps.

Example

## Output Timing

1. **After reading the file**: Immediately inform the user of the file's basic information (row count, column count, size)
2. **During analysis**: If the analysis takes longer than10seconds, output a progress prompt first
3. **After the analysis is complete**: Output the complete statistical summary
4. **After the file is generated**: Display the file path and call the present_files tool

Complete Input/Output Specification Example

The following is a complete input/output specification for a document summarization Skill:

Example

---
name: doc-summarizer
description: >
Extract summaries from user-uploaded documents, supporting PDF, Word (.docx), and plain text.
Use when users need to quickly understand document content, extract key information, or generate document summaries.
---

# Document Summarizer

## Input Specifications

### Required
- Document file (.pdf, .docx, or .txt)

### Optional
- **Summary length**：`short`（3sentences)/ `medium`（1paragraph(s))/ `long`（3paragraphs), default`medium`
- **Language**: Output language, defaults to the same as the original text
- **Focus direction**: Such as"Focus on the conclusion section"、"Extract numerical data"

### Exception Handling
- File exceeds 10MB: Inform the user that the file is too large and suggest uploading it after splitting
- Unsupported format: List the supported formats and ask the user to re-upload
- Document is a scanned image and text cannot be recognized: Inform the user that it cannot be processed and recommend preprocessing with an OCR tool

## Output Specifications

### Output Content (in order)
1. Document basic information: title (if any), page count, estimated word count
2. Core summary: Output according to the user-specified length
3. Keywords:5-8topic keywords

### Output Format
- Display everything in the conversation, using Markdown format
- Do not generate additional files unless the user explicitly requests to save them

### Output Example
---
**Document**：example-annual-report.pdf（24pages, approximately12,000 words)

**Summary**: This report reviews example's annual business performance, with user volume growing year-over-year35%，
Technical documentation coverage increased to98%. The revenue structure is becoming more diversified, with advertising and membership revenue proportions roughly equal.

**Keywords**: Annual report, user growth, technical documentation, revenue structure, diversification
---

Input/Output Conventions at the Script Level

If the Skill comes with scripts, it is recommended to use JSON as the structured input/output format so that Claude can easily parse the results.

Example

# File path: scripts/summarize.py
# Standardized JSON input/output pattern

import json
import sys

def summarize(file_path: str, length: str = "medium") -> dict:
    """
Summarize a document

Parameters:
file_path: Document path (required)
length: Summary length, short/medium/long (optional, default medium)

Returns:
dict, containing status, data, or error fields
    """
    try:
        # Simulate reading the document
        with open(file_path, "r", encoding="utf-8") as f:
            content = f.read()

        # Simulate generating the summary
        summary = content[:200] + "..."  # Should actually call the real summarization logic

        return {
            "status": "success",
            "data": {
                "word_count": len(content),
                "summary": summary,
                "length": length
            }
        }

    except FileNotFoundError:
        return {"status": "error", "error": f"File not found: {file_path}"}
    except Exception as e:
        return {"status": "error", "error": str(e)}

if __name__ == "__main__":
    file_path = sys.argv[1] if len(sys.argv) > 1 else ""
    length    = sys.argv[2] if len(sys.argv) > 2 else "medium"

    result = summarize(file_path, length)

    # Output unified JSON for Claude to parse
    print(json.dumps(result, ensure_ascii=False, indent=2))
{
  "status": "success",
  "data": {
    "word_count": 12480,
    "summary": "example 年度报告回顾了平台在过去一年的业务表现...",
    "length": "medium"
  }
}

Using JSON as the script output format allows Claude to stably parse results without having to make guess-based interpretations of free text.

Other Extensions