git:20260830.734c287 to git:20260905.107dc5a

20 added, 1 removed. Audit A to A.

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Purpose

This repository contains Claude Skills for equity investors and traders. Each skill packages domain-specific prompts, knowledge bases, and helper scripts to assist with market analysis, technical charting, economic calendar monitoring, and trading strategy development. Skills are designed to work in both Claude's web app and Claude Code environments.

⚠️ **Important:** Some skills require paid API subscriptions (FMP API and/or FINVIZ Elite) to function. See the [API Key Management](#api-key-management) section for detailed requirements by skill.

## Repository Architecture

### Skill Structure

Each skill follows a standardized directory structure:

```

<skill-name>/

├── SKILL.md # Required: Skill definition with YAML frontmatter

├── references/ # Knowledge bases loaded into Claude's context

├── scripts/ # Executable Python scripts (not auto-loaded)

└── assets/ # Templates and resources for output generation

```

**SKILL.md Format:**

- YAML frontmatter with `name` and `description` fields

- `name` must match the directory name for proper skill detection

- Description defines when the skill should be triggered

- Body contains workflow instructions written in imperative/infinitive form

- All instructions assume Claude will execute them, not the user

**Progressive Loading:**

1. Metadata (YAML frontmatter) loads first for skill detection

2. SKILL.md body loads when skill is invoked

3. References load conditionally based on analysis needs

4. Scripts execute on demand, never auto-loaded into context

### Key Design Patterns

**Knowledge Base Organization:**

- `references/` contains markdown files with domain knowledge (sector rotation patterns, technical analysis frameworks, news source credibility guides)

- Knowledge bases provide context without requiring Claude to have specialized training

- References are read selectively during skill execution to minimize token usage

**Script vs. Reference Division:**

- Scripts (`scripts/`) are executable code for API calls, data fetching, report generation

- References (`references/`) are documentation for Claude to read and apply

- Scripts handle I/O; references handle knowledge

**Output Generation:**

- Skills generate reports (markdown + JSON) saved to `reports/` directory

- Filename convention: `<skill>_<analysis-type>_<date>.md` (and `.json`)

- Reports use structured templates from `assets/` directories

- Scripts should default `--output-dir` to `reports/` (or pass `--output-dir reports/` when invoking)

## Common Development Tasks

### Creating a New Skill

Use the skill-creator plugin (available in Claude Code):

```bash

# This invokes the skill-creator to guide you through setup

# Follow the 6-step process: Understanding → Planning → Initializing → Editing → Packaging → Iterating

```

The skill-creator will:

1. Ask clarification questions about the skill's purpose

2. Create the directory structure

3. Generate SKILL.md template

4. Set up references and scripts directories

5. Package the skill into a .skill file

**MANDATORY: After creating or committing a new skill, complete ALL of the following:**

1. **Generate documentation pages** (auto-gen handles EN page + JA stub + index updates):

```bash

python3 scripts/generate_skill_docs.py --skill <skill-name>

```

2. **Add to catalog category sections** in `docs/en/skill-catalog.md` and `docs/ja/skill-catalog.md`

3. **Add to API Requirements Matrix** in both catalog files

4. **Add to README** descriptions in `README.md` (English) and `README.ja.md` (Japanese)

5. If the skill requires API keys, add to the API Requirements table in `README.md` and the API要件 section in `README.ja.md`

6. If a new category is needed, create it in both READMEs and both catalogs

> **Pre-commit enforcement:** The `docs-completeness` hook blocks commits if any `skills/*/SKILL.md` exists without corresponding `docs/en/skills/<name>.md` and `docs/ja/skills/<name>.md`. Run the generate command above to fix.

### Creating Documentation Site Pages

Generate documentation pages for the Jekyll site at `docs/`.

**Auto-generation (recommended for most skills):**

```bash

# Generate 6-section EN page + JA stub for a specific skill

# Also updates docs/en/skills/index.md and docs/ja/skills/index.md automatically

python3 scripts/generate_skill_docs.py --skill <skill-name>

# Regenerate all auto-generated pages (ONLY pages marked `generated: true`;

# hand-maintained pages are refused — use --force to override, never in CI)

python3 scripts/generate_skill_docs.py --overwrite

```

> **Skill doc ownership / drift gate:** Committed `docs/{en,ja}/skills/*.md` are

> source-of-truth. A page is generator-owned only if its frontmatter has

> `generated: true`; `generated: false` or an absent marker (and any

> `HAND_WRITTEN` skill) is hand-maintained and **protected** — `--overwrite`

> refuses it (`--force` is the CI-forbidden escape hatch). The

> `skill-docs-drift` pre-commit hook + CI step run `generate_skill_docs.py

> --check`, which content-compares **only** `generated: true` pages and never

> reverts hand-maintained docs. See `docs/README.md` → "Skill Doc Ownership".

**Hand-written ★ guides (for key skills):**

For skills that need detailed documentation with examples, troubleshooting, and CLI reference, create a 10-section guide manually. See `docs/README.md` for the full template and conventions.

Required sections for ★ guides:

1. Overview 2. Prerequisites 3. Quick Start 4. How It Works

5. Usage Examples 6. Understanding the Output 7. Tips & Best Practices

8. Combining with Other Skills 9. Troubleshooting 10. Reference

**What auto-generation handles vs. what requires manual work:**

| Task | Auto-gen | Manual |

|------|----------|--------|

| EN doc page (`docs/en/skills/<name>.md`) | ✅ | -- |

| JA doc stub (`docs/ja/skills/<name>.md`) | ✅ | -- |

| Index table (`docs/{en,ja}/skills/index.md`) | ✅ | -- |

| Catalog category section (`docs/{en,ja}/skill-catalog.md`) | -- | ✅ |

| Catalog API Requirements Matrix | -- | ✅ |

| README.md / README.ja.md | -- | ✅ |

See `docs/README.md` for frontmatter format, badge syntax, and complete checklist.

### Packaging Skills for Distribution

Skills are packaged as ZIP files for Claude web app users:

```bash

# Use the skill-creator's packaging script

python3 ~/.claude/plugins/marketplaces/anthropic-agent-skills/skills/skill-creator/scripts/package_skill.py <skill-name>

```

The packaged .skill files are stored in `skill-packages/` and should be regenerated after any skill modifications.

### Testing Skills

Skills are tested by invoking them in Claude Code conversations:

1. Copy skill folder to Claude Code Skills directory

2. Restart Claude Code to detect the skill

3. Trigger the skill by providing input that matches the skill's description

4. Verify that:

- Skill loads correctly (check YAML frontmatter)

- References load when needed

- Scripts execute with proper error handling

- Output matches expected format

### Code Generation (TDD)

When generating or modifying code in this repository, use a TDD-first workflow:

1. Write or update tests first (expected to fail initially).

2. Implement the minimal code change needed to pass tests.

3. Refactor while keeping tests green.

4. Run the relevant test suite before finishing.

If no test exists for the changed behavior, add one whenever practical.

### Production Verification Metadata

`status: production` is a lifecycle/catalog label, not proof of trading correctness. Production

skills must also carry the eight-axis `verification` block in `skills-index.yaml`. Use

[`docs/dev/production-verification.md`](docs/dev/production-verification.md) for the pass/NA

criteria, audit baseline, live high-severity issue gate, and the rule for resetting stale evidence

to `not_verified`.

### Pre-commit Hooks

> **Maintainer operations:** for the full regenerate / drift-gate / scheduled-job runbook (what to run after editing the SSoT, how to clear a failing gate, what the `launchd` agents do), see [`docs/dev/maintenance-runbook.md`](docs/dev/maintenance-runbook.md).

This repository uses [pre-commit](https://pre-commit.com/) for automated quality checks. Install after cloning:

```bash

pre-commit install && pre-commit install --hook-type pre-push

```

**Pre-commit hooks (run on every commit):**

| Hook | Source | What it checks |

|------|--------|----------------|

| trailing-whitespace | pre-commit-hooks | Trailing whitespace |

| end-of-file-fixer | pre-commit-hooks | Missing newline at end of file |

| check-yaml | pre-commit-hooks | YAML syntax |

| check-toml | pre-commit-hooks | TOML syntax |

| check-merge-conflict | pre-commit-hooks | Leftover conflict markers |

| check-added-large-files | pre-commit-hooks | Files exceeding 500KB |

| ruff | ruff-pre-commit | Python lint + auto-fix |

| ruff-format | ruff-pre-commit | Python formatting |

| codespell | codespell | Typo detection |

| detect-secrets | detect-secrets | Secret/credential leaks |

| no-absolute-paths | local | `/Users/username/` path leaks in public repo |

| skill-frontmatter | local | SKILL.md `name` matches directory, `description` exists |

| docs-completeness | local | Every `skills/*/SKILL.md` has EN + JA doc pages |

**Pre-push hook:**

| Hook | What it checks |

|------|----------------|

| pytest-pre-push | Runs all skill-level tests via `scripts/run_all_tests.sh` |

**Suppressing false positives:**

- `no-absolute-paths`: Add `# noqa: absolute-path` inline comment, or the hook auto-skips regex definitions and test files

- Config: `.pre-commit-config.yaml`

- Local hook scripts: `scripts/hooks/`

### API Key Management

⚠️ **IMPORTANT:** Several skills require paid API subscriptions to function. Review the requirements below before using these skills.

#### API Requirements by Skill

The table below is **auto-generated** from `skills-index.yaml` by `scripts/generate_catalog_from_index.py`. To update a row, edit the skill's `integrations[]` in the index and re-run the generator. The 3-column shape (FMP / FINVIZ / Alpaca) is preserved so existing setup instructions still apply; non-paid integrations (CSV, image, WebSearch, MCP, calculation-only, etc.) surface in the Notes column.

|-------|---------|--------------|--------|-------|

| **Crypto Regime Analyzer** | ❌ Not used | ❌ Not used | ❌ Not used | Free public API, no key; universe, price history, BTC dominance; Public futures endpoint for perp funding; component skipped if unreachable; Offline snapshot path (--input-json); schema in references |

| **MT5 Robot Tester** | ❌ Not used | ❌ Not used | ❌ Not used | Local Windows MT5 terminal, EA and set files, and broker tick data; no API key; Offline report parsing, gates, metrics, checkpoints, and learning aggregation |

| **Trading Skills Navigator** | ❌ Not used | ❌ Not used | ❌ Not used | Reads local skills-index.yaml + workflows/*.yaml (or bundled snapshot); no network |

| **US Undervalued Growth Screener** | 🟡 Optional (Recommended) | ❌ Not used | ❌ Not used | Claude Code-native direct REST path using FMP_API_KEY. Bulk responses are cached and written to local artifacts; only compact screening results are returned to the model. Plan-gated bulk endpoints use bounded per-symbol fallbacks. |

> Note: a skill listed as `❌ Not used` for FMP / FINVIZ / Alpaca may still need WebSearch, public CSVs, chart screenshots, or other non-paid inputs. See each skill's full `integrations[]` entry in `skills-index.yaml` for the complete picture.

#### API Key Setup

**Financial Modeling Prep (FMP) API:**

```bash

# Set environment variable (preferred method)

export FMP_API_KEY=your_key_here

# Or provide via command-line argument when script runs

python3 scripts/get_economic_calendar.py --api-key YOUR_KEY

```

**FINVIZ Elite API:**

```bash

# Set environment variable

export FINVIZ_API_KEY=your_key_here

# Or provide via command-line argument

python3 value-dividend-screener/scripts/screen_dividend_stocks.py \

--use-finviz \

--finviz-api-key YOUR_KEY

```

**Alpaca Trading API:**

```bash

# Set environment variables

export ALPACA_API_KEY="your_api_key_id"

export ALPACA_SECRET_KEY="your_secret_key"

export ALPACA_PAPER="true" # or "false" for live trading

# Configure Alpaca MCP Server in Claude Code settings

# See portfolio-manager/references/alpaca-mcp-setup.md for detailed setup guide

```

#### API Pricing and Access

**Financial Modeling Prep (FMP):**

- **Free Tier:** 250 API calls/day (sufficient for occasional use)

- **Starter Tier:** $29.99/month - 750 calls/day

- **Professional Tier:** $79.99/month - 2,000 calls/day

- **Sign up:** https://site.financialmodelingprep.com/developer/docs

**FINVIZ Elite:**

- **Elite Subscription:** $39.50/month or $299.50/year (~$24.96/month)

- Provides advanced screeners, real-time data, and API access

- **Sign up:** https://elite.finviz.com/

- **Note:** FINVIZ Elite is optional for dividend screeners but reduces execution time from 10-15 minutes to 2-3 minutes

**Alpaca Trading:**

- **Paper Trading:** Free (simulated money, full API access)

- **Live Trading:** Free brokerage account, no commissions on stocks/ETFs

- **Sign up:** https://alpaca.markets/

- **Required for:** Portfolio Manager skill

- **Note:** Paper trading account recommended for testing MCP integration

**Recommendations by Use Case:**

- **Dividend Screening:** FMP free tier + FINVIZ Elite ($330/year) for optimal performance

- **Budget Dividend Screening:** FMP free tier only (slower execution)

- **Portfolio Management:** Alpaca paper account (free) for practice, live account for production

- **Options Education:** FMP free tier sufficient; Options Strategy Advisor works with theoretical pricing alone

#### API Script Pattern

All API scripts follow this pattern:

1. Check for environment variable first

2. Fall back to command-line argument

3. Provide clear error messages if key missing

4. Support both methods for CLI, Desktop, and Web environments

5. Handle rate limits gracefully with retry logic

### Running Helper Scripts

**Economic Calendar Fetcher:** ⚠️ Requires FMP API key

```bash

# Default: next 7 days

python3 economic-calendar-fetcher/scripts/get_economic_calendar.py --api-key YOUR_KEY

# Specific date range (max 90 days)

python3 economic-calendar-fetcher/scripts/get_economic_calendar.py \

--from 2025-11-01 --to 2025-11-30 \

--api-key YOUR_KEY \

--format json

```

**Earnings Calendar:** ⚠️ Requires FMP API key

```bash

# Default: next 7 days, market cap > $2B

python3 earnings-calendar/scripts/fetch_earnings_fmp.py --api-key YOUR_KEY

# Custom date range

python3 earnings-calendar/scripts/fetch_earnings_fmp.py \

--from 2025-11-01 --to 2025-11-07 \

--api-key YOUR_KEY

```

**Value Dividend Screener:** ⚠️ Requires FMP API key; FINVIZ Elite optional but recommended

```bash

# Two-stage screening (RECOMMENDED - 70-80% faster)

python3 value-dividend-screener/scripts/screen_dividend_stocks.py --use-finviz

# FMP-only screening (no FINVIZ required)

python3 value-dividend-screener/scripts/screen_dividend_stocks.py

# Custom parameters

python3 value-dividend-screener/scripts/screen_dividend_stocks.py \

--use-finviz \

--top 50 \

--output custom_results.json

```

**Dividend Growth Pullback Screener:** ⚠️ Requires FMP API key; FINVIZ Elite optional but recommended

```bash

# Two-stage screening with RSI filter (RECOMMENDED)

python3 dividend-growth-pullback-screener/scripts/screen_dividend_growth_rsi.py --use-finviz

# FMP-only screening (limited to ~40 stocks due to API limits)

python3 dividend-growth-pullback-screener/scripts/screen_dividend_growth_rsi.py --max-candidates 40

# Custom RSI threshold and dividend growth requirements

python3 dividend-growth-pullback-screener/scripts/screen_dividend_growth_rsi.py \

--use-finviz \

--rsi-threshold 35 \

--min-div-growth 15

```

**Pair Trade Screener:** ⚠️ Requires FMP API key

```bash

# Screen for pairs in specific sector

python3 pair-trade-screener/scripts/find_pairs.py --sector Technology

# Analyze specific pair

python3 pair-trade-screener/scripts/analyze_spread.py AAPL MSFT

# Custom cointegration parameters

python3 pair-trade-screener/scripts/find_pairs.py \

--sector Financials \

--min-correlation 0.7 \

--lookback-days 365

```

**Earnings Trade Analyzer:** ⚠️ Requires FMP API key

```bash

# Default: 2-day lookback, top 20 results

python3 skills/earnings-trade-analyzer/scripts/analyze_earnings_trades.py \

--output-dir reports/

# Custom parameters with entry quality filter

python3 skills/earnings-trade-analyzer/scripts/analyze_earnings_trades.py \

--lookback-days 3 --top 10 --max-api-calls 200 \

--apply-entry-filter --output-dir reports/

```

**PEAD Screener:** ⚠️ Requires FMP API key

```bash

# Mode A: FMP earnings calendar (standalone)

python3 skills/pead-screener/scripts/screen_pead.py \

--lookback-days 14 --min-gap 3.0 --max-api-calls 200 \

--output-dir reports/

# Mode B: Pipeline from earnings-trade-analyzer output

python3 skills/pead-screener/scripts/screen_pead.py \

--candidates-json reports/earnings_trade_*.json \

--min-grade B --output-dir reports/

```

**Options Strategy Advisor:** 🟡 FMP API optional

```bash

# Calculate Black-Scholes price and Greeks

python3 options-strategy-advisor/scripts/black_scholes.py \

--ticker AAPL \

--strike 150 \

--days-to-expiry 30 \

--option-type call

# Analyze covered call strategy

python3 options-strategy-advisor/scripts/black_scholes.py \

--ticker AAPL \

--strategy covered_call \

--stock-price 155

```

**Theme Detector:** 🟡 FINVIZ Elite optional; FMP optional

```bash

# Static mode (no API keys required)

python3 skills/theme-detector/scripts/theme_detector.py --output-dir reports/

# Dynamic stock selection (uses FINVIZ Public screener, no key needed)

python3 skills/theme-detector/scripts/theme_detector.py \

--dynamic-stocks --output-dir reports/

# With FINVIZ Elite (faster, more reliable)

python3 skills/theme-detector/scripts/theme_detector.py \

--dynamic-stocks --finviz-api-key $FINVIZ_API_KEY --output-dir reports/

```

**Portfolio Manager:** ⚠️ Requires Alpaca MCP Server

```bash

# Test Alpaca connection

python3 skills/portfolio-manager/scripts/check_alpaca_connection.py

# Portfolio analysis is done via Claude with Alpaca MCP tools

# See portfolio-manager/references/alpaca-mcp-setup.md for setup

```

**Position Sizer:** No API key required

```bash

# Basic: stop-loss based sizing

python3 skills/position-sizer/scripts/position_sizer.py \

--entry 155.00 --stop 148.50 \

--account-size 100000 --risk-pct 1.0

# ATR-based sizing

python3 skills/position-sizer/scripts/position_sizer.py \

--entry 155.00 --atr 3.20 --atr-multiplier 2.0 \

--account-size 100000 --risk-pct 1.0

# Kelly Criterion (budget mode: no --entry)

python3 skills/position-sizer/scripts/position_sizer.py \

--win-rate 0.55 --avg-win 2.5 --avg-loss 1.0 \

--account-size 100000

# With portfolio constraints

python3 skills/position-sizer/scripts/position_sizer.py \

--entry 155.00 --stop 148.50 \

--account-size 100000 --risk-pct 1.0 \

--max-position-pct 10 --max-sector-pct 30 \

--sector Technology --current-sector-exposure 22

```

**Data Quality Checker:** No API key required

```bash

# Check a markdown file

python3 skills/data-quality-checker/scripts/check_data_quality.py \

--file reports/weekly_strategy.md

# Run specific checks only

python3 skills/data-quality-checker/scripts/check_data_quality.py \

--file report.md --checks price_scale,dates,allocations

# With reference date for year inference

python3 skills/data-quality-checker/scripts/check_data_quality.py \

--file report.md --as-of 2026-02-28 --output-dir reports/

```

**Edge Strategy Reviewer:** No API key required

```bash

# Review all drafts in a directory

python3 skills/edge-strategy-reviewer/scripts/review_strategy_drafts.py \

--drafts-dir reports/edge_strategy_drafts/ \

--output-dir reports/

# Single draft review with JSON output and markdown summary

python3 skills/edge-strategy-reviewer/scripts/review_strategy_drafts.py \

--draft reports/edge_strategy_drafts/draft_xxx.yaml \

--output-dir reports/ --format json --markdown-summary

```

**Edge Pipeline Orchestrator:** No API key required

```bash

# Full pipeline from tickets

python3 skills/edge-pipeline-orchestrator/scripts/orchestrate_edge_pipeline.py \

--tickets-dir /path/to/tickets/ \

--market-summary /path/to/market_summary.json \

--anomalies /path/to/anomalies.json \

--output-dir reports/edge_pipeline/

# Review-only mode with existing drafts

python3 skills/edge-pipeline-orchestrator/scripts/orchestrate_edge_pipeline.py \

--review-only \

--drafts-dir reports/edge_strategy_drafts/ \

--output-dir reports/edge_pipeline/

# Dry-run (no export)

python3 skills/edge-pipeline-orchestrator/scripts/orchestrate_edge_pipeline.py \

--tickets-dir /path/to/tickets/ \

--output-dir reports/edge_pipeline/ --dry-run

```

**Trader Memory Core:** 🟡 FMP API optional (for MAE/MFE only)

```bash

# Register screener output as thesis

python3 skills/trader-memory-core/scripts/trader_memory_cli.py ingest \

--source kanchi-dividend-sop \

--input reports/kanchi_entry_signals_2026-03-14.json \

--state-dir state/theses/

# Manual brokerage entry (fractional shares; free-form JSON, single or array)

python3 skills/trader-memory-core/scripts/trader_memory_cli.py ingest \

--source manual --input amd.json --state-dir state/theses/

# Walk an existing broker position to ACTIVE (backdated, fractional shares)