Developer Docs

Portfolio Intel Docs

What are Skills?

MCP tools like parse_cas and enrich are primitives — each does one thing and returns raw data. Skills chain those tools together and apply domain-specific evaluation criteria to produce actionable reports.

A skill has an opinion. It flags issues, rates severity, and explains why in plain English.

Available Skills

Skill	Slug	What it checks
Portfolio Health Check	`portfolio-health-check`	Concentration risk, fund overlap, benchmark underperformance, high expense ratios

When to Use Skills vs Tools

Use case	Use this	Why
Parse a PDF and get structured JSON	`parse_cas`	You want raw data
Get benchmark returns for holdings	`enrich`	You want enriched data to analyze yourself
Is my portfolio healthy? What should I fix?	`run_skill`	You want expert analysis with reasoning
Building a custom dashboard	Tools individually	You need raw data to feed your own UI
MFD reviewing a client’s portfolio	`run_skill`	Get actionable flags without manual analysis

How Skills Work

When you call run_skill("portfolio-health-check", snapshot_id), the system:

Fetches the parsed snapshot from the snapshot store
Enriches holdings with MFAPI benchmark data (unless include_enrichment: false)
Runs 4 deterministic checks against thresholds (concentration, overlap, underperformance, expense ratio)
Returns a structured SkillResult with flags, severity ratings, and reasoning

The output is deterministic — same input always produces the same flags. No LLM involved in the analysis.

Using Skills

Claude Desktop / claude.ai

Add the MCP server or connector, then ask naturally:

User: "Run a health check on my portfolio"

Claude calls parse_cas → gets snapshot_id
Claude calls run_skill(slug="portfolio-health-check", snapshot_id="snap_abc123")

Returns a structured report with flagged holdings and reasoning.

Claude Code CLI

Configure the MCP server in your settings, then the list_skills and run_skill tools are available in terminal sessions.

REST API

List available skills:

curl https://api.portfoliointel.co.in/api/v1/skills

Run a skill:

curl -X POST https://api.portfoliointel.co.in/api/v1/skills/portfolio-health-check/run \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"snapshot_id": "snap_abc123", "include_enrichment": true}'

Understanding the Output

A SkillResult contains:

{
  "skill_slug": "portfolio-health-check",
  "skill_version": "1.0.0",
  "ran_at": "2024-12-31T10:00:00.000Z",
  "snapshot_id": "snap_abc123",
  "summary": {
    "total_holdings": 8,
    "flagged_count": 3,
    "health_rating": "NEEDS_ATTENTION",
    "headline": "3 of 8 holdings flagged — portfolio needs attention"
  },
  "flags": [
    {
      "fund_name": "HDFC Small Cap Fund",
      "isin": "INF179KA1YQ1",
      "issue_type": "CONCENTRATION",
      "severity": "HIGH",
      "reasoning": "HDFC Small Cap Fund holds 28% of portfolio (threshold: 20%). Over-concentration in a single scheme increases idiosyncratic risk.",
      "metric_value": 28,
      "threshold_value": 20,
      "suggested_action": "Consider reducing allocation to under 20%."
    }
  ],
  "portfolio_metrics": {
    "total_value": 1250000,
    "total_invested": 1050000,
    "overall_return_pct": 19.0,
    "portfolio_xirr": 14.2,
    "category_allocation": [
      { "name": "Small Cap", "pct": 28 },
      { "name": "Large Cap", "pct": 35 }
    ],
    "top_concentration": { "fund": "HDFC Small Cap Fund", "pct": 28 }
  }
}

Flag Types

Type	What it means
`CONCENTRATION`	Single fund or AMC holds too much of the portfolio
`OVERLAP`	Multiple funds in the same category or tracking the same index
`UNDERPERFORMANCE`	Fund trails its benchmark by more than 2% over 1 year
`HIGH_EXPENSE`	Expense ratio above 2% threshold

Severity Levels

Level	Meaning
`HIGH`	Requires attention — significant risk or persistent underperformance
`MEDIUM`	Worth reviewing — moderate concentration or expense concern
`LOW`	Minor issue — fund overlap that adds complexity

Health Ratings

Rating	Criteria
`EXCELLENT`	0 flags
`GOOD`	1-2 flags, none HIGH severity
`NEEDS_ATTENTION`	3+ flags or any HIGH severity
`POOR`	5+ flags or 2+ HIGH severity