stock-portfolio

name	stock-portfolio
description	Portfolio management. Display holdings, record trades, and analyze portfolio structure. Input data foundation for stress tests.
argument-hint	[command] [args] e.g.: snapshot, buy 7203.T 100 2850, sell AAPL 5, analyze, list
allowed-tools	Bash(python3 *)

Portfolio Management Skill

Parse $ARGUMENTS to determine the command and execute it as shown below.

Execution Command

python3 /Users/kikuchihiroyuki/stock-skills/.claude/skills/stock-portfolio/scripts/run_portfolio.py <command> [args]

Command Reference

snapshot — Portfolio Snapshot

Generates a portfolio snapshot including current prices, P/L, and currency conversions.

python3 .../run_portfolio.py snapshot

buy — Record a Purchase

python3 .../run_portfolio.py buy --symbol <sym> --shares <n> --price <p> [--currency JPY] [--date YYYY-MM-DD] [--memo text] [--yes]

Omitting --yes (-y) displays a confirmation preview of the purchase and exits. Specifying --yes skips confirmation and records directly (KIK-444).

sell — Record a Sale

python3 .../run_portfolio.py sell --symbol <sym> --shares <n> [--price <sale price>] [--date YYYY-MM-DD] [--yes]

Omitting --yes (-y) displays a confirmation preview (cost basis, estimated realized P/L) and exits. Specifying --yes skips confirmation and records directly (KIK-444).

Specifying --price calculates and displays realized P/L, P/L ratio, and estimated after-tax amount, and saves to data/history/trade/*.json (KIK-441).

review — Trade Performance Review (KIK-441)

Aggregates and displays P/L statistics from past sale records (those recorded with --price).

python3 .../run_portfolio.py review [--year 2026] [--symbol NVDA]

Output:

• Trade history table (symbol, sale date, shares, cost basis, sale price, holding period, realized P/L, P/L ratio)
• Statistics (trade count, win rate, average return, average holding period, total realized P/L)

analyze — Structural Analysis

Calculates sector/region/currency/size HHI (Herfindahl index) and analyzes portfolio bias. Includes a 4-axis analysis with size composition table (large/mid/small/ETF/unknown) (KIK-438, KIK-469 P2: ETF classification). ETFs are independently classified as sector "ETF" and size "ETF."

python3 .../run_portfolio.py analyze

health — Health Check

Checks whether the investment thesis for each holding is still valid. Outputs 3-level alerts across multiple axes: technical (SMA50/200, RSI, Golden Cross/Dead Cross detection) and fundamental (change quality score, shareholder return stability). Small-cap stocks are automatically escalated in sensitivity (KIK-438).

python3 .../run_portfolio.py health

Technical Analysis (KIK-356/374/438):

• Trend determination from SMA50/200 (uptrend/sideways/downtrend)
• Golden Cross/Dead Cross detection: Detects cross events within a 60-day lookback, displaying occurrence date and days elapsed
• Small-cap cross lookback reduction (KIK-438): Small-cap stocks use a 30-day lookback for early detection of recent fluctuations

Shareholder Return Stability (KIK-403):

• Evaluates stability from total return rate (dividends + buybacks) (✅Stable high return/📈Increasing trend/⚠️Temporary high return/📉Declining trend)
• Temporary high return → escalate to early warning
• Declining trend → add reason to alert details
• Uses total return rate (dividends + buybacks) for long-term suitability assessment

Small-Cap Allocation (KIK-438):

• Classifies each stock by market cap size (large/mid/small/unknown) and displays [small] badge
• Small-cap stocks are automatically escalated: EARLY_WARNING → CAUTION
• Calculates portfolio-wide small-cap ratio; displays warning at >25%, critical at >35%

ETF Health Check (KIK-469 Phase 2):

• Displays individual stocks and ETFs in separate tables
• ETF table: symbol / P/L / trend / expense ratio / AUM / ETF score / alert
• Individual stock table: as before (change quality / long-term suitability / return stability)

Alert Levels:

• Early Warning: Below SMA50 / RSI sharp decline / 1 fundamental indicator deteriorating / temporary high return
• Caution: SMA50 approaching SMA200 + indicator deterioration / multiple change score deteriorations / small-cap EARLY_WARNING escalation
• Exit: Dead cross detected / trend breakdown + change score deterioration

adjust — Portfolio Adjustment Advisor (KIK-496)

Generates specific adjustment actions (SELL/SWAP/ADD/TRIM_CLASS/FLAG) using 17 rules (P1-P10: per-position, F1-F7: PF-wide) based on health check results + market regime determination.

python3 .../run_portfolio.py adjust [--full]

CLI options:

• --full: Full analysis mode (includes concentration and correlation analysis. Higher API load)

Output:

• Market regime (bull/bear/crash/neutral) — determined from SMA50/200, RSI, drawdown
• Action table by HIGH/MEDIUM/LOW priority (action type / target / reason / rule ID)
• Summary (action count)

Regime adjustment: During crash, urgency is raised one level. During bear, small-cap and downtrend rules are elevated.

rebalance — Rebalancing Proposal

Analyzes current portfolio structure and presents proposals for reducing concentration risk and adjusting toward target allocation.

python3 .../run_portfolio.py rebalance [options]

CLI options:

• --strategy defensive|balanced|aggressive (default: balanced)
• --reduce-sector SECTOR (e.g., Technology)
• --reduce-currency CURRENCY (e.g., USD)
• --max-single-ratio RATIO (e.g., 0.15)
• --max-sector-hhi HHI (e.g., 0.25)
• --max-region-hhi HHI (e.g., 0.30)
• --additional-cash AMOUNT (JPY, e.g., 1000000)
• --min-dividend-yield YIELD (e.g., 0.03)

forecast — Estimated Yield

Estimates 12-month expected return for each holding in 3 scenarios (optimistic/base/pessimistic) from analyst target prices or historical return distributions. Includes value trap warnings and TOP/BOTTOM rankings.

python3 .../run_portfolio.py forecast

Estimation methods:

• Analyst method: Analyst target price + dividend yield + buyback yield (including shareholder return)
• Historical return method: For stocks without analyst coverage (ETFs, etc.), estimates from historical CAGR + standard deviation (KIK-469 P2: ETFs show annualized volatility + [ETF] badge)
• Industry catalyst adjustment (KIK-433, when Neo4j connected): Adds recent same-sector growth_driver catalyst count × 1.7% to optimistic scenario, subtracts risk catalyst count × 1.7% from pessimistic scenario (max ±10%)

Output structure (KIK-390):

1. Portfolio-wide 3-scenario yield and P/L table
2. Caution stocks section (aggregate stocks with value trap warnings)
3. Expected return TOP 3 / BOTTOM 3 rankings
4. Per-stock details (analyst target / Forward P/E / news count / X sentiment / 3 scenarios)

what-if — What-If Simulation (KIK-376 / KIK-451)

Simulates adding, selling, or swapping stocks and displays the impact on the portfolio as a Before/After comparison.

# Add only (traditional)
python3 .../run_portfolio.py what-if --add "SYMBOL:SHARES:PRICE[,...]"

# Swap (sell then buy) (KIK-451)
python3 .../run_portfolio.py what-if --remove "SYMBOL:SHARES[,...]" --add "SYMBOL:SHARES:PRICE[,...]"

# Sell-only simulation (KIK-451)
python3 .../run_portfolio.py what-if --remove "SYMBOL:SHARES[,...]"

CLI options:

• --add: List of stocks to add (optional). Format: SYMBOL:SHARES:PRICE comma-separated
• --remove: List of stocks to sell (optional). Format: SYMBOL:SHARES comma-separated (no price needed — calculated at market value)
• At least one of --add or --remove is required

Output:

• [On sell] Sell candidate context (KIK-470): When --remove is specified, automatically displays screening appearance count, investment memos, and research history before the simulation (when Neo4j connected)
• Before/After sector HHI / region HHI / currency HHI comparison
• Basic info on added stocks (P/E / P/B / dividend yield / ROE)
• [On swap] Sell stock table (symbol, shares, estimated sale proceeds)
• [On swap] Fund balance (required purchase funds / estimated sale proceeds / difference)
• [On swap] Health check on sold stocks (alert status of sell targets)
• Judgment label: Recommended / Proceed with caution / Not recommended (for swaps: "This swap is recommended," etc.)
• ETF quality assessment (KIK-469 P2): When adding an ETF, ETF score is reflected in the judgment (quality good ≥75, warning if quality low <40)

backtest — Backtest

Verifies returns from accumulated screening results and compares against benchmarks (Nikkei 225 / S&P 500).

python3 .../run_portfolio.py backtest [options]

CLI options:

• --preset PRESET: Screening preset to verify (e.g., alpha, value)
• --region REGION: Region to verify (e.g., jp, us)
• --days N: Verifies return N days after retrieval (default: 90)

Output:

• Average return by screening date
• Benchmark comparison (excess return)
• Win rate, average return, max return / max loss

simulate — Compound Interest Simulation

Simulates future asset growth with compound interest based on the current portfolio. Calculates compound interest using forecast expected returns + dividend reinvestment + monthly accumulation, displayed in 3 scenarios (optimistic/base/pessimistic).

python3 .../run_portfolio.py simulate [options]

CLI options:

• --years N (simulation years, default: 10)
• --monthly-add AMOUNT (monthly accumulation, JPY, default: 0)
• --target AMOUNT (target amount, JPY, e.g., 15000000)
• --reinvest-dividends (reinvest dividends, default: ON)
• --no-reinvest-dividends (do not reinvest dividends)

list — Holdings List

Displays the contents of portfolio.csv as-is.

python3 .../run_portfolio.py list

Natural Language Routing

For natural language → skill selection, see .claude/rules/intent-routing.md.

Constraints

• Japan stocks: 100-share lots (standard trading unit)
• ASEAN stocks: 100-share lots (minimum fee: JPY 3,300)
• Rakuten Securities compatible (fee structure)
• portfolio.csv path: .claude/skills/stock-portfolio/data/portfolio.csv

Output

Display results in Markdown format.

snapshot output items

• Symbol / Name / Shares held / Cost basis / Current price / Market value / P/L / P/L ratio / Currency

analyze output items

• Sector HHI / Region HHI / Currency HHI / Size HHI (KIK-438)
• Composition ratio for each axis (size composition table: large/mid/small/ETF/unknown)
• ETF annotation (note that look-through is not supported)
• Risk level determination

health output items

• Individual stock table: Symbol (small-cap stocks show [small] badge) / P/L ratio / Trend / Cross event / Change quality / Alert / Long-term suitability / Return stability
• ETF table (KIK-469 P2): Symbol / P/L / Trend / Expense ratio / AUM / ETF score / Alert
• Details for stocks with alerts (reason, SMA/RSI values, cross occurrence date & days elapsed, change score, shareholder return stability, recommended action)
• Small-cap allocation: Portfolio-wide small-cap ratio summary (✅Normal/⚠️Warning/🔴Critical)

forecast output items

• Portfolio-wide: 3-scenario yield (optimistic/base/pessimistic) + P/L + total market value
• Caution stocks section: List of stocks with value trap warnings
• TOP 3 / BOTTOM 3: Expected return rankings (with analyst count)
• Per-stock: Analyst target price / Forward P/E / news count / X sentiment / 3 scenarios / ETFs show annualized volatility + [ETF] badge

what-if output items

• [On sell] Sell candidate context (KIK-470): Screening appearance count, investment memos, research history
• Before/After HHI comparison (sector/region/currency)
• Fundamentals of added stocks
• Concentration change judgment
• [On swap] Sell stock table (estimated sale proceeds)
• [On swap] Fund balance (required purchase funds / sale proceeds / difference)
• [On swap] Health check on sold stocks
• [On swap] "This swap is recommended / Proceed with caution / Not recommended"

backtest output items

• Return by screening date
• Benchmark comparison (excess return)
• Win rate, statistics

adjust output items

• Market regime (regime name / SMA50 vs SMA200 / RSI / drawdown)
• HIGH Priority table: SELL/SWAP/TRIM_CLASS actions
• MEDIUM Priority table: FLAG/SELL actions
• LOW Priority table: FLAG actions
• Summary (HIGH/MEDIUM/LOW counts, regime)

rebalance output items

• Current HHI (sector/region/currency) and target HHI
• Sell candidates (symbol, shares, reason)
• Buy candidates (symbol, shares, reason, dividend yield)
• Projected HHI after rebalancing

simulate output items

• Annual progression table (year / market value / total invested / investment gain / cumulative dividends)
• 3-scenario comparison (optimistic/base/pessimistic final year)
• Goal achievement analysis (year of reaching goal / required monthly contribution)
• Compound interest effect of dividend reinvestment

Execution Examples

# Snapshot
python3 .../run_portfolio.py snapshot

# Record purchase
python3 .../run_portfolio.py buy --symbol 7203.T --shares 100 --price 2850 --currency JPY --date 2025-06-15 --memo Toyota

# Record sale
python3 .../run_portfolio.py sell --symbol AAPL --shares 5

# Structural analysis
python3 .../run_portfolio.py analyze

# List holdings
python3 .../run_portfolio.py list

# Health check
python3 .../run_portfolio.py health

# Estimated yield
python3 .../run_portfolio.py forecast

# Rebalancing proposal
python3 .../run_portfolio.py rebalance
python3 .../run_portfolio.py rebalance --strategy defensive
python3 .../run_portfolio.py rebalance --reduce-sector Technology --additional-cash 1000000

# What-If simulation (add only)
python3 .../run_portfolio.py what-if --add "7203.T:100:2850,AAPL:10:250"

# What-If simulation (swap: sell 7203.T → buy 9984.T) (KIK-451)
python3 .../run_portfolio.py what-if --remove "7203.T:100" --add "9984.T:50:7500"

# What-If simulation (sell only) (KIK-451)
python3 .../run_portfolio.py what-if --remove "7203.T:50"

# Adjustment advisor (KIK-496)
python3 .../run_portfolio.py adjust
python3 .../run_portfolio.py adjust --full

# Backtest
python3 .../run_portfolio.py backtest --preset alpha --region jp --days 90

Prior Knowledge Integration Rules (KIK-466)

health command

When get_context.py output contains the following, integrate with health check results:

• Trade history (BOUGHT/SOLD): Reference purchase price and date to add unrealized P/L context. If a sold stock appears in warnings, explicitly state "already sold — no issue"
• Investment memos (Note): If thesis or concern memos exist, cross-check with health check results. e.g., "Value trap concern memo → BT score also high this time → truly needs attention"
• Previous health check (HealthCheck): Show diff from previous result. "Previous: HOLD → This time: EXIT: situation deteriorated" / "Previous: EXIT → This time: HOLD: improved"
• Screening history (SURFACED): If a flagged stock has historically been in the top of screenings, "High attention (top 3 times) but currently needs caution"
• Thesis age: If a thesis memo is 90+ days old, prompt "time to review the thesis"

snapshot / forecast

• If a previous snapshot or forecast exists, add diff comments
• e.g., "vs. previous: market value +5.2%, yield improved"

Prompting to Record Analysis Conclusions

When the response includes specific judgments about EXIT/warnings (e.g., "sell recommended," "continue holding"):

💡 Would you like to record this judgment as an investment memo?