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.
8.1 KiB
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:
- Always loaded —
name + descriptionfrom SKILL.md frontmatter (loaded into context on every request for skill matching) - 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 (flaggedlocalin JSON). - symlink mode — the whole source folder, including
.skillignore'd skills (flaggeddisabledin 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 frontendmatches all skills in thefrontend/group--filter reactmatches 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.