shortcutxl 0.2.0

package/skills/integrations/ycharts.md

@@ -0,0 +1,306 @@
+**YCharts Excel Formula Guide**
+
+**Intro**
+You have full access to YCharts data through the native Excel Add-in (included with YCharts Professional subscription), but you should only pull YCharts data **when the user explicitly tells you to**. YCharts specializes in investment research data including fundamental metrics, valuation ratios, and portfolio analytics for stocks, ETFs, and mutual funds. You can retrieve any data point by writing YCharts formulas directly in Excel cells.
+
+**IMPORTANT:** Before completing a task involving YCharts, you must verify:
+1. Your YCharts formulas do not return errors.
+2. All values should seem reasonable and make intuitive sense based on your general knowledge of finance.
+3. Use cell references for tickers and metrics when possible as opposed to hardcoded values.
+4. Be aware of data coverage - YCharts focuses on US securities and major global markets.
+5. Mutual funds require the M: prefix; ETFs use standard tickers.
+
+You should essentially gut check every value that shows up. If there are any errors or the values seem wrong, you likely wrote the formula syntax incorrectly or are using invalid metric names. Please correct the formula until it outputs the proper value.
+
+---
+
+**YCharts Excel Functions Overview**
+
+YCharts provides these main Excel functions:
+
+| Function | Purpose | Use Case |
+|----------|---------|----------|
+| YCD | YCharts Data | Current or point-in-time single value |
+| YCDS | YCharts Data Series | Historical time series data |
+| YCDU | YCharts Data Universe | Screen securities by criteria |
+
+---
+
+**1. YCD - YCharts Data (Single Value)**
+
+Returns a single data point for current or historical date.
+
+**Syntax:** =YCD("ticker", "metric") or =YCD("ticker", "metric", "date")
+
+**Parameters:**
+| Parameter | Description | Required |
+|-----------|-------------|----------|
+| ticker | Security identifier | Yes |
+| metric | Metric name | Yes |
+| date | Optional date (YYYY-MM-DD) | No |
+
+**Examples:**
+=YCD("AAPL", "price")
+-> Apple's current stock price.
+
+=YCD("MSFT", "pe_ratio")
+-> Microsoft's current P/E ratio.
+
+=YCD("AAPL", "price", "2024-01-02")
+-> Apple's price on Jan 2, 2024.
+
+**Using Cell References:**
+=YCD(A1, "price")
+-> Price for ticker in cell A1.
+
+=YCD("AAPL", B1)
+-> Metric specified in cell B1 for Apple.
+
+---
+
+**2. YCDS - YCharts Data Series (Time Series)**
+
+Returns historical data over a date range.
+
+**Syntax:** =YCDS("ticker", "metric", "start_date", "end_date")
+
+**Parameters:**
+| Parameter | Description | Required |
+|-----------|-------------|----------|
+| ticker | Security identifier | Yes |
+| metric | Metric name | Yes |
+| start_date | Start date (YYYY-MM-DD) | Yes |
+| end_date | End date (YYYY-MM-DD) | Yes |
+
+**Examples:**
+=YCDS("AAPL", "price", "2024-01-01", "2024-12-31")
+-> Apple daily prices for 2024.
+
+=YCDS("SPY", "dividend_yield", "2020-01-01", "2024-01-01")
+-> SPY dividend yield history.
+
+=YCDS("M:VFIAX", "nav", "2023-01-01", "2023-12-31")
+-> Vanguard 500 Index Fund NAV history.
+
+---
+
+**3. Ticker Format**
+
+**Stocks:**
+| Type | Format | Example |
+|------|--------|---------|
+| US Stocks | Standard ticker | `AAPL`, `MSFT`, `GOOGL` |
+| ADRs | Standard ticker | `BABA`, `TSM` |
+
+**ETFs:**
+| Type | Format | Example |
+|------|--------|---------|
+| US ETFs | Standard ticker | `SPY`, `QQQ`, `IWM` |
+| International ETFs | Standard ticker | `EFA`, `VWO`, `IEMG` |
+
+**Mutual Funds (IMPORTANT: use M: prefix):**
+| Type | Format | Example |
+|------|--------|---------|
+| Mutual Funds | `M:` + ticker | `M:VFIAX`, `M:FXAIX`, `M:TRBCX` |
+| Money Market | `M:` + ticker | `M:SPAXX`, `M:VMFXX` |
+
+**Indices:**
+| Index | Ticker |
+|-------|--------|
+| S&P 500 | `^SPX` or `SPY` (ETF proxy) |
+| Nasdaq 100 | `^NDX` or `QQQ` (ETF proxy) |
+| Dow Jones | `^DJI` or `DIA` (ETF proxy) |
+| Russell 2000 | `^RUT` or `IWM` (ETF proxy) |
+
+---
+
+**4. Common Metrics Reference**
+
+**Pricing Metrics:**
+| Metric | Description |
+|--------|-------------|
+| `price` | Current/last price |
+| `open` | Opening price |
+| `high` | Day's high |
+| `low` | Day's low |
+| `volume` | Trading volume |
+| `price_change_1d` | 1-day price change |
+| `price_change_1d_pct` | 1-day % change |
+
+**Valuation Metrics:**
+| Metric | Description |
+|--------|-------------|
+| `pe_ratio` | Price/Earnings ratio |
+| `forward_pe_ratio` | Forward P/E ratio |
+| `peg_ratio` | PEG ratio |
+| `ps_ratio` | Price/Sales ratio |
+| `pb_ratio` | Price/Book ratio |
+| `ev_to_ebitda` | EV/EBITDA |
+| `ev_to_revenue` | EV/Revenue |
+| `dividend_yield` | Dividend yield (%) |
+
+**Fundamental Metrics:**
+| Metric | Description |
+|--------|-------------|
+| `market_cap` | Market capitalization |
+| `enterprise_value` | Enterprise value |
+| `revenue` | Total revenue (TTM) |
+| `net_income` | Net income (TTM) |
+| `ebitda` | EBITDA (TTM) |
+| `eps` | Earnings per share |
+| `eps_growth_yoy` | YoY EPS growth |
+| `revenue_growth_yoy` | YoY revenue growth |
+
+**Profitability Metrics:**
+| Metric | Description |
+|--------|-------------|
+| `gross_margin` | Gross margin (%) |
+| `operating_margin` | Operating margin (%) |
+| `profit_margin` | Net profit margin (%) |
+| `roe` | Return on equity (%) |
+| `roa` | Return on assets (%) |
+| `roic` | Return on invested capital (%) |
+
+**Balance Sheet Metrics:**
+| Metric | Description |
+|--------|-------------|
+| `total_assets` | Total assets |
+| `total_liabilities` | Total liabilities |
+| `total_equity` | Shareholders' equity |
+| `cash_and_equivalents` | Cash on hand |
+| `total_debt` | Total debt |
+| `debt_to_equity` | Debt/Equity ratio |
+| `current_ratio` | Current ratio |
+
+**Return Metrics:**
+| Metric | Description |
+|--------|-------------|
+| `return_1m` | 1-month return (%) |
+| `return_3m` | 3-month return (%) |
+| `return_6m` | 6-month return (%) |
+| `return_ytd` | Year-to-date return (%) |
+| `return_1y` | 1-year return (%) |
+| `return_3y` | 3-year annualized return (%) |
+| `return_5y` | 5-year annualized return (%) |
+| `return_10y` | 10-year annualized return (%) |
+
+**Fund-Specific Metrics (ETFs & Mutual Funds):**
+| Metric | Description |
+|--------|-------------|
+| `nav` | Net asset value |
+| `expense_ratio` | Expense ratio (%) |
+| `aum` | Assets under management |
+| `morningstar_rating` | Morningstar star rating (1-5) |
+| `turnover_ratio` | Portfolio turnover (%) |
+| `yield_ttm` | Trailing 12-month yield |
+| `sec_yield` | 30-day SEC yield |
+
+**Dividend Metrics:**
+| Metric | Description |
+|--------|-------------|
+| `dividend_yield` | Annual dividend yield (%) |
+| `dividend_per_share` | Dividend per share |
+| `dividend_payout_ratio` | Payout ratio (%) |
+| `dividend_growth_5y` | 5-year dividend growth (%) |
+| `ex_dividend_date` | Next ex-dividend date |
+
+---
+
+**5. Example Formulas by Use Case**
+
+**Current Stock Analysis:**
+=YCD("AAPL", "price")
+-> Apple stock price.
+
+=YCD("AAPL", "pe_ratio")
+-> Apple P/E ratio.
+
+=YCD("AAPL", "market_cap")
+-> Apple market cap.
+
+**Valuation Comparison:**
+=YCD("MSFT", "ev_to_ebitda")
+-> Microsoft EV/EBITDA.
+
+=YCD("GOOGL", "ps_ratio")
+-> Google price/sales ratio.
+
+**Historical Analysis:**
+=YCDS("AAPL", "price", "2023-01-01", "2023-12-31")
+-> Apple prices for 2023.
+
+=YCDS("NVDA", "pe_ratio", "2020-01-01", "2024-01-01")
+-> NVIDIA P/E ratio history.
+
+**Fund Analysis:**
+=YCD("M:VFIAX", "expense_ratio")
+-> Vanguard 500 expense ratio.
+
+=YCD("M:VFIAX", "morningstar_rating")
+-> Vanguard 500 Morningstar rating.
+
+=YCD("SPY", "nav")
+-> SPY ETF NAV.
+
+=YCD("QQQ", "yield_ttm")
+-> QQQ trailing yield.
+
+**Return Comparison:**
+=YCD("AAPL", "return_1y")
+-> Apple 1-year return.
+
+=YCD("M:TRBCX", "return_5y")
+-> T. Rowe Price Blue Chip 5-year return.
+
+**Dividend Analysis:**
+=YCD("JNJ", "dividend_yield")
+-> J&J dividend yield.
+
+=YCD("KO", "dividend_growth_5y")
+-> Coca-Cola 5-year dividend growth.
+
+**Portfolio Building:**
+=YCD(A2, "price") * B2
+-> Position value (ticker in A2, shares in B2).
+
+=YCD(A2, "dividend_yield") * YCD(A2, "price") * B2
+-> Annual dividend income for position.
+
+---
+
+**6. Error Handling**
+
+**Common Errors:**
+| Error | Cause | Solution |
+|-------|-------|----------|
+| #VALUE! | Invalid ticker | Check ticker symbol spelling |
+| #NAME? | Function not recognized | Verify YCharts add-in is enabled |
+| #N/A | Metric not available | Check metric is valid for security type |
+| No data | Coverage gap | Security may not be covered |
+| Wrong value | Missing M: prefix | Use M: prefix for mutual funds |
+
+**Debugging Tips:**
+1. Verify ticker on YCharts website first
+2. For mutual funds, always use M: prefix
+3. Check metric names are lowercase with underscores
+4. Use date format YYYY-MM-DD
+5. Verify subscription includes Excel add-in access
+
+---
+
+**Final Checklist:**
+- What security type? (Stock, ETF, or mutual fund with M: prefix)
+- What metric is needed? (Price, valuation, fundamental, return?)
+- Is this current data (YCD) or historical series (YCDS)?
+- Is the ticker spelled correctly?
+- For mutual funds, did you include the M: prefix?
+- Are metric names in lowercase with underscores?
+- Is the YCharts add-in connected?
+
+---
+
+**Additional Resources:**
+- YCharts Platform: https://ycharts.com/
+- Excel Add-in Guide: https://ycharts.com/excel
+- Metric Glossary: https://ycharts.com/glossary
+- Data Coverage: https://ycharts.com/coverage

package/skills/pdf-creation/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: pdf-creation
+description: Use when generating or converting PDFs.
+---
+
+# PDF Generation
+
+## CRITICAL: Work in /tmp, Copy Final to /workspace
+
+**Always generate/convert in `/tmp` first**, then copy the final PDF to `/workspace`. Intermediate files aren't useful to the user.
+
+```python
+# Generate in /tmp
+pdf.output('/tmp/report.pdf')
+
+# Copy final result to /workspace
+import shutil
+shutil.copy('/tmp/report.pdf', '/workspace/report.pdf')
+```
+
+---
+
+## CRITICAL: Build Incrementally
+
+**DO NOT** write a single massive script. If it fails on page 15, you lose everything.
+
+**Build iteratively** - generate a few pages, save to `/tmp`, verify, then add more.
+
+---
+
+## Approaches
+
+### 1. Direct Generation (fpdf/fpdf2, reportlab)
+
+Generate in `/tmp`, copy final to `/workspace`:
+
+```python
+pdf = FPDF()
+# ... build PDF ...
+pdf.output('/tmp/report.pdf')
+shutil.copy('/tmp/report.pdf', '/workspace/report.pdf')
+```
+
+### 2. HTML to PDF (Playwright)
+
+Write to `/tmp`, copy final to `/workspace`:
+
+```python
+pdf_bytes = await page.pdf(format="A4")
+with open('/tmp/report.pdf', 'wb') as f:
+    f.write(pdf_bytes)
+shutil.copy('/tmp/report.pdf', '/workspace/report.pdf')
+```
+
+### 3. Office File Conversion (LibreOffice)
+
+LibreOffice **cannot** write directly to `/workspace` in GCS:
+
+```
+Error: SfxBaseModel::impl_store failed: 0x507(Error Area:Io Class:Access Code:7)
+```
+
+**Must** write to `/tmp`, then copy:
+
+```bash
+libreoffice --headless --convert-to pdf --outdir /tmp /workspace/file.pptx && cp /tmp/file.pdf /workspace/
+```
+
+The Java warning (`failed to launch javaldx`) is harmless.
+
+---
+
+## fpdf/fpdf2 Gotchas
+
+### Error: "Not enough horizontal space to render a single character"
+
+`cell()` moves cursor right; `multi_cell()` needs room.
+
+**Fix:** Reset X position before `multi_cell()`:
+
+```python
+pdf.set_x(pdf.l_margin)
+pdf.multi_cell(0, 6, text)
+```
+
+### Page breaks mid-content
+
+**Fix:** Check remaining space before adding content:
+
+```python
+if pdf.get_y() > 250:  # Near bottom of A4
+    pdf.add_page()
+```

package/skills/pdf-extraction/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: pdf-extraction
+description: Use when extracting data from PDFs. Covers programmatic extraction vs multimodal LLM approaches.
+---
+
+# PDF Data Extraction
+
+## When to Use Programmatic Extraction
+
+Use for **structured data with >500 data points** (tables, financial statements, transaction lists). Fast, cheap, accurate, deterministic.
+
+## When to Use Multimodal LLMs
+- **Scanned documents** - No machine-readable text layer
+- **Complex layouts** - Multi-column, nested tables, mixed text/images
+- **Charts and figures** - Visual data that can't be extracted programmatically
+- **Verification** - Spot-check programmatic extraction results
+- **Small extractions** - <500 data points where speed doesn't matter
+
+## Programmatic Library Selection
+
+| Library | Best For | Gotchas |
+|---------|----------|---------|
+| **camelot** | Tables with clear borders | `flavor='stream'` for borderless; requires ghostscript |
+| **pdftotext -layout** | Column-aligned text (ideal for LLM input) | CLI only, no Python API for layout mode |
+| **PyMuPDF (fitz)** | Speed, general extraction | Use `sort=True` for reading order; less accurate table detection |
+| **pdfplumber** | Table detection | Loses internal spaces in text cells |
+
+## Key Practices
+
+1. **Use multiple methods and compare** - Run 2-3 extractors, compare row counts and spot-check values
+2. **Sanity checks** - Verify nulls, empty values, column alignment after extraction
+3. **Hybrid approach** - Programmatic for bulk structured data, LLM for edge cases and verification

package/skills/powerpoint-creation/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: powerpoint-creation
+description: Use when creating pptx presentations
+---
+
+# PowerPoint Creation - Common Errors & Fixes
+
+## CRITICAL: Build Incrementally
+
+**DO NOT** write a single massive script that creates the entire presentation. If it fails on slide 15, you lose everything.
+
+**Instead, build iteratively:**
+
+```python
+# Step 1: Create presentation with title slide, save it
+from pptx import Presentation
+prs = Presentation()
+slide = prs.slides.add_slide(prs.slide_layouts[0])
+slide.shapes.title.text = "Q1 Report"
+prs.save("/workspace/presentation.pptx")
+```
+
+```python
+# Step 2: Load and add next slide
+prs = Presentation("/workspace/presentation.pptx")
+slide = prs.slides.add_slide(prs.slide_layouts[1])
+slide.shapes.title.text = "Executive Summary"
+# ... add content ...
+prs.save("/workspace/presentation.pptx")
+```
+
+```python
+# Step 3: Load and add another slide
+prs = Presentation("/workspace/presentation.pptx")
+slide = prs.slides.add_slide(prs.slide_layouts[1])
+slide.shapes.title.text = "Financial Overview"
+# ... add content ...
+prs.save("/workspace/presentation.pptx")
+```
+
+**Benefits:**
+- If slide 3 fails, slides 1-2 are already saved
+- Easier to debug which slide caused the error
+- Can verify each slide looks correct before continuing
+
+---
+
+## Error: RgbColor format issues
+
+**Wrong:**
+```python
+from pptx.dml.color import RgbColor
+color = RgbColor(26, 115, 232)  # Integers don't work
+color = RgbColor("#1A73E8")     # Strings don't work
+```
+
+**Correct:**
+```python
+from pptx.dml.color import RgbColor
+color = RgbColor(0x1A, 0x73, 0xE8)  # Must use hex literals
+
+# Or convert from RGB integers:
+r, g, b = 26, 115, 232
+color = RgbColor(r, g, b)  # This works if values are 0-255 integers
+```
+
+**Also correct - use theme colors instead:**
+```python
+from pptx.enum.dml import MSO_THEME_COLOR
+shape.fill.solid()
+shape.fill.fore_color.theme_color = MSO_THEME_COLOR.ACCENT_1
+```
+
+---
+
+## Error: OSError [Errno 22] Invalid argument on save
+
+```
+OSError: [Errno 22] Invalid argument
+```
+
+**Causes:**
+1. Invalid file path (special characters, missing directory)
+2. Writing to read-only location
+3. Path doesn't exist
+
+**Fix:**
+```python
+import os
+
+# Always use /workspace/ and ensure directory exists
+output_path = "/workspace/outputs/presentation.pptx"
+os.makedirs(os.path.dirname(output_path), exist_ok=True)
+prs.save(output_path)
+```
+
+**Never do:**
+```python
+prs.save("presentation.pptx")  # Relative path - may fail
+prs.save("/tmp/presentation.pptx")  # /tmp may have issues
+```
+
+---
+
+## Output Location
+
+Always save to `/workspace/`:
+```python
+prs.save("/workspace/my_presentation.pptx")
+```

package/skills/sec-edgar/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: sec-edgar
+description: Research and download SEC EDGAR filings (10-K, 10-Q, 8-K, etc.) for US public companies.
+---
+
+# SEC EDGAR Filing Research
+
+**Why PDF instead of XBRL?** SEC filings contain inline XBRL (HTML with embedded XML tags) which creates noise for LLMs. Additionally, ~34% of filings have XBRL tagging errors, companies use non-standard tags, and narrative content (MD&A, Risk Factors) isn't captured in XBRL. PDF + file_perception reads what humans see.
+
+**Rate limit:** 10 requests/second. All requests require header: `User-Agent: ShortcutAgent/1.0 (support@shortcut.ai)`
+
+## Workflow Overview
+
+1. **Find company** → Get CIK from ticker/name
+2. **Fetch metadata** → Get filing list with dates from SEC API
+3. **VERIFY "LATEST"** → Sort by date, confirm against today's date (CRITICAL!)
+4. **Convert to PDF** → Use `sec_to_pdf.py` script (Playwright + Chrome)
+5. **Analyze** → Use `file_perception` on the PDF
+
+---
+
+## API Reference
+
+All requests require header: `User-Agent: ShortcutAgent/1.0 (support@shortcut.ai)`
+
+| Endpoint | URL |
+|----------|-----|
+| Company tickers | `https://www.sec.gov/files/company_tickers.json` |
+| Filings metadata | `https://data.sec.gov/submissions/CIK{cik_10digit}.json` |
+| Download filing | `https://www.sec.gov/Archives/edgar/data/{cik}/{accession_no_dashes}/{primaryDocument}` |
+
+Rate limit: 10 requests/second
+
+## Step 1: Find Company CIK
+
+Fetch company tickers JSON and search for the ticker:
+
+```
+GET https://www.sec.gov/files/company_tickers.json
+```
+
+Returns: `{"0": {"cik_str": 320193, "ticker": "AAPL", "title": "Apple Inc."}, ...}`
+
+Zero-pad CIK to 10 digits for the next step (e.g., `320193` → `0000320193`).
+
+---
+
+## Step 2: Fetch Filing Metadata
+
+```
+GET https://data.sec.gov/submissions/CIK{cik_10digit}.json
+```
+
+Response contains `filings.recent` with parallel arrays: `form`, `filingDate`, `reportDate`, `accessionNumber`, `primaryDocument`. Index `i` across all arrays gives one filing's info.
+
+---
+
+## Step 3: VERIFY "Latest" Filing (CRITICAL)
+
+**NEVER assume the first result is the latest.** The API doesn't guarantee sort order.
+
+### Verification Protocol
+
+1. **Check today's date** from the system prompt (e.g., "Today's date: 2026-01-06")
+
+2. **Collect ALL filings** of the requested type from the parallel arrays
+
+3. **Sort by `filingDate` descending** to find the truly latest
+
+4. **Sanity check against expected filing schedule:**
+
+   | Filing | Expected Timing |
+   |--------|-----------------|
+   | 10-K | 60-90 days after fiscal year end |
+   | 10-Q | 40-45 days after quarter end |
+   | 8-K | Within 4 business days of event |
+   | DEF 14A | ~120 days before annual meeting |
+
+5. **Report exact dates to user:**
+   > "Found Tesla's latest 10-K filed on 2026-01-29 for fiscal year ending 2025-12-31. Is this the one you need?"
+
+### Red Flags
+
+- If today is January 2026 but the "latest" 10-K shows FY2024 → something's wrong
+- If `reportDate` is more than a year old → re-verify or warn user
+- Multiple filings same day → check for amendments (10-K/A vs 10-K)
+
+---
+
+## Step 4: Convert to PDF
+
+Build URL from metadata:
+
+```
+https://www.sec.gov/Archives/edgar/data/{cik}/{accession_no_dashes}/{primaryDocument}
+```
+
+- Remove dashes from `accessionNumber` for URL path
+- Use unpadded CIK (no leading zeros)
+
+Example:
+- CIK: `320193`
+- Accession: `0000320193-25-000123` → `000032019325000123`
+- Document: `aapl-20250928.htm`
+- URL: `https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.htm`
+
+Use the `sec_to_pdf.py` script to convert directly from URL (renders images properly):
+
+```bash
+python /skills/default/sec-edgar/sec_to_pdf.py "<filing_url>" "/workspace/sec/{TICKER}/{form}_{report_date}.pdf"
+```
+
+**File path convention:** Always save SEC filings to `/workspace/sec/{TICKER}/{form}_{report_date}.pdf`
+- Example: `/workspace/sec/AAPL/10-K_2024-09-28.pdf`
+- Example: `/workspace/sec/TSLA/10-Q_2024-06-30.pdf`
+- This keeps filings organized by company and makes them easy to find later
+
+**Why Chrome?** Two reasons: (1) SEC.gov blocks headless Chromium with 403 errors - real Chrome bypasses this. (2) Downloading HTML locally breaks relative image paths; Chrome navigating directly to the URL keeps images loading from SEC's servers.
+
+**Fallback:** If the script fails, you can use httpx to download locally and `weasyprint` amongst other tools and packages to convert the html to PDF. 
+If you download HTML first and use `filename=`, relative image paths may break and images may not get rendered. You will have to check and fix this.
+
+---
+
+## Step 5: Analyze with file_perception
+
+Use `file_perception` on the PDF to extract information.