# Gh Aw Workflow Maintenance > Edit, fix, debug, update, and upgrade existing Github Agentic Workflows (gh-aw) with the correct recompile behavior, strict validation, run-analysis workflow, and factory-baseline comparisons when relevant. - Skill: `deyil/gh-aw-workflow-maintenance` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add deyil/gh-aw-workflow-maintenance` - Raw SKILL.md: https://api.skillmd.com/api/skills/deyil/gh-aw-workflow-maintenance/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: deyil (https://skillmd.com/u/deyil) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/deyil/gh-aw-workflow-maintenance --- # GH-AW Workflow Maintenance Use this skill when the user wants to edit an existing Github Agentic Workflow, fix a broken workflow, debug a run, upgrade workflows to a newer gh-aw version, or apply targeted maintenance to shared components. ## Start Here Before changing anything, consult `references/maintenance-sources.md`. If the requested behavior or regression aligns with a workflow in Peli's Agent Factory, compare against that upstream workflow first: - Exact match: use the factory workflow source as the baseline for what the workflow should look like now. - Near match: use the closest factory workflow and related write-up as inspiration for the fix, but keep the repository's own requirements primary. ## Example Prompts - "Update the existing gh-aw workflow to use a new engine secret and recompile the lock file." - "Fix the failing gh-aw run for this workflow using the run URL and the current source files." - "Upgrade all gh-aw workflows in the repository to the latest supported patterns without changing prompt-only behavior." Confirm the operational baseline before editing: - The active workflow should exist as both `.github/workflows/.md` and `.github/workflows/.lock.yml`. - If the repository was initialized for GitHub.com or mobile authoring, related bootstrap artifacts such as `.github/agents/agentic-workflows.agent.md` may also be part of the expected setup. - Engine-specific secrets and GitHub Actions availability are part of the runtime contract, so missing-run failures are not always authoring bugs. Then classify the work: - Prompt-only behavior update: edit only the markdown body. - Frontmatter/config change: edit YAML, then recompile. - Run failure or missing tool investigation: use the debug flow. - Bulk upgrade or deprecation cleanup: use the upgrade flow. - Factory-aligned sync or adaptation: compare the existing workflow with the exact or nearest factory workflow before editing. ## Maintenance Rules 1. Make small, surgical changes. Do not rewrite frontmatter unless the change truly requires it. 2. Preserve existing patterns unless the task is explicitly a refactor or upgrade. 3. If the change only touches the markdown body, do not force recompilation. 4. If the change touches frontmatter, recompile the gh-aw markdown source, then run `actionlint` against the generated `.lock.yml` when it is available, and fix all resulting validation errors before stopping. 5. Prefer strict validation and secure defaults over relaxing guardrails. 6. Keep GitHub writes inside `safe-outputs:`. Do not add direct write permissions to the agent job. 7. Use `toolsets:` for GitHub tools. Preserve supported GitHub-tool configuration and do not reintroduce deprecated, undocumented, or bespoke mutation patterns in place of normal gh-aw reads plus safe outputs. 8. When runs fail immediately in a fresh repository, check setup first: - Missing engine secret - Wrong `engine:` value for the configured secret - GitHub Actions disabled - Sample workflow added but never recompiled after frontmatter edits 9. When the task matches a ready-to-use factory workflow, prefer aligning to that proven source over inventing a new maintenance pattern. 10. When only adjacent factory workflows exist, treat them as inspiration and extract the smallest relevant fix or pattern instead of forcing a full upstream rewrite. ## Recommended Flows ### Existing Workflow Updates 1. Read the current workflow and decide whether the change is body-only or frontmatter. 2. For body-only edits, update the prompt and stop there unless the user asked for validation. 3. For frontmatter edits, change the smallest possible YAML surface. 4. Recompile the workflow source and validate the generated workflow. Prefer `gh aw compile --strict` or `gh aw validate` when available. 5. Run `actionlint` against the generated `.github/workflows/.lock.yml` when it is available. 6. If the user started from a quickstart sample such as `gh aw add-wizard`, preserve the sample's working setup unless the requested behavior requires a deliberate config change. ### Factory-Derived Updates 1. Find the exact or nearest matching workflow in Peli's Agent Factory. 2. Compare the current repository workflow against that upstream source before changing anything. 3. Reuse the exact upstream structure only when the user's requested behavior truly matches it. 4. If the fit is partial, borrow the smallest useful prompt or frontmatter patterns and preserve local requirements that the factory workflow does not model. 5. Recompile the workflow source after frontmatter changes, then run `actionlint` against the generated `.lock.yml` when it is available. 6. Verify the adapted workflow still matches the repository's engine, secrets, permissions, and triggers. ### Debugging Failures 1. If the user gives a run URL or run ID, audit that run first. 2. Use `gh aw audit --json` or the equivalent `agentic-workflows` MCP tool. 3. Check for: - Missing tools - Safe-output mismatches - Staged-mode previews that were mistaken for real writes - `call-workflow` or `dispatch-workflow` allowlist and trigger mismatches - Network/firewall denials - Threat-detection verdicts or over-broad detection customizations - MCP startup failures - Permission or auth failures - Missing repository initialization for the intended authoring mode - Missing or mismatched engine secrets - Excessive token usage or long runtimes 4. If the problem is tool availability, compare the requested tool name against configured `tools:` and `safe-outputs:` names. 5. Validate the fix by recompiling the source, then run `actionlint` against the generated `.lock.yml` when it is available, before closing the loop. ### Upgrades And Deprecations 1. Review current release or changelog guidance first. 2. Prefer `gh aw upgrade` for repository-wide upgrades. 3. Use `gh aw fix --write` for codemod-friendly migrations. 4. Recompile after fixes, then handle any remaining errors incrementally. 5. Document breaking changes and manual fixes when the task is upgrade-oriented. ## Useful Commands And Equivalents - `gh aw compile ` - `gh aw compile --strict` - `gh aw validate --json` - `actionlint .github/workflows/.lock.yml` - `gh aw fix --write` - `gh aw update` - `gh aw upgrade` - `gh aw logs --json` - `gh aw audit --json` - `gh aw mcp inspect ` - `gh aw health` If the CLI is unavailable or unauthenticated in the execution environment, use the `agentic-workflows` MCP tools that mirror `compile`, `logs`, `audit`, `status`, `update`, `add`, and `mcp-inspect`. ## Common Fixes - Missing tool calls: correct the tool name in the prompt, or enable the missing tool/safe output in frontmatter. - Firewall denials: add the right ecosystem or domain to `network.allowed`, keeping it minimal. - Orchestration failures: verify `call-workflow` or `dispatch-workflow` targets, allowlists, and required `workflow_call` or `workflow_dispatch` triggers. - Safe-output failures: fix the `safe-outputs:` block rather than adding write permissions. - Threat-detection failures: inspect `threat-detection:` prompts or scanner steps before weakening permissions or output controls. - Preview-only surprises: check whether global or per-output `staged: true` is still enabled. - Missing newer built-ins: prefer `mcp-scripts:`, `cache-memory:`, `repo-memory:`, `qmd:`, or `playwright:` when the workflow is re-implementing those capabilities by hand. - Compile errors: run fixers first, then address schema errors precisely. - High token use: shorten prompts, prefetch deterministic data, or add cache-memory where repeated analysis is expected. - Quickstart customization regressions: if a user edited frontmatter on a sample workflow and skipped `gh aw compile`, regenerate the lock file before chasing deeper runtime issues.