feat(cli): add static Skill token management commands

Open
#176 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
go
Domain
cli

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.

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:

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:
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
Dominant language
Go
Stars
1.5k
Forks
134
Avg merge
1d 22h
Merged PRs (30d)
61

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from alibaba/skill-up

All issues in alibaba/skill-up

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.