historical-market-cap — Claude Code skill: stock market cap history
A skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that pulls historical market capitalization data for any stock ticker via Octagon MCP.
MIT 260 installs ★ 132 updated 2026-06-05
npx skills add OctagonAI/skills --skill historical-market-cap -a claude-codeWhat historical-market-cap does
The skill runs across Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode, calling the octagon-agent tool from the Octagon MCP server. You pass a ticker symbol, a start date, an end date, and an optional record limit; the agent returns a daily series of market cap values calculated as price times split-adjusted shares outstanding.
From that series you can spot peak and trough dates, compute percentage change or CAGR over any interval, measure peak-to-trough drawdown, or run side-by-side comparisons between two tickers over the same window.
Octagon MCP must be configured in your agent before the skill can fire — without it, octagon-agent is unreachable. After installation, the skill file lands at a platform-specific path: ~/.claude/skills/historical-market-cap/SKILL.md for Claude Code, .cursor/skills/historical-market-cap/SKILL.md for Cursor.
What it helps with
- fetch a daily market cap series for a stock over a custom date range
- find the exact date and value of a peak or trough capitalization
- calculate peak-to-trough drawdown as a percentage
- compare market cap trajectories for two companies over the same period
- track when a company first crossed a target capitalization threshold
Example prompts for the agent
- Get historical market cap for
AAPLfrom 2025-01-01 to 2025-04-30 - When did
NVDAhit its highest market cap in 2024? - Compare market cap growth of
AAPLandMSFTover the past five years
How to install historical-market-cap
1Skills CLI (Vercel)
npx skills add OctagonAI/skills --skill historical-market-cap -a claude-code2Manually: put the files in place
~/.claude/skills/historical-market-cap/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/historical-market-cap/
1Skills CLI (Vercel)
npx skills add OctagonAI/skills --skill historical-market-cap -a codex2Manually: put the files in place
.agents/skills/historical-market-cap/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add OctagonAI/skills --skill historical-market-cap -a cursor2Manually: put the files in place
.cursor/skills/historical-market-cap/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install OctagonAI/skills skills/historical-market-cap2Manually: put the files in place
.github/skills/historical-market-cap/SKILL.md1Skills CLI (Vercel)
npx skills add OctagonAI/skills --skill historical-market-cap -a gemini-cli2Platform CLI
gemini skills install https://github.com/OctagonAI/skills --path skills/historical-market-capManually: put the files in place
.devin/skills/historical-market-cap/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add OctagonAI/skills --skill historical-market-cap -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about historical-market-cap
How do I install historical-market-cap in Claude Code?
Run npx skills add OctagonAI/skills --skill historical-market-cap -a claude-code. The skill file will be available at ~/.claude/skills/historical-market-cap/SKILL.md.
What does the historical-market-cap skill do?
It queries the Octagon MCP server for a daily market cap series over a specified date range, returning the highest, lowest, and most recent values along with the full data set.
What does the skill need to work?
The Octagon MCP server must be configured in your AI agent. Without that setup, the octagon-agent tool the skill depends on is not accessible.
Source text
SKILL.md · MIT
---
name: historical-market-cap
description: Retrieve historical market capitalization data for any stock using Octagon MCP. Use when tracking market cap changes over time, analyzing valuation trends, identifying peak and trough valuations, and comparing historical size classifications.
---
# Historical Market Cap
Retrieve historical market capitalization data over a specified date range using the Octagon MCP server.
## Prerequisites
Ensure Octagon MCP is configured in your AI agent (Cursor, Claude Desktop, Windsurf, etc.). See [references/mcp-setup.md](references/mcp-setup.md) for installation instructions.
## Workflow
### 1. Identify Parameters
Determine your query parameters:
- **Ticker**: Stock symbol (e.g., AAPL, MSFT)
- **Start Date**: Beginning of date range
- **End Date**: End of date range
- **Limit** (optional): Maximum records to return
### 2. Execute Query via Octagon MCP
Use the `octagon-agent` tool with a natural language prompt:
```
Retrieve historical market capitalization data for <TICKER> from <START_DATE> to <END_DATE>, limited to <LIMIT> records.
```
**MCP Call Format:**
```json
{
"server": "octagon-mcp",
"toolName": "octagon-agent",
"arguments": {
"prompt": "Retrieve historical market capitalization data for AAPL from 2025-01-01 to 2025-04-30, limited to 1000 records."
}
}
```
### 3. Expected Output
The agent returns daily market cap values:
| Date | Market Cap (USD) |
|------|------------------|
| 2025-04-30 | $3.17 trillion |
| 2025-02-25 | $3.70 trillion (High) |
| 2025-04-08 | $2.57 trillion (Low) |
| ... | ... |
**Summary Statistics**:
- Highest: $3.70 trillion on 2025-02-25
- Lowest: $2.57 trillion on 2025-04-08
- Most Recent: $3.17 trillion on 2025-04-30
**Data Sources**: octagon-stock-data-agent
### 4. Interpret Results
See [references/interpreting-results.md](references/interpreting-results.md) for guidance on:
- Analyzing market cap trends
- Calculating growth rates
- Identifying peaks and troughs
- Understanding volatility
## Example Queries
**Standard Date Range:**
```
Retrieve historical market capitalization data for AAPL from 2025-01-01 to 2025-04-30, limited to 1000 records.
```
**Full Year:**
```
Get historical market cap for MSFT for the entire year 2024.
```
**Quarterly Analysis:**
```
Show TSLA's market cap history for Q1 2025.
```
**Multi-Year Trend:**
```
Retrieve market cap history for NVDA from 2020 to 2025.
```
**Peak Analysis:**
```
When did AAPL reach its highest market cap in 2024?
```
## Understanding Market Cap History
### What the Data Shows
| Metric | Description |
|--------|-------------|
| Daily Market Cap | End-of-day value |
| Date Series | Trading days only |
| Calculation | Price × Shares Outstanding |
| Adjustments | Split-adjusted shares |
### Key Statistics
| Statistic | Purpose |
|-----------|---------|
| Maximum | Peak valuation |
| Minimum | Trough valuation |
| Average | Typical valuation |
| Range | Volatility indicator |
## Trend Analysis
### Calculating Changes
| Metric | Formula |
|--------|---------|
| Absolute Change | End Cap - Start Cap |
| Percentage Change | (End - Start) / Start × 100% |
| CAGR | (End/Start)^(1/years) - 1 |
### Example Calculation
From the AAPL data:
- High: $3.70T (Feb 25)
- Low: $2.57T (Apr 8)
- Range: $1.13T
- Peak-to-Trough: -30.5%
### Trend Patterns
| Pattern | Characteristics |
|---------|-----------------|
| Uptrend | Higher highs, higher lows |
| Downtrend | Lower highs, lower lows |
| Consolidation | Range-bound |
| V-Recovery | Sharp decline, sharp recovery |
| Rounded Top | Gradual peak formation |
## Period Analysis
### Daily Analysis
| Use Case | Focus |
|----------|-------|
| Trading | Short-term moves |
| Volatility | Day-to-day changes |
| Events | Catalyst impact |
### Weekly/Monthly Analysis
| Use Case | Focus |
|----------|-------|
| Trends | Direction over time |
| Comparisons | Period-over-period |
| Smoothing | Reduce noise |
### Annual Analysis
| Use Case | Focus |
|----------|-------|
| Growth | Long-term trajectory |
| Milestones | Major achievements |
| CAGR | Compound growth |
## Volatility Assessment
### Measuring Volatility
| Metric | Calculation |
|--------|-------------|
| Range | High - Low |
| Range % | (High - Low) / Average |
| Daily Moves | Average daily change |
| Standard Deviation | Price dispersion |
### Volatility Interpretation
| Range % | Volatility |
|---------|------------|
| <20% | Low |
| 20-40% | Moderate |
| 40-60% | High |
| >60% | Very High |
### Example
From AAPL data:
- High: $3.70T
- Low: $2.57T
- Range: $1.13T
- Range %: ~35%
- **Interpretation**: Moderate-high volatility
## Peak and Trough Analysis
### Identifying Peaks
| Signal | Description |
|--------|-------------|
| All-time High | Highest ever |
| Period High | Highest in range |
| Local Peak | Temporary high |
### Identifying Troughs
| Signal | Description |
|--------|-------------|
| All-time Low | Lowest ever |
| Period Low | Lowest in range |
| Local Trough | Temporary low |
### Peak-to-Trough Metrics
| Metric | Purpose |
|--------|---------|
| Drawdown % | Decline from peak |
| Recovery Time | Days to recover |
| Drawdown Duration | Peak to trough time |
## Size Classification Over Time
### Tracking Category Changes
| If Market Cap... | Classification |
|------------------|----------------|
| >$200B | Mega-cap |
| $10B-$200B | Large-cap |
| $2B-$10B | Mid-cap |
| $300M-$2B | Small-cap |
### Milestone Analysis
| Milestone | Significance |
|-----------|--------------|
| First $1T | Historic achievement |
| Crossed $2T | Elite status |
| Crossed $3T | World's most valuable |
## Comparative Analysis
### Same Company Over Time
| Comparison | Purpose |
|------------|---------|
| YoY | Year-over-year growth |
| QoQ | Quarterly momentum |
| MoM | Monthly trends |
### Multiple Companies
| Comparison | Purpose |
|------------|---------|
| Relative Size | Market position |
| Relative Growth | Performance comparison |
| Correlation | Movement similarity |
## Common Use Cases
### Trend Analysis
```
How has AAPL's market cap changed over the past year?
```
### Peak Finding
```
When did TSLA reach its highest market cap?
```
### Drawdown Analysis
```
What was NVDA's biggest decline from peak in 2024?
```
### Milestone Tracking
```
When did MSFT first cross $3 trillion market cap?
```
### Comparison
```
Compare the market cap growth of AAPL and MSFT over 5 years.
```
## Analysis Tips
1. **Use appropriate timeframes**: Match analysis to investment horizon.
2. **Identify catalysts**: Major moves often have drivers.
3. **Consider splits**: Ensure data is split-adjusted.
4. **Watch for milestones**: Round numbers are psychologically important.
5. **Calculate drawdowns**: Understand downside risk.
6. **Compare to benchmarks**: Market cap vs. index performance.
## Integration with Other Skills
| Skill | Combined Use |
|-------|--------------|
| company-market-cap | Current vs. historical |
| stock-performance | Price driving cap changes |
| income-statement | Earnings supporting cap |
| financial-metrics-analysis | Valuation evolution |
© OctagonAI · MIT · OctagonAI/skills