From fatfingererr-macro-skills
Track cumulative return of stocks/indices with multi-ticker comparison, index Top N ranking, and visualization. All comparisons use S&P 500 as the fixed benchmark.
npx claudepluginhub joshuarweaver/cascade-code-general-misc-1 --plugin fatfingererr-macro-skillsThis skill uses the workspace's default tool permissions.
<essential_principles>
examples/sample_output.jsonmanifest.jsonreferences/data-sources.mdreferences/index-components.mdreferences/input-schema.mdreferences/methodology.mdscripts/cumulative_return_analyzer.pyscripts/fetch_price_data.pyscripts/index_component_analyzer.pyscripts/tests/golden_cases.jsonscripts/tests/test_calculations.pyscripts/validators.pyscripts/visualize_cumulative.pyskill.yamltemplates/output-json.mdtemplates/output-markdown.mdworkflows/compare.mdworkflows/quick-check.mdworkflows/top-n.mdCreates new Angular apps using Angular CLI with flags for routing, SSR, SCSS, prefixes, and AI config. Follows best practices for modern TypeScript/Angular development. Use when starting Angular projects.
Generates Angular code and provides architectural guidance for projects, components, services, reactivity with signals, forms, dependency injection, routing, SSR, ARIA accessibility, animations, Tailwind styling, testing, and CLI tooling.
Executes ctx7 CLI to fetch up-to-date library documentation, manage AI coding skills (install/search/generate/remove/suggest), and configure Context7 MCP. Useful for current API refs, skill handling, or agent setup.
<essential_principles>
**S&P 500 Fixed Benchmark (Core Methodology)**All cumulative return analyses use S&P 500 (^GSPC) as the fixed benchmark. This is a core methodology decision:
This is hardcoded and cannot be changed.
**Base Date Methodology**For cumulative return calculation, the base date is the last trading day of the previous year:
Cumulative Return = ((Final Price / Base Price) - 1) × 100%
Key methodology:
All tickers are aligned to common trading days with data.
**Four Analysis Scenarios**This skill supports 4 distinct scenarios:
| Scenario | Mode | Description | Example |
|---|---|---|---|
| 1.a | Stock(s), Year Only | Analyze specific tickers for a single full year | NVDA, AMD in 2024 only |
| 1.b | Stock(s), Year to Today | Analyze specific tickers from a year to today | NVDA, AMD from 2022 to today |
| 2.a | Index Top N, Year Only | Rank index components for a single full year | Nasdaq 100 Top N in 2024 only |
| 2.b | Index Top N, Year to Today | Rank index components from a year to today | Nasdaq 100 Top N from 2022 to today |
Use --year-only flag to switch between "Year Only" (a) and "Year to Today" (b) modes.
| Index Code | Name | Components |
|---|---|---|
| nasdaq100 | Nasdaq 100 Index | ~100 |
| sp100 | S&P 100 Index | 100 |
| dow30 | Dow Jones 30 Index | 30 |
| sox | Philadelphia Semiconductor Index | 30 |
Top N analysis fetches all component stocks and ranks by return.
</essential_principles>
Track cumulative return performance of stocks and indices:Output: Cumulative return time series chart, performance ranking table, JSON data, Markdown report.
<quick_start>
Quick Start: Analyze Stock Cumulative Returns
cd skills/track-equity-cumulative-return/scripts
pip install pandas numpy yfinance matplotlib # First time only
# Scenario 1.a: Stock(s), 2024 Year Only
python cumulative_return_analyzer.py --ticker NVDA AMD --year 2024 --year-only
# Scenario 1.b: Stock(s), 2022 to Today
python cumulative_return_analyzer.py --ticker NVDA AMD GOOGL --year 2022
# Scenario 2.a: Nasdaq 100 Top 10, 2024 Year Only
python index_component_analyzer.py --index nasdaq100 --year 2024 --year-only --top 10
# Scenario 2.b: Nasdaq 100 Top 20, 2022 to Today
python index_component_analyzer.py --index nasdaq100 --year 2022 --top 20
# Visualization (with charts)
python visualize_cumulative.py --ticker NVDA AMD --year 2024 --year-only
python visualize_cumulative.py --mode top20 --index nasdaq100 --year 2022 --top 20
Sample output:
{
"skill": "track-equity-cumulative-return",
"as_of": "2026-01-28",
"mode": "year_to_today",
"parameters": {
"tickers": ["NVDA", "AMD"],
"start_year": 2022,
"year_only": false
},
"benchmark": {
"ticker": "^GSPC",
"name": "S&P 500",
"cumulative_return_pct": 45.2
},
"summary": {
"best_performer": "NVDA",
"best_return": 542.2,
"beat_benchmark_count": 2
}
}
</quick_start>
What analysis do you need?Scenario Selection:
Provide your analysis parameters or select a scenario.
| User Input | Scenario | Command | |------------------------------------|----------|-----------------------------------------------------------------------------------------| | "NVDA 2024 full year", "2024 only" | **1.a** | `python cumulative_return_analyzer.py --ticker NVDA --year 2024 --year-only` | | "NVDA from 2022", "since 2022" | **1.b** | `python cumulative_return_analyzer.py --ticker NVDA --year 2022` | | "Nasdaq 100 top 10 2024 only" | **2.a** | `python index_component_analyzer.py --index nasdaq100 --year 2024 --year-only --top 10` | | "Nasdaq 100 top 20 since 2022" | **2.b** | `python index_component_analyzer.py --index nasdaq100 --year 2022 --top 20` | | "chart", "visualization" | Add | `python visualize_cumulative.py` with same parameters | | "methodology", "how" | Info | Read `references/methodology.md` |Key flags:
--year-only: Analyze only the specified year (scenarios a)--year-only: Analyze from year to today (scenarios b)--top N: Select Top N for index analysisAll scripts use Yahoo Finance real data with caching. Benchmark is always S&P 500.
<reference_index>
Reference Documents (references/)
| File | Content |
|---|---|
| methodology.md | Cumulative return calculation methodology |
| data-sources.md | Yahoo Finance data source documentation |
| input-schema.md | Complete input parameter definitions |
| index-components.md | Supported index component lists |
| </reference_index> |
<workflows_index>
| Workflow | Scenario | Use Case |
|---|---|---|
| quick-check.md | 1.a/1.b | Quick check single ticker |
| compare.md | 1.a/1.b | Compare multiple tickers |
| top20.md | 2.a/2.b | Index Top N analysis |
| </workflows_index> |
<templates_index>
| Template | Purpose |
|---|---|
| output-json.md | JSON output structure definition |
| output-markdown.md | Markdown report template |
| </templates_index> |
<scripts_index>
| Script | Command Example | Purpose |
|---|---|---|
| fetch_price_data.py | --ticker NVDA --start 2022-01-01 | Yahoo Finance data fetching |
| cumulative_return_analyzer.py | --ticker NVDA AMD --year 2022 | Cumulative return calculation (1.a/1.b) |
| index_component_analyzer.py | --index nasdaq100 --year 2022 | Index component analysis (2.a/2.b) |
| visualize_cumulative.py | --ticker NVDA AMD --year 2022 | visualization |
| </scripts_index> |
<input_schema_summary>
Required Parameters
| Parameter | Type | Description |
|---|---|---|
| ticker | string | Stock ticker(s) - can be multiple |
| year | int | Start year |
Optional Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| year-only | flag | false | If set, analyze only the specified year |
| index | string | nasdaq100 | Index type (for Top N mode) |
| top | int | 20 | Top N to select |
| output | string | auto | Output file path |
| mode | string | compare | Mode (compare/top20) |
Note: Benchmark is hardcoded to S&P 500 (^GSPC) and cannot be changed.
See references/input-schema.md for complete parameter definitions.
</input_schema_summary>
Chart Specifications
Charts follow thoughts/shared/guide/bloomberg-style-chart-guide.md:
#1a1a2e (dark blue-black)#2d2d44 (dark gray-purple)#ff6b35 (orange-red), #ffaa00 (orange-yellow)#004E89 (deep blue dashed)#666666 (gray dotted)X-axis format:
Output specs:
<output_schema_summary>
{
"skill": "track-equity-cumulative-return",
"as_of": "2026-01-28",
"mode": "year_to_today",
"parameters": {
"tickers": ["NVDA", "AMD"],
"start_year": 2022,
"year_only": false
},
"period": {
"start_date": "2021-12-31",
"end_date": "2026-01-28",
"years_held": 4.08
},
"benchmark": {
"ticker": "^GSPC",
"name": "S&P 500",
"cumulative_return_pct": 45.2
},
"summary": {
"best_performer": "NVDA",
"best_return": 542.2,
"benchmark_return": 45.2,
"beat_benchmark_count": 2
},
"results": [
{
"ticker": "NVDA",
"name": "NVIDIA (NVDA)",
"cumulative_return_pct": 542.2,
"vs_benchmark": 497.0
}
],
"chart_path": "output/cumulative_return_2026-01-28.png"
}
See templates/output-json.md for complete output structure.
</output_schema_summary>
<success_criteria> Successful execution should produce:
Chart X-axis: Year shown in January, month numbers (2-12) for other months. </success_criteria>
<extended_examples>
Example 1: Single Stock Full Year Analysis (Scenario 1.a)
Analyze NVIDIA's performance in 2024:
cd skills/track-equity-cumulative-return/scripts
python cumulative_return_analyzer.py --ticker NVDA --year 2024 --year-only
Expected output:
==========================================================================================
Cumulative Return Analysis Report
==========================================================================================
Period: 2024 Full Year (2023-12-29 ~ 2024-12-31)
Benchmark: S&P 500
==========================================================================================
Rank Ticker Name Cum. Return vs Bench
----------------------------------------------------------------------
1 NVDA NVIDIA (NVDA) +185.52% +160.97% ✓
----------------------------------------------------------------------
Bench ^GSPC S&P 500 +24.54%
==========================================================================================
Statistics:
- Best performer: NVDA (+185.52%)
- Beat benchmark: 1 / 1
Example 2: Multi-Stock Long-Term Comparison (Scenario 1.b)
Compare FAANG stocks from 2020 to today:
python cumulative_return_analyzer.py --ticker META AAPL AMZN NFLX GOOGL --year 2020
python visualize_cumulative.py --ticker META AAPL AMZN NFLX GOOGL --year 2020
Example 3: Semiconductor Index Top 10 (Scenario 2.a)
Find top 10 semiconductor performers in 2024:
python index_component_analyzer.py --index sox --year 2024 --year-only --top 10
python visualize_cumulative.py --mode top20 --index sox --year 2024 --year-only --top 10
Example 4: Dow 30 Long-Term Analysis (Scenario 2.b)
Analyze Dow 30 components from 2020:
python index_component_analyzer.py --index dow30 --year 2020 --top 30
</extended_examples>
<error_handling>
Input Validation
The skill includes comprehensive input validation:
BRK.B → BRK-B, FB → META)nasdaq100, sp100, dow30, soxNetwork Retry Logic
Yahoo Finance API calls include automatic retry:
Data Quality Checks
</error_handling>
Running Tests
cd skills/track-equity-cumulative-return/scripts/tests
python test_calculations.py
Test Coverage:
Golden Cases
Located in scripts/tests/golden_cases.json:
<data_governance>
Data Sources
| Source | Type | Caching | Notes |
|---|---|---|---|
| Yahoo Finance | Primary | 12-hour cache | Free, public API |
Caching
scripts/cache/python fetch_price_data.py --clear-cacheKnown Limitations
</data_governance>