[optimization:skills-curator] Extract Debugging & Logging section from AGENTS.md into debugging-workflows skill

[cao-githubnext-gh-aw-cao-write]

Skill inventory

Skill	Description chars	Body size	Days since change	Commits touching	Referenced in tracked files
debugging-workflows	65	13,325 B	43	6	0
error-pattern-safety	60	5,386 B	20	4	2
github-copilot-agent-tips-and-tricks	61	6,423 B	131	3	0
(+37 more skills, 40 total)	—	—	—	—	—

AGENTS.md: 19 sections, estimated_tokens = 2,188. Procedure-shaped section identified:

• "Debugging & Logging" (AGENTS.md lines 76–146, 2,505 chars across 7 subsections: enabling DEBUG namespaces, key-namespace table, adding debug logs in Go, GitHub Actions debug runs, output format) — this is a step-by-step Go/CLI debugging procedure, not a fact every run needs, and it duplicates ground already covered procedurally by the existing debugging-workflows skill (which currently only covers gh aw logs/gh aw audit, not the pkg/logger namespace conventions).

No skill in the repository currently documents pkg/logger namespace conventions — moving this content into debugging-workflows consolidates all debugging guidance (CLI log/audit tooling + Go instrumentation) into one skill instead of splitting it between the always-loaded file and a skill.

Estimated gain

• Always-loaded tokens today: agents_md.estimated_tokens (2,188) + all skill name+description tokens (4,565 chars ÷ 4 ≈ 1,141) = 3,329 tokens
• Chars removed from AGENTS.md (full "Debugging & Logging" section, lines 76–146): 2,505
• Chars added back (one-line pointer replacing the section): 301
• Net chars removed: 2,204 → ≈ 551 tokens removed
• Net gain: 551 / 3,329 ≈ 16.6% — clears the 10% gate on the extraction alone

Proposed changes

1. AGENTS.md, "Debugging & Logging" section (lines 76–146) — action: extract. Replace the entire section (namespace list, logger.New guidance, DEBUG=* examples, output format) with a single pointer paragraph that keeps the facts needed for a routine task without opening the skill:

   ## Debugging & Logging
Go code uses namespace-based debug logging via pkg/logger(env varDEBUG, e.g. DEBUG=cli:*; output goes to stderr). See .github/skills/debugging-workflows/SKILL.mdfor the namespace list,logger.New(...)conventions, andgh aw logs/gh aw audit command reference.

   Evidence: section has 0 numbered_steps but 7 subsections totaling 2,505 chars of procedural detail (namespace table, Go code sample, DEBUG flag combinations) — a clear extraction candidate per the char-count/subsection-count heuristic, and it is currently the largest single procedure sitting in the always-loaded file.

2. .github/skills/debugging-workflows/SKILL.md — action: merge. Append the extracted "Debugging & Logging" content (namespace table, logger.New convention, DEBUG env var usage, output format) as a new subsection (e.g. under "Advanced Debugging Techniques" or a new "Go Debug Logging" section) so the procedure exists in exactly one place. Evidence: this skill is the only skill matching intent ("debug gh-aw workflows") and currently has zero references in tracked files (referenced_in_tracked_files: 0) despite AGENTS.md's "Use these skills by intent" table not listing it — consolidating strengthens its case for being discoverable and used.

3. .github/skills/debugging-workflows/SKILL.md description — action: sharpen. Current: "Debug gh-aw workflows using run logs, audits, and failure triage." Proposed: "Debug gh-aw workflows and Go code: download/audit run logs with gh aw logs/gh aw audit, and trace execution with pkg/logger DEBUG= namespaces." Evidence: after the merge in change 2, the old description no longer states the trigger for the newly added Go-logging content; the description is the entire selection signal since only it loads up front.

4. .github/skills/error-pattern-safety/SKILL.md description — action: sharpen. Current: "Apply safe error-pattern matching rules for agentic engines." (60 chars, vague on trigger). Proposed: "Review or author regex patterns in agentic-engine error matching; prevents JavaScript infinite loops from zero-width /g-flag matches." Evidence: current description states the domain but not the concrete failure mode (infinite loops from zero-width matches) that the skill body actually addresses, so an agent scanning descriptions cannot tell when to invoke it versus a generic error-handling skill.

Changes 3 and 4 add tokens to the always-loaded description list and are riding along with change 1, which alone already clears the 10% gain gate; they are not the basis for publishing this issue.

Not proposed: retirement of github-copilot-agent-tips-and-tricks (131 days since last change, referenced_in_tracked_files: 0) — flagging for awareness only. Repository data cannot prove whether this skill is actually invoked in practice; staleness and zero static references are not proof of disuse, so no retirement action is recommended here. A maintainer may want to confirm usage before deciding.

Agentic update prompt

You are updating the GitHub Agentic Workflows (gh-aw) repository at github/gh-aw. Only edit these two files; do not touch any other file:

1. `AGENTS.md`
2. `.github/skills/debugging-workflows/SKILL.md`

Before applying any instruction below, re-read the current content of both files and verify the cited evidence still holds. Skip any instruction whose evidence no longer matches the current file content, and say so explicitly in the pull request description rather than applying it anyway.

Apply these individually verifiable changes:

1. In `AGENTS.md`, find the "## Debugging & Logging" section (currently spanning from the "## Debugging & Logging" heading through the end of the "### Output format" subsection, immediately before "## Why this file is intentionally short"). Verify this section still contains the namespace table, the `logger.New(...)` code example, the `DEBUG=` command examples, and the "Output format" example block. If it does, delete the entire section and replace it with exactly this one paragraph (keep the "## Debugging & Logging" heading):

   ```
   ## Debugging & Logging

   Go code uses namespace-based debug logging via `pkg/logger` (env var `DEBUG`, e.g. `DEBUG=cli:*`; output goes to stderr). See `.github/skills/debugging-workflows/SKILL.md` for the namespace list, `logger.New(...)` conventions, and `gh aw logs`/`gh aw audit` command reference.
   ```

2. In `.github/skills/debugging-workflows/SKILL.md`, add a new subsection (place it under "## Advanced Debugging Techniques" or as its own "## Go Debug Logging" section before "## Reference Commands") containing the full content removed from `AGENTS.md` in step 1: the "Enable logging for a `gh aw` run" command examples, the "Key namespaces" table, the "Adding debug logs" Go code example and guidance, the "GitHub Actions debug runs" note, and the "Output format" example. Preserve all example commands and the table verbatim; do not paraphrase the namespace list or the `DEBUG=` examples.

3. Update the YAML frontmatter `description:` field of `.github/skills/debugging-workflows/SKILL.md` to state both trigger conditions and concrete actions, reflecting the newly merged content. Use or closely adapt: "Debug gh-aw workflows and Go code: download/audit run logs with `gh aw logs`/`gh aw audit`, and trace execution with `pkg/logger` `DEBUG=` namespaces."

4. After applying steps 1–3, compute the estimated-token change: (characters removed from `AGENTS.md` in step 1, divided by 4) minus (characters added to `AGENTS.md`'s replacement paragraph in step 1, divided by 4, plus any characters added to the `debugging-workflows` skill's `description` field beyond its original length, divided by 4). Confirm this net reduction is at least 10% of the pre-change always-loaded token estimate (`AGENTS.md` estimated tokens + all skill name/description tokens combined, i.e. approximately 3,329 tokens per this issue's evidence). If verification in the preamble caused you to skip step 1 (the only step that removes tokens), state explicitly in the pull request description that the 10% reduction was not achieved and why, rather than padding the diff with unrelated changes.

5. Do not delete, retire, or remove any skill. Do not touch `.github/skills/error-pattern-safety/SKILL.md` or any file other than the two named above.

6. Open a pull request whose description lists, for each of steps 1–3: what was changed, the evidence that justified it (quote the relevant lines of this prompt), and whether it was applied or skipped (with reason). Include the computed token-reduction percentage from step 4 in the pull request description.

Verification

A reviewer confirms this change by:

1. Diffing AGENTS.md before/after: the "Debugging & Logging" section shrinks from ~2,505 chars to a single pointer paragraph (~301 chars), and no other section changes.
2. Confirming the removed content (namespace table, logger.New example, DEBUG= examples, output format example) now exists verbatim in exactly one place: .github/skills/debugging-workflows/SKILL.md, and nowhere else in the repository.
3. Confirming .github/skills/debugging-workflows/SKILL.md's description field names both a trigger ("debug gh-aw workflows and Go code") and concrete actions (gh aw logs/gh aw audit, pkg/logger DEBUG= namespaces).
4. Recomputing the always-loaded token total (AGENTS.md estimated tokens + all skill name/description tokens) and confirming it dropped by at least 10% versus the ~3,329-token baseline reported in this issue.

Control Plane

• Correlation ID: 35600093434-438
• Central repository: githubnext/gh-aw-cao
• Control plane run URL: https://github.com/githubnext/gh-aw-cao/actions/runs/35600093434

Generated by 🧰 AW Optimization / Skills · copilot · auto · 121.5 AIC · ⌖ 9.02 AIC · ⊞ 15.2K · ◷

• expires on Oct 21, 2026, 12:52 PM UTC

[cao-githubnext-gh-aw-cao-write]

This issue is being closed as outdated. A newer issue has been created: #13227

View newer issue

---

This action was performed automatically by the AW Optimization / Skills workflow.