v0.2.6: skill footprint estimates, agent budget meter, tooltips

- Add shared skill-footprint module (listing slice vs full SKILL.md, aggregates)
- Extend parser/scanner/skill JSON and RPC schema with footprint fields
- Skills UI: dual metrics, agent-filter totals, Settings budget/window hints
- Per-metric native tooltips; compact tok display without ~ prefix
- Bun tests for footprint; exclude *.test.ts from root/node tsc

Made-with: Cursor

Author: beautyfree

package.json

@@ -1,6 +1,6 @@
 {
   "name": "skiller",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "A desktop app for managing AI agent skills across Claude Code, Cursor, Copilot, Gemini CLI, and more",
   "license": "MIT",
   "author": {
@@ -19,6 +19,7 @@
     "build": "electron-vite build",
     "preview": "electron-vite preview",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.node.json --noEmit",
+    "test": "bun test src/shared/skill-footprint.test.ts",
     "dist:mac": "electron-vite build && electron-builder --mac && bash scripts/repack-dmg.sh",
     "dist:win": "electron-vite build && electron-builder --win",
     "dist:linux": "electron-vite build && electron-builder --linux && node scripts/patch-appimage-runtime.mjs artifacts"

src/main/parser.ts

@@ -1,11 +1,28 @@
 import { readFileSync, statSync } from "node:fs";
 import { parse as parseYaml } from "yaml";
 
+function parseFrontmatterBool(v: unknown): boolean | undefined {
+	if (v === true) return true;
+	if (v === false) return false;
+	if (typeof v === "string") {
+		const s = v.trim().toLowerCase();
+		if (s === "true" || s === "1" || s === "yes") return true;
+		if (s === "false" || s === "0" || s === "no") return false;
+	}
+	return undefined;
+}
+
 export type ParsedSkillMd = {
 	name?: string;
 	description?: string;
+	/** Combined with description for listing-size estimates (capped per skill in footprint). */
+	when_to_use?: string;
+	/** When true, description slice is omitted from normal listing (manual invoke). */
+	disable_model_invocation?: boolean;
 	metadata?: unknown;
 	body: string;
+	/** Full SKILL.md character count (entire file). */
+	skill_md_char_count: number;
 };
 
 type ParsedSkillCacheEntry = {
@@ -59,10 +76,22 @@ export function parseSkillMdFile(path: string): ParsedSkillMd {
 
 export function parseSkillMdContent(content: string): ParsedSkillMd {
 	const { fm, body } = splitFrontmatter(content);
+	const whenRaw =
+		typeof fm.when_to_use === "string"
+			? fm.when_to_use
+			: typeof (fm as { whenToUse?: unknown }).whenToUse === "string"
+				? ((fm as { whenToUse: string }).whenToUse as string)
+				: undefined;
+	const disableRaw =
+		parseFrontmatterBool(fm.disable_model_invocation) ??
+		parseFrontmatterBool((fm as { disableModelInvocation?: unknown }).disableModelInvocation);
 	return {
 		name: typeof fm.name === "string" ? fm.name : undefined,
 		description: typeof fm.description === "string" ? fm.description : undefined,
+		when_to_use: whenRaw,
+		disable_model_invocation: disableRaw,
 		metadata: fm.metadata,
 		body,
+		skill_md_char_count: content.length,
 	};
 }

src/main/repos.ts

@@ -13,6 +13,7 @@ import { parse as parseToml } from "@iarna/toml";
 import simpleGit from "simple-git";
 import type { SkillJson } from "../shared/rpc-schema";
 import type { RepoEntryJson } from "../shared/rpc-schema";
+import { computeSkillFootprint } from "../shared/skill-footprint";
 import { installSkillFromPath } from "./install";
 import { parseSkillMdFile } from "./parser";
 import { writeProvenance } from "./provenance";
@@ -172,6 +173,14 @@ function listRepoSkillsSync(repoIdParam: string): Skill[] {
 
 		const dirName = basename(candidate.dir) || "unknown-skill";
 		const skillName = candidate.parsed_name ?? dirName;
+		const fp = computeSkillFootprint({
+			description: parsed.description,
+			when_to_use: parsed.when_to_use,
+			disable_model_invocation: parsed.disable_model_invocation,
+			skill_md_char_count: parsed.skill_md_char_count,
+			display_name: skillName,
+			skill_id: dirName,
+		});
 
 		const source = repoUrl
 			? ({
@@ -188,12 +197,18 @@ function listRepoSkillsSync(repoIdParam: string): Skill[] {
 			id: dirName,
 			name: skillName,
 			description: parsed.description,
+			when_to_use: parsed.when_to_use ?? null,
 			canonical_path: candidate.dir,
 			source,
 			metadata: parsed.metadata,
 			collection: null,
 			scope: { kind: "SharedGlobal" },
 			installations: [],
+			footprint_listing_source_chars: fp.footprint_listing_source_chars,
+			footprint_listing_slice_chars: fp.footprint_listing_slice_chars,
+			footprint_name_chars: fp.footprint_name_chars,
+			footprint_skill_md_chars: fp.footprint_skill_md_chars,
+			listing_excluded: fp.listing_excluded,
 		});
 	}
 

src/main/scanner.ts

@@ -1,5 +1,7 @@
 import { existsSync, lstatSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
+import { computeSkillFootprint } from "../shared/skill-footprint";
+import type { ParsedSkillMd } from "./parser";
 import type { AgentConfig } from "./types";
 import { parseSkillMdFile } from "./parser";
 import { readProvenanceRaw } from "./provenance";
@@ -96,6 +98,25 @@ function collectionFromRealPath(realOrLink: string, skillsRoot: string): string
 	return undefined;
 }
 
+function listingFootprintFromParsed(parsed: ParsedSkillMd, rawName: string, dirName: string) {
+	const fp = computeSkillFootprint({
+		description: parsed.description,
+		when_to_use: parsed.when_to_use,
+		disable_model_invocation: parsed.disable_model_invocation,
+		skill_md_char_count: parsed.skill_md_char_count,
+		display_name: rawName,
+		skill_id: dirName,
+	});
+	return {
+		when_to_use: parsed.when_to_use ?? null,
+		footprint_listing_source_chars: fp.footprint_listing_source_chars,
+		footprint_listing_slice_chars: fp.footprint_listing_slice_chars,
+		footprint_name_chars: fp.footprint_name_chars,
+		footprint_skill_md_chars: fp.footprint_skill_md_chars,
+		listing_excluded: fp.listing_excluded,
+	};
+}
+
 function resolveSource(
 	skillId: string,
 	canonical: string,
@@ -173,6 +194,7 @@ function scanInheritedRoot(
 		const dirName = basename(skillDir);
 		const collection = detectCollection(skillDir, root);
 		const skillName = parsed.name ?? dirName;
+		const fp = listingFootprintFromParsed(parsed, skillName, dirName);
 
 		const installation: SkillInstallation = {
 			agent_slug: agent.slug,
@@ -186,6 +208,7 @@ function scanInheritedRoot(
 			id: dirName,
 			name: skillName,
 			description: parsed.description,
+			...fp,
 			canonical_path: canonical,
 			source: resolveSource(dirName, canonical, provenance),
 			metadata: parsed.metadata,
@@ -234,6 +257,7 @@ function scanSkillMdRoot(
 		const symlink = isSymlink(skillDir);
 		const collection = detectCollection(skillDir, root);
 		const skillId = dirName;
+		const fp = listingFootprintFromParsed(parsed, rawName, dirName);
 
 		const installation: SkillInstallation = {
 			agent_slug: agent.slug,
@@ -249,6 +273,7 @@ function scanSkillMdRoot(
 			id: skillId,
 			name: rawName,
 			description: parsed.description,
+			...fp,
 			canonical_path: canonical,
 			source: resolveSource(skillId, canonical, provenance),
 			metadata: parsed.metadata,

src/main/skill-json.ts

@@ -43,12 +43,18 @@ export function skillToJson(s: Skill): SkillJson {
 		id: s.id,
 		name: s.name,
 		description: s.description ?? null,
+		when_to_use: s.when_to_use ?? null,
 		canonical_path: s.canonical_path,
 		source: s.source ? skillSourceToJson(s.source) : null,
 		metadata: s.metadata ?? null,
 		collection: s.collection ?? null,
 		scope: skillScopeToJson(s.scope),
 		installations: s.installations.map(skillInstallationToJson),
+		footprint_listing_source_chars: s.footprint_listing_source_chars,
+		footprint_listing_slice_chars: s.footprint_listing_slice_chars,
+		footprint_name_chars: s.footprint_name_chars,
+		footprint_skill_md_chars: s.footprint_skill_md_chars,
+		listing_excluded: s.listing_excluded,
 	};
 }
 

src/main/skill-types.ts

@@ -23,12 +23,24 @@ export interface Skill {
 	id: string;
 	name: string;
 	description?: string | null;
+	/** Frontmatter when_to_use (combined with description for listing-size estimate). */
+	when_to_use?: string | null;
 	canonical_path: string;
 	source?: SkillSource | null;
 	metadata?: unknown;
 	collection?: string | null;
 	scope: SkillScope;
 	installations: SkillInstallation[];
+	/** Len(description + when_to_use) before per-entry cap. */
+	footprint_listing_source_chars: number;
+	/** Capped description+when slice used for listing estimate (0 if disable_model_invocation). */
+	footprint_listing_slice_chars: number;
+	/** Display name length (names always included in listing). */
+	footprint_name_chars: number;
+	/** Full SKILL.md file size in characters. */
+	footprint_skill_md_chars: number;
+	/** True when model listing omits description slice (manual invoke). */
+	listing_excluded: boolean;
 }
 
 export interface UpdateProgress {

src/mainview/hooks/useSkills.ts

@@ -17,12 +17,19 @@ export interface Skill {
   id: string;
   name: string;
   description: string | null;
+  when_to_use?: string | null;
   canonical_path: string;
   source: unknown;
   metadata: unknown;
   collection: string | null;
   scope: SkillScope;
   installations: SkillInstallation[];
+  /** Listing estimate: raw len(description + when_to_use) before per-skill cap. */
+  footprint_listing_source_chars?: number;
+  footprint_listing_slice_chars?: number;
+  footprint_name_chars?: number;
+  footprint_skill_md_chars?: number;
+  listing_excluded?: boolean;
 }
 
 /** Direct (non-inherited) agent slugs */

src/mainview/i18n/en.ts

@@ -170,6 +170,20 @@ const en = {
     skillRowMenu: "Skill actions",
     expandCollection: "Expand collection",
     collapseCollection: "Collapse collection",
+    packageSizeLabel: "Size",
+    tokenTooltipListing:
+      "Listing side: description + when_to_use (capped per skill). Approximate tokens = character count ÷ 4; not your model tokenizer.",
+    tokenTooltipFull:
+      "Full skill file (SKILL.md). Approximate tokens = character count ÷ 4; not your model tokenizer.",
+    agentTokensBarOverview:
+      "Approximate token totals for skills in this view. Hover each value for what it measures.",
+    agentTokenTooltipListingSum:
+      "Sum of listing-side estimates: each skill’s description + when_to_use slice (capped), then chars ÷ 4.",
+    agentTokenTooltipFullSum:
+      "Sum of full-file estimates: entire SKILL.md per skill, chars ÷ 4.",
+    listingExcludedTooltip:
+      "Hidden from the agent’s automatic skill list; invoke manually if your tool supports it.",
+    listingExcludedShort: "Excluded from listing",
   },
 
   // === Marketplace ===

src/mainview/pages/Settings.tsx

@@ -24,6 +24,8 @@ interface AppSettings {
   path_overrides: Record<string, string[]> | null
   close_action: string | null
   macos_window_blur?: boolean | null
+  assumed_listing_char_budget?: number | null
+  assumed_context_window_chars?: number | null
 }
 
 const DEFAULT_SETTINGS: AppSettings = {