From 3ce25a03a0d32dae4ef4ca4759bcfaaad6dd3ab0 Mon Sep 17 00:00:00 2001
From: Gale W <mail@galewilliams.com>
Date: Mon, 22 Jun 2026 13:28:51 -0400
Subject: [PATCH 1/2] docs: add token efficiency audit report

---
 ...-efficiency-automation-audit-2026-06-22.md | 390 ++++++++++++++++++
 1 file changed, 390 insertions(+)
 create mode 100644 docs/agents/token-efficiency-automation-audit-2026-06-22.md

diff --git a/docs/agents/token-efficiency-automation-audit-2026-06-22.md b/docs/agents/token-efficiency-automation-audit-2026-06-22.md
new file mode 100644
index 00000000..dae9f2fa
--- /dev/null
+++ b/docs/agents/token-efficiency-automation-audit-2026-06-22.md
@@ -0,0 +1,390 @@
+# Token Efficiency and Automation Audit
+
+Date: 2026-06-22
+Branch: `audit/token-efficiency-automation`
+
+## Summary
+
+Socket has several good existing boundaries for reducing hand-carried work:
+shared Apple snippet sources, maintainer automation guidance, source-bundled
+steward roles, root marketplace validation, and child validation in some
+plugins. The largest remaining token-efficiency opportunities are not generic
+style edits. They are moving repeated high-churn facts into narrower references,
+making generated or mirrored guidance less expensive to load, and adding
+automation that inventories drift before humans edit skill prose.
+
+Top priorities:
+
+1. Collapse repeated SwiftASB API inventory into one current-state reference and
+   keep per-skill files focused on routing, ownership, and workflow-specific
+   decisions.
+2. Replace repeated productivity-skill subagent prose with a short local fit
+   paragraph plus the existing shared maintainer guidance.
+3. Treat Apple shared snippets as generated mirrors and add drift/size reporting
+   so their duplication is visible before release.
+4. Define Socket-owned F# `.fsx` conventions for typed hooks and compact local
+   maintenance scripts, but do not migrate Python validators or the current Node
+   hook until portability and startup costs are measured.
+5. Add a root skill-surface audit script that reports large skills, duplicate
+   snippets, stale current-version wording, missing handoff references, and
+   repeated boilerplate.
+
+## Evidence Snapshot
+
+- `plugins/apple-dev-skills`: 21 skill files, 3,401 `SKILL.md` lines.
+- `plugins/python-skills`: 12 skill files, 1,906 `SKILL.md` lines.
+- `plugins/swiftasb-skills`: 6 skill files, 1,467 `SKILL.md` lines.
+- `plugins/productivity-skills`: 14 skill files, 1,580 `SKILL.md` lines.
+- Root skill total: 12,703 `SKILL.md` lines across shipped child plugins.
+- Root reference total: 11,439 Markdown reference lines under skill references.
+- `apple-dev-skills` carries 23 skill-local snippet copies in three identical
+  checksum groups.
+- `productivity-skills` repeats the phrase `When the user explicitly requests
+  subagents` in 10 maintainer skills, plus one `agent-plugin-skills` workflow.
+- `swiftasb-skills` repeats startup, diagnostics, feature-operation, generated
+  wire-model, same-thread overlap, and Apple handoff facts across multiple
+  skills.
+- Current script inventory includes one `.mjs` file with 592 lines, 137 Python
+  files with 35,750 lines, 29 shell files with 4,675 lines, and no `.fsx` or
+  `.fs` files.
+- The roadmap now includes an explicit Socket-owned F# `.fsx` hook and
+  maintenance-script conventions item covering launch shape, repo-local
+  `DOTNET_CLI_HOME`, event JSON types, validation, and graduation to compiled
+  F# tools.
+
+## Quick Wins
+
+### 1. Add a root token-surface audit script
+
+Create `scripts/audit_skill_surfaces.py` with a report-only default that emits:
+
+- skill line counts by plugin and skill
+- reference line counts by plugin and reference
+- exact duplicate reference checksums
+- repeated phrase counts from a repo-owned phrase list
+- version-sensitive phrases such as `As of SwiftASB v...`
+- missing expected handoff references for known cross-skill boundaries
+
+This should not fail release validation at first. Start with advisory output so
+maintainers can see hotspots without blocking unrelated plugin work.
+
+Evidence:
+
+- Root validation already validates marketplace wiring in
+  `scripts/validate_socket_metadata.py`.
+- Apple has a manual snippet sync script at
+  `plugins/apple-dev-skills/.github/scripts/sync_shared_snippets.sh`.
+- Python has a child metadata validator at
+  `plugins/python-skills/scripts/validate_repo_metadata.py`.
+
+### 2. Put the Apple snippet mirror check into validation
+
+`apple-dev-skills` already has canonical sources under
+`plugins/apple-dev-skills/shared/agents-snippets/` and a script that copies them
+into skill-local `references/snippets/` files. That is a good source-of-truth
+shape, but the repo should also be able to detect drift without relying on a
+maintainer remembering to run the sync script.
+
+Recommended first step:
+
+- Add a check mode to `sync_shared_snippets.sh`, or add a small Python validator
+  that compares each target with its canonical source.
+- Include the check in the Apple child validation path.
+- Keep copies for now if current skill-loader behavior requires references to
+  stay inside each skill directory.
+
+Evidence:
+
+- The sync script copies `apple-xcode-project-core.md` into 12 skills and
+  `apple-swift-package-core.md` into 5 skills.
+- The copied snippets are large enough to matter: 104 lines for Xcode project
+  core and 82 lines for Swift package core.
+
+### 3. Replace repeated productivity subagent boilerplate with compact pointers
+
+`productivity-skills/docs/maintainers/codex-subagent-guidance.md` already defines
+the shared model, good fits, poor fits, and wording pattern. Individual
+maintenance skills only need:
+
+- whether this skill can use read-heavy subagents
+- the skill-specific examples of useful worker jobs
+- whether apply-mode edits stay in the main thread
+
+Avoid repeating the whole trigger model in every skill. Keep one sentence in the
+skill and link the maintainer guidance for the durable policy.
+
+Evidence:
+
+- `maintain-project-readme` lines 47-51 carry a local subagent section.
+- The shared maintainer guidance already covers trigger rules, model selection,
+  sandbox behavior, good fits, poor fits, and wording pattern.
+
+### 4. Add report-only stale-version detection for high-churn skills
+
+SwiftASB skills contain current-version claims such as `As of SwiftASB v1.6.0`.
+Those claims are valuable, but they become expensive and risky when copied
+across several large skills.
+
+Add an audit that reports:
+
+- all `As of ... vX.Y.Z` phrases
+- all repeated symbol inventories over a threshold
+- all SwiftASB skills that mention a current API symbol but do not link to a
+  shared reference
+
+Do not block validation until the plugin has a chosen shared-reference shape.
+
+### 5. Define an `.fsx` convention before migrating scripts
+
+The current repo has no `.fsx` files. The best first move is a convention note or
+small proof script, not a migration. The convention should answer the roadmap
+questions directly:
+
+- place Socket-owned F# scripts under the owning plugin's `scripts/` directory,
+  not under root unless the script operates on the Socket superproject
+- launch hook scripts through a tiny POSIX wrapper using
+  `dotnet fsi --exec <script>.fsx`
+- keep repo-local `.dotnet/`, `.nuget/`, and any chosen `DOTNET_CLI_HOME` cache
+  path ignored before recommending `.fsx` hooks broadly
+- model hook input and output with explicit F# records or discriminated unions
+  decoded from JSON
+- validate with `dotnet fsi --exec`, a smoke payload, and any repo-level
+  formatter or test command the convention chooses
+- graduate to a compiled F# console tool when the hook fires often, startup time
+  is noticeable, the JSON-RPC client grows, or the script needs packaging and
+  tests beyond a single-file proof
+
+Good first `.fsx` candidates:
+
+- report-only skill-surface audits with typed rows and deterministic Markdown or
+  JSON output
+- hook payload shape experiments where discriminated unions make event handling
+  clearer than loosely typed JavaScript objects
+- small maintenance scripts in `.NET` or F# repositories where the contributor
+  already has the SDK and `dotnet` validation path
+
+Poor first `.fsx` candidates:
+
+- root marketplace validation, which is already Python and test-backed
+- Python child metadata validation, which already follows the plugin's `uv`
+  baseline
+- release automation, where the existing shell/Python split is wired into
+  release evidence, marketplace smoke tests, and current maintainer docs
+- frequently fired hooks until startup cost is measured against Node and a
+  compiled F# tool
+
+Evidence:
+
+- `plugins/codex-utilities/hooks/run-thread-title-hook.sh` currently launches
+  the hook with `node`.
+- `plugins/codex-utilities/scripts/session-start-hook.mjs` hand-rolls hook JSON
+  parsing, environment configuration, App Server JSON-RPC over stdio, state file
+  updates, and JSONL logging in one 592-line script.
+- `plugins/dotnet-skills/AGENTS.md` treats F# and C# as equal first-party .NET
+  choices and prefers F# examples first for neutral examples.
+- `plugins/dotnet-skills/skills/build-fsharp-project/SKILL.md` already defines
+  the local F# style preferences that would make typed hook event models easier
+  to read: explicit modules, domain types, functional data flow, and side
+  effects at the edge.
+
+## Medium Changes
+
+### 1. Split SwiftASB current API facts into one loaded reference
+
+Create a reference such as
+`plugins/swiftasb-skills/skills/_shared/references/current-api-inventory.md` only
+if the skill loader and packaging contract can support shared references, or keep
+it under one skill and link it from the others if cross-skill references are
+acceptable.
+
+If shared references are not acceptable, keep skill-local references generated
+from a shared source, mirroring the Apple Dev Skills pattern.
+
+Per-skill `SKILL.md` files should keep:
+
+- when to use the skill
+- what the skill owns
+- which source files to inspect
+- workflow-specific architecture and UI guidance
+- validation and handoff rules
+- guardrails unique to that workflow
+
+The shared reference should own:
+
+- current SwiftASB startup and diagnostics surfaces
+- library, inventory, filesystem, config, extensions, MCP, and workspace
+  companion concepts
+- common thread, turn, dashboard, agenda, minimap, recent-history, and review
+  surfaces
+- generated wire-model boundary
+- same-thread turn overlap limitation
+- feature policy and feature-operation events
+
+Evidence:
+
+- `build-swiftui-app` and `build-appkit-app` each carry a long current API
+  inventory near the top of the skill.
+- The same skills repeat similar UI guidance and guardrails for startup errors,
+  generated wire models, same-thread overlap, feature-operation events, Apple
+  handoffs, and serialized SwiftPM/Xcode validation.
+- `diagnose-integration`, `choose-integration-shape`, `build-swift-package`, and
+  `explain-swiftasb` repeat related startup, feature-operation, and overlap
+  facts.
+
+### 2. Turn repeated validation-command text into plugin-local validation maps
+
+Several language plugins repeat local validation expectations in prose. That is
+appropriate when the command choice changes by project shape, but Socket can
+still make it cheaper to audit by keeping plugin-local validation maps:
+
+- `plugin`
+- `skill`
+- `default_validation`
+- `side_effect_level`
+- `current_docs_required`
+- `handoff_skill`
+
+The first implementation can be a Markdown table or JSON/TOML data file consumed
+by the proposed audit script. Avoid generating skill prose until the data model
+has survived a few maintenance passes.
+
+### 3. Add a scheduled check-only Socket stewardship report
+
+Use the existing automation suitability guidance to create a recurring
+report-only automation or a `codex exec` prompt for:
+
+- skill size deltas
+- duplicated snippets
+- stale version phrases
+- placeholder plugin state
+- marketplace metadata drift
+- custom-agent inventory drift
+- child validators missing from expected plugin families
+
+This should produce a report under `docs/agents/` or as a Codex inbox summary,
+not edit skills automatically.
+
+Evidence:
+
+- `docs/maintainers/automation-suitability.md` already recommends app
+  automations for scheduled reporting and `codex exec` for bounded one-repo
+  tasks.
+
+### 4. Prototype `.fsx` only where it reduces prose and untyped branching
+
+If Socket adopts `.fsx`, the most token-efficient use is to move repeated event
+shape descriptions and maintenance checklist transformations into typed code,
+then let the skill docs say "run this script" with a short contract.
+
+Recommended proof:
+
+1. Add a tiny `scripts/audit_skill_surfaces.fsx` or a plugin-local proof script
+   that reads a bounded set of files and emits deterministic JSON.
+2. Compare the same task in Python and `.fsx` for line count, startup time,
+   dependency setup, error messages, and testability.
+3. Only after that comparison, decide whether the first durable `.fsx` home is
+   `dotnet-skills`, `codex-utilities`, or root Socket maintainer tooling.
+
+Keep the current `.mjs` hook unless the proof shows F# materially improves the
+hook's event model or maintainability. Node is already available in many Codex
+plugin environments and has low-friction stdlib JSON, path, process, and stream
+support. F# may win on typed event modeling, but `dotnet fsi` startup and SDK
+availability are real hook-runtime risks.
+
+## Larger Design Decisions
+
+### 1. Decide whether Socket supports shared skill references
+
+The main blocker to reducing duplicated references is packaging and skill-loader
+behavior. If a skill can reliably link to plugin-level shared references, then
+Apple snippets and future SwiftASB API inventories can live once. If not, keep
+generated skill-local mirrors and validate that every copy matches its source.
+
+Decision needed:
+
+- Canonical shared references with cross-skill links, or
+- generated skill-local mirrors with validator-enforced sync.
+
+Risk: Do not remove skill-local files until installed-plugin behavior is proven.
+Broken skill-relative links would be worse than extra tokens.
+
+### 2. Decide whether SwiftASB gets a steward role
+
+`docs/agents/bundled-subagent-role-candidates.md` already lists
+`swiftasb-skills: swiftasb-steward` as a maybe-later role for read-heavy
+integration triage, source-of-truth comparison, and failed-integration diagnosis.
+This audit supports that direction, but not as a first quick win.
+
+Good first role jobs:
+
+- compare SwiftASB skills against current SwiftASB source files
+- inventory repeated current API facts
+- collect failed-integration evidence for the main thread
+
+Do not bundle it until SwiftASB has a shared-reference or generated-mirror plan,
+otherwise the role may only point at the same duplication without reducing it.
+
+### 3. Decide whether placeholder plugins should have periodic retirement checks
+
+`android-dev-skills` and `spotify` remain placeholder directories. They are
+clearly marked as placeholders in root docs and candidate-role docs. A recurring
+stewardship report should include them so they do not silently become stale
+catalog clutter, but there is no evidence that they should be deleted in this
+audit.
+
+### 4. Decide whether `.fsx` belongs to `dotnet-skills` or `codex-utilities`
+
+There are two plausible ownership models:
+
+- `dotnet-skills` owns the authoring convention because `.fsx` is a .NET/F#
+  runtime choice.
+- `codex-utilities` owns hook-specific conventions because hook event payloads,
+  App Server JSON-RPC, and runtime data paths are Codex utility concerns.
+
+Recommendation: split the ownership. Put general `.fsx` style, validation, and
+project-shape guidance in `dotnet-skills`; put Codex hook payload contracts and
+runtime-data conventions in `codex-utilities`. Avoid a root Socket scripting
+policy until at least one proof exists.
+
+## Do Not Consolidate Yet
+
+- Do not collapse Apple docs freshness rules into generic "check docs" language.
+  Apple, Expo, OpenAI, and SwiftASB surfaces drift for different reasons and need
+  local current-docs gates.
+- Do not merge server-side Swift back into Apple Dev Skills. The roadmap keeps
+  SwiftPM-first service work separate from Xcode/app workflows for good reason.
+- Do not turn `maintain-project-repo` into a bundled worker. The existing
+  candidate-role doc correctly keeps it as a main-thread orchestrator because it
+  owns install, validation, release, and write-capable decisions.
+- Do not remove skill-local Apple snippet copies until the installed plugin
+  loader is verified against shared plugin-level reference paths.
+- Do not migrate Python validators to `.fsx` just to make F# visible. Existing
+  Python scripts have tests, `uv` dependency flow, and repo-local precedent.
+- Do not migrate the current Node hook to `.fsx` until `dotnet fsi --exec`
+  startup, SDK availability, cache behavior, and hook trust UX are measured.
+- Do not automate write-heavy Swift source organization without human-approved
+  slices and PR boundaries.
+
+## Recommended Next Steps
+
+1. Add `scripts/audit_skill_surfaces.py` in report-only mode and run it in this
+   branch to create a baseline.
+2. Add Apple snippet sync check mode and wire it into Apple child validation.
+3. Draft a SwiftASB shared-reference or generated-mirror plan, then shrink one
+   SwiftASB skill as a proof of shape.
+4. Add an `.fsx` convention proposal and one small report-only proof script, then
+   compare it against Python and the current Node hook before recommending
+   migrations.
+5. Compact productivity subagent sections to skill-specific examples plus a
+   shared-guidance pointer.
+6. Add a check-only Socket stewardship automation once the audit script exists,
+   so future token and drift issues are found without hand-scanning.
+
+## Validation
+
+This report is a docs-only proposal. Run root metadata validation after adding
+the file:
+
+```bash
+uv run scripts/validate_socket_metadata.py
+```

From de5f92bb8a8c9a85db90ed1d3544b2d4f402bc14 Mon Sep 17 00:00:00 2001
From: Gale W <mail@galewilliams.com>
Date: Mon, 22 Jun 2026 14:04:37 -0400
Subject: [PATCH 2/2] tools: add skill surface audit script

---
 ...-efficiency-automation-audit-2026-06-22.md |  36 +-
 scripts/audit_skill_surfaces.py               | 386 ++++++++++++++++++
 tests/test_audit_skill_surfaces.py            | 131 ++++++
 3 files changed, 538 insertions(+), 15 deletions(-)
 create mode 100755 scripts/audit_skill_surfaces.py
 create mode 100644 tests/test_audit_skill_surfaces.py

diff --git a/docs/agents/token-efficiency-automation-audit-2026-06-22.md b/docs/agents/token-efficiency-automation-audit-2026-06-22.md
index dae9f2fa..d7e72f08 100644
--- a/docs/agents/token-efficiency-automation-audit-2026-06-22.md
+++ b/docs/agents/token-efficiency-automation-audit-2026-06-22.md
@@ -25,9 +25,9 @@ Top priorities:
 4. Define Socket-owned F# `.fsx` conventions for typed hooks and compact local
    maintenance scripts, but do not migrate Python validators or the current Node
    hook until portability and startup costs are measured.
-5. Add a root skill-surface audit script that reports large skills, duplicate
+5. Use the root skill-surface audit script to keep large skills, duplicate
    snippets, stale current-version wording, missing handoff references, and
-   repeated boilerplate.
+   repeated boilerplate visible before manual cleanup.
 
 ## Evidence Snapshot
 
@@ -51,12 +51,16 @@ Top priorities:
   maintenance-script conventions item covering launch shape, repo-local
   `DOTNET_CLI_HOME`, event JSON types, validation, and graduation to compiled
   F# tools.
+- `scripts/audit_skill_surfaces.py --top 5` now reports 87 skill files, 12,703
+  skill lines, 264 reference files, 11,439 reference lines, 17 exact duplicate
+  reference groups, 4 version-sensitive lines, and 0 missing expected handoffs
+  with the current skill-specific expectation map.
 
 ## Quick Wins
 
-### 1. Add a root token-surface audit script
+### 1. Keep the root token-surface audit script report-only
 
-Create `scripts/audit_skill_surfaces.py` with a report-only default that emits:
+`scripts/audit_skill_surfaces.py` now has a report-only default that emits:
 
 - skill line counts by plugin and skill
 - reference line counts by plugin and reference
@@ -65,8 +69,9 @@ Create `scripts/audit_skill_surfaces.py` with a report-only default that emits:
 - version-sensitive phrases such as `As of SwiftASB v...`
 - missing expected handoff references for known cross-skill boundaries
 
-This should not fail release validation at first. Start with advisory output so
-maintainers can see hotspots without blocking unrelated plugin work.
+Keep it advisory for now so maintainers can see hotspots without blocking
+unrelated plugin work. If it becomes a release gate later, split strict checks
+from exploratory checks first.
 
 Evidence:
 
@@ -367,24 +372,25 @@ policy until at least one proof exists.
 
 ## Recommended Next Steps
 
-1. Add `scripts/audit_skill_surfaces.py` in report-only mode and run it in this
-   branch to create a baseline.
-2. Add Apple snippet sync check mode and wire it into Apple child validation.
-3. Draft a SwiftASB shared-reference or generated-mirror plan, then shrink one
+1. Add Apple snippet sync check mode and wire it into Apple child validation.
+2. Draft a SwiftASB shared-reference or generated-mirror plan, then shrink one
    SwiftASB skill as a proof of shape.
-4. Add an `.fsx` convention proposal and one small report-only proof script, then
+3. Add an `.fsx` convention proposal and one small report-only proof script, then
    compare it against Python and the current Node hook before recommending
    migrations.
-5. Compact productivity subagent sections to skill-specific examples plus a
+4. Compact productivity subagent sections to skill-specific examples plus a
    shared-guidance pointer.
-6. Add a check-only Socket stewardship automation once the audit script exists,
-   so future token and drift issues are found without hand-scanning.
+5. Add a check-only Socket stewardship automation around
+   `scripts/audit_skill_surfaces.py`, so future token and drift issues are found
+   without hand-scanning.
 
 ## Validation
 
 This report is a docs-only proposal. Run root metadata validation after adding
-the file:
+the file. After adding the audit script, also run the focused script tests:
 
 ```bash
+uv run pytest tests/test_audit_skill_surfaces.py
+uv run scripts/audit_skill_surfaces.py --top 5
 uv run scripts/validate_socket_metadata.py
 ```
diff --git a/scripts/audit_skill_surfaces.py b/scripts/audit_skill_surfaces.py
new file mode 100755
index 00000000..c30ab1a9
--- /dev/null
+++ b/scripts/audit_skill_surfaces.py
@@ -0,0 +1,386 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Report token-efficiency and drift hotspots across Socket skill surfaces."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_REPEATED_PHRASES = (
+    "When the user explicitly requests subagents",
+    "Use official documentation first",
+    "Use official docs first",
+    "Do not run multiple SwiftPM or Xcode build/test commands concurrently",
+    "Run the repository's documented validation path",
+    "Report the intended edit scope",
+)
+VERSION_SENSITIVE_RE = re.compile(r"\bAs of\b.*?\bv?\d+\.\d+\.\d+\b")
+HANDOFF_EXPECTATIONS = {
+    "plugins/swiftasb-skills/skills/build-appkit-app/SKILL.md": (
+        ("swiftasb:explain-swiftasb",),
+        ("apple-dev-skills:explore-apple-swift-docs", "Apple Dev Skills"),
+    ),
+    "plugins/swiftasb-skills/skills/build-swift-package/SKILL.md": (
+        ("swiftasb:explain-swiftasb",),
+        ("apple-dev-skills:sync-swift-package-guidance", "Apple Swift package workflow skills"),
+    ),
+    "plugins/swiftasb-skills/skills/build-swiftui-app/SKILL.md": (
+        ("swiftasb:explain-swiftasb",),
+        ("apple-dev-skills:explore-apple-swift-docs", "Apple Dev Skills"),
+    ),
+    "plugins/swiftasb-skills/skills/choose-integration-shape/SKILL.md": (
+        ("Apple Dev Skills", "apple-dev-skills"),
+    ),
+    "plugins/web-dev-skills/skills/expo-inline-native-modules-workflow/SKILL.md": (
+        ("Apple Dev Skills", "apple-dev-skills"),
+    ),
+}
+
+
+@dataclass(frozen=True)
+class TextSurface:
+    plugin: str
+    path: Path
+    relative_path: str
+    line_count: int
+    text: str
+
+
+@dataclass(frozen=True)
+class DuplicateGroup:
+    digest: str
+    line_count: int
+    paths: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class PhraseHit:
+    phrase: str
+    file_count: int
+    total_count: int
+    paths: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class VersionHit:
+    path: str
+    line: int
+    text: str
+
+
+@dataclass(frozen=True)
+class MissingHandoff:
+    plugin: str
+    path: str
+    expected: str
+
+
+@dataclass(frozen=True)
+class AuditReport:
+    skill_count: int
+    skill_lines: int
+    reference_count: int
+    reference_lines: int
+    skill_lines_by_plugin: dict[str, int]
+    largest_skills: tuple[TextSurface, ...]
+    largest_references: tuple[TextSurface, ...]
+    duplicate_references: tuple[DuplicateGroup, ...]
+    phrase_hits: tuple[PhraseHit, ...]
+    version_hits: tuple[VersionHit, ...]
+    missing_handoffs: tuple[MissingHandoff, ...]
+
+
+def plugin_name_for(path: Path) -> str:
+    parts = path.parts
+    try:
+        plugins_index = parts.index("plugins")
+    except ValueError:
+        return "(unknown)"
+    if len(parts) <= plugins_index + 1:
+        return "(unknown)"
+    return parts[plugins_index + 1]
+
+
+def read_text_surface(repo_root: Path, path: Path) -> TextSurface:
+    text = path.read_text(encoding="utf-8")
+    return TextSurface(
+        plugin=plugin_name_for(path.relative_to(repo_root)),
+        path=path,
+        relative_path=path.relative_to(repo_root).as_posix(),
+        line_count=len(text.splitlines()),
+        text=text,
+    )
+
+
+def discover_surfaces(repo_root: Path, pattern: str) -> tuple[TextSurface, ...]:
+    paths = sorted(repo_root.glob(pattern))
+    return tuple(read_text_surface(repo_root, path) for path in paths if path.is_file())
+
+
+def find_duplicate_references(references: tuple[TextSurface, ...]) -> tuple[DuplicateGroup, ...]:
+    by_digest: dict[str, list[TextSurface]] = {}
+    for surface in references:
+        digest = hashlib.sha256(surface.text.encode("utf-8")).hexdigest()
+        by_digest.setdefault(digest, []).append(surface)
+
+    groups: list[DuplicateGroup] = []
+    for digest, surfaces in by_digest.items():
+        if len(surfaces) < 2:
+            continue
+        first = surfaces[0]
+        groups.append(
+            DuplicateGroup(
+                digest=digest,
+                line_count=first.line_count,
+                paths=tuple(surface.relative_path for surface in sorted(surfaces, key=lambda item: item.relative_path)),
+            )
+        )
+
+    return tuple(sorted(groups, key=lambda group: (-len(group.paths), -group.line_count, group.digest)))
+
+
+def find_phrase_hits(surfaces: tuple[TextSurface, ...], phrases: tuple[str, ...]) -> tuple[PhraseHit, ...]:
+    hits: list[PhraseHit] = []
+    for phrase in phrases:
+        paths: list[str] = []
+        total_count = 0
+        for surface in surfaces:
+            count = surface.text.count(phrase)
+            if count == 0:
+                continue
+            total_count += count
+            paths.append(surface.relative_path)
+        if total_count > 0:
+            hits.append(
+                PhraseHit(
+                    phrase=phrase,
+                    file_count=len(paths),
+                    total_count=total_count,
+                    paths=tuple(paths),
+                )
+            )
+    return tuple(sorted(hits, key=lambda hit: (-hit.total_count, hit.phrase)))
+
+
+def find_version_hits(surfaces: tuple[TextSurface, ...]) -> tuple[VersionHit, ...]:
+    hits: list[VersionHit] = []
+    for surface in surfaces:
+        for line_number, line in enumerate(surface.text.splitlines(), start=1):
+            if VERSION_SENSITIVE_RE.search(line):
+                hits.append(VersionHit(path=surface.relative_path, line=line_number, text=line.strip()))
+    return tuple(hits)
+
+
+def find_missing_handoffs(skills: tuple[TextSurface, ...]) -> tuple[MissingHandoff, ...]:
+    missing: list[MissingHandoff] = []
+    for surface in skills:
+        expectations = HANDOFF_EXPECTATIONS.get(surface.relative_path)
+        if not expectations:
+            continue
+        for alternatives in expectations:
+            if not any(expected in surface.text for expected in alternatives):
+                missing.append(
+                    MissingHandoff(
+                        plugin=surface.plugin,
+                        path=surface.relative_path,
+                        expected=" or ".join(alternatives),
+                    )
+                )
+    return tuple(sorted(missing, key=lambda item: (item.plugin, item.path, item.expected)))
+
+
+def build_report(repo_root: Path, *, top: int = 10) -> AuditReport:
+    skills = discover_surfaces(repo_root, "plugins/*/skills/*/SKILL.md")
+    references = discover_surfaces(repo_root, "plugins/*/skills/*/references/**/*.md")
+
+    skill_lines_by_plugin: dict[str, int] = {}
+    for skill in skills:
+        skill_lines_by_plugin[skill.plugin] = skill_lines_by_plugin.get(skill.plugin, 0) + skill.line_count
+
+    return AuditReport(
+        skill_count=len(skills),
+        skill_lines=sum(skill.line_count for skill in skills),
+        reference_count=len(references),
+        reference_lines=sum(reference.line_count for reference in references),
+        skill_lines_by_plugin=dict(sorted(skill_lines_by_plugin.items())),
+        largest_skills=tuple(sorted(skills, key=lambda item: (-item.line_count, item.relative_path))[:top]),
+        largest_references=tuple(sorted(references, key=lambda item: (-item.line_count, item.relative_path))[:top]),
+        duplicate_references=find_duplicate_references(references),
+        phrase_hits=find_phrase_hits(skills, DEFAULT_REPEATED_PHRASES),
+        version_hits=find_version_hits(skills),
+        missing_handoffs=find_missing_handoffs(skills),
+    )
+
+
+def surface_to_json(surface: TextSurface) -> dict[str, object]:
+    return {
+        "plugin": surface.plugin,
+        "path": surface.relative_path,
+        "line_count": surface.line_count,
+    }
+
+
+def report_to_json(report: AuditReport) -> dict[str, object]:
+    return {
+        "skill_count": report.skill_count,
+        "skill_lines": report.skill_lines,
+        "reference_count": report.reference_count,
+        "reference_lines": report.reference_lines,
+        "skill_lines_by_plugin": report.skill_lines_by_plugin,
+        "largest_skills": [surface_to_json(surface) for surface in report.largest_skills],
+        "largest_references": [surface_to_json(surface) for surface in report.largest_references],
+        "duplicate_references": [
+            {
+                "digest": group.digest,
+                "line_count": group.line_count,
+                "paths": list(group.paths),
+            }
+            for group in report.duplicate_references
+        ],
+        "phrase_hits": [
+            {
+                "phrase": hit.phrase,
+                "file_count": hit.file_count,
+                "total_count": hit.total_count,
+                "paths": list(hit.paths),
+            }
+            for hit in report.phrase_hits
+        ],
+        "version_hits": [
+            {
+                "path": hit.path,
+                "line": hit.line,
+                "text": hit.text,
+            }
+            for hit in report.version_hits
+        ],
+        "missing_handoffs": [
+            {
+                "plugin": missing.plugin,
+                "path": missing.path,
+                "expected": missing.expected,
+            }
+            for missing in report.missing_handoffs
+        ],
+    }
+
+
+def markdown_table(rows: list[tuple[object, ...]], headers: tuple[str, ...]) -> str:
+    lines = [
+        "| " + " | ".join(headers) + " |",
+        "| " + " | ".join("---" for _ in headers) + " |",
+    ]
+    for row in rows:
+        lines.append("| " + " | ".join(str(item) for item in row) + " |")
+    return "\n".join(lines)
+
+
+def render_markdown(report: AuditReport) -> str:
+    sections = [
+        "# Socket Skill Surface Audit",
+        "",
+        "## Summary",
+        "",
+        f"- Skills: {report.skill_count} files, {report.skill_lines} lines",
+        f"- References: {report.reference_count} files, {report.reference_lines} lines",
+        f"- Exact duplicate reference groups: {len(report.duplicate_references)}",
+        f"- Version-sensitive lines: {len(report.version_hits)}",
+        f"- Missing expected handoffs: {len(report.missing_handoffs)}",
+        "",
+        "## Skill Lines By Plugin",
+        "",
+        markdown_table(
+            [(plugin, lines) for plugin, lines in sorted(report.skill_lines_by_plugin.items(), key=lambda item: (-item[1], item[0]))],
+            ("Plugin", "Skill lines"),
+        ),
+        "",
+        "## Largest Skills",
+        "",
+        markdown_table(
+            [(surface.relative_path, surface.line_count) for surface in report.largest_skills],
+            ("Path", "Lines"),
+        ),
+        "",
+        "## Largest References",
+        "",
+        markdown_table(
+            [(surface.relative_path, surface.line_count) for surface in report.largest_references],
+            ("Path", "Lines"),
+        ),
+        "",
+        "## Exact Duplicate References",
+        "",
+    ]
+
+    if report.duplicate_references:
+        for group in report.duplicate_references:
+            sections.append(f"- {len(group.paths)} files, {group.line_count} lines, sha256 `{group.digest[:12]}`")
+            sections.extend(f"  - `{path}`" for path in group.paths)
+    else:
+        sections.append("No duplicate reference groups found.")
+
+    sections.extend(["", "## Repeated Phrase Hits", ""])
+    if report.phrase_hits:
+        sections.append(
+            markdown_table(
+                [(hit.phrase, hit.file_count, hit.total_count) for hit in report.phrase_hits],
+                ("Phrase", "Files", "Total hits"),
+            )
+        )
+    else:
+        sections.append("No configured repeated phrase hits found.")
+
+    sections.extend(["", "## Version-Sensitive Lines", ""])
+    if report.version_hits:
+        for hit in report.version_hits:
+            sections.append(f"- `{hit.path}:{hit.line}`: {hit.text}")
+    else:
+        sections.append("No version-sensitive lines found.")
+
+    sections.extend(["", "## Missing Expected Handoffs", ""])
+    if report.missing_handoffs:
+        for missing in report.missing_handoffs:
+            sections.append(f"- `{missing.path}` does not mention `{missing.expected}`")
+    else:
+        sections.append("No missing expected handoffs found.")
+
+    sections.append("")
+    return "\n".join(sections)
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Report token-efficiency hotspots across Socket skill surfaces.")
+    parser.add_argument("--repo-root", type=Path, default=REPO_ROOT, help="Socket repository root to audit.")
+    parser.add_argument("--top", type=int, default=10, help="Number of largest skills and references to show.")
+    parser.add_argument(
+        "--format",
+        choices=("markdown", "json"),
+        default="markdown",
+        help="Output format.",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    output_format: Literal["markdown", "json"] = args.format
+    report = build_report(args.repo_root.resolve(), top=args.top)
+    if output_format == "json":
+        print(json.dumps(report_to_json(report), indent=2, sort_keys=True))
+    else:
+        print(render_markdown(report), end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tests/test_audit_skill_surfaces.py b/tests/test_audit_skill_surfaces.py
new file mode 100644
index 00000000..91cf3629
--- /dev/null
+++ b/tests/test_audit_skill_surfaces.py
@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+
+MODULE_PATH = Path(__file__).resolve().parent.parent / "scripts" / "audit_skill_surfaces.py"
+SPEC = importlib.util.spec_from_file_location("audit_skill_surfaces", MODULE_PATH)
+assert SPEC and SPEC.loader
+audit_skill_surfaces = importlib.util.module_from_spec(SPEC)
+sys.modules[SPEC.name] = audit_skill_surfaces
+SPEC.loader.exec_module(audit_skill_surfaces)
+
+
+def write(path: Path, contents: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(contents, encoding="utf-8")
+
+
+def make_repo(tmp_path: Path) -> Path:
+    write(
+        tmp_path / "plugins" / "swiftasb-skills" / "skills" / "build-swiftui-app" / "SKILL.md",
+        "\n".join(
+            [
+                "# Build SwiftUI App",
+                "",
+                "As of SwiftASB `v1.6.0`, use current app-facing handles.",
+                "",
+                "Use `apple-dev-skills:explore-apple-swift-docs` for Apple framework docs.",
+                "",
+            ]
+        ),
+    )
+    write(
+        tmp_path / "plugins" / "swiftasb-skills" / "skills" / "diagnose-integration" / "SKILL.md",
+        "\n".join(
+            [
+                "# Diagnose Integration",
+                "",
+                "Run the repository's documented validation path.",
+                "",
+            ]
+        ),
+    )
+    write(
+        tmp_path / "plugins" / "productivity-skills" / "skills" / "maintain-project-readme" / "SKILL.md",
+        "\n".join(
+            [
+                "# Maintain README",
+                "",
+                "When the user explicitly requests subagents, use bounded discovery.",
+                "",
+            ]
+        ),
+    )
+    shared_reference = "# Shared\n\nSame text.\n"
+    write(
+        tmp_path
+        / "plugins"
+        / "apple-dev-skills"
+        / "skills"
+        / "xcode-build-run-workflow"
+        / "references"
+        / "snippets"
+        / "apple-core.md",
+        shared_reference,
+    )
+    write(
+        tmp_path
+        / "plugins"
+        / "apple-dev-skills"
+        / "skills"
+        / "xcode-testing-workflow"
+        / "references"
+        / "snippets"
+        / "apple-core.md",
+        shared_reference,
+    )
+    return tmp_path
+
+
+def test_build_report_counts_skill_surfaces_and_hotspots(tmp_path: Path) -> None:
+    repo_root = make_repo(tmp_path)
+
+    report = audit_skill_surfaces.build_report(repo_root, top=2)
+
+    assert report.skill_count == 3
+    assert report.reference_count == 2
+    assert report.skill_lines_by_plugin["swiftasb-skills"] == 8
+    assert [surface.relative_path for surface in report.largest_skills] == [
+        "plugins/swiftasb-skills/skills/build-swiftui-app/SKILL.md",
+        "plugins/productivity-skills/skills/maintain-project-readme/SKILL.md",
+    ]
+    assert len(report.duplicate_references) == 1
+    assert len(report.duplicate_references[0].paths) == 2
+    assert any(hit.phrase == "When the user explicitly requests subagents" for hit in report.phrase_hits)
+    assert report.version_hits[0].path == "plugins/swiftasb-skills/skills/build-swiftui-app/SKILL.md"
+    assert any(
+        missing.path == "plugins/swiftasb-skills/skills/build-swiftui-app/SKILL.md"
+        and missing.expected == "swiftasb:explain-swiftasb"
+        for missing in report.missing_handoffs
+    )
+
+
+def test_json_report_is_serializable(tmp_path: Path) -> None:
+    report = audit_skill_surfaces.build_report(make_repo(tmp_path), top=1)
+
+    payload = audit_skill_surfaces.report_to_json(report)
+
+    assert payload["skill_count"] == 3
+    assert json.loads(json.dumps(payload))["reference_count"] == 2
+    assert payload["largest_skills"] == [
+        {
+            "plugin": "swiftasb-skills",
+            "path": "plugins/swiftasb-skills/skills/build-swiftui-app/SKILL.md",
+            "line_count": 5,
+        }
+    ]
+
+
+def test_markdown_report_includes_primary_sections(tmp_path: Path) -> None:
+    report = audit_skill_surfaces.build_report(make_repo(tmp_path), top=1)
+
+    markdown = audit_skill_surfaces.render_markdown(report)
+
+    assert "# Socket Skill Surface Audit" in markdown
+    assert "## Exact Duplicate References" in markdown
+    assert "## Version-Sensitive Lines" in markdown
+    assert "plugins/swiftasb-skills/skills/build-swiftui-app/SKILL.md:3" in markdown