A great 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 with wildly varying input formats.

A Skill without clear specifications will cause Claude to guess at input intentions, leading to unstable behavior.

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

---

Four Elements of Input Specifications

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

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
• First row must be column headers
• File size does not exceed 50MB

Optional Inputs

• Target columns: Specify which columns to analyze; defaults to all numeric columns

• Output format: table (table) or text (text summary), default table
• Precision: Number of decimal places to retain, default 2

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.

---

Three Dimensions of Output Specifications

Dimension One: Output Content

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

Example

Output Content

After analysis is complete, provide the following content:

1. Statistical summary table: Row count, mean, max/min values, and null value count for each column
2. Data quality report: List discovered issues (e.g., excessive null values, mixed data types)
3. File path: If an output file was generated, provide the download path

Dimension Two: Output Format

Specify which format to use for output and where to store it.

Output Target	Format	Storage Path
Displayed in conversation	Markdown table, code block	No storage needed
Downloadable file	.xlsx, .pdf, .html	/mnt/user-data/outputs/
Intermediate results	JSON, CSV	/home/claude/ (temporary)

Dimension Three: Output Timing

Specify when to output—whether all at once or step by step.

Example

Output Timing

1. After reading file: Immediately inform the user of basic file information (row count, column count, size)
2. During analysis: If analysis takes longer than 10 seconds, output a progress message first
3. After analysis completes: Output the complete statistical summary
4. After file generation: Display the file path and call the present_files tool

---

Complete Input/Output Specification Example

Below 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 (3 sentences) / medium (1 paragraph) / long (3 paragraphs), default medium
• Language: Output language, default same as original
• Focus area: Such as "focus on conclusion section", "extract numerical data"

Exception Handling

• File exceeds 10MB: Inform user the file is too large, suggest splitting and re-uploading
• Unsupported format: List supported formats and ask user to re-upload
• Document is image scan and text cannot be recognized: Inform that it cannot be processed, suggest using OCR tool for preprocessing

Output Specifications

Output Content (in order)

1. Basic document information: Title (if available), page count, estimated word count
2. Core summary: Output according to user-specified length
3. Keywords: 5-8 topic keywords

Output Format

• All displayed in conversation, using Markdown format
• No additional files generated unless user explicitly requests to save

Output Example

---

Document: tutorial-annual-report.pdf (24 pages, approximately 12,000 words)

Summary: This report reviews tutorial's annual business performance, with user volume growing 35% year-over-year, technical document coverage increased to 98%. Revenue structure is becoming more diversified, with advertising and membership revenue reaching parity.

Keywords: Annual Report, User Growth, Technical Documentation, Revenue Structure, Diversification

---

---

Script-Level Input/Output Conventions

If a Skill includes scripts, it is recommended to use JSON as the structured input/output format for easy parsing by Claude.

Example

# File path: scripts/summarize.py

# Standardized JSON input/output pattern

import json
import sys

def summarize(file_path: str, length: str="medium") ->dict:
    """
    Generate document summary
    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 document
        with open(file_path,"r", encoding="utf-8")as f:
            content = f.read()
        
        # Simulate generating summary
        summary = content[:200] + "..."# Actual implementation should call real summarization logic
        
        return{
            "status": "success",
            "data": {
                "word_count": len(content),
                "summary": summary,
                "length": length
            }
        }
    except FileNotFoundError:
        return{"status": "error","error": f"File does not exist：{file_path}"}
    except Exception as e:
        return{"status": "error","error": str(e)}

if __name__ =="__main__":
    file_path =sys.argvif len(sys.argv)>1 else""
    length =sys.argvif len(sys.argv)>2 else"medium"
    
    result = summarize(file_path, length)
    
    # Unified JSON output for Claude to parse
    print(json.dumps(result, ensure_ascii=False, indent=2))

{ "status": "success", "data": { "word_count": 12480, "summary": "tutorial annual report reviews the platform's business performance over the past year...", "length": "medium" }}

Using JSON as the script output format allows Claude to parse results stably, without needing to perform guesswork interpretation of free text.