Files
skillshare/website/docs/reference/commands/analyze.md
T
Willie 1fb23f1e59 feat(analyze): measure what each target actually loads
The analyze numbers were drifting from what tools really see. Symlink-mode
targets expose the whole source folder, so .skillignore'd skills still load
but were left out; merge/copy targets often hold skills the user dropped in
by hand that skillshare never counted; and chars/4 undercounted CJK text by
roughly four times.

Route the CLI, TUI, web handler and sync summary through one
sync.TargetSkills so the three copies of the filter logic cannot disagree
again. Disabled skills stay in the discovery with Disabled=true and are
priced for symlink targets; unmanaged folders in a target are reported as
Local. Token estimates now charge one token per wide rune.

The dashboard keeps the chosen target in the URL so target and project
pages can deep-link into the analysis, lists project targets after own
targets with their tool icon, and tags local/disabled rows. Select gives
single-select icons a key to silence a React warning.
2026-09-21 04:17:26 +08:00

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

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.

Budget Warnings

When context_budget thresholds are configured, analyze shows a warning if any target exceeds the budget. See sync — Context Cost for configuration details.

See Also

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