agentleFS
Sign inStart free
attilaszaszattilaszasz/sdd-pilot/.github/skills/markdown-compression/SKILL.md

markdown-compression

Skill98 starsChanged 24 days agoMITView on GitHub

Safely compresses narrative Markdown using deterministic compaction plus validator checks. Only for allowlisted and gated artifacts.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 8 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this only for safe narrative Markdown or explicitly gated governance prose.

    line 8
  2. Distinctive:

    all other governance files require a separate manifest entry and dry-run review before compression

    line 21
  3. Very specific:

    all unlisted workflow, agent, instruction, and wrapper Markdown under .github/, .agents/, .claude/, .windsurf/, .opencode/, .codex/

    line 26
  4. Very specific:

    Run node scripts/compress-markdown.mjs --check <path> to confirm the path is allowlisted or explicitly gated and validator-safe.

    line 32
  5. Very specific:

    Run node scripts/compress-markdown.mjs --idempotent <path> after writing and in CI.

    line 36
  6. Distinctive:

    If validation fails, stop.

    line 38
  7. Distinctive:

    every line outside gated narrative blocks

    line 56
  8. Distinctive:

    Keep commands, paths, and structural lines exact.

    line 63
  9. Distinctive:

    Prefer concise normal prose, not stylized shorthand, for persisted files.

    line 65
  10. Distinctive:

    If Node is unavailable, do not auto-compress.

    line 69
  11. Distinctive:

    If the target is blocked, leave it unchanged and tighten the source workflow instructions instead.

    line 70

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Markdown Compression

Use this only for safe narrative Markdown or explicitly gated governance prose. This is not a general rewrite tool.

Safe Targets

  • README.md
  • docs/**/*.md
  • specs/<feature>/research.md
  • specs/<feature>/analysis-report.md
  • specs/<feature>/manual-test.md

Gated Targets

  • .github/sddp/workflows/implement-tasks/WORKFLOW.md - exact manifest entry; compresses only prose inside <rules> and <workflow> blocks
  • all other governance files require a separate manifest entry and dry-run review before compression

Blocked Targets

  • project-instructions.md, AGENTS.md, CLAUDE.md
  • all unlisted workflow, agent, instruction, and wrapper Markdown under .github/, .agents/, .claude/, .windsurf/, .opencode/, .codex/
  • specs/prd.md, specs/sad.md, specs/dod.md, specs/project-plan.md, specs/adrs/*.md, specs/plan/*.md
  • feature-workspace parser-sensitive artifacts: spec.md, plan.md, tasks.md, qc-report.md, checklists/*.md, autopilot-log.md

Process

  1. Run node scripts/compress-markdown.mjs --check <path> to confirm the path is allowlisted or explicitly gated and validator-safe.
  2. For preview only, run node scripts/compress-markdown.mjs --stdout <path>; gated targets automatically use narrative-only mode.
  3. Review the proposed diff. For a manual narrative-only preview, add --narrative-only.
  4. To write the compressed file, run node scripts/compress-markdown.mjs <path>.
  5. Run node scripts/compress-markdown.mjs --idempotent <path> after writing and in CI.
  6. The script creates <name>.original.md once, then preserves it on later runs.
  7. If validation fails, stop. Do not write partial output.
  8. Symbolic-link paths are blocked; authorization uses the canonical target path.

Validation Guarantees

The validator preserves these elements exactly:

  • frontmatter
  • headings
  • fenced code blocks
  • inline code
  • bare URLs and Markdown links
  • requirement and task identifiers
  • table rows
  • checkbox lines
  • Markdown list prefixes and indented lines
  • HTML comment blocks
  • <rules> and <workflow> tag lines
  • every line outside gated narrative blocks
  • HTML blocks, tables, nested blockquotes, and ordered-parenthesis lists
  • original line endings

Compression Rules

  • Normalize redundant whitespace and punctuation spacing only; do not substitute words or phrases.
  • Keep commands, paths, and structural lines exact.
  • Compress governance prose only inside the explicitly supported narrative blocks.
  • Prefer concise normal prose, not stylized shorthand, for persisted files.

Fallback

  • If Node is unavailable, do not auto-compress.
  • If the target is blocked, leave it unchanged and tighten the source workflow instructions instead.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free