# Skills

> Deterministic portfolio checks — portfolio-health-check and more.

## 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:

1. Fetches the parsed snapshot from the snapshot store
2. Enriches holdings with MFAPI benchmark data (unless `include_enrichment: false`)
3. Runs 4 deterministic checks against thresholds (concentration, overlap, underperformance, expense ratio)
4. 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:

```text
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:

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

Run a skill:

```bash
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:

```json
{
  "skill_slug": "portfolio-health-check",
  "skill_version": "1.5.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": "Above 20%, one scheme's returns move a large share of the portfolio's returns."
    }
  ],
  "disclaimer": "Analytics only, not investment advice. Portfolio Intel is not a SEBI-registered investment adviser and does not recommend buying, selling or switching any scheme.",
  "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 }
  }
}
```

`suggested_action` explains what a flag means in one sentence. It keeps its name for compatibility, but since skill 1.3.0 it never tells the holder to buy, sell, hold or switch a scheme. Show `disclaimer` wherever you show the flags.

`checks` lists each of the four checks with a `status` of `passed`, `flagged` or `skipped`, and a `skipped_reason` when it was skipped. A skipped check was not evaluated, so do not report it as passed. The underperformance and expense ratio checks are skipped when enrichment is off. Since skill 1.4.0 the expense ratio check is also skipped when no fund has an expense ratio (TER).

Since skill 1.5.0 expense ratios come from AMFI's TER disclosures, for the holding's own plan (Direct or Regular), and the check's `source` is `amfi_ter`. Holdings are matched to AMFI schemes by name; a holding whose name does not match exactly one AMFI scheme, or whose plan is not known, gets no expense ratio. The expense ratio check then reports `evaluated_count` (funds it had a TER for) and `eligible_count` (all mutual funds), and the headline ends "(expense ratio checked for 4 of 6 funds)" when it did not cover every fund. Report the check as covering only those funds.

### 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 1.5% (LOW), 2% (MEDIUM) or 2.5% (HIGH) |

### 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 |

Source: https://docs.portfoliointel.co.in/skills/
