skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
rheinmir/setup95 installs

tidy

Dọn + validate kho nháp và render (wiki/sources/draft/*.md + llmwiki/html/*.html) khi phình to — ex docs-curate (đổi tên 2026-09-09 vì tên cũ không ai gọi). Ba tầng — PROMOTE bản chất quý lên wiki ADR/concept, ARCHIVE nháp đã xong (status done/implemented hoặc task done) vào archive/<nhóm>/ bằng git mv (TRACKED, không xoá, không giết draft còn proposed), KEEP canonical — rồi RE-INDEX. Gọi tay bất cứ lúc nào, hoặc khi đầu phiên báo "[tidy] draft/ có N file (> 10)". Trigger — "tidy", "dọn nháp", "dọn docs", "draft quá nhiều", "archive draft", "quét nháp lỗi thời", "/tidy".

How do I install this agent skill?

npx skills add https://github.com/rheinmir/setup --skill tidy
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The tidy skill is a utility designed to manage and organize documentation drafts and wiki entries. It automates the process of checking, planning, and applying changes to draft files using git and local Python scripts. The primary security consideration is the potential for indirect prompt injection, as the agent is tasked with reading user-generated drafts to determine if their content should be promoted to a permanent wiki, which could allow instructions within those drafts to affect the agent's judgment or output.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

Skill: tidy

WHAT

Purpose và context

  • Purpose: dọn + validate kho nháp và render (wiki/sources/draft/*.md + llmwiki/html/*.html) khi phình to: PROMOTE bản chất quý lên wiki, ARCHIVE nháp đã xong (tracked, không xoá), KEEP canonical, rồi RE-INDEX.
  • Trigger (when to use):
    • Đầu phiên thấy 🧹 [tidy] draft/ có N file .md tầng gốc (> ngưỡng 10) — hook session_start.py hỏi user; user ĐỒNG Ý → chạy skill này. User TỪ CHỐI → bỏ qua, không hỏi lại trong phiên.
    • User tự gọi /tidy khi thấy draft/ hoặc llmwiki/html/ lộn xộn, khó tìm, sợ mất bản chất quý.
    • /lint bước 8c (docs-sprawl pulse) hoặc medic probe tidy báo warn.
  • Non-goals: không xoá nháp, không archive draft còn sống chỉ vì cũ, không "sửa cho đúng chuẩn" file đã nằm trong archive/.

Mental model

Vì sao 3 tầng (không chỉ "merge"): Cái QUÝ trong nháp là quyết định / bài học / pattern — nó phải lên wiki (concept/ADR, travel + được commit + được index). Còn nháp đã thi hành xong và render html là lịch sử → archive (giữ, không xoá). Tool tất định lo đếm + phân loại + dời + index; phần đọc-hiểu để promote là việc của agent.

draft/ + html/ → check (đếm) → plan (KEEP · ARCHIVE · PROMOTE?) → agent promote → apply (git mv vào archive/<nhóm>/) → re-index → verify + commit.

Input và output contract

FieldRequired?Ý nghĩa
In--threshold N / env OVERSTACK_DRAFT_THRESHOLDkhông (mặc định 10)ngưỡng số file .md tầng gốc
In--keep-dates Nkhông (mặc định 2)số mốc ngày html report giữ lại
In--root .khôngdùng khi downstream không có harness/
Outbảng plancóKEEP / ARCHIVE / PROMOTE? kèm lý do từng file
OutADR/concept mới trong wikitheo nội dungbản chất quý đã promote, có ## Origin
Outrename vào archive/<proposals/superseded/analysis/reports>/ + indexcó (khi apply)git thấy rename, không delete

Rules và capabilities

  • RULE-01 (MUST): PROMOTE trước APPLY. Archive giờ TRACKED nên promote-sau vẫn làm được, nhưng đừng để bản chất chôn dưới archive/ mà không ai biết.
  • RULE-02 (MUST): Archive = DỜI, KHÔNG XOÁ. Không bao giờ rm nháp; git mv giữ history (git log --follow).
  • RULE-03 (MUST): Tuổi không phải lý do archive một draft còn status: proposed/open/implementing. Chỉ status/task đã xong (hoặc PLAN/seq đi theo SPEC đã archive) mới archive. Muốn dọn draft treo → người quyết, đổi status, chạy lại.
  • RULE-04 (MUST): Canonical (overstack.html, index.html, wiki-graph.html, *-cheatsheet, *-health-dashboard, problem-tree, line-status) không bao giờ archive. Html report có ngày: giữ 2 mốc ngày gần nhất (--keep-dates N), cũ hơn archive — html là render, không áp cho .md.
  • RULE-05 (MUST): Vai rõ: tool = đếm/phân loại/dời/re-index (tất định, 0 token); agent = promote (đọc-hiểu). Không lẫn.
  • RULE-06 (MUST): Wiki entry mới phải có ## Origin + frontmatter type (R2/R9); cập nhật wiki/index.md + wiki/log.md (R3).
  • RULE-07 (MUST): Validator R7/R9/R18 và wiki-health/index_sync bỏ qua archive/ (nháp đông cứng) — đừng "sửa cho đúng chuẩn" file trong archive, chúng là lịch sử.
  • Capabilities: đọc draft/html + frontmatter; dời file bằng git (tracked rename); ghi wiki (ADR/concept/index/log); chạy kiểm wiki-health/index_sync cục bộ.

Failure boundaries

  • check exit 3 = vượt ngưỡng → đi tiếp plan; dưới ngưỡng và user không tự gọi → dừng, không có gì dọn.
  • Draft treo (status: proposed/open…) → clarify: hỏi user làm-tiếp hay reject, không tự archive.
  • Đích archive bị .gitignore → tool từ chối dời (chủ ý), in dòng gitignore cần bỏ → blocked cho file đó.
  • wiki-health --fail-on broken hoặc index_sync đỏ → failed, sửa trước khi commit.

HOW

Main workflow

StepTypeInputsActionOutputs/exitFailure/next
W01deterministicdraft/Check (0 token, không đụng file): tidy.py checkexit 3 = vượt ngưỡngdưới ngưỡng → dừng trừ khi user tự gọi
W02deterministicdraft + htmlPlan (dry-run): tidy.py plan, đọc kỹ cột lý dobảng KEEP/ARCHIVE/PROMOTE?draft treo → B01; cờ outdated → B02
W03judgmentmục PROMOTE? + ARCHIVE có quyết địnhPROMOTE bản chất quý vào wiki TRƯỚC khi applyADR/concept + index + logđã có trong wiki → chỉ archive
W04effectplanApply: tidy.py apply — git mv vào archive + re-indexrename + indexđích gitignored → B03
W05deterministicworktreeVerify + commit: git status, wiki-health, index_synccommit + logđỏ → sửa, lặp W05

Chi tiết từng bước (nguồn chân lý cho W01–W05, bước 0–4):

  1. Check (0 token, không đụng file):
    python3 harness/scripts/tidy.py check          # downstream không có harness/: python3 ~/.claude/harness/harness/scripts/tidy.py check --root .
    
    Exit 3 = vượt ngưỡng (mặc định 10 file .md tầng gốc, thư mục con không tính; đổi bằng --threshold N hoặc env OVERSTACK_DRAFT_THRESHOLD).
  2. Plan (dry-run): python3 harness/scripts/tidy.py plan → bảng KEEP / ARCHIVE / PROMOTE? kèm lý do từng file. Đọc kỹ cột lý do:
    • OUTDATED — status done|implemented|… hoặc task T-… đã done → nháp đã xong → ARCHIVE.
    • ⏱ TREO — status proposed/open… → còn sống, tuổi không phải lý do archive; muốn dọn thì hỏi user quyết làm-tiếp hay reject (đổi status: trong frontmatter rồi chạy lại).
    • PROMOTE? = draft không status, không task → agent đọc rồi quyết.
    • ↳ ⚠ nội dung có thể outdated dưới một draft GIỮ = file nó trích dẫn đã chết (claim-receipts) hoặc code nó nói tới đã đổi sau khi viết (cờ code-drift trong stale.json). Status còn sống không có nghĩa là nội dung còn đúng: đối chiếu với code, rồi (a) đã làm xong → đổi status và archive, (b) còn làm → sửa đúng câu sai, (c) bỏ → rejected hoặc dời need-review/. Có dương tính giả (đường dẫn ví dụ), nên phải đọc trước khi kết luận.
  3. PROMOTE bản chất QUÝ vào wiki — làm TRƯỚC khi apply (phán đoán của agent): với mỗi mục PROMOTE? và mỗi mục ARCHIVE có vẻ chứa quyết định/bài học chưa có trong wiki → viết llmwiki/wiki/sources/adr/ADR-NNN-<slug>.md (quyết định) hoặc llmwiki/wiki/concepts/<slug>.md (khái niệm), đúng frontmatter type: + ## Origin trỏ draft; cập nhật wiki/index.md + wiki/log.md. Đã có trong wiki → chỉ archive. Không promote thứ tầm thường (report tiến độ, render trùng).
  4. Apply: python3 harness/scripts/tidy.py apply — dời nhóm ARCHIVE vào archive/<proposals|superseded|analysis|reports>/ (file tracked → git mv, git thấy rename không delete), sắp xếp cả file đã archive từ trước, rồi re-index (build-docs-index nếu có, index_sync --fix, html/archive/INDEX.md).
    • Tool từ chối dời file tracked khi đích bị .gitignore (dời = xoá khỏi repo) và in dòng gitignore cần bỏ. Đây là chủ ý, không phải lỗi.
  5. Verify + commit: git status chỉ thấy rename/archive/INDEX.md; python3 harness/scripts/wiki-health.py --wiki-dir llmwiki/wiki --fail-on broken sạch (wikilink trỏ stem trong archive/ = resolved-frozen, không broken); index_sync xanh. Commit gồm ADR/concept mới promote + các rename. Append wiki/log.md.

Branches

IDKindGuardHành viSkip / failureRejoin
B01conditional_requiredplan báo ⏱ TREO — status proposed/open…giữ; muốn dọn thì hỏi user làm-tiếp hay reject, đổi status: rồi chạy lại planuser không quyết → KEEPW02
B02conditional_requireddòng ↳ ⚠ nội dung có thể outdated dưới draft GIỮđối chiếu code: (a) xong → đổi status + archive, (b) còn làm → sửa đúng câu sai, (c) bỏ → rejected hoặc dời need-review/dương tính giả (đường dẫn ví dụ) → giữ nguyênW03
B03recoverytool từ chối dời vì đích bị .gitignorebáo user dòng gitignore cần bỏ; không lách bằng xoáuser không bỏ → file đó ở yênW04

Validation và stopping

Tất định: bash harness/tests/tidy-test.sh (mục Test tất định dưới), wiki-health --fail-on broken sạch, index_sync xanh, git status chỉ thấy rename/archive/INDEX.md. Cần review: quyết định PROMOTE (agent đọc-hiểu). Dừng sau W05 commit; không lặp apply nhiều lần trong một phiên nếu plan không đổi.

Examples

  • Positive: đầu phiên báo [tidy] draft/ có 57 file, user đồng ý → plan: 40 ARCHIVE (status done), 4 PROMOTE?, 13 KEEP → agent viết 1 ADR cho quyết định chưa có trong wiki → tidy.py apply → git status chỉ thấy rename → wiki-health sạch → commit.
  • Boundary/failure: draft status: proposed 3 tháng tuổi → plan đánh ⏱ TREO, KHÔNG archive; hỏi user làm-tiếp hay reject. Đích archive/reports/ bị gitignore → apply từ chối dời file tracked đó và in dòng gitignore cần bỏ.

Test tất định

bash harness/tests/tidy-test.sh — 11 assertion: ngưỡng >10 (thư mục con không tính), status done → archive, proposed cũ → keep, đích gitignored → không dời, đích tracked → git rename, vòng khép về exit 0.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/rheinmir/setup/tidy">View tidy on skillZs</a>