process-file

name	process-file
description	Process arbitrary files (email, PDF, Office docs, images, audio/video) and integrate with AkashicRecords for intelligent archiving. Reads file content, analyzes intent, and suggests appropriate storage location based on content and project preferences.

Process File Skill

Generic file processing Skill supporting multiple file formats for parsing and intelligent archiving, fully integrated with the AkashicRecords governance system.

When to use this Skill

• User says "read", "process"
• User says "archive", "import"
• User provides file path for processing
• User wants to integrate external files into knowledge base
• User provides email, PDF, Office documents, images, etc.

Workflow

1. Initialization - Read Preferences

Check claude.md:

1. Read current project's claude.md
2. Look for file-handling-preferences related record
3. If path found, read preferences file

If no preferences file exists:

1. Ask user: "This is the first time using process-file skill in this project. Where would you like to create the file handling preferences?"
2. Suggest default location: file-handling-preferences.md in project root
3. After user confirmation, create file and record location in claude.md

Preferences file structure:

• Processing pattern records (by file type and content category)
• Auto processing settings (whether to allow saving without confirmation)
• Historical processing records

2. File Type Detection

Detect file type: Determine processing method based on file extension:

Type	Extension	Processing Tool
Email	.eml	mu view <filepath>
PDF	.pdf	markitdown <filepath>
Word	.docx	markitdown <filepath>
PowerPoint	.pptx	markitdown <filepath>
Excel	.xlsx	markitdown <filepath>
Image	.jpg, .png, .gif, .webp, .bmp	Read tool (language model direct read)
Audio	.mp3, .wav, .m4a, .aac, .ogg	Ask user
Video	.mp4, .mov, .avi, .webm	Ask user

Tool availability check:

• Check if required tools are installed before execution
• If mu not installed: Prompt Please install maildir-utils: sudo apt install maildir-utils
• If markitdown not installed: Prompt Please install markitdown: pip install markitdown

3. Content Extraction

Email (.eml):

mu view <filepath>

Extract: sender, recipient, subject, date, body

PDF/Office documents:

markitdown <filepath>

Convert to markdown format

Images: Use Read tool to directly read image, let language model analyze content:

• Identify image subject
• Extract text (if any)
• Describe image content

Audio/Video:

1. Ask user for suggested processing method
2. Possible options:
   • Record file metadata only
   • Use external tool for transcription
   • Record manual summary
3. Record user's chosen processing method in project claude.md

4. Content Analysis

Analyze content:

• Identify topics and keywords
• Determine content type (technical, personal, work, academic, etc.)
• Extract important information (dates, people, places, events)

Infer user intent:

• Archive for storage (long-term preservation)
• Project update (related to existing project)
• Record memo (personal notes)
• Data organization (batch processing)

Match against preferences:

• Check if preferences file has matching patterns
• If historical records exist, prioritize suggesting same processing method

5. Directory Discovery

Use akashicrecords mechanism:

1. Based on content analysis results, build search query
2. Scan knowledge base directory structure
3. Read each directory's RULE.md to understand purpose
4. Evaluate content-to-directory purpose match

Suggestion logic:

• Technical document + directory purpose "research" → high match
• Email + directory purpose "communications" → high match
• Personal photo + directory purpose "personal life" → high match
• No clear match → suggest Miscellaneous or ask user

6. User Confirmation

Present analysis results:

## File Analysis Results

**File**: [filename]
**Type**: [file type]
**Content Summary**: [brief summary]

**Inferred Intent**: [archive/update/record]

**Suggested Location**: [target directory path]
**Reason**: [why this location was chosen]

**Planned Operation**:
- Call add-content skill
- Format: [according to RULE.md]
- Filename: [suggested filename]

Do you approve this operation?

Wait for confirmation:

• Default requires user approval
• If auto_save: true in preferences, can skip confirmation
• User can modify suggested location or cancel

7. Execute

Call corresponding akashicrecords skill:

• Add new content → add-content skill
• Update existing → update-content skill

Format according to target RULE.md:

• Read target directory's RULE.md
• Follow naming conventions
• Apply frontmatter format (if required)

8. Update Preferences

Record this processing experience:

### [Date] [File Type]
- Content characteristics: [key features]
- Target location: [actual storage location]
- Processing method: [skill used]

Learning pattern:

• Accumulate user preferences
• Prioritize suggesting same method for similar content next time

Multi-File Processing

When user provides multiple files:

Parallel Analysis

1. Launch a subagent for each file
2. Each subagent independently executes Phase 2-5
3. Wait for all subagents to complete

Consolidated Presentation

## Multi-File Processing Analysis Results

| # | Filename | Type | Content Summary | Suggested Location | Operation |
|---|----------|------|-----------------|-------------------|-----------|
| 1 | file1.pdf | PDF | [summary] | Research/ | add-content |
| 2 | photo.jpg | Image | [summary] | Personal/ | add-content |
| 3 | email.eml | Email | [summary] | Work/ | add-content |

Please choose:
- Approve all
- Confirm individually
- Cancel

Batch Execution

• After user approves all, execute sequentially
• When user confirms individually, confirm each file separately

Error Handling

Tool Not Installed

Warning: Cannot process .eml file: mu tool not installed
Please run: sudo apt install maildir-utils

Unsupported File Format

Warning: Unsupported file format: .xyz
How would you like to proceed?
1. Try reading as plain text
2. Record file metadata only
3. Skip this file

Parse Failure

Warning: Unable to parse file content
Error: [error message]
How would you like to proceed?
1. Retry
2. Enter summary manually
3. Skip this file

Integration with Governance

Before operation:

• Read preferences file
• Confirm akashicrecords governance structure exists

During operation:

• Use akashicrecords skills for actual operations
• Follow target directory's RULE.md

After operation:

• Update preferences file
• akashicrecords skills automatically handle README.md updates

Examples

Example 1: Process PDF Paper

User: "Read ~/Downloads/transformer-paper.pdf"

Workflow:

1. Check preferences → Find historical record "technical paper → Research/Papers/"
2. Detect .pdf → Use markitdown
3. Execute markitdown ~/Downloads/transformer-paper.pdf
4. Analyze content → AI/machine learning topic
5. Match preferences → Matches "technical paper" pattern
6. Suggest Research/Papers/AI/
7. User confirms
8. Call add-content skill
9. Update preferences file

Example 2: Batch Process Emails

User: "Archive these emails: email1.eml email2.eml email3.eml"

Workflow:

1. Detect multiple files → Launch 3 subagents
2. Each subagent processes in parallel:
   • Parse using mu view
   • Analyze sender, subject, content
   • Suggest target location
3. Consolidate results into list
4. User selects "Approve all"
5. Execute add-content sequentially
6. Update preferences

Example 3: Process Image

User: "Process this photo ~/Photos/vacation.jpg"

Workflow:

1. Detect .jpg → Use Read tool
2. Language model analyzes image content → "Beach vacation photo"
3. Check preferences → Find "travel photos → Personal/Travel/"
4. Suggest Personal/Travel/2025/
5. User confirms
6. Call add-content (convert to descriptive markdown)
7. Update preferences

Best Practices

1. Always check preferences first - Prioritize historical processing patterns
2. Confirm before saving - Default requires user approval
3. Update preferences after success - Accumulate learning user preferences
4. Use parallel processing - Leverage subagents for multiple files
5. Handle errors gracefully - Provide alternatives
6. Integrate with akashicrecords - Use existing skills for operations

Notes

• Preferences file path is recorded in project claude.md
• Each project can have different preferences
• Audio/video processing methods are recorded in claude.md
• This Skill does not modify files directly, operates through akashicrecords skills