Skip to content

Adonis0123/adonis-skills / skills/agent-practice-audit

agent-practice-audit

Flagged

Score how someone uses coding agents (Claude Code, Codex, Grok and WorkBuddy session logs, instruction files, hooks, permissions, Codex config) against practices quoted from official vendor docs, and write a local HTML report with coverage, trend and suggestions; also refresh or verify that practice list from official docs with multi-model consensus. Use when the user asks how far their agent usage is from official practice, wants an agent usage check-up or grade, or wants the practice list refreshed, its links checked, or either run on a schedule. Chinese triggers: Agent 用法体检、对照官方最佳实践、我的 agent 用得对不对、给 agent 用法打分、更新最佳实践清单. Not for whether a tool, MCP or skill is worth keeping (dev-environment-roi-audit), for writing or reviewing one CLAUDE.md or AGENTS.md, for general best-practice questions, or for Cursor or Gemini CLI logs, which it does not read. Never edits the user's config.

FileKindSize
SKILL.mdskill md18.3 KB
assets/default-config.jsonconfig352 B
assets/img/hero.webpbinary106.5 KB
assets/img/nika-wordmark-white.svgother490 B
assets/img/nika-wordmark.svgother490 B
assets/report-template.htmlother41.2 KB
evals/evals.jsonconfig844 B
evals/trigger-eval-set.jsonconfig1.6 KB
references/audit-files.mdmarkdown32.2 KB
references/changelog.mdmarkdown7.2 KB
references/practices.jsonconfig37.3 KB
references/scheduling.mdmarkdown11.9 KB
references/sources.mdmarkdown6.5 KB
references/sources/cc-art-loops.mdmarkdown1.7 KB
references/sources/cc-art-maximizing-sessions.mdmarkdown1.9 KB
references/sources/cc-art-opus-5-5-context.mdmarkdown1.4 KB
references/sources/cc-art-sdlc-playbook.mdmarkdown1.9 KB
references/sources/cc-art-steering.mdmarkdown1.9 KB
references/sources/cc-art-verification-loops.mdmarkdown1.6 KB
references/sources/cc-best-practices.mdmarkdown3.0 KB
references/sources/cc-common-workflows.mdmarkdown1.7 KB
references/sources/cc-costs.mdmarkdown2.3 KB
references/sources/cc-memory.mdmarkdown1.7 KB
references/sources/codex-agents-md.mdmarkdown1.5 KB
references/sources/codex-best-practices.mdmarkdown2.6 KB
references/sources/codex-non-interactive.mdmarkdown1.3 KB
references/sources/codex-sandboxing.mdmarkdown1.4 KB
references/sources/cursor-agent-best-practices.mdmarkdown1.8 KB
references/verify-prompt.mdmarkdown4.6 KB
scripts/aggregate.pyscript22.3 KB
scripts/audit_common.pyscript8.6 KB
scripts/build_report.pyscript30.8 KB
scripts/check_practices.pyscript24.8 KB
scripts/config_scan.pyscript28.3 KB
scripts/consensus.pyscript38.1 KB
scripts/digests.pyscript10.2 KB
scripts/export_metrics.pyscript10.3 KB
scripts/extract.pyscript42.5 KB
scripts/prejudge.pyscript41.8 KB
scripts/run_audit.pyscript3.8 KB
scripts/safe_output.pyscript2.0 KB
scripts/test_agent_practice_audit.pyscript81.1 KB
scripts/test_consensus_run.pyscript26.9 KB
scripts/test_measurement.pyscript68.7 KB
scripts/test_prejudge.pyscript24.2 KB

scripts/digests.py

View on GitHub
"""Offline source digests: references/sources/<slug>.md with a small frontmatter block.

The frontmatter is flat `key: value` lines between `---` fences, so it is parsed
without a YAML dependency. Digests let the report and verifiers fall back to a
stored summary when an official page cannot be opened.
"""

from __future__ import annotations

import datetime as dt
import hashlib
import json
import os
import re
import subprocess
import uuid

SKILL = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
SOURCES_DIR = os.path.join(SKILL, "references", "sources")
REQUIRED = ("slug", "title", "publisher", "url", "fetchedAt", "lastVerifiedAt", "linkStatus")
LINK_STATUSES = ("ok", "redirected", "unreachable")
MANIFEST = "manifest.json"  # written by check_practices.py --save-pages beside the page files
MAX_PAGE_AGE_HOURS = 24  # a saved page older than this is not live text for verifiers
DEFAULT_BRANCHES = ("main", "master")  # used when the clone has no origin/HEAD


class RefreshWriteRefused(ValueError):
    """A refresh write (digest update) is outside the allowed boundary; the message says what to do."""


def parse_frontmatter(text: str) -> tuple[dict, str]:
    """Return (fields, body). Text without a leading `---` block has no fields."""
    if not text.startswith("---"):
        return {}, text
    end = text.find("\n---", 3)
    if end < 0:
        return {}, text
    fields = {}
    for line in text[3:end].strip("\n").splitlines():
        if not line.strip() or line.lstrip().startswith("#") or ":" not in line:
            continue
        key, value = line.split(":", 1)
        fields[key.strip()] = value.strip().strip('"').strip("'")
    body = text[end + 4:].lstrip("\n")
    return fields, body


def section_bullets(body: str, heading: str) -> list[str]:
    """Bullet lines under `## heading`, without the leading dash."""
    m = re.search(rf"^##\s+{re.escape(heading)}\s*$(.*?)(?=^##\s|\Z)", body, re.M | re.S)
    if not m:
        return []
    return [ln.strip()[2:].strip() for ln in m.group(1).splitlines() if ln.strip().startswith("- ")]


def digest_path(slug: str, sources_dir: str = SOURCES_DIR) -> str:
    return os.path.join(sources_dir, f"{slug}.md")


def load_digest(slug: str, sources_dir: str = SOURCES_DIR) -> dict | None:
    path = digest_path(slug, sources_dir)
    if not os.path.isfile(path):
        return None
    with open(path, encoding="utf-8") as f:
        fields, body = parse_frontmatter(f.read())
    return {**fields, "summary": section_bullets(body, "Summary"), "quotes": section_bullets(body, "Cited quotes"),
            "path": f"references/sources/{slug}.md"}


def problems(slug: str, digest: dict | None) -> list[str]:
    if digest is None:
        return [f"digest references/sources/{slug}.md is missing; write one (see SKILL.md, refresh step 3)"]
    out = [f"{slug}: frontmatter needs {k}" for k in REQUIRED if not digest.get(k)]
    if digest.get("slug") and digest["slug"] != slug:
        out.append(f"{slug}: frontmatter slug is {digest['slug']!r}; make it match the file name")
    if digest.get("linkStatus") and digest["linkStatus"] not in LINK_STATUSES:
        out.append(f"{slug}: linkStatus must be one of {', '.join(LINK_STATUSES)}")
    if digest.get("linkStatus") == "redirected" and not digest.get("finalUrl"):
        out.append(f"{slug}: linkStatus redirected needs finalUrl")
    if not 5 <= len(digest.get("summary") or []) <= 12:
        out.append(f"{slug}: Summary should have 5-12 bullets (has {len(digest.get('summary') or [])})")
    return out


def _git(root: str, *args: str) -> str | None:
    try:
        r = subprocess.run(["git", "-C", root, *args], capture_output=True, text=True, timeout=10, check=False,
                           stdin=subprocess.DEVNULL)
    except (OSError, subprocess.TimeoutExpired):
        return None
    return r.stdout.strip() if r.returncode == 0 else None


def refresh_write_problem(path: str, allow_default_branch: bool = False) -> str | None:
    """Why refresh mode may not write this file (None when it may).

    Refresh writes belong in a clone of the skill repository on a review branch, so the change
    reaches users through a pull request: refuse symlinked targets, an installed copy outside
    git, a detached HEAD, and the default branch unless allow_default_branch is set.
    """
    p = os.path.abspath(os.path.expanduser(path))
    if os.path.islink(p):
        return f"refusing to write {p}: it is a symlink. Write the real file in a clone of the skill repository."
    root = _git(os.path.dirname(p), "rev-parse", "--show-toplevel")
    if not root:
        return (f"refusing to write {p}: it is not inside a git work tree, so this looks like an installed copy. "
                "Run refresh in a clone of the skill repository; installed copies update through skill updates.")
    # Walk the path as given up to the directory holding .git: a symlink on the way means the write
    # would go through a linked install into some repository. Links above the repository root
    # (such as /var -> /private/var on macOS) are not part of the install and are ignored.
    q = p
    while True:
        if os.path.islink(q):
            return (f"refusing to write {p}: {q} is a symlink. Run refresh in a real clone of the skill "
                    "repository, not through a linked install.")
        if os.path.exists(os.path.join(q, ".git")):
            break
        if os.path.dirname(q) == q:
            return f"refusing to write {p}: the path reaches {root} only through a symlink; use the clone's real path."
        q = os.path.dirname(q)
    branch = _git(root, "symbolic-ref", "--quiet", "--short", "HEAD")
    if not branch:
        return f"refusing to write {p}: {root} has a detached HEAD. Create a branch, e.g. git switch -c practices-refresh/<date>."
    origin_head = _git(root, "symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD")
    default = {origin_head.split("/", 1)[-1]} if origin_head else set(DEFAULT_BRANCHES)
    if branch in default and not allow_default_branch:
        return (f"refusing to write {p}: {root} is on the default branch {branch}. Create a review branch "
                "(git switch -c practices-refresh/<date>) or pass --allow-default-branch.")
    return None


def update_frontmatter(path: str, updates: dict, allow_default_branch: bool = False) -> None:
    """Rewrite selected frontmatter keys in place, keeping order and the body; new keys are appended.

    Raises RefreshWriteRefused outside a review branch of a git clone (see refresh_write_problem).
    """
    problem = refresh_write_problem(path, allow_default_branch)
    if problem:
        raise RefreshWriteRefused(problem)
    with open(path, encoding="utf-8") as f:
        text = f.read()
    end = text.find("\n---", 3)
    head, rest = text[3:end].strip("\n").splitlines(), text[end:]
    seen = set()
    for i, line in enumerate(head):
        key = line.split(":", 1)[0].strip()
        if key in updates:
            head[i] = f"{key}: {updates[key]}".rstrip()
            seen.add(key)
    head += [f"{k}: {v}".rstrip() for k, v in updates.items() if k not in seen]
    with open(path, "w", encoding="utf-8") as f:
        f.write("---\n" + "\n".join(head) + rest)


# ---------------------------------------------------------------- saved page text (refresh step 4)

def sha256_file(path: str) -> str:
    with open(path, "rb") as f:
        return hashlib.sha256(f.read()).hexdigest()


def new_run_id() -> str:
    return uuid.uuid4().hex


def write_manifest(pages_dir: str, entries: dict[str, dict], run_id: str | None = None) -> str:
    """Replace PAGES/manifest.json with this run's pages: slug -> {status, fetchedAt, url, runId, sha256?}.

    Only entries with status "fresh" and this manifest's runId may be used as live text; a file left
    over from an earlier run is not in the new manifest (or not fresh), so verifiers use the digest.
    """
    path = os.path.join(pages_dir, MANIFEST)
    if os.path.islink(path):
        raise RefreshWriteRefused(f"refusing to write {path}: it is a symlink")
    with open(path, "w", encoding="utf-8") as f:
        json.dump({"runId": run_id or new_run_id(),
                   "writtenAt": dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds"), "pages": entries},
                  f, ensure_ascii=False, indent=1)
    return path


def _recent(stamp, now: dt.datetime) -> bool:
    try:
        t = dt.datetime.fromisoformat(str(stamp))
    except ValueError:
        return False
    if t.tzinfo is None:
        t = t.replace(tzinfo=dt.timezone.utc)
    return dt.timedelta(0) <= now - t <= dt.timedelta(hours=MAX_PAGE_AGE_HOURS) or abs(now - t) < dt.timedelta(minutes=5)


def fresh_pages(pages_dir: str, now: dt.datetime | None = None) -> tuple[dict[str, dict], str | None]:
    """slug -> {path, url} for pages this run's manifest marks fresh.

    A page counts only when its entry has status "fresh", carries the manifest's runId, was
    fetched within MAX_PAGE_AGE_HOURS, and its file still matches the recorded sha256. The caller
    must also check that the entry's url is the source url it cites. Returns ({}, note) when the
    directory has no readable manifest, so every source uses its digest.
    """
    path = os.path.join(pages_dir, MANIFEST)
    try:
        with open(path, encoding="utf-8") as f:
            manifest = json.load(f)
        pages, run_id = manifest.get("pages") or {}, manifest.get("runId")
    except (OSError, ValueError, AttributeError):
        return {}, (f"no readable {MANIFEST} in {pages_dir}; every source uses its digest. "
                    "Save pages with check_practices.py --save-pages DIR.")
    now = now or dt.datetime.now(dt.timezone.utc)
    out, stale = {}, []
    for slug, e in pages.items():
        f = os.path.join(pages_dir, f"{slug}.txt")
        if not (isinstance(e, dict) and e.get("status") == "fresh"):
            continue
        if (run_id and e.get("runId") == run_id and _recent(e.get("fetchedAt"), now) and os.path.isfile(f)
                and not os.path.islink(f) and e.get("sha256") == sha256_file(f)):
            out[slug] = {"path": f, "url": e.get("url")}
        else:
            stale.append(slug)
    note = (f"saved page(s) not from this run, older than {MAX_PAGE_AGE_HOURS} h or changed since saving: "
            f"{', '.join(stale)}; their digests are used") if stale else None
    return out, note
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall