Skip to content

armelhbobdad/oh-my-skills / .claude/skills/skf-export-skill

skf-export-skill

Verified

Exports an SKF skill, validating its package, writing its context snippet and updating the managed section in CLAUDE.md, AGENTS.md or .cursorrules. Use when the user requests to "export a skill" or "package a skill."

references/token-report.md

View on GitHub
---
nextStepFile: 'summary.md'
# SKILL.md's On Activation resolved {countTokensHelper}. It emits per-artifact
# word and token metrics as JSON, so this step renders exact numbers instead of
# word-counting every file in the prompt.
---

<!-- Config: communicate in {communication_language}. Render the token report in {document_output_language}. -->

# Step 5: Token Report

## STEP GOAL:

To calculate approximate token counts for all exported artifacts and present a clear report showing the token cost of each component, helping users understand the context budget impact of their skills.

## Rules

- Focus only on token counting and reporting — read-only measurement
- Auto-proceed when complete
- **Multi-skill mode:** when step 1 loaded more than one skill (`len(skill_batch) > 1`), run the helper once per skill, then present one aggregate table with one row per skill (context-snippet.md, SKILL.md, metadata.json, references/, package total) and the Context Budget Impact per skill (its `context_budget.on_trigger`, `full_disclosure` and `snippet`). The `managed_section` and `context_budget.always_on` values are identical across runs (same target files): measure and report them once for the run. See step 1 §1c.

## MANDATORY SEQUENCE

### 1. Measure Token Counts

Run `{countTokensHelper}` against the resolved skill package, passing every target context file so the shared managed section is measured:

```bash
python3 {countTokensHelper} {resolved_skill_package} --target-file {context_file_1} --target-file {context_file_2}
```

Pass one `--target-file` per entry in `target_context_files` (resolved in step 1). The helper measures the managed section from the first target file that contains a `<!-- SKF:BEGIN -->…<!-- SKF:END -->` block.

The helper emits JSON:

```json
{
  "files": [{"path": "…", "role": "…", "exists": true, "words": 0, "tokens": 0}],
  "references_total": {"count": 0, "words": 0, "tokens": 0},
  "managed_section": {"present": true, "source_file": "…", "target_files": ["…"], "skills": 0, "words": 0, "tokens": 0},
  "package_total": {"words": 0, "tokens": 0},
  "context_budget": {"always_on": 0, "on_trigger": 0, "full_disclosure": 0, "snippet": 0}
}
```

**Read the JSON — do not re-count words in-prompt.** Each `tokens` value is a char-over-four estimate (`len(text)//4`, the SKF-wide convention shared with `skf-validate-output.py`); each `words` value is the whitespace-split count for the report's Words column. The `files` array carries one row per artifact — `role` is one of `context-snippet`, `skill-md`, `metadata`, `reference`. `package_total` already sums context-snippet.md + SKILL.md + metadata.json + `references_total` and **excludes** the `managed_section` row: the managed section is a shared all-skills cost (it bundles this skill's snippet plus every other skill's snippet), so folding it in would double-count this skill's snippet and pull in unrelated skills. It is reported separately under Context Budget Impact.

`managed_section.skills` counts the skill rows (each `[name v…]` row header, as the managed-section rebuild counts them) in the measured block. `managed_section.target_files` lists every target file that holds a block, each once, and `managed_section.source_file` names the one the helper measured, the first of them; a target file that cannot be read is skipped. `context_budget` gives the Context Budget Impact values, in tokens: `always_on` is the managed section's (null when no target file holds a block: render it as N/A), `on_trigger` SKILL.md's, `full_disclosure` SKILL.md's plus `references_total.tokens` (what an agent loads when it reads every reference too: neither the snippet nor metadata.json, so it is not `package_total`), and `snippet` the context-snippet.md row's.

**If `passive_context` was disabled:** the helper reports the `context-snippet.md` row with `exists: false` and `managed_section.present: false`: render both rows, the always-on cost and the benchmark as "N/A (disabled)".

### 2. Present Token Report

Render the report straight from the helper JSON, with no re-counting. In each table row, `{n}` ← the row's `words` and `{t}` ← its `tokens`:

- `context-snippet.md` row → `files[].tokens` / `.words` for `role: context-snippet`
- `Managed section` row → `managed_section.words` / `.tokens`; `{target-file-list}` ← `managed_section.target_files`, joined with commas; `{skill-count}` ← `managed_section.skills` (report the row once for the run)
- `SKILL.md` row → `files[]` for `role: skill-md`
- `metadata.json` row → `files[]` for `role: metadata`
- `references/` row → `references_total.words` / `.tokens`; `{count}` ← `references_total.count`
- `Package total` row → `package_total.words` / `.tokens`

The Context Budget Impact lines, per skill in multi-skill mode (the always-on cost once for the run):

- `{managed-section-tokens}` ← `context_budget.always_on`, the managed section's tokens (N/A when null)
- `{measured-file}` ← `managed_section.source_file`, the target file the helper measured
- `{skill-tokens}` ← `context_budget.on_trigger`, SKILL.md's tokens
- `{total-tokens}` ← `context_budget.full_disclosure`, SKILL.md's tokens plus `references_total.tokens` (never `package_total`, which also counts the snippet and metadata.json)
- `{snippet-tokens}` ← `context_budget.snippet`, the context-snippet.md row's tokens
- `{skill-name}` ← `skill_package`, its last folder (multi-skill mode only)

"**Token Report**

| Artifact | Words | Est. Tokens | Notes |
|----------|-------|-------------|-------|
| context-snippet.md | {n} | ~{t} | Passive context (always-on) |
| Managed section (all skills) | {n} | ~{t} | In {target-file-list}, all {skill-count} skills |
| SKILL.md | {n} | ~{t} | Active skill (on-trigger) |
| metadata.json | {n} | ~{t} | Machine-readable |
| references/ | {n} | ~{t} | {count} files |
| **Package total** | **{n}** | **~{t}** | **This skill's own artifacts (snippet + SKILL.md + metadata + references); excludes the shared Managed section row** |

**Context Budget Impact:**
- **Always-on cost:** ~{managed-section-tokens} tokens (measured in {measured-file}; the managed section is in {target-file-list})
- **On-trigger cost:** ~{skill-tokens} tokens (when SKILL.md is loaded)
- **Full disclosure cost:** ~{total-tokens} tokens (if references/ also loaded)

**Benchmark:** Target is ~80-120 tokens per skill in managed section. Current: ~{snippet-tokens} tokens."

**In multi-skill mode**, render the Context Budget Impact and the Benchmark this way instead: the always-on cost once for the run, then one line per skill, each from that skill's own run:

"**Context Budget Impact:**
- **Always-on cost:** ~{managed-section-tokens} tokens (measured in {measured-file}; the managed section is in {target-file-list})
- **{skill-name}:** on-trigger ~{skill-tokens} tokens, full disclosure ~{total-tokens} tokens, snippet ~{snippet-tokens} tokens

**Benchmark:** Target is ~80-120 tokens per skill in managed section."

### 3. Proceed to Summary

Display: "**Proceeding to export summary...**"

Auto-proceed (no user choices): once the token report is displayed, load, read entirely, and execute `{nextStepFile}`.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall