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

265 lines
8.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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 <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
```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