--- sidebar_position: 4 --- # analyze Analyze context window usage and skill quality for each target's skills. ```bash skillshare analyze # Interactive TUI (default) skillshare analyze claude # Details for a single target skillshare analyze --verbose # Top 10 largest descriptions skillshare analyze --json # Machine-readable output skillshare analyze -p # Project mode ``` ## When to Use ### Optimize Context Budget Identify which skills consume the most context window tokens: ```bash skillshare analyze # Browse all targets interactively ``` ### Compare Across Targets See how context usage differs between targets (e.g., Claude vs Cursor): ```bash skillshare analyze # Tab to switch targets in TUI ``` ### Check Skill Quality Find skills with missing fields, short descriptions, or no trigger phrases: ```bash skillshare analyze # Lint icons (✗/⚠) appear in TUI ``` ### CI/Scripting Get machine-readable context metrics and lint results: ```bash skillshare analyze --json | jq '.targets[].always_loaded.estimated_tokens' skillshare analyze --json | jq '.targets[].skills[] | select(.lint_issues | length > 0)' ``` ## What It Does `analyze` calculates two layers of context cost for each skill: 1. **Always loaded** — `name + description` from SKILL.md frontmatter (loaded into context on every request for skill matching) 2. **On-demand** — Skill body after frontmatter (loaded only when the skill is triggered) Token estimates count about 4 characters per token for ASCII text and 1 token per character for CJK and other wide scripts. Each target is measured as the tool sees it: - **merge / copy mode** — source skills that pass the target's include/exclude and `targets:` filters, minus anything disabled in `.skillignore`, plus skills that already live in the target folder without coming from the source (flagged `local` in JSON). - **symlink mode** — the whole source folder, including `.skillignore`'d skills (flagged `disabled` in JSON), because the symlink exposes them anyway. ### Skill Quality Lint In addition to token analysis, `analyze` runs a built-in lint engine against every skill. Lint rules check SKILL.md structure and description quality, surfacing issues directly in the TUI and JSON output. | Rule | Severity | What it checks | |------|----------|----------------| | `missing-name` | error | `name` field is empty or missing | | `missing-description` | error | `description` field is empty or missing | | `empty-body` | error | Skill body (after frontmatter) is empty | | `description-too-short` | warning | Description under 50 characters | | `description-too-long` | warning | Description exceeds 1024-character target limit | | `description-near-limit` | warning | Description between 900–1024 characters | | `no-trigger-phrase` | warning | Description lacks trigger phrases (e.g. "Use when…") | In the TUI, skills with lint issues show ✗ (error) or ⚠ (warning) icons next to their name. The detail panel includes a **Quality** section listing all findings. ## Interactive TUI By default, `analyze` launches an interactive TUI with: - **Left panel** — Skill list sorted by token cost, with color-coded dots (red/yellow/green by percentile) - **Right panel** — Detail view: token breakdown, lint quality issues, path, tracked status, description preview - **Bottom bar** — Target selector (Tab/Shift+Tab to switch) + token totals + estimation formula ### TUI Controls | Key | Action | |-----|--------| | `↑`/`↓` | Navigate skill list | | `←`/`→` | Page up/down | | `Tab` / `Shift+Tab` | Switch target | | `/` | Filter skills by name | | `s` | Cycle sort: tokens↓ → tokens↑ → name A→Z → name Z→A | | `Ctrl+d` / `Ctrl+u` | Scroll detail panel | | `q` | Quit | ### Color Coding Token consumption levels use dynamic percentile thresholds per target: | Color | Meaning | |-------|---------| | 🔴 Red | P75+ (top 25% consumers) | | 🟡 Yellow | P25–P75 (middle 50%) | | 🟢 Green | Below P25 (lowest 25%) | ## Example Output ### Default (--no-tui) ``` Context Analysis (global) ℹ claude (7 skills) Always loaded: ~362 tokens On-demand max: ~22 tokens ``` ### Verbose ``` skillshare analyze --verbose Context Analysis (global) ℹ claude (7 skills) Always loaded: ~362 tokens On-demand max: ~22 tokens Largest descriptions: my-big-skill ~180 tokens another-skill ~120 tokens ... ``` ### Single Target Passing a target name automatically enables verbose output: ```bash skillshare analyze claude ``` ### Filter by Group ```bash # See total token cost of all frontend skills skillshare analyze claude --json --filter frontend # Pre-populate the search box in TUI skillshare analyze --filter marketing ``` ## Options | Flag | Description | |------|-------------| | `[target]` | Show details for a single target (auto-enables verbose) | | `--verbose`, `-v` | Show top 10 largest descriptions per target | | `--no-tui` | Disable interactive TUI, print plain text | | `--project`, `-p` | Analyze project-level skills (`.skillshare/`) | | `--global`, `-g` | Analyze global skills (`~/.config/skillshare`) | | `--filter ` | Filter skills by name/path substring | | `--json` | Output as JSON (for scripting/CI) | | `--help`, `-h` | Show help | :::tip Auto-detection If neither `--project` nor `--global` is specified, skillshare auto-detects: if `.skillshare/config.yaml` exists in the current directory, it defaults to project mode; otherwise global mode. ::: ## JSON Output ```bash skillshare analyze --json ``` ```json { "targets": [ { "name": "claude", "skill_count": 7, "always_loaded": { "chars": 1448, "estimated_tokens": 362 }, "on_demand_max": { "chars": 88, "estimated_tokens": 22 }, "skills": [ { "name": "my-skill", "description_chars": 180, "description_tokens": 45, "body_chars": 400, "body_tokens": 100, "lint_issues": [ { "rule": "no-trigger-phrase", "severity": "warning", "category": "format", "message": "Description lacks trigger phrases (e.g. 'Use when...'); agents may not know when to invoke this skill" } ] } ] } ] } ``` Skills with no lint issues omit the `lint_issues` field. ## Project Mode ```bash skillshare analyze -p # Interactive TUI for project skills skillshare analyze -p --verbose # Verbose text output skillshare analyze -p claude # Single target details skillshare analyze -p --json # JSON output ``` ## Filtering Use `--filter` to narrow results to a subset of skills. The filter performs a case-insensitive substring match on the skill's relative path (which includes the group directory). For example, if you installed skills with `--into frontend`: - `--filter frontend` matches all skills in the `frontend/` group - `--filter react` matches any skill with "react" in its path In TUI mode, `--filter` pre-populates the filter input. You can also use the `/` key to start filtering interactively. In JSON mode, the output includes a `filtered_summary` with aggregated token counts: ```json { "filter": "frontend", "matched_count": 5, "total_count": 50, "filtered_summary": { "always_loaded": { "chars": 2400, "tokens": 600 }, "on_demand": { "chars": 8000, "tokens": 2000 }, "total": { "chars": 10400, "tokens": 2600 } }, "skills": [...] } ``` The Web UI also shows a dynamic token summary bar when search or filter is active. ## Budget Warnings When `context_budget` thresholds are configured, `analyze` shows a warning if any target exceeds the budget. See [sync — Context Cost](/docs/reference/commands/sync#context-cost) for configuration details. ## See Also - [list](/docs/reference/commands/list) — View installed skills - [audit](/docs/reference/commands/audit) — Scan skills for security threats - [tui](/docs/reference/commands/tui) — Toggle interactive TUI on/off