feat(cli): add static Skill token management commands
- Dominant language
- Go
- Stars
- 894
- Forks
- 68
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 38
Description
## Background
skill-up can report runtime token usage after eval run, if the agent engine provides token numbers. But this is different from the static size of a Skill itself.
For Skill authors, it is useful to know the token size of SKILL.md, references, scripts and other source files before running eval. This can help to control context size, detect token growth in PR, and find which files or sections are too large.
## Proposal
Add a new command group:
```bash
skill-up tokens count [paths...]
skill-up tokens profile [path]
skill-up tokens compare [ref-or-path] [paths...]
skill-up tokens suggest [paths...]
```
This should be static Skill source token management. It should not run evals, should not call agent, and should not call LLM.
## Scope
### tokens count
- scan Skill source assets
- print per-file estimated_tokens
- print total estimated_tokens
- support multiple paths and avoid duplicate counting
### tokens profile
- show the biggest token contributors
- support file level, directory level and Markdown section level profile
- non-Markdown text files can be counted as whole file
### tokens compare
- compare current workspace with git ref, for example:
```bash
skill-up tokens compare main --skills
```
- also support comparing with another path or directory
- report added/removed/changed/unchanged token delta
- support max total budget or max token growth gates
### tokens suggest
- print deterministic suggestions only
- do not modify files
- find possible problems like:
- oversized sections
- duplicated paragraphs or headings
- long code blocks
- generated or noisy files
## Design notes
- First version can use built-in lightweight estimator, not model tokenizer
- Use field name `estimated_tokens`, because it is estimate, not provider billing tokens
- Keep it separate from runtime `input_tokens` and `output_tokens`
- Default scan should exclude:
- evals/
- .git/
- cache/build/workspace outputs
- binary files
- oversized files
- Git ref compare should use non-destructive reads like `git ls-tree` and `git show`. It should not checkout or reset user workspace.
## Non-goals
- Do not auto edit Skill files
- Do not call LLM for suggestions
- Do not require network access
- Do not mix static Skill estimate with runtime usage tokens
## Acceptance criteria
- `skill-up tokens count skills/my-skill` prints per-file and total estimates
- `profile` can show large Markdown sections
- `compare main --skills` can show token increase/decrease and fail by threshold
- `suggest` prints deterministic reduce suggestions
- all four subcommands support JSON output
- skipped binary/oversized files have skip reason in JSON output
Contributor guide
Research direction
No implementation files or tests are named. Start by locating the existing CLI command registration and JSON-output paths, then map the scan and non-destructive Git-read entry points; done means all four commands meet the stated acceptance criteria without evals, LLM calls, network access, or file edits.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100