Workflow & Core Tools · daymade/claude-code-skills

claude-md-progressive-disclosurer

Name: claude-md-progressive-disclosurer
Author: daymade/claude-code-skills

Optimize, slim, or restructure CLAUDE.md/AGENTS.md with progressive disclosure and zero information loss. Use when the user explicitly asks to audit, 精简, 瘦身, 重构, split, or diagnose adherence problems in instruction files. Profiles the whole resident startup surface, allocates rules among prose, path rules, Skills, hooks, and references, then moves low-frequency sections verbatim with content-integrity checks. Also use when an active task starts moving or compressing instruction sections. Not for generic task drift unless instruction files are in scope.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandWrite FileDual-pass Audit

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Acts as a disciplined 'methodology executor': The core of SKILL.md is not a set of prompting tricks, but an auditable workflow (Establish Baseline -> Signal Triage -> Layering -> Verbatim Migration -> Whole-String Verification -> Host-Specific Acceptance Testing), equipped with built-in guardrails against drift at every step.

daymade-claude-code/claude-md-progressive-disclosurer/SKILL.md

**目标是让指令在实际任务中被正确加载、找到并执行。** 信息效率、可读性与可维护性服务于这个结果；文件大小、审阅次数和脚本绿灯都不能替代行为证据。

Defines acceptance criteria upfront by 'behavioral evidence' rather than file size, setting the tone for the iron rule that 'line count is strictly forbidden as a KPI'.

Iron rule: Line count is not an optimization goal. Evaluation criteria rely on single source of truth, cognitive relevance, and maintenance consistency; claiming success via 'slimmed from X lines to Y lines / reduced by Z%' is strictly forbidden in reporting.

daymade-claude-code/claude-md-progressive-disclosurer/SKILL.md

- 行数少不代表更好，行数多不代表更差 - 评判标准是：**单一信息源**（同一信息不在多处维护）、**认知相关性**（当前任务不需要的信息不干扰注意力）、**维护一致性**（改一处不需要同步另一处）——不是行数

Major differentiator from typical 'CLAUDE.md slimming' skills: codifies anti-KPI into iron rules and demonstrates how trimming line counts causes information loss through case studies (15/16/19).

Two-tier architecture + target carrier precedes hierarchy: Routes rules to the correct carrier first (Resident L1 / Reference / Skill / Hook / Tool Index) before deciding on L1↔L2 layering; evaluates whether a rule can leave resident memory using a 'Violation Recoverability × Trigger Self-Reporting × Tool Event Observability' matrix.

daymade-claude-code/claude-md-progressive-disclosurer/SKILL.md

**先问载体，再问层级。** 判据是模型能否在决策前找到这条规则，以及现有机制能否覆盖所需条件。下表是候选路由，不证明机制已存在，也不授权安装新机制。

The matrix's three tiers (trigger self-reporting / time-observable / neither) determine the choice among Skill, reference, hook reminder, or resident L1; emphasizes that hooks only report timing while judgment remains with the model.

Mechanical offloading is handled via script: `sink_sections.py` appends whole sections verbatim (fence-aware accurate heading demarcation) into references per spec, replaces original L1 spots with compressed snippets using an 'extract-first, replace-later, bottom-up' approach to prevent line drift, and runs whole-string byte verification with automatic rollback on failure.

daymade-claude-code/claude-md-progressive-disclosurer/scripts/sink_sections.py

extract [start_heading, end_heading) from the source (exact-line match, code-fence-aware) -> append verbatim to the target reference under a dated provenance header (new files get an intro) -> replace the L1 range with the compressed snippet, bottom-up so earlier line numbers stay valid -> verify every original is a WHOLE-BYTE-STRING substring of its target

SKILL Step 3 mandates scripts for ≥3 sections, banning manual moves; a script printing OK only signifies mechanical checks passed, not semantic preservation.

Integrity verification relies on exact byte whole-strings: Checking whether a section is fully relocated cannot use `grep` (line-by-line OR misses truncated sections) and must use `python3` whole-string substring matching; compressed restatements require clause-level diffs (qualifiers like '/forks' are primary drop-off points).

daymade-claude-code/claude-md-progressive-disclosurer/SKILL.md

**不能用 grep** —— 原句多行时 `grep -F` 按行 OR，**丢半段照样报命中**，必须用 python3 整串子串判断

'Dangling pointers are stealthier than lost content': Step 4 strictly verifies target content exists on the spot before writing pointers, forbidding references to empty files.

Profiling instruments include fence awareness and CJK token ratio calibration: `profile_claude_md.py` outputs per-section byte tables, line-length distributions, and longest lines, explicitly rejecting the chars/4 rule for estimating CJK tokens (measured at ~0.42 token/byte).

daymade-claude-code/claude-md-progressive-disclosurer/scripts/profile_claude_md.py

Token estimates: chars/4 UNDERESTIMATES CJK-dense files by >2x. Measured ratio on a real CJK-heavy CLAUDE.md was ~0.42 tokens/byte.

The script header documents two real-world failure cases (pseudo-45.9KB section, token underestimation) and requires calibrating instruments on known-answer samples first.

Host differences are explicitly addressed: Claude's `@import` fully expands at startup (saving no context), `.claude/rules` remain resident, and `paths` trigger based on file matching; Codex AGENTS hierarchy and budget are measured separately using `codex debug prompt-input`, strictly prohibiting extrapolating behavior across hosts.

daymade-claude-code/claude-md-progressive-disclosurer/SKILL.md

`@path` import 在**启动时全量展开载入**——拆成 `@import` 只改善组织，**不减少任何上下文**（官方 *memory* 文档原文）

The same constraint is included in references Case 11; offers four citation formats, with Principle 2 requiring that every reference must include trigger conditions.

2Core Capabilities

01Read-only audit and hotspot profiling: per-section byte tables, line-length distribution (>1KB giant line detection), and fence-aware heading parsing

02Signal triage: passes each section through the Anthropic litmus test ('will mistakes happen if deleted?') to distinguish signal from anti-signal

03Whole-section verbatim sinking (spec-driven via `sink_sections.py`, mechanical multi-section batch migration + rollback)

04Section-by-section content integrity checks (5b) and clause-level fidelity audits for compressed summaries (expected-hunks-only `difflib` checks)

05Strict gate against dangling pointers: verifies target content actually exists on the spot before writing 'see X for details' (existence via `grep -F` distinct strings; completeness via `python3` whole strings)

06Host-level actual loading surface verification: empirical testing via `/context`, `/memory`, `InstructionsLoaded` hook, and `codex debug prompt-input`

3External Dependencies

Kind	Dependency / Endpoint
cli	python3
cli	codex（官方 CLI，仅调试读取 prompt 注入）
cli	claude（/context、/memory、InstructionsLoaded hook）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Executes local scripts or commands: scripts/profile_claude_md.py
本地工作目录: File read/write and artifact output: user's CLAUDE.md/AGENTS.md files (only upon explicit modification authorization)

Audit Notes: Bundled scripts are stdlib-only ('Stdlib-only by design (skill scripts must run with no installs)') and strictly local: `profile`/`markdown_headings` are read-only; `sink_sections` performs local modifications on user instruction files with automated backups, rollback support, symlink traversal prevention, and whole-string validation; no outbound network traffic, no credential access, and no exposure to settings/secret files. Write targets are user CLAUDE.md/AGENTS.md files—governed as 'controlled, reversible local modifications' with strict SKILL authorization boundaries constraining the agent.

5Second-Pass Verification

[ok] 无网络外发 — 脚本零网络；md 中 https 全为 references 的官方文档/论文引用
[ok] 无凭证读取 — 脚本无 environ/getenv/settings.json 读取
[ok] sink_sections.py 写入面与 SKILL 声称一致（含备份、回滚、symlink 拒绝） — main() 实测：preflight abort 条件、copy2 备份、whole-string 校验失败恢复源文件均在代码中
[ok] ‘行数禁作 KPI’纪律是否被脚本弱化 — profile_claude_md.py 输出分节字节表，但说明明确仅作工作顺序与诊断，不输出‘精简目标’
[ok] 宿主机制断言（@import 全量展开、96KiB 截断）有依据 — 引用官方 memory 文档并标注历史事故作‘必须实测’示例，SKILL 反复要求以当前官方文档与真实宿主读回裁决

6Verdict & Scenarios

Complete methodology rejecting line-count KPIs: establishes 'no duplicate maintenance / cognitive relevance / maintenance consistency' as the sole criteria, backed by 19 real-world cases

High-fidelity engineering for mechanical sinking: fence-aware demarcation, extract-first-replace-later workflow, byte-level whole-string validation, failure rollback, and standard backup naming conventions

Empirically validated across host mechanisms (verifying `@import` does not save context, `InstructionsLoaded`, and measuring bytes via `codex debug prompt-input`), refusing cross-host assumptions

Concrete safety design: blocks writes to symlink targets (including parent directories), enforces hard gates on dangling pointers, and uses clause-level fidelity audits to catch missing qualifiers

Best for: Ideal for maintainers who need to systematically restructure or slim down `CLAUDE.md` and `AGENTS.md` with zero information loss and verifiable fidelity. Also fits teams establishing instruction governance discipline (multi-entrypoint, SSOT, carrier routing, verification gates). Especially suited for Chinese/bilingual instruction files (CJK token calibration) and dual Claude Code + Codex users.

Not for: Not suitable for quick-and-dirty slimming purely aiming to 'make files smaller or reduce line count' (blocked by iron rules); not for scenarios without explicit authorization boundaries where an agent freely deletes 'seemingly useless' content; not for general code refactoring (targets instruction files only); low cost-performance when applied blindly using low-tier models or short context windows.

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload claude-md-progressive-disclosurer.tar.gz

sha256: 57ac229162c67d07…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.