alibaba / alibaba/skill-up

feat(cli): add static Skill token management commands

Open
#176 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.