Files
skillshare/website/docs/reference/commands/analyze.md
T
Willie fb044d68a6 feat(analyze): add filtered token summary bar to Web UI
Shows always-loaded, on-demand, and total token sums for the current
search/filter result set using mini stat chips with icon + label + value.
Appears only when a filter is active. Search matches on path (relPath)
to support group filtering. Lint filter badge shows readable rule name.
2026-03-27 00:33:36 +08:00

7.3 KiB
Raw Blame History

sidebar_position
sidebar_position
4

analyze

Analyze context window usage and skill quality for each target's skills.

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:

skillshare analyze           # Browse all targets interactively

Compare Across Targets

See how context usage differs between targets (e.g., Claude vs Cursor):

skillshare analyze           # Tab to switch targets in TUI

Check Skill Quality

Find skills with missing fields, short descriptions, or no trigger phrases:

skillshare analyze           # Lint icons (✗/⚠) appear in TUI

CI/Scripting

Get machine-readable context metrics and lint results:

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 use chars / 4 as an approximation.

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:

skillshare analyze claude

Filter by Group

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

skillshare analyze --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

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:

{
  "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.

See Also

  • list — View installed skills
  • audit — Scan skills for security threats
  • tui — Toggle interactive TUI on/off