Skip to main content
track-equity-cumulative-return 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.
الانتقال إلى التثبيت سوق المهارات اكتشف واستكشف مهارات الذكاء الاصطناعي التي بناها المجتمع.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
عرض تفاصيل Prompt يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/fatfingererr/macro-skills --skill track-equity-cumulative-returnيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
تحميل Zip جاري التحميل... المهن ذات الصلة SOC
استنادا إلى تصنيف SOC المهني
name track-equity-cumulative-return version 1.1.0 updated "2026-01-28T00:00:00.000Z" description 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.
<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:
S&P 500 represents the broad US equity market
Provides consistent, comparable baseline across all analyses
"vs Benchmark" = Stock Return - S&P 500 Return
Positive vs Benchmark indicates outperformance (Alpha)
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 :
Analyzing 2024 → Base date is 2023-12-29 (last trading day of 2023)
This captures the true return from year-end investment to period end
All tickers are aligned to common trading days with data.
**Four Analysis Scenarios**
This skill supports 4 distinct scenarios:
**Supported Index Components**
Track cumulative return performance of stocks and indices:
What analysis do you need?
| 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` |
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.
Fetch Data : Get historical prices from Yahoo Finance (with caching)Calculate Returns : Cumulative returnBenchmark Comparison : Compare against S&P 500 (fixed)Rank Analysis : Index component Top N performance rankingVisualization : dark theme PNG charts Output: Cumulative return time series chart, performance ranking table, JSON data, Markdown report.
Quick Start: Analyze Stock Cumulative Returns
cd skills/track-equity-cumulative-return/scripts
pip install pandas numpy yfinance matplotlib
python cumulative_return_analyzer.py --ticker NVDA AMD --year 2024 --year-only
python cumulative_return_analyzer.py --ticker NVDA AMD GOOGL --year 2022
python index_component_analyzer.py --index nasdaq100 --year 2024 --year-only --top 10
python index_component_analyzer.py --index nasdaq100 --year 2022 --top 20
python visualize_cumulative.py --ticker NVDA AMD --year 2024 --year-only
python visualize_cumulative.py --mode top20 --index nasdaq100 --year 2022 --top 20
{
"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
}
}
Scenario 1.a - Analyze stock(s) for a specific year only (e.g., "NVDA in 2024 full year")Scenario 1.b - Analyze stock(s) from a year to today (e.g., "NVDA from 2022 to today")Scenario 2.a - Index Top N for a specific year only (e.g., "Nasdaq 100 Top N in 2024")Scenario 2.b - Index Top N from a year to today (e.g., "Nasdaq 100 Top N since 2022")Methodology - Learn about cumulative return calculation Provide your analysis parameters or select a scenario.
--year-only: Analyze only the specified year (scenarios a)Without --year-only: Analyze from year to today (scenarios b)
--top N: Select Top N for index analysis All 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>
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>
Template Purpose output-json.md JSON output structure definition output-markdown.md Markdown report template </templates_index>
Script Command Example Purpose fetch_price_data.py --ticker NVDA --start 2022-01-01Yahoo Finance data fetching cumulative_return_analyzer.py --ticker NVDA AMD --year 2022Cumulative return calculation (1.a/1.b) index_component_analyzer.py --index nasdaq100 --year 2022Index component analysis (2.a/2.b) visualize_cumulative.py --ticker NVDA AMD --year 2022visualization </scripts_index>
Parameter Type Description ticker string Stock ticker(s) - can be multiple year int Start year
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.
Charts follow thoughts/shared/guide/bloomberg-style-chart-guide.md:
Background : #1a1a2e (dark blue-black)Grid : #2d2d44 (dark gray-purple)Primary lines : #ff6b35 (orange-red), #ffaa00 (orange-yellow)Benchmark line : #004E89 (deep blue dashed)Zero line : #666666 (gray dotted)
January: Show year (e.g., "2024")
February-December: Show month number (e.g., "2", "3", ... "12")
Size: 14×8 inches (compare) / 16×10 inches (top20)
Resolution: 150 dpi
Format: PNG
{
"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>
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
==========================================================================================
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
The skill includes comprehensive input validation:
Ticker validation : Checks format, applies corrections (e.g., BRK.B → BRK-B, FB → META)Year validation : Must be between 1970 and current yearIndex validation : Must be one of: nasdaq100, sp100, dow30, soxTop N validation : Must be positive integer ≤ 100 Yahoo Finance API calls include automatic retry:
Up to 3 retry attempts
Exponential backoff (2s, 3s, 4.5s delays)
Clear error messages on failure
Minimum data points required (5 rows)
NaN percentage threshold (max 10%)
Invalid price detection (non-positive values)
Automatic data cleaning with warnings
cd skills/track-equity-cumulative-return/scripts/tests
python test_calculations.py
Cumulative return formula - Validates calculation accuracyCumulative return series - Validates time series generationValidators - Tests all input validation functionsGolden cases - Structure validation of expected results Located in scripts/tests/golden_cases.json:
NVDA 2024 full year (expected: 170-190% return)
AMD 2024 full year (expected: -20% to -10% return)
S&P 500 2024 benchmark (expected: 20-28% return)
Source Type Caching Notes Yahoo Finance Primary 12-hour cache Free, public API
Cache directory: scripts/cache/
Cache format: Parquet (efficient storage)
Cache validity: 12 hours
Clear cache: python fetch_price_data.py --clear-cache
Survivorship bias : Index components are current, not historicalPrice-only returns : Does not include dividendsYahoo Finance rate limits : Heavy usage may be throttled 