How to Use the Portfolio-Review Skill in AI Berkshire: A Complete Guide to Portfolio Management

The portfolio-review skill transforms textual holdings descriptions into comprehensive audit reports through a deterministic seven-step pipeline that fetches live market data, validates valuations with financial rigor tools, and generates actionable rebalancing recommendations.

The AI Berkshire repository provides institutional-grade portfolio management capabilities as executable skills. The portfolio-review skill, defined in skills/portfolio-review.md, orchestrates a multi-agent workflow that analyzes position concentrations, stress-tests against macro shocks, and maintains persistent audit trails in reports/portfolio-latest.md for incremental reviews.

Skill Architecture and Components

The portfolio-review skill operates as a canonical workflow that bridges natural language inputs with rigorous financial analysis. According to the source code in xbtlin/ai-berkshire, the architecture comprises four integrated components:

• Skill Definition (skills/portfolio-review.md): Declares the user-facing command syntax, accepted input formats, and the multi-step analysis pipeline. This file is parsed by the Claude Code/Codex engine to generate the executable skill.
• Financial Rigor Tools (tools/financial_rigor.py): Provides the verify-valuation function for data quality checks and the three-scenario function for expected annual return modeling.
• Persistent Report (reports/portfolio-latest.md): Stores the latest holdings table and previous audit results, enabling historic trend analysis across multiple review cycles.
• Codex Wrapper (codex-skills/portfolio-review/SKILL.md): Auto-generated from the markdown source to ensure identical behavior across Claude Code and OpenAI Codex environments.

The Seven-Step Analysis Pipeline

The skill executes a deterministic workflow that progresses from data ingestion to persistent report generation.

Step 1: Parse Holdings

The skill normalizes user input into a structured tabular format containing fields such as 标的 (asset name), 代码 (ticker), and 持仓量 (position size). This parser handles diverse input styles including percentage allocations, share counts with cost basis, or references to existing portfolios.

Step 2: Fetch Latest Data

The system launches a Task Agent that executes parallel WebSearch calls for each holding. This background agent retrieves current market prices, valuation metrics (PE/PB ratios), dividend yields, quarterly financial changes, major corporate events, and analyst forecasts. During this phase, the skill invokes tools/financial_rigor.py to run verify-valuation checks on the retrieved data.

Step 3: Single-Position Health Check

For each holding, the skill generates a concise health matrix evaluating PE ratios, fundamental logic changes, and paper profit/loss status. The system then prompts the user with three binary questions, including: "如果今天没有持仓，你还会在当前价格买入吗？" (If you did not hold this position today, would you still buy at the current price?)

Step 4: Portfolio-Level Analysis

This phase conducts four critical assessments:

• Concentration Analysis: Validates that no single holding exceeds 40%, top-3 holdings comprise 50-80% of the portfolio, total positions number between 5-15, and cash reserves maintain 10-30%.
• Correlation Check: Detects hidden exposures across industries, countries, and currencies while estimating potential losses under macro-shocks.
• Opportunity-Cost Ranking: Uses financial_rigor.py three-scenario to compute expected annual returns for each position and compares them against the risk-free cash rate (~4%).
• Stress Testing: Qualitative and quantitative impact assessments for scenarios including global recession, US-China conflict, interest rate surges, and tech-bubble bursts.

Step 5: Optimization Recommendations

The skill generates concrete rebalancing actions categorized as 加仓 (add), 减仓 (reduce), 清仓 (liquidate), or 新建仓 (new position), each accompanied by detailed rationale and a cash-management allocation table.

Step 6: Report Assembly

The system compiles a comprehensive markdown report containing the portfolio overview, single-position health matrices, portfolio-level analysis results, actionable suggestions, and a scheduled next-review date.

Step 7: Persist

The final report writes back to reports/portfolio-latest.md, creating a historic audit trail that subsequent reviews can reference for trend analysis.

How to Invoke the Portfolio-Review Skill

You can trigger the skill through natural language commands in Claude Code or Codex environments, or programmatically via the provided wrapper scripts.

Command-Line Examples

Percentage Allocation Input:

/portfolio-review 腾讯30%, 美团20%, 茅台20%, 英伟达15%, 现金15%

Detailed Share-Count Input:

/portfolio-review 腾讯 500股 @480港元, 美团 1000股 @130港元, 英伟达 120股 @1200港元

Reference Existing Portfolio:

/portfolio-review 我的持仓

When invoking with "我的持仓", the skill reads the existing holdings table from reports/portfolio-latest.md and performs an incremental audit against the previous baseline.

Programmatic Execution

For automated workflows, invoke the skill via the repository's wrapper script:

import subprocess

cmd = [
    "python3", "scripts/run_skill.py",
    "--skill", "portfolio-review",
    "--args", "腾讯30%, 美团20%, 茅台20%, 英伟达15%, 现金15%"
]

result = subprocess.run(cmd, capture_output=True, text=True)
print(result.stdout)   # The generated markdown report

Note: Adjust the wrapper script path according to your local setup.

Input Formats and Validation

The skill accepts three primary input modalities:

1. Percentage Strings: Comma-separated lists of tickers with percentage weights (e.g., "AAPL50%, MSFT50%")
2. Share Specifications: Ticker symbols with share quantities and cost basis in natural language (e.g., "腾讯 500股 @480港元")
3. Portfolio References: The keyword "我的持仓" triggers a read operation on reports/portfolio-latest.md

All inputs undergo normalization into a standard schema before the seven-step pipeline executes.

Summary

• The portfolio-review skill is defined in skills/portfolio-review.md and auto-generated for Codex at codex-skills/portfolio-review/SKILL.md
• It executes a seven-step pipeline: Parse → Fetch → Health Check → Portfolio Analysis → Optimize → Report → Persist
• Financial rigor is enforced through tools/financial_rigor.py functions verify-valuation and three-scenario
• Concentration limits enforce single-position caps of 40% and cash reserves of 10-30%
• Results persist to reports/portfolio-latest.md for incremental audit trails
• Compatible with both Claude Code and OpenAI Codex environments

Frequently Asked Questions

How does the portfolio-review skill handle data quality for market prices?

The skill invokes verify-valuation from tools/financial_rigor.py during Step 2 to validate retrieved market data. This function cross-checks valuation metrics against historical ranges and flags anomalies before they enter the analysis pipeline, ensuring the health-check matrices and stress-test calculations rely on verified inputs.

Can I use the skill with US stock tickers instead of Chinese equities?

Yes. The parser in skills/portfolio-review.md normalizes any ticker format into the standard holdings table. The Task Agent's WebSearch calls retrieve data based on the provided ticker symbols regardless of exchange, making the skill compatible with NYSE, NASDAQ, HKEX, and SSE listings.

What happens if my portfolio violates the concentration constraints?

The skill flags violations during Step 4 (Portfolio-Level Analysis) and includes specific rebalancing recommendations in Step 5. For example, if a single holding exceeds 40%, the generated report will prioritize 减仓 (reduce position) actions with target allocation percentages to bring the portfolio within the 5-15 position range and 40% single-asset limit.

How is the report from a previous review preserved?

When you invoke /portfolio-review 我的持仓, the skill reads the existing reports/portfolio-latest.md in Step 1 to establish a baseline. After completing Step 7, it overwrites this file with the new audit results, maintaining a continuous record that enables comparative analysis between review cycles.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}