Upload and extract
Skill Powder-Finance/claude-code-powder-plugin/skills/powder/upload-and-extract
Use when user asks to upload, analyze, or extract data from a financial statement (PDF, Excel, or image). Handles brokerage statements, 401k statements, and account documents. Validates files, monitors processing, and formats results as human-readable tables.From its SKILL.md
npx -y skills add Powder-Finance/claude-code-powder-plugin --skill upload-and-extractAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
8.2 KB, as published. Nobody here has run it
Powder Upload and Extract
Automates the complete workflow of uploading financial statements (brokerage, bank, credit card) to the Powder API and extracting structured data. Handles validation, status monitoring, error recovery, and formatting of results.
Quick Start
- Verify Prerequisites - Check
powderCLI is installed and API token is configured - Validate File - Ensure file exists, is supported type (.pdf/.xlsx/.png/.jpg/.jpeg), and under 50MB
- Upload - Run
powder --json upload <path> [--portfolio <id>] - Monitor - Watch processing with
powder --json status <id> --watch --timeout 600 - Extract & Format - On success, fetch data and present as formatted table with totals and anomaly flags
When to Use This Skill
- User asks to "analyze this statement", "extract holdings", "upload brokerage statement"
- User provides a file path to a financial document
- User wants to know what's in a PDF/Excel statement
- User needs portfolio composition or transaction history
Upload and Extract Workflow
Step 0: Prerequisite Check
Before starting, verify the environment:
# Check powder CLI is available
which powder
# Verify auth token is set (checks both plugin config and env var)
test -n "${POWDER_API_TOKEN:-$CLAUDE_PLUGIN_OPTION_POWDER_API_TOKEN}" && echo "set" || echo "not set"
Decision Tree:
- ✅ Both available → Proceed to Step 1
- ❌
powdernot found → Suggest running/Powder:setupto install the CLI - ❌ Token not set → Suggest running
/Powder:setupto configure authentication
Important: Token Passthrough — Always prefix powder commands with:
POWDER_API_TOKEN="${POWDER_API_TOKEN:-$CLAUDE_PLUGIN_OPTION_POWDER_API_TOKEN}" powder ...
Step 1: Validate File
Before uploading, check the file meets requirements:
# Check file exists and get size
ls -lh "$FILE_PATH"
# Verify extension
file "$FILE_PATH"
Validation Checklist:
- File exists and is readable
- Extension is one of:
.pdf,.xlsx,.png,.jpg,.jpeg - Size is under 50MB (52,428,800 bytes)
- File is not empty (> 0 bytes)
Decision Tree:
- ✅ All checks pass → Proceed to Step 2
- ❌ File not found → Ask user to provide correct path
- ❌ Unsupported extension → Tell the user which formats are supported. Common unsupported types:
.csvand.xls(convert to.xlsx),.doc/.docx(export to PDF),.html(save as PDF) - ❌ Too large → Ask user to split or compress the file
- ❌ Empty file → File is corrupted or incomplete
Step 2: Upload
Execute the upload command with JSON output:
powder --json upload "$FILE_PATH"
Optional Flags:
--type brokerage- Statement type (default, currently the only supported type — can be omitted)--portfolio <id>- Associate with existing portfolio ID
Expected Response:
{
"id": 12345,
"status": "processing",
"portfolio_id": 67890
}
Capture:
id- Document ID for status trackingportfolio_id- Portfolio this data belongs to
Error Handling:
- 401 Unauthorized → Check API token is valid (plugin config or POWDER_API_TOKEN env var)
- 403 Forbidden → Token valid but lacks permissions, contact [email protected]
- 413 Payload Too Large → File exceeds 50MB limit
- 429 Rate Limited → Wait 60 seconds, then retry
- 400 Bad Request → Check file extension and type
- 500/503 Server Error → Powder API is down, wait a few minutes and retry
Step 3: Watch Processing Status
Monitor the document processing with automatic polling:
powder --json status 12345 --watch --timeout 600
Flags:
--watch- Poll every 2 seconds until terminal status--timeout 600- Wait up to 10 minutes (recommended for complex statements)
Terminal Statuses:
done→ Success, proceed to Step 4failed→ Extraction failed, see error detailserror→ Processing error, see error detailsclosed→ Document was closed or cancelled
Non-Terminal Statuses:
pending→ Upload is queued for processingprocessing→ OCR/extraction in progressin_review→ Manual review required (rare)
Decision Tree:
- ✅ Status =
done→ Proceed to Step 5 (fetch data) - ⏱️ Timeout reached → Document still processing, suggest:
powder status <id>to check later - ❌ Status =
failed,error, orclosed→ Go to Step 4 (error recovery)
Step 4: Error Recovery
When processing fails, extract error details:
powder --json status 12345
Common Error Scenarios:
| Error Code | Meaning | Fix |
|---|---|---|
PASSWORD_PROTECTED_PDF | PDF requires password | Remove password protection and re-upload |
CORRUPT_PDF / INVALID_PDF_HEADER | File is damaged | Re-download or re-export the PDF |
UNSUPPORTED_FILE_TYPE | Wrong file format | Convert to supported format (.pdf, .xlsx, .png, .jpg) |
EMPTY_PDF / EMPTY_EXCEL | No extractable content | Check source file has visible content |
See reference/error-codes.md for the full error code reference.
Next Steps:
- If fixable → Tell the user what's wrong and suggest they fix the source file and re-upload
- If unfixable or unclear → Report the error details and suggest contacting [email protected] with the document ID
Step 5: Fetch and Format Data
Once status is done, retrieve the extracted data:
powder --json data 12345
Response Structure:
{
"id": 12345,
"status": "done",
"data": {
"portfolio_id": 67890,
"ownerships": [...]
},
"count": 1,
"page": 1
}
Formatting Rules (see reference/output-formatting.md):
- Summary Line:
Found {count} holdings in portfolio {portfolio_id} - Holdings Table: Name, Ticker, Account, Quantity, Statement Value
- Totals Row: Sum of Statement Value, EOD Value, count
- Anomaly Flags: Highlight >20% gaps, missing tickers, multiple accounts
- Never show: Raw JSON, unmasked account numbers, full file paths
Example Output:
Found 1 holdings in portfolio 67890
Holdings:
┌──────────────────────────────────────┬────────┬──────────────────────────┬───────────┬─────────────────┐
│ Name │ Ticker │ Account │ Quantity │ Statement Value │
├──────────────────────────────────────┼────────┼──────────────────────────┼───────────┼─────────────────┤
│ Example Target Date Fund │ EXMPL │ Brokerage Account *** │ 1,000.00 │ $50,000.00 │
└──────────────────────────────────────┴────────┴──────────────────────────┴───────────┴─────────────────┘
Totals:
- Statement Value: $50,000.00
- Current EOD Value: $114,992.97
- Holdings: 1
⚠️ Anomalies Detected:
- Large valuation gap (66.5% difference) between statement and current EOD price
Examples
See reference/output-formatting.md for the full API response shape, field definitions, and formatted output example.
Related Skills
- ../data-retrieval/SKILL.md - Retrieve previously uploaded data
Reference Documentation
- reference/output-formatting.md - Formatting rules and privacy requirements
- reference/error-codes.md - All error codes with user-facing messages