Structural check: SKILL.md token budget with section-level breakdown

[dacharyc]

Context

From a PR review patterns audit across 7 MongoDB Agent Skills, token efficiency / content placement was the most frequent pattern (14 instances across 5 PRs). SKILL.md is always loaded into context, so every token there has a high cost.

Proposed check

Add an info-level check that reports SKILL.md token count with a section-level breakdown, and a warning when the total exceeds a configurable threshold.

Behavior

1. Info output: For every skill-validator check run, report:

   • Total SKILL.md estimated token count
   • Per-section breakdown (split by ## headings)
   • Largest section highlighted

2. Warning threshold: Flag when SKILL.md exceeds a configurable token budget (suggested default: 3,000 tokens). The threshold should be configurable via CLI flag (e.g., --skill-md-token-budget 3000).

3. Message:

   • Info: SKILL.md: ~{N} tokens ({sections} sections). Largest section: "{name}" (~{M} tokens).
   • Warning: SKILL.md exceeds token budget ({N} tokens > {budget} threshold). Consider moving conditionally-needed content to reference files.

Token estimation

Use a simple whitespace-based heuristic (words × 1.3) or a tiktoken-compatible tokenizer. Exact count is less important than consistent, directional guidance.

Relationship to existing work

• Issue Consider adding title + description token count #30 covers title + description token count (complementary, different scope)
• This check covers the full SKILL.md body content
• Together they give authors visibility into the "always-loaded" token cost of their skill

Examples from PR reviews

PR	Issue
10	Create/update/delete sections always loaded but most invocations are read-only
10	Validation constraints only needed for create operations
9	Atlas Search-only content loads for all search types
6	Inline sections duplicate their respective reference files

Related

Complements #30 (title + description token count). Part of a series of checks derived from PR review pattern analysis.