diff --git a/README.md b/README.md
index 0a0684c..8005fa7 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 A CLI tool that analyzes your Claude Code session history to identify token waste patterns and provide actionable fixes. Runs locally, no LLM needed.
 
-**v2.2** adds human-readable findings with plain-English explanations, collapsible HTML report sections, and evidence-based action items.
+**v2.3** adds `--analyze-skill` — analyze any AI agent skill package for token efficiency with cost estimates, letter grades, section-level breakdowns, and actionable shortening tips. Designed for integration with skill registries like [Tank](https://github.com/tankpkg/tank).
 
 **The mental model: tokenomics is a coach, not a remote control.** It writes suggestions into your CLAUDE.md where Claude can see them. Claude is smart enough to follow most of them — suggesting `/compact` when context grows, recommending Sonnet for simple tasks, warning when you're overspending. But it cannot switch models, run commands, or force behavior. The user is always in control.
 
@@ -240,6 +240,7 @@ Budget config lives at `~/.claude/tokenomics.json`:
 | `--inject` | Re-analyze sessions + update CLAUDE.md findings | false |
 | `--quiet` | Suppress terminal output (used by hooks) | false |
 | `--verbose` | Show discovery progress and debug info | false |
+| `--analyze-skill <dir>` | Analyze skill package for token efficiency | - |
 | `--help` | Show help message | - |
 | `--version` | Show version | - |
 
@@ -264,13 +265,170 @@ Budget config lives at `~/.claude/tokenomics.json`:
 | Subagent Opportunity | Delegation opportunities | Parallel execution |
 | Smart Router | Historical routing patterns | ~80% on simple tasks |
 
+## Skill Analysis (`--analyze-skill`)
+
+Analyze an AI agent skill package directory for token efficiency. Produces a grade (A/B/C/D), cost per use in real money, per-section token breakdowns, and actionable suggestions for what to cut and why.
+
+```bash
+# Terminal report (default)
+tokenomics --analyze-skill ./my-skill
+
+# JSON output (for scripts, CI, Tank integration)
+tokenomics --analyze-skill ./my-skill --json
+```
+
+### Terminal output
+
+```
+  SKILL TOKEN ANALYSIS
+  ──────────────────────────────────────────────────
+
+  "Well-structured skill with no significant waste."
+
+  Grade:  A  (86/100)
+  Size:   33,598 tokens — above average (avg is ~20,000 tokens)
+
+  [░░░░░░░░░░░░░█░░░░░░░░░░░░░░░░]
+           ▲ avg
+
+  Cost per use:  ~$0.18 (Sonnet)  |  ~$0.91 (Opus)
+
+  Findings (3):
+  ● prompt-size [medium]
+    Prompt file "SKILL.md" is ~2,388 tokens (9,549 chars).
+    Consider trimming for faster invocations.
+    Fix: Consider trimming "SKILL.md" to under 2000 tokens.
+    Extract verbose examples into separate reference files.
+
+  ● section-analysis [low]
+    SKILL.md: 2 section(s) overlap each other.
+    Fix: "web app setup" overlaps with "library setup":
+    consolidate shared content into one section.
+    Tip: References 18 specific file paths — consider
+    replacing with a glob pattern or naming convention rule.
+```
+
+### JSON output
+
+With `--json`, the output includes all fields for programmatic consumption:
+
+```json
+{
+  "one_liner": "Slightly above average size. Works fine, could be leaner.",
+  "grade": "B",
+  "estimated_tokens": 8500,
+  "comparison": "8,500 tokens — below average (avg is ~20,000 tokens)",
+  "cost_per_use": {
+    "sonnet": "~$0.05",
+    "opus": "~$0.23"
+  },
+  "what_this_means": "Bigger skills cost more per invocation and leave less room for conversation. Smaller skills respond faster and cost less.",
+  "findings": [
+    {
+      "rule": "section-analysis",
+      "severity": "low",
+      "description": "SKILL.md: 2 section(s) overlap each other...",
+      "remediation": "\"Setup\" overlaps with \"Config\": consolidate...",
+      "sections": [
+        { "heading": "Setup", "tokens": 420, "redundantWith": ["Config"] },
+        { "heading": "Config", "tokens": 380, "redundantWith": ["Setup"] }
+      ]
+    }
+  ],
+  "summary": {
+    "total_findings": 3,
+    "estimated_tokens_per_invocation": 8500,
+    "efficiency_score": 72
+  }
+}
+```
+
+### Report fields
+
+| Field | What it means |
+|-------|---------------|
+| `one_liner` | Plain English summary of the skill's efficiency |
+| `grade` | A (lean) / B (good) / C (bloated) / D (wasteful) |
+| `estimated_tokens` | Total token count across all skill files |
+| `comparison` | How this skill compares to average (~20k tokens) |
+| `cost_per_use` | Real money per invocation on Sonnet and Opus |
+| `what_this_means` | Why size matters: cost + speed + context window competition |
+| `sections[]` | Per-heading token breakdown with redundancy and shortening tips |
+
+### Analysis rules
+
+| Rule | What it checks | Thresholds |
+|------|---------------|------------|
+| `prompt-size` | SKILL.md and `.atom.md` files exceeding token limits | >2000 tokens = medium, >4000 = high |
+| `claude-md-size` | CLAUDE.md injection blocks that bloat system prompts | >1500 tokens = medium, >3000 = high |
+| `tool-overhead` | Tool definitions in manifest (tank.json, skills.json) | >8 tools = medium, >15 = high |
+| `large-files` | Files with >500 lines that are expensive to read | >500 lines = low, >1000 = medium |
+| `redundant-instructions` | Duplicated instruction lines across skill files | >30% duplication = low/medium |
+| `section-analysis` | Per-section token breakdown, cross-file redundancy, content tips | See below |
+
+### Section analysis details
+
+The `section-analysis` rule parses markdown headings and provides:
+
+**Token breakdown**: Every section gets a token count, so you can see exactly where the weight is.
+
+**Cross-file redundancy**: Detects when a section in SKILL.md says the same thing as a section in `references/*.md`. Example: `"The Bridge"` in SKILL.md duplicates `"The Bridge Model"` in `references/orchestration-workflow.md`.
+
+**Content-level shortening tips** (not just structural):
+
+| Tip | What it detects |
+|-----|----------------|
+| Concept repetition | Same key phrase restated 3+ times — state once, reference elsewhere |
+| Restatements | "remember that", "note that", "in other words" — AI understood the first time |
+| Bad/good example pairs | Shows both wrong and right patterns — use a negative constraint rule instead |
+| File path enumeration | 6+ specific paths — replace with glob patterns or naming conventions |
+| Verbose justification | "this is important because" — AI follows rules without persuasion |
+| Large directory trees | ASCII trees >10 lines — keep top-level, link to reference |
+| Repeated lines | Identical lines within a section — dedup or collapse |
+| Code block bloat | 2+ code blocks — replace with file references |
+| Long lists | 8+ list items — group into categories |
+| Table bloat | 15+ table rows — move details to reference files |
+
+### Cost estimation
+
+Based on Claude API pricing with an 80/20 input/output token split:
+
+| Tokens | Sonnet cost | Opus cost |
+|--------|-------------|-----------|
+| 5,000 | ~$0.03 | ~$0.15 |
+| 20,000 (avg) | ~$0.12 | ~$0.59 |
+| 50,000 | ~$0.29 | ~$1.47 |
+| 100,000 | ~$0.59 | ~$2.94 |
+
+Every skill is loaded into context on every turn. A 50k-token skill costs ~$1.47 per turn on Opus — trimming it to 20k saves ~$0.88 per turn.
+
+### Integration with skill registries
+
+Designed to be called as a subprocess from scanning pipelines:
+
+```python
+import subprocess, json
+
+result = subprocess.run(
+    ["tokenomics", "--analyze-skill", skill_dir, "--json"],
+    capture_output=True, text=True, timeout=10
+)
+if result.returncode == 0:
+    analysis = json.loads(result.stdout)
+    print(f"Grade: {analysis['grade']} | Cost: {analysis['cost_per_use']['sonnet']}/use")
+    for finding in analysis["findings"]:
+        print(f"[{finding['severity']}] {finding['rule']}: {finding['description']}")
+```
+
+Graceful degradation: if tokenomics is not installed, skip the stage and continue.
+
 ## Output Examples
 
 ### Terminal
 
 ```
   TOKENOMICS — Token Intelligence for Claude Code
-  60 sessions // 30 day range // v2.2.2
+  60 sessions // 30 day range // v2.3.0
 
   Sessions:   60
   Total:     1.2M tokens
diff --git a/package.json b/package.json
index 7b66cd2..96ad5ee 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "tokenomics",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "Token intelligence for Claude Code — analyze sessions, find waste, get actionable fixes",
   "type": "module",
   "main": "dist/analyze.js",
diff --git a/src/analyze.ts b/src/analyze.ts
index f9980d2..3cf8674 100644
--- a/src/analyze.ts
+++ b/src/analyze.ts
@@ -20,6 +20,7 @@ import { writeFileSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import type { AnalysisOutput, CliOptions, DetectorResult, SessionData } from './types.js';
+import { analyzeSkill, renderSkillReport } from './skill-analyzer.js';
 import { discoverFiles, logDiscoverySummary } from './discovery.js';
 import { extractHumanReadableBlock, renderTerminalBlock } from './recommendation.js';
 import { parseSessionFiles } from './parser.js';
@@ -34,7 +35,7 @@ import { auditPrompt } from './auditor.js';
 import { renderPromptOutput } from './prompt-output.js';
 import { ensureBudgetConfig, readBudgetConfig } from './budget-config.js';
 
-const VERSION = '2.2.2';
+const VERSION = '2.3.0';
 
 // ─── CLI ──────────────────────────────────────────────────────────────────────
 
@@ -60,6 +61,7 @@ function parseCliArgs(): CliOptions {
       budget: { type: 'boolean', default: false },
       'budget-check': { type: 'boolean', default: false },
       'no-alerts': { type: 'boolean', default: false },
+      'analyze-skill': { type: 'string' },
     },
     strict: true,
   });
@@ -88,6 +90,7 @@ function parseCliArgs(): CliOptions {
     budget: values.budget,
     budgetCheck: values['budget-check'],
     noAlerts: values['no-alerts'],
+    analyzeSkill: values['analyze-skill'],
   };
 }
 
@@ -131,6 +134,10 @@ PROMPT ANALYSIS
   --budget-check       Lightweight budget check (for hooks)
   --no-alerts          Suppress budget alerts (no CLAUDE.md injection)
 
+SKILL ANALYSIS
+  --analyze-skill <dir> Analyze skill package for token efficiency
+                       Outputs JSON with findings and efficiency score
+
 OTHER
   --verbose            Show discovery progress and debug info
   --help               Show this message
@@ -516,6 +523,17 @@ async function main(): Promise<void> {
     process.exit(result.ceilingExceeded ? 1 : 0);
   }
 
+  // ── Skill analysis mode ──
+  if (options.analyzeSkill) {
+    const result = analyzeSkill(options.analyzeSkill);
+    if (options.json) {
+      console.log(JSON.stringify(result, null, options.verbose ? 2 : 0));
+    } else {
+      console.log(renderSkillReport(result));
+    }
+    return;
+  }
+
   // Discover JSONL files (auto-detects all ~/.claude* installations)
   const discoveryOpts: import('./types.js').DiscoveryOptions = {
     days: options.days,
diff --git a/src/skill-analyzer.ts b/src/skill-analyzer.ts
new file mode 100644
index 0000000..78b5bfb
--- /dev/null
+++ b/src/skill-analyzer.ts
@@ -0,0 +1,340 @@
+/**
+ * Skill Analyzer Engine
+ *
+ * Analyzes an AI agent skill package directory for token efficiency.
+ * Discovers skill files, runs all skill rules, and returns findings.
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { join, extname, relative } from 'node:path'
+import type { SkillAnalysisContext, SkillAnalysisReport, SkillAnalysisSummary, SkillCostEstimate, SkillFinding, SkillGrade, SkillRule } from './types.js'
+
+// Import all rules
+import * as promptSizeRule from './skill-rules/prompt-size.js'
+import * as claudeMdSizeRule from './skill-rules/claude-md-size.js'
+import * as toolOverheadRule from './skill-rules/tool-overhead.js'
+import * as largeFilesRule from './skill-rules/large-files.js'
+import * as redundantInstructionsRule from './skill-rules/redundant-instructions.js'
+import * as sectionAnalysisRule from './skill-rules/section-analysis.js'
+
+const CHARS_PER_TOKEN = 4
+
+const SKILL_FILES = [
+  'SKILL.md',
+  'CLAUDE.md',
+  'tank.json',
+  'skills.json',
+]
+
+const SKILL_EXTENSIONS = ['.md', '.json']
+
+const rules: SkillRule[] = [
+  { name: 'prompt-size', analyze: promptSizeRule.analyze },
+  { name: 'claude-md-size', analyze: claudeMdSizeRule.analyze },
+  { name: 'tool-overhead', analyze: toolOverheadRule.analyze },
+  { name: 'large-files', analyze: largeFilesRule.analyze },
+  { name: 'redundant-instructions', analyze: redundantInstructionsRule.analyze },
+  { name: 'section-analysis', analyze: sectionAnalysisRule.analyze },
+]
+
+function discoverSkillFiles(dir: string): Map<string, string> {
+  const files = new Map<string, string>()
+
+  function walk(currentDir: string): void {
+    const entries = readdirSync(currentDir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      // Skip symlinks to prevent path traversal
+      if (entry.isSymbolicLink()) continue
+
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === 'dist') continue
+        walk(join(currentDir, entry.name))
+        continue
+      }
+
+      const fullPath = join(currentDir, entry.name)
+      const relativePath = relative(dir, fullPath)
+
+      // Include known skill files or files with skill extensions
+      const isKnownFile = SKILL_FILES.some(f => entry.name.toLowerCase() === f.toLowerCase())
+      const isAtomFile = entry.name.toLowerCase().endsWith('.atom.md')
+      const hasSkillExt = SKILL_EXTENSIONS.includes(extname(entry.name).toLowerCase())
+
+      if (isKnownFile || isAtomFile || hasSkillExt) {
+        try {
+          const content = readFileSync(fullPath, 'utf-8')
+          files.set(relativePath, content)
+        } catch {
+          // Skip unreadable files
+        }
+      }
+    }
+  }
+
+  walk(dir)
+  return files
+}
+
+function loadManifest(files: Map<string, string>): Record<string, unknown> | null {
+  // Try tank.json first, then skills.json
+  for (const manifestName of ['tank.json', 'skills.json']) {
+    for (const [filename, content] of files) {
+      if (filename.toLowerCase().endsWith(manifestName.toLowerCase())) {
+        try {
+          return JSON.parse(content) as Record<string, unknown>
+        } catch {
+          // Invalid JSON, skip
+        }
+      }
+    }
+  }
+  return null
+}
+
+function estimateTokens(files: Map<string, string>): number {
+  let totalChars = 0
+  for (const content of files.values()) {
+    totalChars += content.length
+  }
+  return Math.ceil(totalChars / CHARS_PER_TOKEN)
+}
+
+// ── Cost estimation ──────────────────────────────────────────────────────────
+
+// Approximate USD per 1M tokens (as of 2026)
+const SONNET_INPUT_PER_M = 3.00
+const SONNET_OUTPUT_PER_M = 15.00
+const OPUS_INPUT_PER_M = 15.00
+const OPUS_OUTPUT_PER_M = 75.00
+
+// Assume ~80% input / ~20% output split for skill context loading
+const INPUT_RATIO = 0.8
+const OUTPUT_RATIO = 0.2
+
+const AVG_SKILL_TOKENS = 20000
+
+function estimateCost(tokens: number): SkillCostEstimate {
+  const tokenMillions = tokens / 1_000_000
+  const sonnetCost = tokenMillions * (SONNET_INPUT_PER_M * INPUT_RATIO + SONNET_OUTPUT_PER_M * OUTPUT_RATIO)
+  const opusCost = tokenMillions * (OPUS_INPUT_PER_M * INPUT_RATIO + OPUS_OUTPUT_PER_M * OUTPUT_RATIO)
+
+  return {
+    sonnet: formatUsd(sonnetCost),
+    opus: formatUsd(opusCost),
+  }
+}
+
+function formatUsd(amount: number): string {
+  if (amount < 0.001) return '<$0.001'
+  if (amount < 0.01) return `~$${amount.toFixed(3)}`
+  if (amount < 0.1) return `~$${amount.toFixed(2)}`
+  if (amount < 1) return `~$${amount.toFixed(2)}`
+  return `~$${amount.toFixed(2)}`
+}
+
+// ── Grading ──────────────────────────────────────────────────────────────────
+
+function calculateGrade(score: number): SkillGrade {
+  if (score >= 85) return 'A'
+  if (score >= 65) return 'B'
+  if (score >= 40) return 'C'
+  return 'D'
+}
+
+function calculateEfficiencyScore(findings: SkillFinding[], totalTokens: number): number {
+  let score = 100
+
+  for (const finding of findings) {
+    const deduction = finding.severity === 'high' ? 15
+      : finding.severity === 'medium' ? 8
+      : finding.severity === 'low' ? 3
+      : 1 // info
+    score -= deduction
+  }
+
+  if (totalTokens < 1000) score = Math.min(score + 10, 100)
+
+  return Math.max(0, Math.min(100, score))
+}
+
+// ── Plain-English summaries ──────────────────────────────────────────────────
+
+function generateOneLiner(grade: SkillGrade, tokens: number, findingsCount: number): string {
+  if (grade === 'A' && tokens < 5000) return 'Lean and efficient. No meaningful improvements needed.'
+  if (grade === 'A') return 'Well-structured skill with no significant waste.'
+  if (grade === 'B') {
+    if (findingsCount <= 2) return 'Slightly above average size. Works fine, could be leaner.'
+    return 'Good shape overall, with a few areas that could be tightened up.'
+  }
+  if (grade === 'C') return 'Carries noticeable token overhead. Several sections could be trimmed or consolidated.'
+  return 'Bloated — significant token waste. Multiple sections duplicate content or over-explain.'
+}
+
+function generateComparison(tokens: number): string {
+  const ratio = tokens / AVG_SKILL_TOKENS
+  if (ratio < 0.3) return `${tokens.toLocaleString()} tokens — much smaller than avg (~${AVG_SKILL_TOKENS.toLocaleString()} tokens)`
+  if (ratio < 0.7) return `${tokens.toLocaleString()} tokens — below average (avg is ~${AVG_SKILL_TOKENS.toLocaleString()} tokens)`
+  if (ratio < 1.3) return `${tokens.toLocaleString()} tokens — about average for a skill (~${AVG_SKILL_TOKENS.toLocaleString()} tokens)`
+  if (ratio < 2.0) return `${tokens.toLocaleString()} tokens — above average (avg is ~${AVG_SKILL_TOKENS.toLocaleString()} tokens)`
+  return `${tokens.toLocaleString()} tokens — much larger than avg (~${AVG_SKILL_TOKENS.toLocaleString()} tokens)`
+}
+
+function generateWhatThisMeans(tokens: number): string {
+  const ratio = tokens / AVG_SKILL_TOKENS
+  if (ratio < 0.5) return 'Low overhead — the AI loads this context quickly and cheaply. No action needed.'
+  if (ratio < 1.2) return 'Bigger skills cost more per invocation and leave less room for conversation. Smaller skills respond faster and cost less.'
+  return 'This skill is expensive to load on every turn — every byte competes with your actual conversation for the context window. Trimming it saves real money and improves response speed.'
+}
+
+// ── Size bar ─────────────────────────────────────────────────────────────────
+
+function sizeBar(tokens: number): string {
+  const maxTokens = 80000
+  const barWidth = 30
+  const fill = Math.min(Math.round((tokens / maxTokens) * barWidth), barWidth)
+  const avgPos = Math.min(Math.round((AVG_SKILL_TOKENS / maxTokens) * barWidth), barWidth - 1)
+  const bar = '░'.repeat(fill) + '█' + '░'.repeat(Math.max(barWidth - fill - 1, 0))
+  const marker = ' '.repeat(avgPos) + '▲'
+  return `[${bar}]\n [${marker} avg]`
+}
+
+// ── Main export ──────────────────────────────────────────────────────────────
+
+export function analyzeSkill(dir: string): SkillAnalysisReport {
+  // Validate directory
+  if (!existsSync(dir)) {
+    throw new Error(`Directory not found: ${dir}`)
+  }
+
+  if (!statSync(dir).isDirectory()) {
+    throw new Error(`Not a directory: ${dir}`)
+  }
+
+  // Discover and read files
+  const files = discoverSkillFiles(dir)
+  const manifest = loadManifest(files)
+
+  // Build analysis context
+  const context: SkillAnalysisContext = {
+    skillDir: dir,
+    files,
+    skillManifest: manifest,
+  }
+
+  // Run all rules
+  const allFindings: SkillFinding[] = []
+  for (const rule of rules) {
+    const ruleFindings = rule.analyze(context)
+    allFindings.push(...ruleFindings)
+  }
+
+  // Calculate summary
+  const estimatedTokens = estimateTokens(files)
+  const efficiencyScore = calculateEfficiencyScore(allFindings, estimatedTokens)
+  const grade = calculateGrade(efficiencyScore)
+
+  const summary: SkillAnalysisSummary = {
+    total_findings: allFindings.length,
+    estimated_tokens_per_invocation: estimatedTokens,
+    efficiency_score: efficiencyScore,
+  }
+
+  return {
+    one_liner: generateOneLiner(grade, estimatedTokens, allFindings.length),
+    grade,
+    estimated_tokens: estimatedTokens,
+    comparison: generateComparison(estimatedTokens),
+    cost_per_use: estimateCost(estimatedTokens),
+    what_this_means: generateWhatThisMeans(estimatedTokens),
+    findings: allFindings,
+    summary,
+  }
+}
+
+// ── Terminal renderer ────────────────────────────────────────────────────────
+
+function gradeColor(grade: SkillGrade): string {
+  switch (grade) {
+    case 'A': return '\x1b[32m'  // green
+    case 'B': return '\x1b[33m'  // yellow
+    case 'C': return '\x1b[33m\x1b[1m' // bold yellow
+    case 'D': return '\x1b[31m\x1b[1m' // bold red
+  }
+}
+
+function severityIcon(sev: string): string {
+  switch (sev) {
+    case 'high': return '\x1b[31m●\x1b[0m'
+    case 'medium': return '\x1b[33m●\x1b[0m'
+    case 'low': return '\x1b[36m●\x1b[0m'
+    default: return '\x1b[2m●\x1b[0m'
+  }
+}
+
+function wrapText(text: string, width: number): string[] {
+  const words = text.split(' ')
+  const lines: string[] = []
+  let current = ''
+  for (const word of words) {
+    if (current.length + word.length + 1 > width && current.length > 0) {
+      lines.push(current)
+      current = word
+    } else {
+      current = current.length === 0 ? word : `${current} ${word}`
+    }
+  }
+  if (current.length > 0) lines.push(current)
+  return lines
+}
+
+export function renderSkillReport(report: SkillAnalysisReport): string {
+  const bold = '\x1b[1m'
+  const dim = '\x1b[2m'
+  const reset = '\x1b[0m'
+  const cyan = '\x1b[36m'
+  const gc = gradeColor(report.grade)
+
+  const lines: string[] = []
+  lines.push('')
+  lines.push(`${cyan}${bold}  SKILL TOKEN ANALYSIS${reset}`)
+  lines.push(`${dim}  ${'─'.repeat(50)}${reset}`)
+  lines.push('')
+  lines.push(`  ${bold}"${report.one_liner}"${reset}`)
+  lines.push('')
+  lines.push(`  Grade:  ${gc}${bold}${report.grade}${reset}  (${report.summary.efficiency_score}/100)`)
+  lines.push(`  Size:   ${report.comparison}`)
+  lines.push('')
+  lines.push(`  ${sizeBar(report.estimated_tokens)}`)
+  lines.push('')
+  lines.push(`  Cost per use:  ${report.cost_per_use.sonnet} (Sonnet)  |  ${report.cost_per_use.opus} (Opus)`)
+  lines.push('')
+
+  if (report.findings.length > 0) {
+    lines.push(`  ${bold}Findings (${report.findings.length}):${reset}`)
+    for (const f of report.findings) {
+      const icon = severityIcon(f.severity)
+      lines.push(`  ${icon} ${bold}${f.rule}${reset} [${f.severity}]`)
+      // Wrap description to 76 chars (terminal width minus indentation)
+      for (const ln of wrapText(f.description, 76)) {
+        lines.push(`    ${dim}${ln}${reset}`)
+      }
+      if (f.remediation) {
+        for (const remediationLine of f.remediation.split('\n')) {
+          for (const ln of wrapText(`Fix: ${remediationLine}`, 76)) {
+            lines.push(`    ${dim}${ln}${reset}`)
+          }
+        }
+      }
+      lines.push('')
+    }
+  } else {
+    lines.push(`  ${dim}No findings. Structure looks clean.${reset}`)
+    lines.push('')
+  }
+
+  lines.push(`  ${dim}${report.what_this_means}${reset}`)
+  lines.push('')
+
+  return lines.join('\n')
+}
diff --git a/src/skill-rules/claude-md-size.ts b/src/skill-rules/claude-md-size.ts
new file mode 100644
index 0000000..7646e6d
--- /dev/null
+++ b/src/skill-rules/claude-md-size.ts
@@ -0,0 +1,91 @@
+/**
+ * CLAUDE.md Size Rule
+ *
+ * Detects CLAUDE.md injection blocks and flags oversized ones.
+ * Looks for <!-- TOKENOMICS:START --> markers or large markdown blocks
+ * in CLAUDE.md files.
+ *
+ * Thresholds:
+ *   >1500 tokens (6000 chars) → medium
+ *   >3000 tokens (12000 chars) → high
+ */
+
+import type { SkillAnalysisContext, SkillFinding } from '../types.js'
+
+const CHARS_PER_TOKEN = 4
+const MEDIUM_TOKEN_THRESHOLD = 1500
+const HIGH_TOKEN_THRESHOLD = 3000
+
+export function analyze(context: SkillAnalysisContext): SkillFinding[] {
+  const findings: SkillFinding[] = []
+
+  for (const [filename, content] of context.files) {
+    if (!filename.toLowerCase().includes('claude.md')) continue
+
+    // Check for TOKENOMICS injection blocks
+    const tokenomicsBlocks = extractTokenomicsBlocks(content)
+    if (tokenomicsBlocks.length > 0) {
+      for (const block of tokenomicsBlocks) {
+        const tokenEstimate = Math.ceil(block.length / CHARS_PER_TOKEN)
+        flagBlock(findings, filename, tokenEstimate, 'tokenomics injection block')
+      }
+      continue
+    }
+
+    // No injection markers — evaluate the whole file if it looks like an injection target
+    const tokenEstimate = Math.ceil(content.length / CHARS_PER_TOKEN)
+    flagBlock(findings, filename, tokenEstimate, 'CLAUDE.md content')
+  }
+
+  return findings
+}
+
+function extractTokenomicsBlocks(content: string): string[] {
+  const blocks: string[] = []
+  const startMarker = '<!-- TOKENOMICS:START'
+  const endMarker = '<!-- TOKENOMICS:END'
+
+  let searchFrom = 0
+  while (searchFrom < content.length) {
+    const startIdx = content.indexOf(startMarker, searchFrom)
+    if (startIdx === -1) break
+
+    const endIdx = content.indexOf(endMarker, startIdx)
+    if (endIdx === -1) break
+
+    // Include from start marker to end of end marker line
+    const endOfBlock = content.indexOf('\n', endIdx)
+    const blockEnd = endOfBlock === -1 ? content.length : endOfBlock
+    blocks.push(content.slice(startIdx, blockEnd))
+    searchFrom = blockEnd
+  }
+
+  return blocks
+}
+
+function flagBlock(
+  findings: SkillFinding[],
+  filename: string,
+  tokenEstimate: number,
+  blockDescription: string,
+): void {
+  if (tokenEstimate > HIGH_TOKEN_THRESHOLD) {
+    findings.push({
+      rule: 'claude-md-size',
+      severity: 'high',
+      confidence: 0.9,
+      description: `${blockDescription} in "${filename}" is ~${tokenEstimate.toLocaleString()} tokens. This injects into every session's system prompt.`,
+      location: filename,
+      remediation: `Reduce the ${blockDescription} in "${filename}" to under ${HIGH_TOKEN_THRESHOLD} tokens. Use dynamic placeholders or move static content to files that are read on demand.`,
+    })
+  } else if (tokenEstimate > MEDIUM_TOKEN_THRESHOLD) {
+    findings.push({
+      rule: 'claude-md-size',
+      severity: 'medium',
+      confidence: 0.85,
+      description: `${blockDescription} in "${filename}" is ~${tokenEstimate.toLocaleString()} tokens. Every session pays this context cost.`,
+      location: filename,
+      remediation: `Trim the ${blockDescription} in "${filename}" to under ${MEDIUM_TOKEN_THRESHOLD} tokens. Remove redundant instructions or consolidate overlapping guidance.`,
+    })
+  }
+}
diff --git a/src/skill-rules/large-files.ts b/src/skill-rules/large-files.ts
new file mode 100644
index 0000000..f4041bc
--- /dev/null
+++ b/src/skill-rules/large-files.ts
@@ -0,0 +1,32 @@
+/**
+ * Large Files Rule
+ *
+ * Flags files >500 lines that would be expensive to read during skill execution.
+ * Large files in a skill package indicate potential token waste when the AI reads them.
+ */
+
+import type { SkillAnalysisContext, SkillFinding } from '../types.js'
+
+const CHARS_PER_TOKEN = 4
+const LINE_THRESHOLD = 500
+
+export function analyze(context: SkillAnalysisContext): SkillFinding[] {
+  const findings: SkillFinding[] = []
+
+  for (const [filename, content] of context.files) {
+    const lineCount = content.split('\n').length
+
+    if (lineCount > LINE_THRESHOLD) {
+      findings.push({
+        rule: 'large-files',
+        severity: lineCount > 1000 ? 'medium' : 'low',
+        confidence: 0.8,
+        description: `"${filename}" is ${lineCount.toLocaleString()} lines. Reading this file costs ~${Math.ceil(content.length / CHARS_PER_TOKEN).toLocaleString()} tokens per invocation.`,
+        location: filename,
+        remediation: `Split "${filename}" into smaller, focused files. Use lazy-loading: keep an index/summary file and load detailed sections only when needed.`,
+      })
+    }
+  }
+
+  return findings
+}
diff --git a/src/skill-rules/prompt-size.ts b/src/skill-rules/prompt-size.ts
new file mode 100644
index 0000000..4615f55
--- /dev/null
+++ b/src/skill-rules/prompt-size.ts
@@ -0,0 +1,57 @@
+/**
+ * Prompt Size Rule
+ *
+ * Flags SKILL.md and .atom.md files that exceed token thresholds.
+ * Token estimation: 1 token ≈ 4 characters.
+ *
+ * Thresholds:
+ *   >2000 tokens (8000 chars) → medium
+ *   >4000 tokens (16000 chars) → high
+ */
+
+import type { SkillAnalysisContext, SkillFinding } from '../types.js'
+
+const CHARS_PER_TOKEN = 4
+const MEDIUM_TOKEN_THRESHOLD = 2000
+const HIGH_TOKEN_THRESHOLD = 4000
+
+const PROMPT_FILE_PATTERNS = [
+  /^SKILL\.md$/i,
+  /\.atom\.md$/i,
+]
+
+function isPromptFile(filename: string): boolean {
+  return PROMPT_FILE_PATTERNS.some(p => p.test(filename))
+}
+
+export function analyze(context: SkillAnalysisContext): SkillFinding[] {
+  const findings: SkillFinding[] = []
+
+  for (const [filename, content] of context.files) {
+    if (!isPromptFile(filename)) continue
+
+    const tokenEstimate = Math.ceil(content.length / CHARS_PER_TOKEN)
+
+    if (tokenEstimate > HIGH_TOKEN_THRESHOLD) {
+      findings.push({
+        rule: 'prompt-size',
+        severity: 'high',
+        confidence: 0.95,
+        description: `Prompt file "${filename}" is ~${tokenEstimate.toLocaleString()} tokens (${content.length.toLocaleString()} chars). This loads into context on every skill invocation.`,
+        location: filename,
+        remediation: `Trim "${filename}" to under ${HIGH_TOKEN_THRESHOLD} tokens. Move detailed examples, edge cases, or reference material to separate files that are read on demand. Keep the core instructions concise.`,
+      })
+    } else if (tokenEstimate > MEDIUM_TOKEN_THRESHOLD) {
+      findings.push({
+        rule: 'prompt-size',
+        severity: 'medium',
+        confidence: 0.9,
+        description: `Prompt file "${filename}" is ~${tokenEstimate.toLocaleString()} tokens (${content.length.toLocaleString()} chars). Consider trimming for faster invocations.`,
+        location: filename,
+        remediation: `Consider trimming "${filename}" to under ${MEDIUM_TOKEN_THRESHOLD} tokens. Extract verbose examples or lengthy explanations into separate reference files.`,
+      })
+    }
+  }
+
+  return findings
+}
diff --git a/src/skill-rules/redundant-instructions.ts b/src/skill-rules/redundant-instructions.ts
new file mode 100644
index 0000000..8659588
--- /dev/null
+++ b/src/skill-rules/redundant-instructions.ts
@@ -0,0 +1,96 @@
+/**
+ * Redundant Instructions Rule
+ *
+ * Detects repeated instruction patterns across skill files (SKILL.md, .atom.md, CLAUDE.md).
+ * Flags when >30% of instruction lines are duplicates across files.
+ *
+ * Uses line-level deduplication with normalization:
+ * - Lowercased, trimmed, collapsed whitespace
+ * - Ignores blank lines and very short lines (<20 chars)
+ */
+
+import type { SkillAnalysisContext, SkillFinding } from '../types.js'
+
+const DUPLICATION_THRESHOLD = 0.3
+const MIN_LINE_LENGTH = 20
+
+const SKILL_FILE_PATTERNS = [
+  /SKILL\.md$/i,
+  /\.atom\.md$/i,
+  /CLAUDE\.md$/i,
+]
+
+function isSkillFile(filename: string): boolean {
+  return SKILL_FILE_PATTERNS.some(p => p.test(filename))
+}
+
+function normalizeLine(line: string): string {
+  return line.toLowerCase().trim().replace(/\s+/g, ' ')
+}
+
+export function analyze(context: SkillAnalysisContext): SkillFinding[] {
+  const findings: SkillFinding[] = []
+
+  // Collect normalized lines per skill file
+  const fileLines = new Map<string, string[]>()
+  for (const [filename, content] of context.files) {
+    if (!isSkillFile(filename)) continue
+    const lines = content
+      .split('\n')
+      .map(normalizeLine)
+      .filter(l => l.length >= MIN_LINE_LENGTH)
+    fileLines.set(filename, lines)
+  }
+
+  if (fileLines.size < 2) return findings
+
+  // Count total unique lines and total lines
+  const allLines: string[] = []
+  // Track how many times each line appears across all files (with file source)
+  const lineFileCount = new Map<string, { count: number; files: string[] }>()
+
+  for (const [filename, lines] of fileLines) {
+    for (const line of lines) {
+      allLines.push(line)
+      const entry = lineFileCount.get(line) ?? { count: 0, files: [] }
+      entry.count++
+      if (!entry.files.includes(filename)) {
+        entry.files.push(filename)
+      }
+      lineFileCount.set(line, entry)
+    }
+  }
+
+  const totalLines = allLines.length
+  if (totalLines === 0) return findings
+
+  // Count duplicated lines: lines that appear in 2+ different files
+  const duplicatedLines = [...lineFileCount.entries()]
+    .filter(([, entry]) => entry.files.length >= 2)
+
+  // Count actual duplicated occurrences (total occurrences minus one per unique line)
+  const duplicatedCount = duplicatedLines.reduce((sum, [, entry]) => {
+    // All occurrences beyond the first file's count are redundant
+    return sum + entry.count - Math.ceil(entry.count / entry.files.length)
+  }, 0)
+
+  const duplicationRate = duplicatedCount / totalLines
+
+  if (duplicationRate > DUPLICATION_THRESHOLD) {
+    const exampleDuplicates = duplicatedLines
+      .slice(0, 3)
+      .map(([line, entry]) => `"${line.slice(0, 60)}${line.length > 60 ? '...' : ''}" in ${entry.files.join(', ')}`)
+      .join('\n    ')
+
+    findings.push({
+      rule: 'redundant-instructions',
+      severity: duplicationRate > 0.5 ? 'medium' : 'low',
+      confidence: 0.75,
+      description: `${Math.round(duplicationRate * 100)}% of instruction lines are duplicated across skill files. ${duplicatedCount} of ${totalLines} lines are redundant, wasting tokens on every invocation.`,
+      location: [...fileLines.keys()].join(', '),
+      remediation: `Consolidate shared instructions into a single file and reference it from others. Remove duplicated lines from individual files. Examples:\n    ${exampleDuplicates}`,
+    })
+  }
+
+  return findings
+}
diff --git a/src/skill-rules/section-analysis.ts b/src/skill-rules/section-analysis.ts
new file mode 100644
index 0000000..017b535
--- /dev/null
+++ b/src/skill-rules/section-analysis.ts
@@ -0,0 +1,426 @@
+/**
+ * Section Analysis Rule
+ *
+ * Parses markdown files into sections (by headings) and:
+ * 1. Reports per-section token counts (always for files >1000 tokens)
+ * 2. Detects sections with redundant/overlapping content (within file AND cross-file)
+ * 3. Suggests which sections can be shortened and why
+ *
+ * Analyzes SKILL.md, .atom.md, and reference files under references/.
+ */
+
+import type { SkillAnalysisContext, SkillFinding, SkillSection } from '../types.js'
+
+const CHARS_PER_TOKEN = 4
+const SECTION_TOKEN_THRESHOLD = 500
+const LARGE_SECTION_THRESHOLD = 1000
+const FILE_TOKEN_BREAKDOWN_THRESHOLD = 1000 // Always report breakdown for files above this
+
+const PROMPT_FILE_PATTERNS = [
+  /^SKILL\.md$/i,
+  /\.atom\.md$/i,
+]
+
+const ALL_MD_PATTERN = /\.md$/i
+
+function isPromptFile(filename: string): boolean {
+  return PROMPT_FILE_PATTERNS.some(p => p.test(filename))
+}
+
+function isMarkdownFile(filename: string): boolean {
+  return ALL_MD_PATTERN.test(filename)
+}
+
+interface ParsedSection {
+  heading: string
+  level: number
+  lineStart: number
+  content: string
+  tokens: number
+}
+
+interface FileSections {
+  filename: string
+  sections: ParsedSection[]
+  totalTokens: number
+}
+
+function parseSections(content: string): ParsedSection[] {
+  const lines = content.split('\n')
+  const sections: ParsedSection[] = []
+  let currentHeading = '(preamble)'
+  let currentLevel = 0
+  let currentLineStart = 0
+  let currentLines: string[] = []
+
+  for (let i = 0; i < lines.length; i++) {
+    // Match markdown headings: # through ######, also handle frontmatter (---)
+    const headingMatch = lines[i]!.match(/^(#{1,6})\s+(.+)$/)
+    if (headingMatch) {
+      // Flush previous section
+      if (currentLines.length > 0 || currentHeading !== '(preamble)') {
+        const sectionContent = currentLines.join('\n')
+        sections.push({
+          heading: currentHeading,
+          level: currentLevel,
+          lineStart: currentLineStart,
+          content: sectionContent,
+          tokens: Math.ceil(sectionContent.length / CHARS_PER_TOKEN),
+        })
+      }
+      currentHeading = headingMatch[2]!.trim()
+      currentLevel = headingMatch[1]!.length
+      currentLineStart = i
+      currentLines = []
+    } else {
+      currentLines.push(lines[i]!)
+    }
+  }
+
+  // Flush last section
+  const lastContent = currentLines.join('\n')
+  if (lastContent.trim().length > 0 || currentHeading !== '(preamble)') {
+    sections.push({
+      heading: currentHeading,
+      level: currentLevel,
+      lineStart: currentLineStart,
+      content: lastContent,
+      tokens: Math.ceil(lastContent.length / CHARS_PER_TOKEN),
+    })
+  }
+
+  return sections
+}
+
+function normalizeContent(content: string): string {
+  return content
+    .toLowerCase()
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/`[^`]+`/g, '')
+    .replace(/[^\w\s]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+function jaccardSimilarity(textA: string, textB: string): number {
+  const normA = normalizeContent(textA)
+  const normB = normalizeContent(textB)
+  if (normA.length < 20 || normB.length < 20) return 0
+
+  const wordsA = new Set(normA.split(' ').filter(w => w.length > 3))
+  const wordsB = new Set(normB.split(' ').filter(w => w.length > 3))
+  if (wordsA.size === 0 || wordsB.size === 0) return 0
+
+  const intersection = [...wordsA].filter(w => wordsB.has(w))
+  const union = new Set([...wordsA, ...wordsB])
+  return intersection.length / union.size
+}
+
+interface RedundancyLink {
+  sourceFile: string
+  sourceSection: string
+  targetFile: string
+  targetSection: string
+  similarity: number
+}
+
+interface RedundancyPeer {
+  file: string
+  section: string
+}
+
+function detectRedundancy(allFileSections: FileSections[]): RedundancyLink[] {
+  const links: RedundancyLink[] = []
+  const allSections: Array<{ file: string; section: ParsedSection }> = []
+
+  for (const fs of allFileSections) {
+    for (const s of fs.sections) {
+      allSections.push({ file: fs.filename, section: s })
+    }
+  }
+
+  for (let i = 0; i < allSections.length; i++) {
+    const a = allSections[i]!
+    if (a.section.tokens < 20) continue // Skip tiny sections
+
+    for (let j = i + 1; j < allSections.length; j++) {
+      const b = allSections[j]!
+      if (b.section.tokens < 20) continue
+
+      const similarity = jaccardSimilarity(a.section.content, b.section.content)
+      if (similarity > 0.25) {
+        links.push({
+          sourceFile: a.file,
+          sourceSection: a.section.heading,
+          targetFile: b.file,
+          targetSection: b.section.heading,
+          similarity,
+        })
+      }
+    }
+  }
+
+  return links.sort((a, b) => b.similarity - a.similarity)
+}
+
+function getShorteningTip(section: ParsedSection): string | undefined {
+  const lines = section.content.split('\n').filter(l => l.trim().length > 0)
+  const tips: string[] = []
+
+  // Check for repeated lines
+  const lineCounts = new Map<string, number>()
+  for (const line of lines) {
+    const norm = line.toLowerCase().trim()
+    if (norm.length < 20) continue
+    lineCounts.set(norm, (lineCounts.get(norm) ?? 0) + 1)
+  }
+  const repeatedLines = [...lineCounts.entries()].filter(([, c]) => c > 1)
+  if (repeatedLines.length > 0) {
+    const example = repeatedLines[0]![0]!.slice(0, 60)
+    tips.push(`Contains ${repeatedLines.length} repeated line(s), e.g. "${example}..."`)
+  }
+
+  // Check for code blocks
+  const codeBlockCount = (section.content.match(/```/g) ?? []).length / 2
+  if (codeBlockCount >= 2) {
+    tips.push(`Has ${Math.floor(codeBlockCount)} code blocks — consider replacing examples with file references`)
+  }
+
+  // Check for list items that could be collapsed
+  const listItems = lines.filter(l => /^\s*[-*]\s/.test(l) || /^\s*\d+\.\s/.test(l))
+  if (listItems.length > 8) {
+    tips.push(`${listItems.length} list items — consider grouping into categories or moving details to separate files`)
+  }
+
+  // Check for table-heavy content
+  const tableRows = lines.filter(l => /^\|/.test(l.trim()))
+  if (tableRows.length > 15) {
+    tips.push(`${tableRows.length} table rows — consider moving detailed tables to reference files and keeping only a summary`)
+  }
+
+  // ── Content-level suggestions ──────────────────────────────────────────
+
+  const normalizedContent = normalizeContent(section.content)
+
+  // Detect concept repetition: same key phrase appearing many times
+  const PHRASE_MIN_LENGTH = 4
+  const words = normalizedContent.split(' ').filter(w => w.length > 2)
+  const phraseCounts = new Map<string, number>()
+  for (let i = 0; i < words.length - PHRASE_MIN_LENGTH; i++) {
+    const phrase = words.slice(i, i + PHRASE_MIN_LENGTH).join(' ')
+    phraseCounts.set(phrase, (phraseCounts.get(phrase) ?? 0) + 1)
+  }
+  const repeatedPhrases = [...phraseCounts.entries()].filter(([, c]) => c >= 3)
+  if (repeatedPhrases.length > 0) {
+    const topPhrase = repeatedPhrases.sort((a, b) => b[1]! - a[1]!)[0]!
+    tips.push(`Concept "${topPhrase[0]!.slice(0, 50)}..." is restated ${topPhrase[1]!} times — state the rule once, reference it elsewhere`)
+  }
+
+  // Detect restatement patterns: "X is Y" followed later by "X means Y" or "remember: X is Y"
+  const restatementPatterns = [
+    /remember.{0,10}(that|:)\s/gi,
+    /note.{0,5}(that|:)\s/gi,
+    /this (is|means)\s/gi,
+    /in other words/gi,
+    /that (is to say|means)\s/gi,
+    /this is (non-)?negotiable/gi,
+  ]
+  let restatementCount = 0
+  for (const pattern of restatementPatterns) {
+    const matches = section.content.match(pattern)
+    if (matches) restatementCount += matches.length
+  }
+  if (restatementCount >= 2) {
+    tips.push(`${restatementCount} restatement(s) detected ("remember that", "note that", "in other words") — the AI already understood the first time; remove re-explanations`)
+  }
+
+  // Detect anti-pattern examples that double the content
+  // Pattern: shows bad example then immediately shows the fix
+  const badGoodPairs = section.content.match(/\bad\b|\bwrong\b|\bdon't\b|\bavoid\b|\bnever\b/gi) ?? []
+  const goodExamples = section.content.match(/\bgood\b|\bcorrect\b|\bfixed\b|\bfixed\b|\binstead\b|\brather\b/gi) ?? []
+  if (badGoodPairs.length >= 3 && goodExamples.length >= 3) {
+    tips.push(`Shows ${badGoodPairs.length} bad examples alongside good ones — consider showing only the correct pattern and stating the rule as a negative constraint (e.g. "never do X")`)
+  }
+
+  // Detect overly specific enumeration that could be a rule
+  // e.g. listing 8 specific file paths when a glob pattern or rule would suffice
+  const specificPaths = section.content.match(/[\w/-]+\.\w{2,4}/g) ?? []
+  const uniquePaths = new Set(specificPaths.map(p => p.toLowerCase()))
+  if (uniquePaths.size > 6) {
+    tips.push(`References ${uniquePaths.size} specific file paths — consider replacing some with a glob pattern or naming convention rule`)
+  }
+
+  // Detect verbose justification that the AI doesn't need
+  // "This is important because..." / "The reason for this is..." / "Why? Because..."
+  const justificationPatterns = section.content.match(/(this is important|the reason for|why\? because|this matters because|this is critical because)/gi) ?? []
+  if (justificationPatterns.length >= 2) {
+    tips.push(`${justificationPatterns.length} justification(s) ("this is important because", "the reason for") — the AI follows instructions without needing persuasion; state the rule directly`)
+  }
+
+  // Detect duplicate directory trees / ASCII diagrams
+  const treeLineCount = lines.filter(l => /^[├└│─┤┬┴┼┌┐└┘││  ]+[a-z]/.test(l) || /^\s+[a-z_]+\/\s*$/i.test(l)).length
+  if (treeLineCount > 10) {
+    tips.push(`Directory tree is ${treeLineCount} lines — consider keeping only the top-level structure and linking to a reference file for the full tree`)
+  }
+
+  return tips.length > 0 ? tips.join('. ') + '.' : undefined
+}
+
+export function analyze(context: SkillAnalysisContext): SkillFinding[] {
+  const findings: SkillFinding[] = []
+
+  // Parse all markdown files into sections
+  const promptFileSections: FileSections[] = []
+  const referenceFileSections: FileSections[] = []
+
+  for (const [filename, content] of context.files) {
+    if (!isMarkdownFile(filename)) continue
+    if (content.trim().length === 0) continue
+
+    const sections = parseSections(content)
+    if (sections.length === 0) continue
+
+    const totalTokens = Math.ceil(content.length / CHARS_PER_TOKEN)
+    const entry: FileSections = { filename, sections, totalTokens }
+
+    if (isPromptFile(filename)) {
+      promptFileSections.push(entry)
+    } else if (filename.includes('references/')) {
+      referenceFileSections.push(entry)
+    }
+  }
+
+  // Cross-file + within-file redundancy detection across all files
+  const allFileSections = [...promptFileSections, ...referenceFileSections]
+  const redundancyLinks = detectRedundancy(allFileSections)
+
+  // Build redundancy lookup: filename → section heading → redundant peers
+  const redundancyLookup = new Map<string, Map<string, RedundancyPeer[]>>()
+  for (const link of redundancyLinks) {
+    // Forward direction
+    let fileMap = redundancyLookup.get(link.sourceFile)
+    if (!fileMap) { fileMap = new Map(); redundancyLookup.set(link.sourceFile, fileMap) }
+    let peers = fileMap.get(link.sourceSection)
+    if (!peers) { peers = []; fileMap.set(link.sourceSection, peers) }
+    peers.push({ file: link.targetFile, section: link.targetSection })
+
+    // Reverse direction
+    fileMap = redundancyLookup.get(link.targetFile)
+    if (!fileMap) { fileMap = new Map(); redundancyLookup.set(link.targetFile, fileMap) }
+    peers = fileMap.get(link.targetSection)
+    if (!peers) { peers = []; fileMap.set(link.targetSection, peers) }
+    peers.push({ file: link.sourceFile, section: link.sourceSection })
+  }
+
+  // Generate findings per prompt file
+  for (const { filename, sections, totalTokens } of promptFileSections) {
+    const fileRedundancy = redundancyLookup.get(filename) ?? new Map()
+
+    // Build per-section data
+    const sectionData: SkillSection[] = sections.map((s) => {
+      const peers: RedundancyPeer[] | undefined = fileRedundancy.get(s.heading)
+      // Deduplicate peer labels
+      const peerLabels: string[] | undefined = peers
+        ? [...new Set(peers.map((p: RedundancyPeer) => p.file === filename ? `"${p.section}"` : `${p.file} → "${p.section}"`))]
+        : undefined
+
+      return {
+        heading: s.heading,
+        level: s.level,
+        lineStart: s.lineStart,
+        tokens: s.tokens,
+        redundantWith: peerLabels && peerLabels.length > 0 ? peerLabels : undefined,
+        shorteningTip: getShorteningTip(s),
+      }
+    })
+
+    // Determine what's actionable
+    const largeSections = sections.filter(s => s.tokens > SECTION_TOKEN_THRESHOLD)
+    const redundantSections = sections.filter(s => (fileRedundancy.get(s.heading) ?? []).length > 0)
+    const shortenableSections = sections.filter((_, idx) => sectionData[idx]!.shorteningTip !== undefined)
+    const hasLargeFile = totalTokens > FILE_TOKEN_BREAKDOWN_THRESHOLD
+
+    // Generate finding if anything actionable OR file is large enough to warrant breakdown
+    if (!hasLargeFile && largeSections.length === 0 && redundantSections.length === 0 && shortenableSections.length === 0) continue
+
+    // Build description
+    const parts: string[] = []
+    if (largeSections.length > 0) {
+      const top = largeSections.sort((a, b) => b.tokens - a.tokens)[0]!
+      parts.push(`Largest section "${top.heading}" is ~${top.tokens.toLocaleString()} tokens`)
+    }
+    if (redundantSections.length > 0) {
+      const crossFile = redundantSections.filter(s => {
+        const peers: RedundancyPeer[] = fileRedundancy.get(s.heading) ?? []
+        return peers.some((p: RedundancyPeer) => p.file !== filename)
+      })
+      if (crossFile.length > 0) {
+        parts.push(`${crossFile.length} section(s) duplicate content from reference files`)
+      }
+      const withinFile = redundantSections.filter(s => {
+        const peers: RedundancyPeer[] = fileRedundancy.get(s.heading) ?? []
+        return peers.some((p: RedundancyPeer) => p.file === filename)
+      })
+      if (withinFile.length > 0) {
+        const names = withinFile.map(s => `"${s.heading}"`)
+        parts.push(`${withinFile.length} section(s) overlap each other: ${names.join(', ')}`)
+      }
+    }
+    if (shortenableSections.length > 0) {
+      parts.push(`${shortenableSections.length} section(s) have shortening opportunities`)
+    }
+
+    // Determine severity
+    const maxTokens = Math.max(...sections.map(s => s.tokens))
+    const severity = maxTokens > LARGE_SECTION_THRESHOLD
+      ? 'high'
+      : largeSections.length > 0
+        ? 'medium'
+        : redundantSections.length > 0
+          ? 'low'
+          : 'info'
+
+    // Build remediation
+    const remediationParts: string[] = []
+    for (const s of largeSections.sort((a, b) => b.tokens - a.tokens).slice(0, 3)) {
+      remediationParts.push(`"${s.heading}" (${s.tokens} tokens): split into smaller focused subsections or move details to separate files`)
+    }
+    for (const s of redundantSections.slice(0, 3)) {
+      const peers: RedundancyPeer[] = fileRedundancy.get(s.heading) ?? []
+      const crossFilePeers = peers.filter((p: RedundancyPeer) => p.file !== filename)
+      const sameFilePeers = peers.filter((p: RedundancyPeer) => p.file === filename)
+
+      if (crossFilePeers.length > 0) {
+        const targets = [...new Set(crossFilePeers.map((p: RedundancyPeer) => `${p.file} "${p.section}"`))].join(', ')
+        remediationParts.push(`"${s.heading}" duplicates content from ${targets}: keep it in one place, reference from the other`)
+      }
+      if (sameFilePeers.length > 0) {
+        const targets = [...new Set(sameFilePeers.map((p: RedundancyPeer) => `"${p.section}"`))].join(', ')
+        remediationParts.push(`"${s.heading}" overlaps with ${targets}: consolidate shared content into one section`)
+      }
+    }
+    for (const s of shortenableSections.slice(0, 3)) {
+      const idx = sections.indexOf(s)
+      const tip = sectionData[idx]!.shorteningTip
+      remediationParts.push(`"${s.heading}": ${tip}`)
+    }
+
+    // Section token breakdown for context
+    const topSections = [...sections].sort((a, b) => b.tokens - a.tokens).slice(0, 5)
+    const breakdown = topSections.map(s => `"${s.heading}": ${s.tokens}`).join(', ')
+
+    findings.push({
+      rule: 'section-analysis',
+      severity,
+      confidence: 0.8,
+      description: parts.length > 0
+        ? `${filename}: ${parts.join('. ')}. Total: ~${totalTokens.toLocaleString()} tokens across ${sections.length} sections (top: ${breakdown})`
+        : `${filename}: ~${totalTokens.toLocaleString()} tokens across ${sections.length} sections. Token breakdown: ${breakdown}`,
+      location: filename,
+      remediation: remediationParts.length > 0 ? remediationParts.join('\n') : 'No shortening opportunities detected — structure looks efficient.',
+      sections: sectionData,
+    })
+  }
+
+  return findings
+}
diff --git a/src/skill-rules/tool-overhead.ts b/src/skill-rules/tool-overhead.ts
new file mode 100644
index 0000000..1a8d80b
--- /dev/null
+++ b/src/skill-rules/tool-overhead.ts
@@ -0,0 +1,101 @@
+/**
+ * Tool Overhead Rule
+ *
+ * Counts tool definitions in skill config files (tank.json, skills.json).
+ * Each tool adds ~200-500 tokens of context overhead per invocation.
+ *
+ * Thresholds:
+ *   >8 tools → medium (1600-4000 extra tokens per invocation)
+ *   >15 tools → high (3000-7500 extra tokens per invocation)
+ */
+
+import type { SkillAnalysisContext, SkillFinding } from '../types.js'
+
+const MEDIUM_TOOL_THRESHOLD = 8
+const HIGH_TOOL_THRESHOLD = 15
+
+const TOOL_SECTIONS = ['tools', 'mcpServers', 'mcp_servers', 'serverTools', 'server_tools']
+const MANIFEST_FILES = ['tank.json', 'skills.json']
+
+interface ToolEntry {
+  name: string
+  source: string
+}
+
+function countTools(manifest: Record<string, unknown> | null, files: Map<string, string>): ToolEntry[] {
+  const tools: ToolEntry[] = []
+
+  // Extract from manifest
+  if (manifest) {
+    // Check common manifest structures
+    const toolSections = TOOL_SECTIONS
+    for (const section of toolSections) {
+      const sectionData = manifest[section]
+      if (typeof sectionData === 'object' && sectionData !== null) {
+        if (Array.isArray(sectionData)) {
+          for (const entry of sectionData) {
+            if (typeof entry === 'object' && entry !== null && 'name' in entry) {
+              tools.push({ name: String((entry as Record<string, unknown>)['name']), source: 'manifest' })
+            }
+          }
+        } else {
+          // Object with keys = tool names
+          for (const key of Object.keys(sectionData as Record<string, unknown>)) {
+            tools.push({ name: key, source: 'manifest' })
+          }
+        }
+      }
+    }
+  }
+
+  // Also scan config files for tool definitions
+  for (const [filename, content] of files) {
+    if (!MANIFEST_FILES.includes(filename) && !filename.endsWith('.json')) continue
+
+    try {
+      const parsed = JSON.parse(content)
+      for (const section of TOOL_SECTIONS) {
+        const sectionData = parsed[section]
+        if (typeof sectionData === 'object' && sectionData !== null && !Array.isArray(sectionData)) {
+          for (const key of Object.keys(sectionData)) {
+            if (!tools.some(t => t.name === key)) {
+              tools.push({ name: key, source: filename })
+            }
+          }
+        }
+      }
+    } catch {
+      // Not valid JSON, skip
+    }
+  }
+
+  return tools
+}
+
+export function analyze(context: SkillAnalysisContext): SkillFinding[] {
+  const findings: SkillFinding[] = []
+  const tools = countTools(context.skillManifest, context.files)
+  const toolCount = tools.length
+
+  if (toolCount > HIGH_TOOL_THRESHOLD) {
+    findings.push({
+      rule: 'tool-overhead',
+      severity: 'high',
+      confidence: 0.9,
+      description: `${toolCount} tool definitions found. Each tool adds ~200-500 tokens of context overhead per invocation (~${toolCount * 200}-${toolCount * 500} extra tokens total).`,
+      location: 'manifest/config',
+      remediation: `Reduce to ${HIGH_TOOL_THRESHOLD} or fewer tools. Remove unused tools, or use lazy-loading patterns where tools are only registered when the skill enters a specific workflow.`,
+    })
+  } else if (toolCount > MEDIUM_TOOL_THRESHOLD) {
+    findings.push({
+      rule: 'tool-overhead',
+      severity: 'medium',
+      confidence: 0.85,
+      description: `${toolCount} tool definitions found. Each tool adds ~200-500 tokens of context overhead per invocation (~${toolCount * 200}-${toolCount * 500} extra tokens total).`,
+      location: 'manifest/config',
+      remediation: `Consider reducing to ${MEDIUM_TOOL_THRESHOLD} or fewer tools. Consolidate related tools or implement on-demand registration.`,
+    })
+  }
+
+  return findings
+}
diff --git a/src/types.ts b/src/types.ts
index 13f1076..7368f05 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -490,6 +490,8 @@ export interface CliOptions {
   budgetCheck: boolean;
   /** Suppress budget alerts (no CLAUDE.md injection) */
   noAlerts: boolean;
+  /** Analyze a skill package directory for token efficiency */
+  analyzeSkill: string | undefined;
 }
 
 // ============================================================================
@@ -674,3 +676,78 @@ export interface AuditReport {
     info: number;
   };
 }
+
+// ============================================================================
+// Skill Analysis Types (--analyze-skill)
+// ============================================================================
+
+export type SkillSeverity = 'info' | 'low' | 'medium' | 'high';
+
+export interface SkillFinding {
+  rule: string;
+  severity: SkillSeverity;
+  confidence: number;
+  description: string;
+  location: string;
+  remediation: string;
+  /** Optional per-section token breakdown (section-analysis rule) */
+  sections?: SkillSection[];
+}
+
+export interface SkillSection {
+  /** Section heading text (e.g. "## Instructions") */
+  heading: string;
+  /** Heading level (1-6) */
+  level: number;
+  /** 0-based line offset where this section starts */
+  lineStart: number;
+  /** Estimated token count for this section's content (excluding heading) */
+  tokens: number;
+  /** Whether this section overlaps with another section */
+  redundantWith?: string[];
+  /** Why this section could be shortened */
+  shorteningTip?: string;
+}
+
+export interface SkillAnalysisSummary {
+  total_findings: number;
+  estimated_tokens_per_invocation: number;
+  efficiency_score: number; // 0-100
+}
+
+export interface SkillCostEstimate {
+  /** Cost per invocation on Claude Sonnet (USD) */
+  sonnet: string;
+  /** Cost per invocation on Claude Opus (USD) */
+  opus: string;
+}
+
+export type SkillGrade = 'A' | 'B' | 'C' | 'D';
+
+export interface SkillAnalysisReport {
+  /** Plain English one-liner summarizing the skill */
+  one_liner: string;
+  /** Single letter grade */
+  grade: SkillGrade;
+  /** Estimated token count */
+  estimated_tokens: number;
+  /** Comparison to average skill size */
+  comparison: string;
+  /** Cost per invocation in real money */
+  cost_per_use: SkillCostEstimate;
+  /** What this means for the user, 2 sentences max */
+  what_this_means: string;
+  findings: SkillFinding[];
+  summary: SkillAnalysisSummary;
+}
+
+export interface SkillRule {
+  name: string;
+  analyze(context: SkillAnalysisContext): SkillFinding[];
+}
+
+export interface SkillAnalysisContext {
+  skillDir: string;
+  files: Map<string, string>; // filename → content
+  skillManifest: Record<string, unknown> | null;
+}
diff --git a/tests/skill-analyzer.test.ts b/tests/skill-analyzer.test.ts
new file mode 100644
index 0000000..ae8280e
--- /dev/null
+++ b/tests/skill-analyzer.test.ts
@@ -0,0 +1,581 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdirSync, writeFileSync, rmSync, mkdtempSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { analyzeSkill } from '../src/skill-analyzer.js'
+
+import * as promptSizeRule from '../src/skill-rules/prompt-size.js'
+import * as claudeMdSizeRule from '../src/skill-rules/claude-md-size.js'
+import * as toolOverheadRule from '../src/skill-rules/tool-overhead.js'
+import * as largeFilesRule from '../src/skill-rules/large-files.js'
+import * as redundantInstructionsRule from '../src/skill-rules/redundant-instructions.js'
+import * as sectionAnalysisRule from '../src/skill-rules/section-analysis.js'
+import type { SkillAnalysisContext } from '../src/types.js'
+
+function createTempDir(): string {
+  return mkdtempSync(join(tmpdir(), 'skill-test-'))
+}
+
+function createFixture(dir: string, files: Record<string, string>): void {
+  for (const [name, content] of Object.entries(files)) {
+    const fullPath = join(dir, name)
+    const parentDir = fullPath.substring(0, fullPath.lastIndexOf('/'))
+    if (parentDir !== dir) {
+      mkdirSync(parentDir, { recursive: true })
+    }
+    writeFileSync(fullPath, content, 'utf-8')
+  }
+}
+
+// ─── Helpers for rule-level testing ──────────────────────────────────────────
+
+function makeContext(files: Record<string, string>, manifest: Record<string, unknown> | null = null): SkillAnalysisContext {
+  return {
+    skillDir: '/test',
+    files: new Map(Object.entries(files)),
+    skillManifest: manifest,
+  }
+}
+
+// ─── Prompt Size Rule ────────────────────────────────────────────────────────
+
+describe('prompt-size rule', () => {
+  it('flags SKILL.md >4000 tokens as high severity', () => {
+    // 16000+ chars = 4000+ tokens
+    const largeSkill = 'A'.repeat(16001)
+    const ctx = makeContext({ 'SKILL.md': largeSkill })
+    const findings = promptSizeRule.analyze(ctx)
+
+    expect(findings.length).toBe(1)
+    expect(findings[0]!.severity).toBe('high')
+    expect(findings[0]!.rule).toBe('prompt-size')
+    expect(findings[0]!.location).toBe('SKILL.md')
+  })
+
+  it('flags SKILL.md >2000 tokens as medium severity', () => {
+    // 8001 chars = ~2001 tokens (>2000 threshold)
+    const mediumSkill = 'A'.repeat(8001)
+    const ctx = makeContext({ 'SKILL.md': mediumSkill })
+    const findings = promptSizeRule.analyze(ctx)
+
+    expect(findings.length).toBe(1)
+    expect(findings[0]!.severity).toBe('medium')
+  })
+
+  it('does not flag small SKILL.md', () => {
+    const smallSkill = 'A'.repeat(1000)
+    const ctx = makeContext({ 'SKILL.md': smallSkill })
+    const findings = promptSizeRule.analyze(ctx)
+
+    expect(findings.length).toBe(0)
+  })
+
+  it('flags .atom.md files', () => {
+    const largeAtom = 'A'.repeat(8001)
+    const ctx = makeContext({ 'tools/search.atom.md': largeAtom })
+    const findings = promptSizeRule.analyze(ctx)
+
+    expect(findings.length).toBe(1)
+    expect(findings[0]!.location).toContain('.atom.md')
+  })
+
+  it('ignores non-prompt files', () => {
+    const ctx = makeContext({ 'package.json': 'A'.repeat(16001) })
+    const findings = promptSizeRule.analyze(ctx)
+
+    expect(findings.length).toBe(0)
+  })
+})
+
+// ─── CLAUDE.md Size Rule ────────────────────────────────────────────────────
+
+describe('claude-md-size rule', () => {
+  it('flags CLAUDE.md >3000 tokens as high severity', () => {
+    const largeClaude = 'A'.repeat(12001)
+    const ctx = makeContext({ 'CLAUDE.md': largeClaude })
+    const findings = claudeMdSizeRule.analyze(ctx)
+
+    expect(findings.length).toBe(1)
+    expect(findings[0]!.severity).toBe('high')
+    expect(findings[0]!.rule).toBe('claude-md-size')
+  })
+
+  it('flags CLAUDE.md >1500 tokens as medium severity', () => {
+    const mediumClaude = 'A'.repeat(6001)
+    const ctx = makeContext({ 'CLAUDE.md': mediumClaude })
+    const findings = claudeMdSizeRule.analyze(ctx)
+
+    expect(findings.length).toBe(1)
+    expect(findings[0]!.severity).toBe('medium')
+  })
+
+  it('does not flag small CLAUDE.md', () => {
+    const ctx = makeContext({ 'CLAUDE.md': 'small content' })
+    const findings = claudeMdSizeRule.analyze(ctx)
+
+    expect(findings.length).toBe(0)
+  })
+
+  it('detects TOKENOMICS injection blocks', () => {
+    const block = '<!-- TOKENOMICS:START:session-coaching -->\n' + 'A'.repeat(12001) + '\n<!-- TOKENOMICS:END -->'
+    const ctx = makeContext({ 'CLAUDE.md': block })
+    const findings = claudeMdSizeRule.analyze(ctx)
+
+    expect(findings.length).toBe(1)
+    expect(findings[0]!.description).toContain('tokenomics injection block')
+  })
+})
+
+// ─── Tool Overhead Rule ─────────────────────────────────────────────────────
+
+describe('tool-overhead rule', () => {
+  it('flags >15 tools as high severity', () => {
+    const tools: Record<string, unknown> = {}
+    for (let i = 0; i < 16; i++) {
+      tools[`tool-${i}`] = { command: 'echo' }
+    }
+    const manifest = { mcpServers: tools }
+    const ctx = makeContext({}, manifest)
+
+    const findings = toolOverheadRule.analyze(ctx)
+    expect(findings.length).toBe(1)
+    expect(findings[0]!.severity).toBe('high')
+    expect(findings[0]!.rule).toBe('tool-overhead')
+  })
+
+  it('flags >8 tools as medium severity', () => {
+    const tools: Record<string, unknown> = {}
+    for (let i = 0; i < 10; i++) {
+      tools[`tool-${i}`] = { command: 'echo' }
+    }
+    const manifest = { mcpServers: tools }
+    const ctx = makeContext({}, manifest)
+
+    const findings = toolOverheadRule.analyze(ctx)
+    expect(findings.length).toBe(1)
+    expect(findings[0]!.severity).toBe('medium')
+  })
+
+  it('does not flag <=8 tools', () => {
+    const tools: Record<string, unknown> = {}
+    for (let i = 0; i < 5; i++) {
+      tools[`tool-${i}`] = { command: 'echo' }
+    }
+    const manifest = { mcpServers: tools }
+    const ctx = makeContext({}, manifest)
+
+    const findings = toolOverheadRule.analyze(ctx)
+    expect(findings.length).toBe(0)
+  })
+
+  it('scans config files for tool definitions', () => {
+    const tankJson = JSON.stringify({
+      mcpServers: Object.fromEntries(
+        Array.from({ length: 12 }, (_, i) => [`tool-${i}`, { command: 'echo' }])
+      ),
+    })
+    const ctx = makeContext({ 'tank.json': tankJson }, null)
+
+    const findings = toolOverheadRule.analyze(ctx)
+    expect(findings.length).toBe(1)
+    expect(findings[0]!.severity).toBe('medium')
+  })
+})
+
+// ─── Large Files Rule ────────────────────────────────────────────────────────
+
+describe('large-files rule', () => {
+  it('flags files >500 lines', () => {
+    const lines = Array(501).fill('line of code').join('\n')
+    const ctx = makeContext({ 'src/large.ts': lines })
+    const findings = largeFilesRule.analyze(ctx)
+
+    expect(findings.length).toBe(1)
+    expect(findings[0]!.rule).toBe('large-files')
+    expect(findings[0]!.location).toBe('src/large.ts')
+  })
+
+  it('flags files >1000 lines as medium severity', () => {
+    const lines = Array(1001).fill('line of code').join('\n')
+    const ctx = makeContext({ 'src/very-large.ts': lines })
+    const findings = largeFilesRule.analyze(ctx)
+
+    expect(findings.length).toBe(1)
+    expect(findings[0]!.severity).toBe('medium')
+  })
+
+  it('does not flag files <=500 lines', () => {
+    const lines = Array(200).fill('line of code').join('\n')
+    const ctx = makeContext({ 'src/small.ts': lines })
+    const findings = largeFilesRule.analyze(ctx)
+
+    expect(findings.length).toBe(0)
+  })
+})
+
+// ─── Redundant Instructions Rule ────────────────────────────────────────────
+
+describe('redundant-instructions rule', () => {
+  it('flags when >30% duplication across skill files', () => {
+    const sharedInstructions = Array(10).fill('Always use TypeScript strict mode for all new files in this project').join('\n')
+    const uniqueA = 'Specific to SKILL.md that is unique content'
+    const uniqueB = 'Specific to CLAUDE.md that is different content'
+
+    const ctx = makeContext({
+      'SKILL.md': sharedInstructions + '\n' + uniqueA,
+      'CLAUDE.md': sharedInstructions + '\n' + uniqueB,
+    })
+    const findings = redundantInstructionsRule.analyze(ctx)
+
+    expect(findings.length).toBeGreaterThanOrEqual(1)
+    expect(findings[0]!.rule).toBe('redundant-instructions')
+  })
+
+  it('does not flag when duplication is low', () => {
+    const ctx = makeContext({
+      'SKILL.md': 'Unique content about the first skill that is quite different from others',
+      'CLAUDE.md': 'Different content about project guidelines that does not overlap at all',
+    })
+    const findings = redundantInstructionsRule.analyze(ctx)
+
+    expect(findings.length).toBe(0)
+  })
+
+  it('returns nothing with fewer than 2 skill files', () => {
+    const ctx = makeContext({
+      'SKILL.md': 'A'.repeat(500),
+    })
+    const findings = redundantInstructionsRule.analyze(ctx)
+
+    expect(findings.length).toBe(0)
+  })
+})
+
+// ─── Section Analysis Rule ────────────────────────────────────────────────────
+
+describe('section-analysis rule', () => {
+  it('reports per-section token counts', () => {
+    const skill = [
+      '# My Skill',
+      '',
+      'A brief description of the skill.',
+      '',
+      '## Instructions',
+      '',
+      ...Array(50).fill('When the user asks for help, follow these steps carefully and provide detailed feedback.'),
+      '',
+      '## Examples',
+      '',
+      ...Array(30).fill('Here is an example of how to handle a request from the user.'),
+    ].join('\n')
+
+    const ctx = makeContext({ 'SKILL.md': skill })
+    const findings = sectionAnalysisRule.analyze(ctx)
+
+    expect(findings.length).toBe(1)
+    expect(findings[0]!.rule).toBe('section-analysis')
+    expect(findings[0]!.sections).toBeDefined()
+    expect(findings[0]!.sections!.length).toBe(3) // preamble, Instructions, Examples
+
+    // Check that sections have token counts
+    const instructionsSection = findings[0]!.sections!.find(s => s.heading === 'Instructions')
+    expect(instructionsSection).toBeDefined()
+    expect(instructionsSection!.tokens).toBeGreaterThan(0)
+  })
+
+  it('flags sections with redundant/overlapping content', () => {
+    const sharedContent = Array(20).fill(
+      'Always use TypeScript strict mode for all new files in this project and follow the established patterns'
+    ).join(' ')
+
+    const skill = [
+      '# My Skill',
+      '',
+      '## Code Review',
+      '',
+      sharedContent,
+      'Also check for security issues in the authentication module.',
+      '',
+      '## Security Review',
+      '',
+      sharedContent,
+      'Also verify that authentication tokens are properly validated.',
+    ].join('\n')
+
+    const ctx = makeContext({ 'SKILL.md': skill })
+    const findings = sectionAnalysisRule.analyze(ctx)
+
+    expect(findings.length).toBe(1)
+    const finding = findings[0]!
+    expect(finding.description).toContain('overlap')
+
+    // Check redundantWith is populated
+    const codeReview = finding.sections!.find(s => s.heading === 'Code Review')
+    expect(codeReview!.redundantWith).toBeDefined()
+    expect(codeReview!.redundantWith!.some(r => r.includes('Security Review'))).toBe(true)
+  })
+
+  it('suggests shortening tips for sections with repeated lines', () => {
+    const skill = [
+      '# My Skill',
+      '',
+      '## Guidelines',
+      '',
+      ...Array(5).fill('Always check the types before submitting code changes.'),
+      '',
+      'Some unique content here that is different.',
+    ].join('\n')
+
+    const ctx = makeContext({ 'SKILL.md': skill })
+    const findings = sectionAnalysisRule.analyze(ctx)
+
+    // Should have findings since Guidelines has repeated lines
+    if (findings.length > 0) {
+      const guidelines = findings[0]!.sections!.find(s => s.heading === 'Guidelines')
+      if (guidelines?.shorteningTip) {
+        expect(guidelines.shorteningTip).toContain('repeated')
+      }
+    }
+  })
+
+  it('suggests shortening for sections with many list items', () => {
+    const listItems = Array(12).fill(0).map((_, i) => `- Item number ${i + 1} that describes a specific check to perform`).join('\n')
+
+    const skill = [
+      '# My Skill',
+      '',
+      '## Checklist',
+      '',
+      listItems,
+    ].join('\n')
+
+    const ctx = makeContext({ 'SKILL.md': skill })
+    const findings = sectionAnalysisRule.analyze(ctx)
+
+    if (findings.length > 0) {
+      const checklist = findings[0]!.sections!.find(s => s.heading === 'Checklist')
+      if (checklist?.shorteningTip) {
+        expect(checklist.shorteningTip).toContain('list items')
+      }
+    }
+  })
+
+  it('suggests shortening for sections with many code blocks', () => {
+    const codeBlocks = Array(3).fill(0).map((_, i) => `Example ${i}:\n\`\`\`ts\nconst x = ${i};\n\`\`\``).join('\n\n')
+
+    const skill = [
+      '# My Skill',
+      '',
+      '## Examples',
+      '',
+      codeBlocks,
+      '',
+      'Some additional content to make this section large enough to be over the threshold.',
+      'More filler content that pushes the token count above the detection minimum.',
+    ].join('\n')
+
+    const ctx = makeContext({ 'SKILL.md': skill })
+    const findings = sectionAnalysisRule.analyze(ctx)
+
+    if (findings.length > 0) {
+      const examples = findings[0]!.sections!.find(s => s.heading === 'Examples')
+      if (examples?.shorteningTip) {
+        expect(examples.shorteningTip).toContain('code blocks')
+      }
+    }
+  })
+
+  it('does not flag small, clean sections', () => {
+    const skill = [
+      '# My Skill',
+      '',
+      'A brief skill that does one thing.',
+      '',
+      '## Usage',
+      '',
+      'Run the command with the file path.',
+    ].join('\n')
+
+    const ctx = makeContext({ 'SKILL.md': skill })
+    const findings = sectionAnalysisRule.analyze(ctx)
+
+    expect(findings.length).toBe(0)
+  })
+
+  it('ignores non-prompt files', () => {
+    const ctx = makeContext({ 'package.json': '{"name": "test"}' })
+    const findings = sectionAnalysisRule.analyze(ctx)
+
+    expect(findings.length).toBe(0)
+  })
+
+  it('analyzes .atom.md files', () => {
+    const skill = [
+      '## Search',
+      '',
+      ...Array(60).fill('Detailed search instructions that explain how to search for files in the project directory.'),
+    ].join('\n')
+
+    const ctx = makeContext({ 'tools/search.atom.md': skill })
+    const findings = sectionAnalysisRule.analyze(ctx)
+
+    expect(findings.length).toBe(1)
+    expect(findings[0]!.location).toContain('.atom.md')
+  })
+
+  it('includes sections array in JSON output', () => {
+    const skill = [
+      '# Skill',
+      '',
+      'Preamble content here.',
+      '',
+      '## Section A',
+      '',
+      'Content for section A that is reasonably sized.',
+      '',
+      '## Section B',
+      '',
+      'Content for section B that is also reasonably sized.',
+    ].join('\n')
+
+    const ctx = makeContext({ 'SKILL.md': skill })
+    const findings = sectionAnalysisRule.analyze(ctx)
+
+    // Even if no findings (sections are small), verify JSON serialization
+    if (findings.length > 0) {
+      const json = JSON.stringify(findings[0])
+      const parsed = JSON.parse(json)
+      expect(parsed.sections).toBeDefined()
+      expect(Array.isArray(parsed.sections)).toBe(true)
+    }
+  })
+
+  it('high severity for sections >1000 tokens', () => {
+    const hugeSection = 'Very detailed instruction content. '.repeat(600) // ~16800 chars = ~4200 tokens
+
+    const skill = [
+      '# Skill',
+      '',
+      '## Deep Dive',
+      '',
+      hugeSection,
+    ].join('\n')
+
+    const ctx = makeContext({ 'SKILL.md': skill })
+    const findings = sectionAnalysisRule.analyze(ctx)
+
+    expect(findings.length).toBe(1)
+    expect(findings[0]!.severity).toBe('high')
+  })
+})
+
+// ─── Integration: Full Skill Analyzer ────────────────────────────────────────
+
+describe('skill analyzer integration', () => {
+  let tempDir: string
+
+  beforeEach(() => {
+    tempDir = createTempDir()
+  })
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  it('returns valid SkillAnalysisResult for a clean skill', () => {
+    createFixture(tempDir, {
+      'SKILL.md': 'A simple skill that does one thing well.',
+      'tank.json': JSON.stringify({ name: 'test-skill', version: '1.0.0' }),
+    })
+
+    const result = analyzeSkill(tempDir)
+
+    expect(result).toHaveProperty('findings')
+    expect(result).toHaveProperty('summary')
+    expect(Array.isArray(result.findings)).toBe(true)
+    expect(result.summary.total_findings).toBe(result.findings.length)
+    expect(result.summary.efficiency_score).toBeGreaterThanOrEqual(0)
+    expect(result.summary.efficiency_score).toBeLessThanOrEqual(100)
+    expect(result.summary.estimated_tokens_per_invocation).toBeGreaterThan(0)
+  })
+
+  it('detects all issue types in a bloated skill', () => {
+    const largeSkill = 'Large prompt content. '.repeat(800) // ~19k chars
+    const largeClaude = 'Inject all the things. '.repeat(800) // ~19k chars
+    const duplicated = Array(15).fill('Always use TypeScript strict mode for all files in this project').join('\n')
+
+    const tools: Record<string, unknown> = {}
+    for (let i = 0; i < 16; i++) {
+      tools[`tool-${i}`] = { command: `echo ${i}` }
+    }
+
+    createFixture(tempDir, {
+      'SKILL.md': largeSkill + '\n' + duplicated,
+      'CLAUDE.md': largeClaude + '\n' + duplicated,
+      'search.atom.md': largeSkill,
+      'tank.json': JSON.stringify({ name: 'bloated-skill', mcpServers: tools }),
+    })
+
+    const result = analyzeSkill(tempDir)
+
+    expect(result.findings.length).toBeGreaterThanOrEqual(3)
+
+    const rules = result.findings.map(f => f.rule)
+    expect(rules).toContain('prompt-size')
+    expect(rules).toContain('claude-md-size')
+    expect(rules).toContain('tool-overhead')
+    expect(rules).toContain('redundant-instructions')
+  })
+
+  it('throws for non-existent directory', () => {
+    expect(() => analyzeSkill('/nonexistent/path')).toThrow('Directory not found')
+  })
+
+  it('throws for a file path instead of directory', () => {
+    const filePath = join(tempDir, 'file.txt')
+    writeFileSync(filePath, 'test', 'utf-8')
+    expect(() => analyzeSkill(filePath)).toThrow('Not a directory')
+  })
+
+  it('produces valid JSON output', () => {
+    createFixture(tempDir, {
+      'SKILL.md': 'Simple skill content.',
+    })
+
+    const result = analyzeSkill(tempDir)
+    const json = JSON.stringify(result)
+
+    expect(() => JSON.parse(json)).not.toThrow()
+
+    const parsed = JSON.parse(json)
+    expect(parsed).toHaveProperty('findings')
+    expect(parsed).toHaveProperty('summary')
+    expect(parsed.summary).toHaveProperty('total_findings')
+    expect(parsed.summary).toHaveProperty('estimated_tokens_per_invocation')
+    expect(parsed.summary).toHaveProperty('efficiency_score')
+  })
+
+  it('calculates efficiency score correctly for clean skill', () => {
+    createFixture(tempDir, {
+      'SKILL.md': 'A concise skill with minimal overhead.',
+    })
+
+    const result = analyzeSkill(tempDir)
+
+    // Clean small skill should score high
+    expect(result.summary.efficiency_score).toBeGreaterThanOrEqual(90)
+  })
+
+  it('calculates efficiency score correctly for bloated skill', () => {
+    const largeContent = 'X'.repeat(20000)
+    createFixture(tempDir, {
+      'SKILL.md': largeContent,
+      'CLAUDE.md': largeContent,
+    })
+
+    const result = analyzeSkill(tempDir)
+
+    // Bloated skill should score lower
+    expect(result.summary.efficiency_score).toBeLessThan(90)
+  })
+})