Skill Filetypes

Filetypes Skill

Thin wrapper that routes file format operations to the filetypes-router-agent, which then delegates to specialized sub-agents based on file type.

Context Pointers

Reference (do not load eagerly):

• Path: .claude/context/formats/subagent-return.md
• Purpose: Return validation
• Load at: Subagent execution only

Note: This skill is a thin wrapper. Context is loaded by the delegated agents, not this skill.

Trigger Conditions

This skill activates when:

Direct Invocation

• User explicitly runs /convert command
• User requests file format conversion in conversation

Implicit Invocation (during task implementation)

When an implementing agent encounters any of these patterns:

Plan step language patterns:

• "Extract text from [file].pdf"
• "Extract content from [file]"
• "Convert [file] to markdown"
• "Convert [file] to PDF"
• "Generate PDF from [documentation/file]"
• "Read content from [file].docx"
• "Create PDF version of [file]"
• "Parse [file].pdf for content"
• "Import [file] content"

File extension detection:

• Source file has extension: .pdf, .docx, .xlsx, .pptx, .html
• Target mentions: "markdown", ".md", "PDF", ".pdf"

Task description keywords:

• "document conversion"
• "format transformation"
• "extract from PDF"
• "generate PDF"

When NOT to trigger

Do not invoke for:

• Reading source code files (.py, .js, .lean, etc.)
• Viewing images without extraction
• Operations that don't involve format conversion
• Files already in the target format
• Spreadsheet-specific operations (use skill-spreadsheet)
• Presentation-specific operations (use skill-presentation)
• XLSX creation, editing, or analysis (use skill-sheet via /sheet or /edit file.xlsx)

XLSX routing distinction: This skill handles xlsx-to-markdown content extraction via /convert file.xlsx. For xlsx creation, editing, and analysis, route to skill-sheet instead.

Execution

1. Input Validation

Validate required inputs:

• source_path - Must be provided and file must exist
• output_path - Optional, defaults to source dir with appropriate extension

# Validate source exists
if [ ! -f "$source_path" ]; then
  return error "Source file not found: $source_path"
fi

# Determine output path if not provided
if [ -z "$output_path" ]; then
  source_dir=$(dirname "$source_path")
  source_base=$(basename "$source_path" | sed 's/\.[^.]*$//')
  source_ext="${source_path##*.}"

  # Infer target extension
  case "$source_ext" in
    pdf|docx|xlsx|pptx|html) output_path="${source_dir}/${source_base}.md" ;;
    md) output_path="${source_dir}/${source_base}.pdf" ;;
    *) return error "Cannot infer output format for .$source_ext" ;;
  esac
fi

2. Context Preparation

Prepare delegation context:

{
  "source_path": "/absolute/path/to/source.pdf",
  "output_path": "/absolute/path/to/output.md",
  "metadata": {
    "session_id": "sess_{timestamp}_{random}",
    "delegation_depth": 1,
    "delegation_path": ["orchestrator", "convert", "skill-filetypes"]
  }
}

3. Invoke Router Agent

CRITICAL: You MUST use the Agent tool to spawn the router agent.

Required Tool Invocation:

Tool: Agent (NOT Skill, NOT Plan)
Parameters:
  - subagent_type: "filetypes-router-agent"
  - prompt: [Include source_path, output_path, metadata]
  - description: "Convert {source_path} to {output_path}"

DO NOT use Skill(filetypes-router-agent) - this will FAIL. Agents live in .claude/agents/ or extension agent directories, not .claude/skills/. The Skill tool can only invoke skills from .claude/skills/.

The router will:

• Detect source and target formats
• Select appropriate sub-agent (document, spreadsheet, presentation)
• Delegate to sub-agent for actual conversion
• Return standardized JSON result

4. Return Validation

Validate return matches subagent-return.md schema:

• Status is one of: converted, extracted, partial, failed
• Summary is non-empty and <100 tokens
• Artifacts array present with output file path
• Metadata contains session_id, agent_type, delegation info

5. Return Propagation

Return validated result to caller without modification.

Return Format

See .claude/context/formats/subagent-return.md for full specification.

Expected successful return:

{
  "status": "converted",
  "summary": "Successfully converted document.pdf to document.md using markitdown",
  "artifacts": [
    {
      "type": "implementation",
      "path": "/absolute/path/to/document.md",
      "summary": "Converted markdown document"
    }
  ],
  "metadata": {
    "session_id": "sess_...",
    "agent_type": "document-agent",
    "delegation_depth": 2,
    "delegation_path": ["orchestrator", "convert", "skill-filetypes", "filetypes-router-agent", "document-agent"],
    "tool_used": "markitdown"
  },
  "next_steps": "Review converted document"
}

Error Handling

Input Validation Errors

Return immediately with failed status if source file not found.

Unsupported Format

Return failed status with clear message about supported formats.

Router/Subagent Errors

Pass through the router/subagent's error return verbatim.

Tool Not Available

Return failed status with installation instructions.