[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6MZ2WHT9CJ90QJX0K79Z61C":3,"skill-same:01M6MZ2WHT9CJ90QJX0K79Z61C":80},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":39,"linkOnly":40,"markdownContent":41,"markdownBody":42,"frontMatter":43,"refName":44,"commitSha":45,"skillDirectory":46,"forksCount":47,"repositoryHtmlUrl":48,"repositoryHomepageUrl":6,"ownerHtmlUrl":49,"ownerBlogUrl":6,"ownerDescription":50,"updatedAt":51,"install":52,"resources":65},"01M6MZ2WHT9CJ90QJX0K79Z61C","logging-and-comments",null,"Logging and code-comment standard for Python and Bash: library vs app logging, stderr vs stdout, no silent failures, run-level context for pipelines, why-comments, docstrings, constant rationale, TODO format, and the Ruff rules that enforce it. Use when writing or reviewing any script, CLI, hook, pipeline, or library code, or when adding try\u002Fexcept, || true, or 2>\u002Fdev\u002Fnull.","snewhouse\u002Faa-ma-forge","snewhouse","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6317143?v=4","01M6MYYWF28C4KBQHHWB9SC6TS","Stephen J Newhouse","01M6MYYWJWQMDN2ZPFMJ584SSM",6,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fsnewhouse\u002Faa-ma-forge\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Flogging-and-comments\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38],"logging and comments","comments","logging","use","docstrings","for","true","app","enforce","todo","ruff","writing","Rules","Bash","pipeline","dev","code","run","python","cli","2026-11-10 10:12:30",false,"---\nname: logging-and-comments\ndescription: \"Logging and code-comment standard for Python and Bash: library vs app logging, stderr vs stdout, no silent failures, run-level context for pipelines, why-comments, docstrings, constant rationale, TODO format, and the Ruff rules that enforce it. Use when writing or reviewing any script, CLI, hook, pipeline, or library code, or when adding try\u002Fexcept, || true, or 2>\u002Fdev\u002Fnull.\"\n---\n\n# Logging & Comments Standard\n\n**Why this exists:** a 2026-10-06 audit of our repos found that the most expensive defects were *silent*. Examples:\n- The `~\u002F.claude` rm-guard hook was fail-open with no log line. It never fired, and nothing showed it.\n- Backfill sources dropped repos with `except: continue`, so billing totals undercounted.\n- `except Exception: pass` sat on a state write.\n\nThe rules below exist so that failures are visible and the reason behind the code is written down.\n\nDetail: [references\u002Fpython.md](references\u002Fpython.md) · [references\u002Fbash.md](references\u002Fbash.md) · lint config: [references\u002Fruff-baseline.toml](references\u002Fruff-baseline.toml)\n\n## The five non-negotiables\n\n1. **No silent failure.** Every `except`, `|| true`, `2>\u002Fdev\u002Fnull`, `continue`-on-error or fail-open exit must do one of these:\n   - log one line saying what failed and why it's safe to continue;\n   - **increment a counter that is reported** in the run summary;\n   - re-raise.\n\n   If it's deliberately silent, add a `# why:` comment saying so.\n2. **Data → stdout, diagnostics → stderr.** stdout is for pipeable output (in Claude Code hooks it carries model context or a JSON decision; see the hooks section below). Logs, progress, warnings and errors go to stderr or a log file.\n3. **Configure logging once, at the entrypoint.**\n   - Library modules only do `logger = logging.getLogger(__name__)`.\n   - Never call `basicConfig` or add handlers in an importable module.\n   - Never call the root `logging.info(...)` directly.\n4. **Never log secrets or PII.** That covers tokens, keys, passwords, connection strings with userinfo, git remote URLs containing credentials, patient or person identifiers, and full request payloads. Log the *shape* (field names, counts, hashes), not the values. See lessons.md \"git config key containing a token\".\n5. **Comments explain *why*, never *what*.** If a comment restates the code, delete it or rename the variable. Update comments in the same diff as the code they describe.\n\n## Python logging — quick reference\n\n```python\nimport logging\nlogger = logging.getLogger(__name__)          # module level, always __name__\n\nlogger.info(\"Loaded %d records from %s\", n, path)   # lazy %-args, NOT f-strings (Ruff G004)\ntry:\n    parse(row)\nexcept ValueError:\n    skipped[\"bad_row\"] += 1                    # count it…\n    logger.warning(\"Skipping row %d: unparseable\", i)   # …and\u002For say it\nexcept Exception:\n    logger.exception(\"Unexpected failure on row %d\", i) # includes traceback (TRY400)\n    raise\n```\n\n| Level | Use for |\n|---|---|\n| DEBUG | Internals useful when diagnosing (payload shapes, branch taken) |\n| INFO | Milestones a user running the job wants: start, stage done, summary |\n| WARNING | Something unexpected, but the run continues (skips, fallbacks, retries) |\n| ERROR | An operation failed; the output is incomplete |\n| CRITICAL | The process cannot continue |\n\n**CLIs:**\n- Provide `-v\u002F--verbose` (repeatable) and `-q\u002F--quiet`, with a `LOG_LEVEL` env var as the default; flags win over the env var.\n- **Two debug switches only:** `LOG_LEVEL` for programs, `HOOK_DEBUG=1` for hooks. No per-tool verbose or debug variables; one switch per kind means one thing to remember.\n- `print()` is fine *only* for the CLI's real output. Ruff T20 is ignored for `cli.py`, `__main__.py` and `scripts\u002F**`.\n\n**Batch \u002F pipeline \u002F scientific runs:** log enough to reproduce the run and to check it.\n- **At start:** `run_id`, git SHA (+ dirty flag), tool\u002Fpackage versions, config (or its hash), input paths + sha256, random seed.\n- **At end:** counts in \u002F out \u002F dropped-by-reason, per-stage wall time, output paths.\n- Write the same facts to a `manifest.json` next to the outputs.\n- Shape: one `run()` entrypoint that writes the start facts, runs the stages, then writes the end facts and `manifest.json`.\n\n**JSON logs: the default for long-running services, opt-in everywhere else.**\n- A service emits JSON lines to stdout and lets the platform collect them (12-factor). Bind a `trace_id`\u002F`run_id` to every line via `contextvars` or a `LoggerAdapter`. Don't run two logging libraries in one service.\n- CLIs, hooks and batch jobs log text to stderr. JSON is an opt-in, `LOG_FORMAT=json|text` (default `text`), because a human reads them first.\n- Use stdlib logging and a JSON formatter. `aa_ma.logsetup.configure_logging` is the forge's own: it masks secrets in both formats.\n- Node: pino defaults to **stdout**, so CLIs and hooks must pass `pino.destination(2)` to keep stdout for data.\n\n## Bash \u002F hooks — quick reference\n\n```bash\nset -Eeuo pipefail\nlog() { printf '%s %-5s %s\\n' \"$(date -Is)\" \"$1\" \"${*:2}\" >&2; }   # ISO time, level, stderr\ntrap 'log ERROR \"line $LINENO: \\\"$BASH_COMMAND\\\" exited $?\"' ERR\n\ncp \"$src\" \"$dst\" || { log WARN \"copy failed for $src; continuing with stale copy\"; }\ngrep -q foo f 2>\u002Fdev\u002Fnull || true   # why: f may not exist yet on first run; absence == no match\n```\n\n`set -e` is a safety net, not error handling. It does not fire inside `if`, `&&` and `||`, in functions called from those, or in `$(…)` without `inherit_errexit`, and `local x=$(cmd)` hides the status ([BashFAQ\u002F105](https:\u002F\u002Fmywiki.wooledge.org\u002FBashFAQ\u002F105)). So check the status wherever a failure changes the result. Detail: `Skill(bash-defensive-patterns)`.\n\nClaude Code hooks are a special case (rules verified against [the hooks docs](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fhooks), 2026-10-06):\n- **On exit 0, stderr reaches only the debug log; nobody sees it.** Plain stdout goes to the model for UserPromptSubmit and SessionStart, and to the debug log for most other events. Hooks must exit fast.\n- **To tell the user something on exit 0, print JSON `{\"systemMessage\": \"...\"}` to stdout.** It is shown to the user but not to the model, and on PreToolUse the tool call still proceeds. Verified live, it shows as `PreToolUse:Bash says: …`.\n- **A fail-open path writes a `systemMessage` and also one line to a log file:** `~\u002F.claude\u002Flogs\u002Fhooks.log` (override: `CLAUDE_HOOK_LOG`). Each line is `ISO-ts LEVEL hook-name: msg`, e.g. `2026-10-12T09:41:00+01:00 WARN pre-compact-aa-ma: could not append …`. `hooks\u002Flib\u002Faa-ma-log.sh` writes it: `log_info|warn|error|debug \u003Chook> \u003Cmsg>` masks secrets, caps the line at 8192 chars, and never trips `set -e`; `fail_open_notice \u003Chook> \u003Cmsg>` emits the `systemMessage` too. Keep its regression test, feed it a real payload, and assert that the message is emitted. Patterns: `claude-code\u002Fhooks\u002Fpre-compact-aa-ma.sh` (`fail_open_notice` on an append failure) and its test `tests\u002Fhooks\u002Fpre-compact.bats`.\n- **Debug chatter is opt-in.** Gate it with `HOOK_DEBUG=1` → `log_debug` (`hooks\u002Flib\u002Faa-ma-log.sh`).\n\n## Comments & docstrings\n\n- **Docstrings on every public module, class and function**, in Google style (`Args:`, `Returns:`, `Raises:`). State constraints the signature can't show: units, side effects, idempotency, which HTTP verb (PUT vs PATCH), and thread safety.\n- **Every magic number gets a name, a unit and a reason**, ideally with its source or a test that pins it:\n  ```python\n  LINE_TOL = 1.5  # pt; JS1 definition text puts \"a)\" markers 1.0 pt off their line's baseline\n  MAX_FINDINGS = 200  # `check` output reaches an agent's context; the rest is counted, not printed\n  ```\n- **Suppressions carry a reason:** `# noqa: S105  # why: enum value, not a credential`. The same applies to `# nosec`, `# type: ignore[...]`, `|| true` and `2>\u002Fdev\u002Fnull`.\n- **TODOs are traceable:** `# TODO(#123): drop once upstream fixes X` or `# TODO(ADR-0014): …`. A bare `# TODO` is not allowed (Ruff TD).\n- **Non-obvious design choices point to the record:** `# See ADR-0009` or `# See lessons.md L-1300`.\n- **Delete commented-out code** (Ruff ERA). Git remembers it.\n- **Deliberate shortcuts are marked `# ponytail: \u003Cceiling>, \u003Cupgrade path>`.**\n- **Don't** narrate (`# loop over rows`), leave section banners in short functions, or write docstrings that claim features the code doesn't have (e.g. \"async queue\" when there is no queue).\n\n## Enforcement\n\n- **Ruff:** merge `references\u002Fruff-baseline.toml` into each project's `pyproject.toml`. If an existing repo has many pre-existing violations, put the noisy codes in `extend-ignore` tagged `# TODO(logging-std): burn down`, rather than mass-fixing them.\n- **The PostToolUse `ruff-format.sh` hook** runs `ruff check --fix` on every edit. T201's fix is unsafe-only, so prints are reported, never deleted (verified on ruff 0.15.4). Findings it cannot fix come back to the model as `additionalContext` (≤10 lines). Hook failures are logged to `~\u002F.claude\u002Flogs\u002Fhooks.log`.\n- **Review checklist for a diff:**\n  - grep the added lines for `except`, `|| true`, `2>\u002Fdev\u002Fnull`, `continue` and `pass`, and check that each one logs, counts or has a `# why:`;\n  - check that each new constant has a rationale;\n  - check that each new public function has a docstring.\n\n## Sources\n\nPython [Logging HOWTO](https:\u002F\u002Fdocs.python.org\u002F3\u002Fhowto\u002Flogging.html) and [Cookbook](https:\u002F\u002Fdocs.python.org\u002F3\u002Fhowto\u002Flogging-cookbook.html) · [PEP 8 comments](https:\u002F\u002Fpeps.python.org\u002Fpep-0008\u002F#comments) · [PEP 257](https:\u002F\u002Fpeps.python.org\u002Fpep-0257\u002F) · [Google Python style §3.8, §3.10, §3.12](https:\u002F\u002Fgoogle.github.io\u002Fstyleguide\u002Fpyguide.html) · [Google Shell style §3.1, §4](https:\u002F\u002Fgoogle.github.io\u002Fstyleguide\u002Fshellguide.html) · [Ruff rules](https:\u002F\u002Fdocs.astral.sh\u002Fruff\u002Frules\u002F) · [clig.dev](https:\u002F\u002Fclig.dev\u002F) · [12-factor logs](https:\u002F\u002F12factor.net\u002Flogs) · [OWASP Logging Cheat Sheet](https:\u002F\u002Fcheatsheetseries.owasp.org\u002Fcheatsheets\u002FLogging_Cheat_Sheet.html)\n","# Logging & Comments Standard\n\n**Why this exists:** a 2026-10-06 audit of our repos found that the most expensive defects were *silent*. Examples:\n- The `~\u002F.claude` rm-guard hook was fail-open with no log line. It never fired, and nothing showed it.\n- Backfill sources dropped repos with `except: continue`, so billing totals undercounted.\n- `except Exception: pass` sat on a state write.\n\nThe rules below exist so that failures are visible and the reason behind the code is written down.\n\nDetail: [references\u002Fpython.md](references\u002Fpython.md) · [references\u002Fbash.md](references\u002Fbash.md) · lint config: [references\u002Fruff-baseline.toml](references\u002Fruff-baseline.toml)\n\n## The five non-negotiables\n\n1. **No silent failure.** Every `except`, `|| true`, `2>\u002Fdev\u002Fnull`, `continue`-on-error or fail-open exit must do one of these:\n   - log one line saying what failed and why it's safe to continue;\n   - **increment a counter that is reported** in the run summary;\n   - re-raise.\n\n   If it's deliberately silent, add a `# why:` comment saying so.\n2. **Data → stdout, diagnostics → stderr.** stdout is for pipeable output (in Claude Code hooks it carries model context or a JSON decision; see the hooks section below). Logs, progress, warnings and errors go to stderr or a log file.\n3. **Configure logging once, at the entrypoint.**\n   - Library modules only do `logger = logging.getLogger(__name__)`.\n   - Never call `basicConfig` or add handlers in an importable module.\n   - Never call the root `logging.info(...)` directly.\n4. **Never log secrets or PII.** That covers tokens, keys, passwords, connection strings with userinfo, git remote URLs containing credentials, patient or person identifiers, and full request payloads. Log the *shape* (field names, counts, hashes), not the values. See lessons.md \"git config key containing a token\".\n5. **Comments explain *why*, never *what*.** If a comment restates the code, delete it or rename the variable. Update comments in the same diff as the code they describe.\n\n## Python logging — quick reference\n\n```python\nimport logging\nlogger = logging.getLogger(__name__)          # module level, always __name__\n\nlogger.info(\"Loaded %d records from %s\", n, path)   # lazy %-args, NOT f-strings (Ruff G004)\ntry:\n    parse(row)\nexcept ValueError:\n    skipped[\"bad_row\"] += 1                    # count it…\n    logger.warning(\"Skipping row %d: unparseable\", i)   # …and\u002For say it\nexcept Exception:\n    logger.exception(\"Unexpected failure on row %d\", i) # includes traceback (TRY400)\n    raise\n```\n\n| Level | Use for |\n|---|---|\n| DEBUG | Internals useful when diagnosing (payload shapes, branch taken) |\n| INFO | Milestones a user running the job wants: start, stage done, summary |\n| WARNING | Something unexpected, but the run continues (skips, fallbacks, retries) |\n| ERROR | An operation failed; the output is incomplete |\n| CRITICAL | The process cannot continue |\n\n**CLIs:**\n- Provide `-v\u002F--verbose` (repeatable) and `-q\u002F--quiet`, with a `LOG_LEVEL` env var as the default; flags win over the env var.\n- **Two debug switches only:** `LOG_LEVEL` for programs, `HOOK_DEBUG=1` for hooks. No per-tool verbose or debug variables; one switch per kind means one thing to remember.\n- `print()` is fine *only* for the CLI's real output. Ruff T20 is ignored for `cli.py`, `__main__.py` and `scripts\u002F**`.\n\n**Batch \u002F pipeline \u002F scientific runs:** log enough to reproduce the run and to check it.\n- **At start:** `run_id`, git SHA (+ dirty flag), tool\u002Fpackage versions, config (or its hash), input paths + sha256, random seed.\n- **At end:** counts in \u002F out \u002F dropped-by-reason, per-stage wall time, output paths.\n- Write the same facts to a `manifest.json` next to the outputs.\n- Shape: one `run()` entrypoint that writes the start facts, runs the stages, then writes the end facts and `manifest.json`.\n\n**JSON logs: the default for long-running services, opt-in everywhere else.**\n- A service emits JSON lines to stdout and lets the platform collect them (12-factor). Bind a `trace_id`\u002F`run_id` to every line via `contextvars` or a `LoggerAdapter`. Don't run two logging libraries in one service.\n- CLIs, hooks and batch jobs log text to stderr. JSON is an opt-in, `LOG_FORMAT=json|text` (default `text`), because a human reads them first.\n- Use stdlib logging and a JSON formatter. `aa_ma.logsetup.configure_logging` is the forge's own: it masks secrets in both formats.\n- Node: pino defaults to **stdout**, so CLIs and hooks must pass `pino.destination(2)` to keep stdout for data.\n\n## Bash \u002F hooks — quick reference\n\n```bash\nset -Eeuo pipefail\nlog() { printf '%s %-5s %s\\n' \"$(date -Is)\" \"$1\" \"${*:2}\" >&2; }   # ISO time, level, stderr\ntrap 'log ERROR \"line $LINENO: \\\"$BASH_COMMAND\\\" exited $?\"' ERR\n\ncp \"$src\" \"$dst\" || { log WARN \"copy failed for $src; continuing with stale copy\"; }\ngrep -q foo f 2>\u002Fdev\u002Fnull || true   # why: f may not exist yet on first run; absence == no match\n```\n\n`set -e` is a safety net, not error handling. It does not fire inside `if`, `&&` and `||`, in functions called from those, or in `$(…)` without `inherit_errexit`, and `local x=$(cmd)` hides the status ([BashFAQ\u002F105](https:\u002F\u002Fmywiki.wooledge.org\u002FBashFAQ\u002F105)). So check the status wherever a failure changes the result. Detail: `Skill(bash-defensive-patterns)`.\n\nClaude Code hooks are a special case (rules verified against [the hooks docs](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fhooks), 2026-10-06):\n- **On exit 0, stderr reaches only the debug log; nobody sees it.** Plain stdout goes to the model for UserPromptSubmit and SessionStart, and to the debug log for most other events. Hooks must exit fast.\n- **To tell the user something on exit 0, print JSON `{\"systemMessage\": \"...\"}` to stdout.** It is shown to the user but not to the model, and on PreToolUse the tool call still proceeds. Verified live, it shows as `PreToolUse:Bash says: …`.\n- **A fail-open path writes a `systemMessage` and also one line to a log file:** `~\u002F.claude\u002Flogs\u002Fhooks.log` (override: `CLAUDE_HOOK_LOG`). Each line is `ISO-ts LEVEL hook-name: msg`, e.g. `2026-10-12T09:41:00+01:00 WARN pre-compact-aa-ma: could not append …`. `hooks\u002Flib\u002Faa-ma-log.sh` writes it: `log_info|warn|error|debug \u003Chook> \u003Cmsg>` masks secrets, caps the line at 8192 chars, and never trips `set -e`; `fail_open_notice \u003Chook> \u003Cmsg>` emits the `systemMessage` too. Keep its regression test, feed it a real payload, and assert that the message is emitted. Patterns: `claude-code\u002Fhooks\u002Fpre-compact-aa-ma.sh` (`fail_open_notice` on an append failure) and its test `tests\u002Fhooks\u002Fpre-compact.bats`.\n- **Debug chatter is opt-in.** Gate it with `HOOK_DEBUG=1` → `log_debug` (`hooks\u002Flib\u002Faa-ma-log.sh`).\n\n## Comments & docstrings\n\n- **Docstrings on every public module, class and function**, in Google style (`Args:`, `Returns:`, `Raises:`). State constraints the signature can't show: units, side effects, idempotency, which HTTP verb (PUT vs PATCH), and thread safety.\n- **Every magic number gets a name, a unit and a reason**, ideally with its source or a test that pins it:\n  ```python\n  LINE_TOL = 1.5  # pt; JS1 definition text puts \"a)\" markers 1.0 pt off their line's baseline\n  MAX_FINDINGS = 200  # `check` output reaches an agent's context; the rest is counted, not printed\n  ```\n- **Suppressions carry a reason:** `# noqa: S105  # why: enum value, not a credential`. The same applies to `# nosec`, `# type: ignore[...]`, `|| true` and `2>\u002Fdev\u002Fnull`.\n- **TODOs are traceable:** `# TODO(#123): drop once upstream fixes X` or `# TODO(ADR-0014): …`. A bare `# TODO` is not allowed (Ruff TD).\n- **Non-obvious design choices point to the record:** `# See ADR-0009` or `# See lessons.md L-1300`.\n- **Delete commented-out code** (Ruff ERA). Git remembers it.\n- **Deliberate shortcuts are marked `# ponytail: \u003Cceiling>, \u003Cupgrade path>`.**\n- **Don't** narrate (`# loop over rows`), leave section banners in short functions, or write docstrings that claim features the code doesn't have (e.g. \"async queue\" when there is no queue).\n\n## Enforcement\n\n- **Ruff:** merge `references\u002Fruff-baseline.toml` into each project's `pyproject.toml`. If an existing repo has many pre-existing violations, put the noisy codes in `extend-ignore` tagged `# TODO(logging-std): burn down`, rather than mass-fixing them.\n- **The PostToolUse `ruff-format.sh` hook** runs `ruff check --fix` on every edit. T201's fix is unsafe-only, so prints are reported, never deleted (verified on ruff 0.15.4). Findings it cannot fix come back to the model as `additionalContext` (≤10 lines). Hook failures are logged to `~\u002F.claude\u002Flogs\u002Fhooks.log`.\n- **Review checklist for a diff:**\n  - grep the added lines for `except`, `|| true`, `2>\u002Fdev\u002Fnull`, `continue` and `pass`, and check that each one logs, counts or has a `# why:`;\n  - check that each new constant has a rationale;\n  - check that each new public function has a docstring.\n\n## Sources\n\nPython [Logging HOWTO](https:\u002F\u002Fdocs.python.org\u002F3\u002Fhowto\u002Flogging.html) and [Cookbook](https:\u002F\u002Fdocs.python.org\u002F3\u002Fhowto\u002Flogging-cookbook.html) · [PEP 8 comments](https:\u002F\u002Fpeps.python.org\u002Fpep-0008\u002F#comments) · [PEP 257](https:\u002F\u002Fpeps.python.org\u002Fpep-0257\u002F) · [Google Python style §3.8, §3.10, §3.12](https:\u002F\u002Fgoogle.github.io\u002Fstyleguide\u002Fpyguide.html) · [Google Shell style §3.1, §4](https:\u002F\u002Fgoogle.github.io\u002Fstyleguide\u002Fshellguide.html) · [Ruff rules](https:\u002F\u002Fdocs.astral.sh\u002Fruff\u002Frules\u002F) · [clig.dev](https:\u002F\u002Fclig.dev\u002F) · [12-factor logs](https:\u002F\u002F12factor.net\u002Flogs) · [OWASP Logging Cheat Sheet](https:\u002F\u002Fcheatsheetseries.owasp.org\u002Fcheatsheets\u002FLogging_Cheat_Sheet.html)\n",{"name":5,"description":7},"main","cd9a2962c9a7e0797fe440f7b1ba4ceccc16ae0d","claude-code\u002Fskills\u002Flogging-and-comments",1,"https:\u002F\u002Fgithub.com\u002Fsnewhouse\u002Faa-ma-forge","https:\u002F\u002Fgithub.com\u002Fsnewhouse","Data Scientist, Bioinformatician, Dad, Husband, MS warrior","2026-11-11 21:34:39",{"source":8,"skillName":5,"commands":53,"prompt":63,"zipAvailable":64},[54,57,60],{"tool":55,"command":56},"npx","npx skills add snewhouse\u002Faa-ma-forge --skill logging-and-comments",{"tool":58,"command":59},"bunx","bunx skills add snewhouse\u002Faa-ma-forge --skill logging-and-comments",{"tool":61,"command":62},"pnpm","pnpm dlx skills add snewhouse\u002Faa-ma-forge --skill logging-and-comments","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fsnewhouse\u002Faa-ma-forge\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Flogging-and-comments\u002FSKILL.md",true,[66,72,76],{"path":67,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":70,"sourceHtmlUrl":71},"references\u002Fbash.md","REFERENCE","参考文档",4134,"https:\u002F\u002Fgithub.com\u002Fsnewhouse\u002Faa-ma-forge\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Flogging-and-comments\u002Freferences\u002Fbash.md",{"path":73,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":74,"sourceHtmlUrl":75},"references\u002Fpython.md",5645,"https:\u002F\u002Fgithub.com\u002Fsnewhouse\u002Faa-ma-forge\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Flogging-and-comments\u002Freferences\u002Fpython.md",{"path":77,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":78,"sourceHtmlUrl":79},"references\u002Fruff-baseline.toml",1250,"https:\u002F\u002Fgithub.com\u002Fsnewhouse\u002Faa-ma-forge\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Flogging-and-comments\u002Freferences\u002Fruff-baseline.toml",[81,105,131,152,176,206],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":92,"publishedAt":39},"01M6MZ588SD5DDH59H18PRNWEV","deploy-helper","You can use this to help with deploy stuff, deploying, deployments, releases, shipping, pushing to prod, going live, rollouts.","https:\u002F\u002Fgithub.com\u002Fsnewhouse\u002Faa-ma-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fevals\u002Fskill-draft\u002Fdraft\u002FSKILL.md",[87],{"categoryNo":88,"categoryName":89,"taxonomyType":90,"taxonomyTypeDesc":91},"01JBSEEDCAT000000000000011","运维与部署","SCENARIO","使用场景",[93,94,95,96,97,98,99,100,101,22,102,103,104],"deploy","deploy helper","helper","you","live","with","can","rollouts","shipping","deployments","releases","help",{"skillNo":106,"name":107,"nameZh":6,"description":108,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":109,"licenseFileUrl":110,"sourceHtmlUrl":111,"categories":112,"keywords":124,"publishedAt":39},"01M6MZ54NEKRYXGMJ1KJWYMKM7","writing-for-agents","Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.","MIT","https:\u002F\u002Fgithub.com\u002Fsnewhouse\u002Faa-ma-forge\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fwriting-for-agents\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fsnewhouse\u002Faa-ma-forge\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fwriting-for-agents\u002FSKILL.md",[113,116,119],{"categoryNo":114,"categoryName":115,"taxonomyType":90,"taxonomyTypeDesc":91},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":117,"categoryName":118,"taxonomyType":90,"taxonomyTypeDesc":91},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":120,"categoryName":121,"taxonomyType":122,"taxonomyTypeDesc":123},"01JBSEEDCAT000000000000036","内容创作者","PROFESSION","适用职业",[30,125,24,126,22,127,128,129,130],"writing for agents","line","instructions","read","editing","documents",{"skillNo":132,"name":133,"nameZh":6,"description":134,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":135,"categories":136,"keywords":137,"publishedAt":39},"01M6MZ500T0FH1G8TBSQV7G5G2","verify-plan","Slash entry for plan verification: runs plan-verification on an existing AA-MA plan, writes [task]-verification.md, and with --iterate loops until the plan converges. Use when the user types \u002Fverify-plan or wants the verification report saved.","https:\u002F\u002Fgithub.com\u002Fsnewhouse\u002Faa-ma-forge\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fverify-plan\u002FSKILL.md",[],[138,139,140,141,142,22,143,98,144,145,146,147,148,149,150,24,151],"verify","plan","verify plan","loops","task","user","verification","report","types","plan verification","entry","iterate","Existing","saved",{"skillNo":153,"name":154,"nameZh":6,"description":155,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":156,"categories":157,"keywords":158,"publishedAt":39},"01M6MZ4V9ST4K54NT1SRBGCE7P","verify-impl","Post-impl adversarial review symmetric to \u002Fverify-plan. Dispatches up to 5 parallel audit agents (code-reviewer, security-auditor, tdd-sequence-auditor, context7-evidence-auditor, future-proofing-auditor) based on the milestone's plan-declared Audit-Profile. CRITICAL findings surface via AskUserQuestion accept\u002Fdispute\u002Fdefer panel before §7.3 user authorization. Introduced in v0.8.0 per ADR-0005. Invoked by Phase 6.8 of \u002Fexecute-aa-ma-milestone.","https:\u002F\u002Fgithub.com\u002Fsnewhouse\u002Faa-ma-forge\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fverify-impl\u002FSKILL.md",[],[159,160,138,161,162,163,164,165,166,167,168,169,170,171,172,139,173,35,174,175],"impl","verify impl","adversarial","post","panel","via","critical","review","context7","up","evidence","reviewer","parallel","adr","audit","tdd","milestone",{"skillNo":177,"name":178,"nameZh":6,"description":179,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":180,"categories":181,"keywords":186,"publishedAt":39},"01M6MZ4K7CC9PMJ1KEY3F53RS1","understand-codebase","Onboard to a new, inherited, or shared codebase. Read it, understand it, map it, and learn its conventions, versioning, tests, tech stack, rules (AGENTS.md \u002F CLAUDE.md \u002F .cursorrules \u002F etc.), build\u002Frun\u002FCI, integrations, security posture, and repo health — then produce an honest pros\u002Fcons verdict, a \"contribute safely\" playbook, and an \"add a feature\" playbook, written to ONBOARDING.md at the repo root plus a .claude\u002Fonboarding\u002F set of deep-dives — and optionally author an AGENTS.md if one is missing, or review and propose improvements to an existing one. Tiered (Quick \u002F Standard \u002F Deep). Reuses codemem (index + diagrams), gsd-map-codebase, system-mapping, code-intelligence, impact-analysis rather than re-implementing them; Deep tier runs a TeamCreate agent-team. Keywords: new codebase, shared codebase, inherited code, onboard, understand this repo, how do I contribute, how do I add a feature, ramp up, get oriented, ONBOARDING.md, AGENTS.md, codebase walkthrough, joining a project.","https:\u002F\u002Fgithub.com\u002Fsnewhouse\u002Faa-ma-forge\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Funderstand-codebase\u002FSKILL.md",[182,183],{"categoryNo":117,"categoryName":118,"taxonomyType":90,"taxonomyTypeDesc":91},{"categoryNo":184,"categoryName":185,"taxonomyType":122,"taxonomyTypeDesc":123},"01JBSEEDCAT000000000000038","人力资源",[187,188,189,168,190,191,192,193,194,195,196,197,198,199,200,201,202,203,204,205],"understand codebase","codebase","understand","walkthrough","analysis","SET","ci","learn","diagrams","repo health","implementing","re","quick","impact","get","project","deep","shared","map",{"skillNo":207,"name":208,"nameZh":6,"description":209,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":210,"categories":211,"keywords":212,"publishedAt":39},"01M6MZ4D1ZC8MTW064QXY6WC76","token-compression","Output token compression for AA-MA workflows. Reduces response tokens by 40-75% while preserving full technical accuracy. Three intensity levels mapped to execution modes: lite (HITL), full (general), ultra (AFK). Auto-activates during AA-MA execution based on task Mode field. Manual activation via \u002Fcompress lite|full|ultra.","https:\u002F\u002Fgithub.com\u002Fsnewhouse\u002Faa-ma-forge\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Ftoken-compression\u002FSKILL.md",[],[213,214,215,216,217,218,219,24,220,221,164,222,223,224,225,142,226,227,228,229],"compression","token compression","token","workflows","output","modes","accuracy","mode","manual","intensity","tokens","hitl","three","general","auto","technical","execution"]