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/audit_common.py

View on GitHub
"""Definitions shared by extract.py, aggregate.py, config_scan.py and prejudge.py.

One place for tool-name sets, the path reducer, worktree folding and the practice
rule loader, so the modules cannot drift apart. Thresholds are not defined here:
they live only in references/practices.json (`rule.params`).
"""

from __future__ import annotations

import json
import os
import re

PRACTICES_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "references", "practices.json")
LOW_SAMPLE = 10  # hosts with fewer human sessions get a caveat, not a verdict

# File-edit tools (any host); a session that edits files or commits counts as a coding session.
EDIT_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit", "apply_patch", "write_file", "edit_file",
              "search_replace", "write", "create_file", "str_replace_based_edit_tool", "append_to_file"}
CHECK_TAGS = ("bash:test", "bash:lint", "bash:typecheck", "bash:screenshot")
# Tools (any host) that put a question to the user; extract.py also notes which came before the first edit.
ASK_USER_TOOLS = {"AskUserQuestion", "ask_user_question", "request_user_input", "request_user_input_async"}
# Runs of this skill itself (scheduled audits, refresh verifiers): never counted as the user's automation.
OWN_RUN = re.compile(r"agent-practice-audit|\b(?:run_audit|build_report|consensus|prejudge|config_scan)\.py\b")

# Worktree checkouts, folded into the repository they belong to. Codex keeps its worktrees under
# ~/.codex/worktrees/<id>/<repo>, so those fold to a `*` placeholder that keeps the repo name.
WORKTREE_RX = (
    re.compile(r"^(?P<root>.+?)/\.claude/worktrees/[^/]+"),
    re.compile(r"^(?P<root>.+?)/\.worktrees/[^/]+"),
    re.compile(r"^(?P<base>.*/\.codex[^/]*/worktrees)/[^/]+/(?P<repo>[^/]+)"),
    re.compile(r"^(?P<root>.+?)/worktrees/[^/]+"),
)


def home() -> str:
    return os.path.expanduser("~")


def tilde(p, home_dir: str | None = None) -> str:
    """The one path reducer: `~/...` under home, `(outside ~)/<name>` for anything else."""
    p = str(p or "")
    if not p or p == "~" or p.startswith("~/") or p.startswith("(outside ~)/"):
        return p
    h = (home_dir if home_dir is not None else home()).rstrip(os.sep)
    if h and (p == h or p.startswith(h + os.sep)):
        return "~" + p[len(h):]
    return "(outside ~)/" + os.path.basename(p.rstrip("/"))


def home_relative(p, home_dir: str | None = None):
    """Home prefix replaced by `~`; other paths unchanged (local-only files that still need full paths)."""
    if not isinstance(p, str):
        return p
    h = (home_dir if home_dir is not None else home()).rstrip(os.sep)
    if h and (p == h or p.startswith(h + os.sep)):
        return "~" + p[len(h):]
    return p


def worktree_root(path) -> tuple[str, bool]:
    """(repository the path belongs to, whether the path is inside a worktree checkout)."""
    p = str(path or "").rstrip("/")
    for rx in WORKTREE_RX:
        m = rx.match(p)
        if m:
            if "repo" in m.groupdict():
                return f"{m.group('base')}/*/{m.group('repo')}", True
            return m.group("root"), True
    return p, False


_REPO_CACHE: dict[str, str] = {}


def repo_identity(cwd) -> str:
    """Full path of the repository a working directory belongs to: worktree checkouts folded, and for a
    linked worktree whose `.git` file still exists, the main checkout it points to (read-only, cached).
    Two repositories that merely share a directory name stay distinct."""
    p = os.path.expanduser(str(cwd or "")).rstrip("/")
    if p in _REPO_CACHE:
        return _REPO_CACHE[p]
    root, is_wt = worktree_root(p)
    if is_wt:
        try:
            with open(os.path.join(os.path.expanduser(p), ".git"), encoding="utf-8") as f:
                line = f.read(4096).strip()
            m = re.match(r"gitdir:\s*(.+?)/\.git/worktrees/[^/]+/?$", line)
            if m:
                root = m.group(1)
        except OSError:
            pass
    _REPO_CACHE[p] = root
    return root


_CHECKOUT_CACHE: dict[str, str] = {}


def checkout_root(cwd) -> str:
    """The working tree a directory sits in: nearest ancestor with a `.git` entry (a clone's directory or a
    linked worktree's file), stopping below home and /. Unlike repo_identity, worktrees are NOT folded, so
    two checkouts of one repository stay apart. Falls back to the directory itself."""
    p = os.path.expanduser(str(cwd or "")).rstrip("/")
    if p in _CHECKOUT_CACHE:
        return _CHECKOUT_CACHE[p]
    h, cur, found = home().rstrip(os.sep), p, p
    while cur and cur != h and cur != os.path.dirname(cur):
        if os.path.exists(os.path.join(cur, ".git")):
            found = cur
            break
        cur = os.path.dirname(cur)
    _CHECKOUT_CACHE[p] = found
    return found


def file_checkout(path) -> str | None:
    """The checkout an edited file sits in, or None when no `.git` is found below home. A path inside a
    known worktree layout (`.claude/worktrees/<n>`, `.worktrees/<n>`, `~/.codex/worktrees/<id>/<repo>`,
    `worktrees/<n>`) maps to that worktree even after it was removed from disk."""
    p = os.path.expanduser(str(path or "")).rstrip("/")
    for rx in WORKTREE_RX:
        m = rx.match(p)
        if m:
            return m.group(0)
    h, cur = home().rstrip(os.sep), os.path.dirname(p)
    while cur and cur != h and cur != os.path.dirname(cur):
        if os.path.exists(os.path.join(cur, ".git")):
            return cur
        cur = os.path.dirname(cur)
    return None


def main_checkout(checkout) -> str:
    """For a linked worktree (its `.git` is a file pointing at `<main>/.git/worktrees/<n>`), the main
    checkout; else the path itself. Read-only."""
    p = os.path.expanduser(str(checkout or "")).rstrip("/")
    try:
        with open(os.path.join(p, ".git"), encoding="utf-8") as f:
            m = re.match(r"gitdir:\s*(.+?)/\.git/worktrees/[^/]+/?$", f.read(4096).strip())
        if m:
            return m.group(1)
    except OSError:
        pass
    return repo_identity(p)


def project_identity(checkout) -> str:
    """The project a checkout belongs to: its main checkout's remote, else the main checkout path."""
    main = main_checkout(checkout)
    return remote_identity(main) or main


_REMOTE_CACHE: dict[str, str | None] = {}
_REMOTE_URL = re.compile(r"^\s*url\s*=\s*(\S+)\s*$", re.M)


def normalise_remote(url: str) -> str:
    """`git@host:o/r.git`, `https://user:pw@host/o/r` and `ssh://git@host/o/r/` all become `host/o/r`."""
    u = url.strip()
    u = re.sub(r"^[a-z+]+://", "", u, flags=re.I)
    u = re.sub(r"^[^@/]*@", "", u)  # credentials or the ssh user
    u = re.sub(r"^([^/:]+):(?!\d+/)", r"\1/", u)  # scp-like host:path
    u = re.sub(r"^([^/:]+):\d+/", r"\1/", u)  # explicit port
    u = re.sub(r"(\.git)?/*$", "", u)
    host, _, rest = u.partition("/")
    return f"{host.lower()}/{rest}"


def remote_identity(repo) -> str | None:
    """Normalised URL of the `origin` remote (else the first remote) of a repository path, read from its
    `.git/config` (read-only, cached); None when there is none. Clones of one remote in different
    directories share it. The URL itself never leaves this process: callers hash it."""
    p = os.path.expanduser(str(repo or "")).rstrip("/")
    if p in _REMOTE_CACHE:
        return _REMOTE_CACHE[p]
    out = None
    try:
        with open(os.path.join(p, ".git", "config"), encoding="utf-8", errors="replace") as f:
            text = f.read(1 << 16)
        sections = re.split(r"(?m)^\s*\[", text)
        remotes = [s for s in sections if s.startswith("remote ")]
        remotes.sort(key=lambda s: not s.startswith('remote "origin"'))
        for s in remotes:
            m = _REMOTE_URL.search(s)
            if m:
                out = normalise_remote(m.group(1))
                break
    except OSError:
        pass
    _REMOTE_CACHE[p] = out
    return out


def rules_from(practices) -> dict:
    """{practice id: rule.params} for practices that define params; nothing is filled in by code."""
    out = {}
    for p in practices if isinstance(practices, list) else []:
        rule = p.get("rule") if isinstance(p, dict) else None
        if isinstance(rule, dict) and isinstance(rule.get("params"), dict):
            out[p.get("id")] = {k: v for k, v in rule["params"].items() if isinstance(v, (int, float))}
    return out


def load_practices(path: str = PRACTICES_PATH) -> list:
    try:
        with open(path, encoding="utf-8") as f:
            doc = json.load(f)
    except (OSError, ValueError):
        return []
    doc = doc.get("practices") if isinstance(doc, dict) else doc
    return doc if isinstance(doc, list) else []


def load_rules(path: str = PRACTICES_PATH) -> dict:
    return rules_from(load_practices(path))
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