{ "schemaVersion": "1.0", "item": { "slug": "simplify-and-harden", "name": "simplify-and-harden", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/pskoett/simplify-and-harden", "canonicalUrl": "https://clawhub.ai/pskoett/simplify-and-harden", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/simplify-and-harden", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=simplify-and-harden", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md", "references/agent-context-snippets.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-05-07T17:22:31.273Z", "expiresAt": "2026-05-14T17:22:31.273Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report", "contentDisposition": "attachment; filename=\"afrexai-annual-report-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/simplify-and-harden" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/simplify-and-harden", "agentPageUrl": "https://openagent3.xyz/skills/simplify-and-harden/agent", "manifestUrl": "https://openagent3.xyz/skills/simplify-and-harden/agent.json", "briefUrl": "https://openagent3.xyz/skills/simplify-and-harden/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "Install", "body": "npx skills add pskoett/pskoett-ai-skills/simplify-and-harden\n\nFor CI-only execution, use:\n\nnpx skills add pskoett/pskoett-ai-skills/simplify-and-harden-ci" }, { "title": "Metadata", "body": "FieldValueSkill IDsimplify-and-hardenVersion0.1.0TriggerPost-completion hookAuthorPeter Skøtt PedersenCategoryCode Quality / SecurityPriorityRecommended" }, { "title": "Rationale and Philosophy", "body": "When a coding agent completes a task, it holds peak contextual understanding of the problem, the solution, and the tradeoffs it made along the way. This context degrades immediately -- the next task wipes the slate. Simplify & Harden exploits that peak context window to perform two focused review passes before the agent moves on.\n\nMost agents solve the ticket and stop. This skill turns \"done\" into \"done well.\"\n\nThe operating philosophy is a deliberate \"fresh eyes\" self-review before moving on: carefully re-read all newly written code and all existing code modified in the task, and look hard for obvious bugs, errors, confusing logic, brittle assumptions, naming issues, and missed hardening opportunities. The goal is not to expand scope or rewrite the solution -- it is to use peak context to perform a disciplined first review pass while the agent still remembers the intent behind every change." }, { "title": "Best Use with Independent Review", "body": "This skill is a post-completion self-pass and does not replace an independent review pass.\n\nRecommended flow:\n\nImplement the task.\nRun Simplify & Harden to clean, harden, and document non-obvious decisions.\nRun an independent review pass for severity-ordered findings.\nMerge only after both passes are addressed.\n\nIf the two disagree, treat the independent review findings as the external gate and either fix or explicitly waive findings." }, { "title": "Trigger Conditions", "body": "The skill activates automatically when ALL of the following are true:\n\nThe agent has completed its primary coding task\nThe agent signals task completion (exit code 0, PR ready, or equivalent)\nThe diff contains a non-trivial code change (see definition below)\nThe skill has not already run on this task (no re-entry loops)\n\nNon-trivial code change definition\n\nTreat a diff as non-trivial when it satisfies BOTH of the following:\n\nIt touches at least one executable source file (for example: *.ts, *.tsx, *.js, *.jsx, *.py, *.go, *.rs, *.java, *.cs, *.rb, *.php, *.swift, *.kt, *.scala, *.sh).\nIt includes either:\n\nAt least 10 changed non-comment, non-whitespace lines in executable source files, OR\nAt least one high-impact logic change (auth/authz checks, input validation, data access/query logic, external command execution, file path handling, network request handling, or concurrency control).\n\nTreat the diff as non-trivial = false when it is docs-only, config-only, comments-only, formatting-only, generated artifacts only, or tests-only.\n\nThe skill does NOT activate when:\n\nThe agent failed or was interrupted\nThe change is documentation-only\nThe change is tests-only\nThe change is a generated file (lockfiles, build artifacts)\nThe user explicitly skips it via --no-review or equivalent flag" }, { "title": "Scope Constraints", "body": "Hard rule: Only touch code modified in this task.\n\nThe agent MUST NOT:\n\nRefactor adjacent code it did not modify\nPursue \"while I'm here\" improvements outside the diff\nIntroduce new dependencies or architectural changes\nMake speculative fixes based on patterns it noticed elsewhere\n\nThe agent SHOULD flag out-of-scope concerns in the summary output rather than acting on them.\n\nBudget limits:\n\nMaximum additional changes: 20% of the original diff size (measured in lines changed)\nMaximum execution time: 60 seconds (configurable)\nIf either limit is hit, the agent stops and outputs what it has with a budget_exceeded flag" }, { "title": "Pass 1: Simplify", "body": "Objective: Reduce unnecessary complexity introduced during implementation.\n\nDefault posture: simplify, don't restructure. The primary goal of this pass is lightweight cleanup -- removing noise, tightening naming, killing dead code. The agent should bias heavily toward cosmetic fixes that make the code cleaner without changing its structure. Refactoring is the exception, not the rule.\n\nFresh-eyes start (mandatory): Before making any edits in this pass, re-read all code added or modified in this task with \"fresh eyes\" and actively look for obvious bugs, errors, confusing logic, brittle assumptions, naming issues, and missed hardening opportunities.\n\nThe agent reviews its own work and asks:\n\n\"Now that I understand the full solution, is there a simpler way to express this?\"" }, { "title": "Review Checklist", "body": "Dead code and scaffolding -- Did I leave behind debug logs, commented-out attempts, unused imports, or temporary variables from my iteration loop? Remove them.\n\n\nNaming clarity -- Do function names, variables, and parameters make sense when read fresh? Names that made sense mid-implementation often read poorly after the fact. Rename them.\n\n\nControl flow -- Can any nested conditionals be flattened? Can early returns replace deep nesting? Are there boolean expressions that could be simplified? Tighten them.\n\n\nAPI surface -- Did I expose more than necessary? Could any public methods/functions be private? Reduce visibility.\n\n\nOver-abstraction -- Did I create classes, interfaces, or wrapper functions that aren't justified by the current scope? Agents tend to over-engineer. Flag it, but don't restructure unless the win is significant.\n\n\nConsolidation opportunities -- Did I spread logic across multiple functions or files when it could live in one place? Flag it, but only propose a refactor if the duplication is egregious and the consolidation is clean." }, { "title": "Simplify Actions", "body": "For each finding, the agent categorizes it as:\n\nCosmetic fix (dead code removal, unused imports, naming, control flow tightening, visibility reduction) -- applied automatically if within budget. This is the bread and butter of the skill.\nRefactor (consolidation, restructuring, abstraction changes) -- proposed ONLY when the agent determines it is genuinely necessary or the benefit is substantial. A refactor is not the default action. The bar is: \"Would a senior engineer look at this and say the current state is clearly wrong, not just imperfect?\"\n\nRefactor Stop Hook (mandatory):\n\nAny change the agent classifies as a refactor triggers an interactive prompt. The agent MUST:\n\nDescribe what it wants to change and why\nShow the before/after (or a clear description of the structural change)\nWait for explicit human approval before applying\n\nThe agent does not batch refactor proposals. Each refactor is presented individually so the human can approve, reject, or modify on a case-by-case basis.\n\n[simplify-and-harden] Refactor proposal (1 of 2):\n\n I want to merge duplicated validation logic from handleCreate() and \n handleUpdate() into a shared validatePayload() function.\n\n Why: Both functions validate the same fields with identical rules.\n The duplication was introduced because I built handleUpdate as a \n copy of handleCreate during implementation.\n\n Files affected: src/api/handler.ts (lines 34-67)\n Estimated diff: -22 lines, +14 lines\n\n [approve] [reject] [show diff] [skip all refactors]\n\nIf the human selects skip all refactors, the agent skips remaining refactor proposals and moves to the Harden pass. Skipped refactors still appear in the output summary as flagged with status skipped_by_user.\n\nCosmetic fixes do not trigger the stop hook. They are applied silently (and reported in the output summary). The rationale: removing an unused import is not a judgment call. Restructuring code is." }, { "title": "Pass 2: Harden", "body": "Objective: Close security and resilience gaps while the agent still understands the code's intent.\n\nThe agent reviews its own work and asks:\n\n\"If someone malicious saw this code, what would they try?\"" }, { "title": "Review Checklist", "body": "Input validation -- Are all external inputs (user input, API params, file paths, environment variables) validated before use? Check for type coercion issues, missing bounds checks, and unconstrained string lengths.\n\n\nError handling -- Are catch blocks specific? Are errors logged with context but without leaking sensitive data? Are there any swallowed exceptions?\n\n\nInjection vectors -- Check for SQL injection, XSS, command injection, path traversal, and template injection in any code that builds strings from external input.\n\n\nAuthentication and authorization -- Do new endpoints or functions enforce auth? Are permission checks present and correct? Is there any privilege escalation risk?\n\n\nSecrets and credentials -- Are there hardcoded secrets, API keys, tokens, or passwords? Are connection strings parameterized? Check for credentials in log output.\n\n\nData exposure -- Does error output, logging, or API responses leak internal state, stack traces, database schemas, or PII?\n\n\nDependency risk -- Did the agent introduce new dependencies? If so, are they well-maintained, properly versioned, and free of known vulnerabilities?\n\n\nRace conditions and state -- For concurrent code: are shared resources properly synchronized? Are there TOCTOU (time-of-check-to-time-of-use) vulnerabilities?" }, { "title": "Harden Actions", "body": "For each finding, the agent categorizes it as:\n\nPatch (adding a validation check, escaping output, removing a hardcoded secret) -- applied automatically if within budget\nSecurity refactor (restructuring auth flow, replacing a vulnerable pattern with a new approach, changing data handling architecture) -- ALWAYS requires human approval before proceeding\n\nThe same Refactor Stop Hook from the Simplify pass applies here. Security refactors are presented individually with the added context of severity and attack vector:\n\n[simplify-and-harden] Security refactor proposal:\n\n The new /admin/export endpoint inherits base authentication but has \n no role-based access check. Any authenticated user can trigger a \n full data export.\n\n Severity: HIGH\n Vector: Privilege escalation\n \n Proposed fix: Add role guard requiring 'admin' role before the \n handler executes. This changes the middleware chain for this route.\n\n Files affected: src/api/routes/admin.ts (line 12)\n Estimated diff: +8 lines\n\n [approve] [reject] [show diff] [skip all security refactors]\n\nFlagged as critical -- findings the agent cannot safely patch without human input (noted in output regardless of approval)\nFlagged as advisory -- hardening opportunities that are not active vulnerabilities\n\nSecurity patches (not refactors) are prioritized over simplification changes when budget is constrained." }, { "title": "Pass 3: Document (Micro-pass)", "body": "Objective: Capture non-obvious decisions while the agent still remembers why it made them.\n\nThis is deliberately lightweight -- not a documentation pass, just decision capture." }, { "title": "Rules", "body": "For any logic that requires more than 5 seconds of \"why does this exist?\" thought: add a single-line comment explaining the decision\nFor any workaround or hack: add a comment with context and ideally a TODO with conditions for removal\nFor any performance-sensitive choice: note why the current approach was chosen over the obvious alternative\nMaximum: 5 comments added per task. This is not a documentation sprint." }, { "title": "Output Schema", "body": "The skill produces a structured summary appended to the task output:\n\nsimplify_and_harden:\n version: \"0.1.0\"\n task_id: \"\"\n execution:\n mode: \"interactive\"\n mode_source: \"auto_detected\" # \"auto_detected\", \"config\", \"env_override\"\n human_present: true\n scope:\n files_reviewed: [\"src/api/handler.ts\", \"src/utils/validate.ts\"]\n original_diff_lines: 142\n additional_changes_lines: 18\n budget_exceeded: false\n\n simplify:\n applied:\n - file: \"src/api/handler.ts\"\n line: 45\n type: \"consolidation\"\n category: \"refactor\"\n approval: \"approved_by_user\"\n description: \"Merged duplicated validation logic from handleCreate and handleUpdate into shared validatePayload function\"\n flagged:\n - file: \"src/utils/validate.ts\"\n type: \"over-abstraction\"\n category: \"refactor\"\n approval: \"skipped_by_user\"\n description: \"ValidationStrategy interface may be unnecessary -- only one implementation exists. Consider inlining if no additional strategies are planned.\"\n confidence: \"medium\"\n cosmetic_applied:\n - file: \"src/api/handler.ts\"\n line: 12\n type: \"dead_code\"\n description: \"Removed unused import of deprecated AuthHelper\"\n\n harden:\n applied:\n - file: \"src/api/handler.ts\"\n line: 62\n type: \"input_validation\"\n severity: \"high\"\n description: \"Added bounds check on pageSize parameter -- previously accepted arbitrary integers\"\n flagged_critical:\n - file: \"src/api/handler.ts\"\n type: \"authorization\"\n description: \"New /admin/export endpoint inherits base auth but no role check -- any authenticated user can access it. Requires human decision on role policy.\"\n flagged_advisory:\n - file: \"src/utils/validate.ts\"\n type: \"error_handling\"\n description: \"Catch block on L31 logs full request body which may contain PII in production\"\n\n document:\n comments_added: 2\n locations:\n - file: \"src/api/handler.ts\"\n line: 78\n comment: \"// Pagination uses cursor-based approach instead of offset -- offset breaks when items are deleted between pages\"\n - file: \"src/api/handler.ts\" \n line: 93\n comment: \"// WORKAROUND: Legacy API returns dates as strings without timezone. Assuming UTC until migration completes (see TICKET-1234)\"\n\n learning_loop:\n target_skill: \"self-improvement\"\n log_file: \".learnings/LEARNINGS.md\"\n candidates:\n - pattern_key: \"simplify.dead_code\"\n pass: \"simplify\"\n finding_type: \"dead_code\"\n severity: \"low\"\n source_file: \"src/api/handler.ts\"\n source_line: 12\n suggested_rule: \"Remove dead code and unused imports before finalizing a task.\"\n - pattern_key: \"harden.input_validation\"\n pass: \"harden\"\n finding_type: \"input_validation\"\n severity: \"high\"\n source_file: \"src/api/handler.ts\"\n source_line: 62\n suggested_rule: \"Validate and bound-check external inputs before use.\"\n recurrence_window_days: 30\n promotion_threshold:\n min_occurrences: 3\n min_distinct_tasks: 2\n\n summary:\n simplify_applied: 1\n simplify_cosmetic_applied: 1\n simplify_flagged: 1\n simplify_rejected_by_user: 0\n simplify_skipped_by_user: 1\n harden_applied: 1\n harden_flagged_critical: 1\n harden_flagged_advisory: 1\n harden_rejected_by_user: 0\n comments_added: 2\n total_additional_lines: 18\n budget_utilization: \"12.7%\"\n human_prompts_shown: 3\n human_prompts_approved: 1\n human_prompts_rejected: 0\n human_prompts_skipped: 1\n human_prompts_timed_out: 1\n learning_candidates: 2\n learning_promotions_recommended: 1\n review_followup_required: true\n\nSet review_followup_required to true when any unresolved finding remains (critical/advisory flags, skipped or timed-out refactor proposals), or when budget_exceeded is true. Set it to false only when no follow-up is required." }, { "title": "Self-Improvement Integration (Learning Loop)", "body": "Simplify & Harden feeds its recurring quality/security findings into the\nself-improvement skill so repeated issues can become durable prompt rules.\n\nAfter each run:\n\nNormalize each finding into a pattern_key:\n\nSimplify examples: simplify.dead_code, simplify.naming, simplify.control_flow\nHarden examples: harden.input_validation, harden.authorization, harden.error_handling\n\n\nEmit those pattern candidates in simplify_and_harden.learning_loop.candidates.\nHand off candidates to self-improvement, which logs or updates entries in\n.learnings/LEARNINGS.md (instead of creating duplicate one-off notes).\nMark candidates as promotion-ready when they cross the recurrence threshold:\n>= 3 occurrences across >= 2 distinct tasks in a 30-day window.\nPromote promotion-ready patterns into the agent context/system prompt files\n(CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, or equivalent)\nto reduce repeat issues.\n\nThis keeps Simplify & Harden focused on per-task cleanup/hardening while\nself-improvement owns cross-task memory and promotion." }, { "title": "Execution Model", "body": "This skill is for general coding-agent sessions where a human can approve\nrefactors in-line.\n\nBehavior:\n\nRefactor proposals are shown one at a time with clear rationale\nThe agent pauses and waits for [approve], [reject], [show diff], or [skip all refactors]\nCosmetic fixes and straightforward security patches are applied automatically\n\nFor CI pipelines and headless automation, use simplify-and-harden-ci." }, { "title": "Agent Context File References", "body": "To activate this skill, reference it in your agent context file.\n\nAgent-specific copy-paste snippets are in references/agent-context-snippets.md.\nLoad only the snippet for your active agent to keep context lean.\n\nCore invariants for any agent integration:\n\nScope lock -- only files modified in the current task\nBudget cap -- 20% max additional diff\nSimplify-first posture -- cleanup is the default, refactoring is the exception\nRefactor stop hook -- structural changes always require human approval\nThree passes -- simplify, harden, document (in that order)\nStructured output -- summary of applied, approved, rejected, and flagged items\n\nPrecaution: some agents may not reliably pause for approval in high-autonomy modes. Validate this behavior before production use." }, { "title": "Agent Compatibility", "body": "This skill is designed to work with any coding agent that follows a task-based workflow. It is not tied to any specific agent framework or product.\n\nProgrammatic integration (agents with skill/hook APIs):\n\nClaude Code, GitHub Copilot Workspace, Codex, Opencode, OpenClaw, Cursor Agent, Windsurf, Aider, SWE-Agent, OpenHands, Devin, and any agent exposing a task completion lifecycle event\n\nPrompt-based integration (chat-based agents without formal skill APIs):\n\nAny LLM-based coding assistant that accepts post-task instructions -- the skill's logic can be injected as a follow-up prompt after the agent signals completion\n\nThe output schema is agent-agnostic YAML. Consuming tools only need to parse the structured summary." }, { "title": "Integration Notes", "body": "This skill is agent-agnostic. It hooks into any coding agent that exposes a task completion lifecycle event. The examples below are generic -- adapt them to your agent's specific API." }, { "title": "Agent Integration", "body": "The skill hooks into the agent's task completion lifecycle. Suggested integration pattern:\n\nagent.on('task:complete', async (context) => {\n if (context.diff.isNonTrivial() && !context.flags.includes('no-review')) {\n const result = await skills.run('simplify-and-harden', {\n diff: context.diff,\n files: context.modifiedFiles,\n budget: { maxLines: context.diff.linesChanged * 0.2, maxTime: 60000 }\n });\n context.appendOutput(result.summary);\n }\n});\n\nAgents that support this skill should implement the following interface:\n\nAccess to the diff produced by the completed task\nA list of modified files with full content\nThe ability to present interactive prompts (for interactive mode)\nAn output channel for the structured summary (stdout, PR comment, or equivalent)" }, { "title": "Prompt-based Integration", "body": "For agents that don't support programmatic skill hooks (e.g., chat-based coding agents like Claude Code, Cursor, Copilot Chat), this skill can be implemented as a post-task prompt injection:\n\nAfter completing the task, run the Simplify & Harden review:\n1. Review only the files you modified\n2. Simplify: Your default action is cleanup -- remove dead code, unused \n imports, fix naming, tighten control flow, reduce unnecessary public \n surface. Apply these directly. Refactoring (merging functions, changing \n abstractions, restructuring) is NOT the default. Only propose a refactor \n when the code is genuinely wrong or the improvement is substantial. \n If you propose one, describe it and ask for approval before applying.\n3. Harden: Check for input validation gaps, injection vectors, auth issues, \n exposed secrets, and error handling problems. Apply simple patches directly.\n For security refactors that change structure, describe the issue with\n severity and ask for approval.\n4. Document: Add up to 5 comments on non-obvious decisions.\n5. Output a summary of what you changed, what you flagged, and \n what you left alone." }, { "title": "CI Pipeline Variant", "body": "For GitHub Actions or other CI/headless usage, run simplify-and-harden-ci." }, { "title": "Configuration", "body": "# Example configuration (adapt path to your agent's config format)\n# e.g., .agent/skills.yaml, .claude/skills.yaml, .cursor/skills.yaml\nsimplify-and-harden:\n enabled: true\n budget:\n max_diff_ratio: 0.2 # Max additional changes as ratio of original diff\n max_time_seconds: 60 # Hard time limit\n simplify:\n enabled: true\n auto_apply_cosmetic: true # Cosmetic fixes applied without prompting\n refactor_requires_approval: true # ALWAYS true -- cannot be disabled\n harden:\n enabled: true\n auto_apply_patches: true # Simple security patches applied without prompting\n refactor_requires_approval: true # ALWAYS true -- cannot be disabled\n document:\n enabled: true\n max_comments: 5\n stop_hook:\n mode: \"interactive\"\n show_diff_preview: true\n allow_skip_all: true\n timeout_seconds: 300 # 5 min -- human is at the keyboard\n timeout_action: \"flag\" # Assume they stepped away, don't discard\n skip_patterns: # Glob patterns to exclude from review\n - \"**/*.test.*\"\n - \"**/*.spec.*\"\n - \"**/migrations/**\"" }, { "title": "Design Decisions", "body": "Why post-completion and not continuous?\nContinuous review during implementation creates feedback loops that slow the agent down and can cause oscillation (simplify, then re-complicate, then re-simplify). Post-completion gives the agent a stable codebase to review against.\n\nWhy simplify-first, not refactor-first?\nAgents love to refactor. Given permission to \"improve\" code, they will restructure it. But most post-task improvements are cosmetic: a dead import, a bad name, a needlessly deep conditional. These account for 80%+ of the value with near-zero risk. Refactoring carries real risk -- it can introduce bugs, break tests, and bloat diffs. By making simplification the default and refactoring the exception, the skill delivers consistent value without surprise rewrites. The bar for a refactor should be \"this is genuinely wrong\" not \"this could be slightly better.\"\n\nWhy a budget?\nWithout constraints, agents will use review passes as license for unbounded refactoring. The 20% rule keeps the skill focused: improve what you built, don't rebuild it.\n\nWhy separate simplify from harden?\nThey require different mindsets. Simplify asks \"is this the clearest expression of my intent?\" while Harden asks \"how could this be exploited?\" Conflating them leads to mediocre results on both. Running them sequentially also lets us prioritize security fixes when budget is tight.\n\nWhy the document micro-pass?\nAgents are terrible at documenting their reasoning unprompted. Humans reviewing agent-generated code consistently report that the biggest friction is understanding why a choice was made. Five comments is a trivial cost for enormous review-time savings." }, { "title": "Future Considerations", "body": "Team calibration: Allow teams to weight the review checklist (e.g., \"we care more about injection vectors than naming\")\nDiff-aware context loading: For large codebases, intelligently load only the files and symbols relevant to the diff rather than the full project\nCross-skill composition: Simplify & Harden could feed into a \"PR Description\" skill that uses its summary to auto-generate meaningful PR descriptions" } ], "body": "Agent Skill: Simplify & Harden\nInstall\nnpx skills add pskoett/pskoett-ai-skills/simplify-and-harden\n\n\nFor CI-only execution, use:\n\nnpx skills add pskoett/pskoett-ai-skills/simplify-and-harden-ci\n\nMetadata\nField\tValue\nSkill ID\tsimplify-and-harden\nVersion\t0.1.0\nTrigger\tPost-completion hook\nAuthor\tPeter Skøtt Pedersen\nCategory\tCode Quality / Security\nPriority\tRecommended\nRationale and Philosophy\n\nWhen a coding agent completes a task, it holds peak contextual understanding of the problem, the solution, and the tradeoffs it made along the way. This context degrades immediately -- the next task wipes the slate. Simplify & Harden exploits that peak context window to perform two focused review passes before the agent moves on.\n\nMost agents solve the ticket and stop. This skill turns \"done\" into \"done well.\"\n\nThe operating philosophy is a deliberate \"fresh eyes\" self-review before moving on: carefully re-read all newly written code and all existing code modified in the task, and look hard for obvious bugs, errors, confusing logic, brittle assumptions, naming issues, and missed hardening opportunities. The goal is not to expand scope or rewrite the solution -- it is to use peak context to perform a disciplined first review pass while the agent still remembers the intent behind every change.\n\nBest Use with Independent Review\n\nThis skill is a post-completion self-pass and does not replace an independent review pass.\n\nRecommended flow:\n\nImplement the task.\nRun Simplify & Harden to clean, harden, and document non-obvious decisions.\nRun an independent review pass for severity-ordered findings.\nMerge only after both passes are addressed.\n\nIf the two disagree, treat the independent review findings as the external gate and either fix or explicitly waive findings.\n\nTrigger Conditions\n\nThe skill activates automatically when ALL of the following are true:\n\nThe agent has completed its primary coding task\nThe agent signals task completion (exit code 0, PR ready, or equivalent)\nThe diff contains a non-trivial code change (see definition below)\nThe skill has not already run on this task (no re-entry loops)\n\nNon-trivial code change definition\n\nTreat a diff as non-trivial when it satisfies BOTH of the following:\n\nIt touches at least one executable source file (for example: *.ts, *.tsx, *.js, *.jsx, *.py, *.go, *.rs, *.java, *.cs, *.rb, *.php, *.swift, *.kt, *.scala, *.sh).\nIt includes either:\nAt least 10 changed non-comment, non-whitespace lines in executable source files, OR\nAt least one high-impact logic change (auth/authz checks, input validation, data access/query logic, external command execution, file path handling, network request handling, or concurrency control).\n\nTreat the diff as non-trivial = false when it is docs-only, config-only, comments-only, formatting-only, generated artifacts only, or tests-only.\n\nThe skill does NOT activate when:\n\nThe agent failed or was interrupted\nThe change is documentation-only\nThe change is tests-only\nThe change is a generated file (lockfiles, build artifacts)\nThe user explicitly skips it via --no-review or equivalent flag\nScope Constraints\n\nHard rule: Only touch code modified in this task.\n\nThe agent MUST NOT:\n\nRefactor adjacent code it did not modify\nPursue \"while I'm here\" improvements outside the diff\nIntroduce new dependencies or architectural changes\nMake speculative fixes based on patterns it noticed elsewhere\n\nThe agent SHOULD flag out-of-scope concerns in the summary output rather than acting on them.\n\nBudget limits:\n\nMaximum additional changes: 20% of the original diff size (measured in lines changed)\nMaximum execution time: 60 seconds (configurable)\nIf either limit is hit, the agent stops and outputs what it has with a budget_exceeded flag\nPass 1: Simplify\n\nObjective: Reduce unnecessary complexity introduced during implementation.\n\nDefault posture: simplify, don't restructure. The primary goal of this pass is lightweight cleanup -- removing noise, tightening naming, killing dead code. The agent should bias heavily toward cosmetic fixes that make the code cleaner without changing its structure. Refactoring is the exception, not the rule.\n\nFresh-eyes start (mandatory): Before making any edits in this pass, re-read all code added or modified in this task with \"fresh eyes\" and actively look for obvious bugs, errors, confusing logic, brittle assumptions, naming issues, and missed hardening opportunities.\n\nThe agent reviews its own work and asks:\n\n\"Now that I understand the full solution, is there a simpler way to express this?\"\n\nReview Checklist\n\nDead code and scaffolding -- Did I leave behind debug logs, commented-out attempts, unused imports, or temporary variables from my iteration loop? Remove them.\n\nNaming clarity -- Do function names, variables, and parameters make sense when read fresh? Names that made sense mid-implementation often read poorly after the fact. Rename them.\n\nControl flow -- Can any nested conditionals be flattened? Can early returns replace deep nesting? Are there boolean expressions that could be simplified? Tighten them.\n\nAPI surface -- Did I expose more than necessary? Could any public methods/functions be private? Reduce visibility.\n\nOver-abstraction -- Did I create classes, interfaces, or wrapper functions that aren't justified by the current scope? Agents tend to over-engineer. Flag it, but don't restructure unless the win is significant.\n\nConsolidation opportunities -- Did I spread logic across multiple functions or files when it could live in one place? Flag it, but only propose a refactor if the duplication is egregious and the consolidation is clean.\n\nSimplify Actions\n\nFor each finding, the agent categorizes it as:\n\nCosmetic fix (dead code removal, unused imports, naming, control flow tightening, visibility reduction) -- applied automatically if within budget. This is the bread and butter of the skill.\nRefactor (consolidation, restructuring, abstraction changes) -- proposed ONLY when the agent determines it is genuinely necessary or the benefit is substantial. A refactor is not the default action. The bar is: \"Would a senior engineer look at this and say the current state is clearly wrong, not just imperfect?\"\n\nRefactor Stop Hook (mandatory):\n\nAny change the agent classifies as a refactor triggers an interactive prompt. The agent MUST:\n\nDescribe what it wants to change and why\nShow the before/after (or a clear description of the structural change)\nWait for explicit human approval before applying\n\nThe agent does not batch refactor proposals. Each refactor is presented individually so the human can approve, reject, or modify on a case-by-case basis.\n\n[simplify-and-harden] Refactor proposal (1 of 2):\n\n I want to merge duplicated validation logic from handleCreate() and \n handleUpdate() into a shared validatePayload() function.\n\n Why: Both functions validate the same fields with identical rules.\n The duplication was introduced because I built handleUpdate as a \n copy of handleCreate during implementation.\n\n Files affected: src/api/handler.ts (lines 34-67)\n Estimated diff: -22 lines, +14 lines\n\n [approve] [reject] [show diff] [skip all refactors]\n\n\n\nIf the human selects skip all refactors, the agent skips remaining refactor proposals and moves to the Harden pass. Skipped refactors still appear in the output summary as flagged with status skipped_by_user.\n\nCosmetic fixes do not trigger the stop hook. They are applied silently (and reported in the output summary). The rationale: removing an unused import is not a judgment call. Restructuring code is.\n\nPass 2: Harden\n\nObjective: Close security and resilience gaps while the agent still understands the code's intent.\n\nThe agent reviews its own work and asks:\n\n\"If someone malicious saw this code, what would they try?\"\n\nReview Checklist\n\nInput validation -- Are all external inputs (user input, API params, file paths, environment variables) validated before use? Check for type coercion issues, missing bounds checks, and unconstrained string lengths.\n\nError handling -- Are catch blocks specific? Are errors logged with context but without leaking sensitive data? Are there any swallowed exceptions?\n\nInjection vectors -- Check for SQL injection, XSS, command injection, path traversal, and template injection in any code that builds strings from external input.\n\nAuthentication and authorization -- Do new endpoints or functions enforce auth? Are permission checks present and correct? Is there any privilege escalation risk?\n\nSecrets and credentials -- Are there hardcoded secrets, API keys, tokens, or passwords? Are connection strings parameterized? Check for credentials in log output.\n\nData exposure -- Does error output, logging, or API responses leak internal state, stack traces, database schemas, or PII?\n\nDependency risk -- Did the agent introduce new dependencies? If so, are they well-maintained, properly versioned, and free of known vulnerabilities?\n\nRace conditions and state -- For concurrent code: are shared resources properly synchronized? Are there TOCTOU (time-of-check-to-time-of-use) vulnerabilities?\n\nHarden Actions\n\nFor each finding, the agent categorizes it as:\n\nPatch (adding a validation check, escaping output, removing a hardcoded secret) -- applied automatically if within budget\nSecurity refactor (restructuring auth flow, replacing a vulnerable pattern with a new approach, changing data handling architecture) -- ALWAYS requires human approval before proceeding\n\nThe same Refactor Stop Hook from the Simplify pass applies here. Security refactors are presented individually with the added context of severity and attack vector:\n\n[simplify-and-harden] Security refactor proposal:\n\n The new /admin/export endpoint inherits base authentication but has \n no role-based access check. Any authenticated user can trigger a \n full data export.\n\n Severity: HIGH\n Vector: Privilege escalation\n \n Proposed fix: Add role guard requiring 'admin' role before the \n handler executes. This changes the middleware chain for this route.\n\n Files affected: src/api/routes/admin.ts (line 12)\n Estimated diff: +8 lines\n\n [approve] [reject] [show diff] [skip all security refactors]\n\n\nFlagged as critical -- findings the agent cannot safely patch without human input (noted in output regardless of approval)\nFlagged as advisory -- hardening opportunities that are not active vulnerabilities\n\nSecurity patches (not refactors) are prioritized over simplification changes when budget is constrained.\n\nPass 3: Document (Micro-pass)\n\nObjective: Capture non-obvious decisions while the agent still remembers why it made them.\n\nThis is deliberately lightweight -- not a documentation pass, just decision capture.\n\nRules\nFor any logic that requires more than 5 seconds of \"why does this exist?\" thought: add a single-line comment explaining the decision\nFor any workaround or hack: add a comment with context and ideally a TODO with conditions for removal\nFor any performance-sensitive choice: note why the current approach was chosen over the obvious alternative\nMaximum: 5 comments added per task. This is not a documentation sprint.\nOutput Schema\n\nThe skill produces a structured summary appended to the task output:\n\nsimplify_and_harden:\n version: \"0.1.0\"\n task_id: \"\"\n execution:\n mode: \"interactive\"\n mode_source: \"auto_detected\" # \"auto_detected\", \"config\", \"env_override\"\n human_present: true\n scope:\n files_reviewed: [\"src/api/handler.ts\", \"src/utils/validate.ts\"]\n original_diff_lines: 142\n additional_changes_lines: 18\n budget_exceeded: false\n\n simplify:\n applied:\n - file: \"src/api/handler.ts\"\n line: 45\n type: \"consolidation\"\n category: \"refactor\"\n approval: \"approved_by_user\"\n description: \"Merged duplicated validation logic from handleCreate and handleUpdate into shared validatePayload function\"\n flagged:\n - file: \"src/utils/validate.ts\"\n type: \"over-abstraction\"\n category: \"refactor\"\n approval: \"skipped_by_user\"\n description: \"ValidationStrategy interface may be unnecessary -- only one implementation exists. Consider inlining if no additional strategies are planned.\"\n confidence: \"medium\"\n cosmetic_applied:\n - file: \"src/api/handler.ts\"\n line: 12\n type: \"dead_code\"\n description: \"Removed unused import of deprecated AuthHelper\"\n\n harden:\n applied:\n - file: \"src/api/handler.ts\"\n line: 62\n type: \"input_validation\"\n severity: \"high\"\n description: \"Added bounds check on pageSize parameter -- previously accepted arbitrary integers\"\n flagged_critical:\n - file: \"src/api/handler.ts\"\n type: \"authorization\"\n description: \"New /admin/export endpoint inherits base auth but no role check -- any authenticated user can access it. Requires human decision on role policy.\"\n flagged_advisory:\n - file: \"src/utils/validate.ts\"\n type: \"error_handling\"\n description: \"Catch block on L31 logs full request body which may contain PII in production\"\n\n document:\n comments_added: 2\n locations:\n - file: \"src/api/handler.ts\"\n line: 78\n comment: \"// Pagination uses cursor-based approach instead of offset -- offset breaks when items are deleted between pages\"\n - file: \"src/api/handler.ts\" \n line: 93\n comment: \"// WORKAROUND: Legacy API returns dates as strings without timezone. Assuming UTC until migration completes (see TICKET-1234)\"\n\n learning_loop:\n target_skill: \"self-improvement\"\n log_file: \".learnings/LEARNINGS.md\"\n candidates:\n - pattern_key: \"simplify.dead_code\"\n pass: \"simplify\"\n finding_type: \"dead_code\"\n severity: \"low\"\n source_file: \"src/api/handler.ts\"\n source_line: 12\n suggested_rule: \"Remove dead code and unused imports before finalizing a task.\"\n - pattern_key: \"harden.input_validation\"\n pass: \"harden\"\n finding_type: \"input_validation\"\n severity: \"high\"\n source_file: \"src/api/handler.ts\"\n source_line: 62\n suggested_rule: \"Validate and bound-check external inputs before use.\"\n recurrence_window_days: 30\n promotion_threshold:\n min_occurrences: 3\n min_distinct_tasks: 2\n\n summary:\n simplify_applied: 1\n simplify_cosmetic_applied: 1\n simplify_flagged: 1\n simplify_rejected_by_user: 0\n simplify_skipped_by_user: 1\n harden_applied: 1\n harden_flagged_critical: 1\n harden_flagged_advisory: 1\n harden_rejected_by_user: 0\n comments_added: 2\n total_additional_lines: 18\n budget_utilization: \"12.7%\"\n human_prompts_shown: 3\n human_prompts_approved: 1\n human_prompts_rejected: 0\n human_prompts_skipped: 1\n human_prompts_timed_out: 1\n learning_candidates: 2\n learning_promotions_recommended: 1\n review_followup_required: true\n\n\nSet review_followup_required to true when any unresolved finding remains (critical/advisory flags, skipped or timed-out refactor proposals), or when budget_exceeded is true. Set it to false only when no follow-up is required.\n\nSelf-Improvement Integration (Learning Loop)\n\nSimplify & Harden feeds its recurring quality/security findings into the self-improvement skill so repeated issues can become durable prompt rules.\n\nAfter each run:\n\nNormalize each finding into a pattern_key:\nSimplify examples: simplify.dead_code, simplify.naming, simplify.control_flow\nHarden examples: harden.input_validation, harden.authorization, harden.error_handling\nEmit those pattern candidates in simplify_and_harden.learning_loop.candidates.\nHand off candidates to self-improvement, which logs or updates entries in .learnings/LEARNINGS.md (instead of creating duplicate one-off notes).\nMark candidates as promotion-ready when they cross the recurrence threshold: >= 3 occurrences across >= 2 distinct tasks in a 30-day window.\nPromote promotion-ready patterns into the agent context/system prompt files (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, or equivalent) to reduce repeat issues.\n\nThis keeps Simplify & Harden focused on per-task cleanup/hardening while self-improvement owns cross-task memory and promotion.\n\nExecution Model\n\nThis skill is for general coding-agent sessions where a human can approve refactors in-line.\n\nBehavior:\n\nRefactor proposals are shown one at a time with clear rationale\nThe agent pauses and waits for [approve], [reject], [show diff], or [skip all refactors]\nCosmetic fixes and straightforward security patches are applied automatically\n\nFor CI pipelines and headless automation, use simplify-and-harden-ci.\n\nAgent Context File References\n\nTo activate this skill, reference it in your agent context file.\n\nAgent-specific copy-paste snippets are in references/agent-context-snippets.md. Load only the snippet for your active agent to keep context lean.\n\nCore invariants for any agent integration:\n\nScope lock -- only files modified in the current task\nBudget cap -- 20% max additional diff\nSimplify-first posture -- cleanup is the default, refactoring is the exception\nRefactor stop hook -- structural changes always require human approval\nThree passes -- simplify, harden, document (in that order)\nStructured output -- summary of applied, approved, rejected, and flagged items\n\nPrecaution: some agents may not reliably pause for approval in high-autonomy modes. Validate this behavior before production use.\n\nAgent Compatibility\n\nThis skill is designed to work with any coding agent that follows a task-based workflow. It is not tied to any specific agent framework or product.\n\nProgrammatic integration (agents with skill/hook APIs):\n\nClaude Code, GitHub Copilot Workspace, Codex, Opencode, OpenClaw, Cursor Agent, Windsurf, Aider, SWE-Agent, OpenHands, Devin, and any agent exposing a task completion lifecycle event\n\nPrompt-based integration (chat-based agents without formal skill APIs):\n\nAny LLM-based coding assistant that accepts post-task instructions -- the skill's logic can be injected as a follow-up prompt after the agent signals completion\n\nThe output schema is agent-agnostic YAML. Consuming tools only need to parse the structured summary.\n\nIntegration Notes\n\nThis skill is agent-agnostic. It hooks into any coding agent that exposes a task completion lifecycle event. The examples below are generic -- adapt them to your agent's specific API.\n\nAgent Integration\n\nThe skill hooks into the agent's task completion lifecycle. Suggested integration pattern:\n\nagent.on('task:complete', async (context) => {\n if (context.diff.isNonTrivial() && !context.flags.includes('no-review')) {\n const result = await skills.run('simplify-and-harden', {\n diff: context.diff,\n files: context.modifiedFiles,\n budget: { maxLines: context.diff.linesChanged * 0.2, maxTime: 60000 }\n });\n context.appendOutput(result.summary);\n }\n});\n\n\nAgents that support this skill should implement the following interface:\n\nAccess to the diff produced by the completed task\nA list of modified files with full content\nThe ability to present interactive prompts (for interactive mode)\nAn output channel for the structured summary (stdout, PR comment, or equivalent)\nPrompt-based Integration\n\nFor agents that don't support programmatic skill hooks (e.g., chat-based coding agents like Claude Code, Cursor, Copilot Chat), this skill can be implemented as a post-task prompt injection:\n\nAfter completing the task, run the Simplify & Harden review:\n1. Review only the files you modified\n2. Simplify: Your default action is cleanup -- remove dead code, unused \n imports, fix naming, tighten control flow, reduce unnecessary public \n surface. Apply these directly. Refactoring (merging functions, changing \n abstractions, restructuring) is NOT the default. Only propose a refactor \n when the code is genuinely wrong or the improvement is substantial. \n If you propose one, describe it and ask for approval before applying.\n3. Harden: Check for input validation gaps, injection vectors, auth issues, \n exposed secrets, and error handling problems. Apply simple patches directly.\n For security refactors that change structure, describe the issue with\n severity and ask for approval.\n4. Document: Add up to 5 comments on non-obvious decisions.\n5. Output a summary of what you changed, what you flagged, and \n what you left alone.\n\nCI Pipeline Variant\n\nFor GitHub Actions or other CI/headless usage, run simplify-and-harden-ci.\n\nConfiguration\n# Example configuration (adapt path to your agent's config format)\n# e.g., .agent/skills.yaml, .claude/skills.yaml, .cursor/skills.yaml\nsimplify-and-harden:\n enabled: true\n budget:\n max_diff_ratio: 0.2 # Max additional changes as ratio of original diff\n max_time_seconds: 60 # Hard time limit\n simplify:\n enabled: true\n auto_apply_cosmetic: true # Cosmetic fixes applied without prompting\n refactor_requires_approval: true # ALWAYS true -- cannot be disabled\n harden:\n enabled: true\n auto_apply_patches: true # Simple security patches applied without prompting\n refactor_requires_approval: true # ALWAYS true -- cannot be disabled\n document:\n enabled: true\n max_comments: 5\n stop_hook:\n mode: \"interactive\"\n show_diff_preview: true\n allow_skip_all: true\n timeout_seconds: 300 # 5 min -- human is at the keyboard\n timeout_action: \"flag\" # Assume they stepped away, don't discard\n skip_patterns: # Glob patterns to exclude from review\n - \"**/*.test.*\"\n - \"**/*.spec.*\"\n - \"**/migrations/**\"\n\nDesign Decisions\n\nWhy post-completion and not continuous? Continuous review during implementation creates feedback loops that slow the agent down and can cause oscillation (simplify, then re-complicate, then re-simplify). Post-completion gives the agent a stable codebase to review against.\n\nWhy simplify-first, not refactor-first? Agents love to refactor. Given permission to \"improve\" code, they will restructure it. But most post-task improvements are cosmetic: a dead import, a bad name, a needlessly deep conditional. These account for 80%+ of the value with near-zero risk. Refactoring carries real risk -- it can introduce bugs, break tests, and bloat diffs. By making simplification the default and refactoring the exception, the skill delivers consistent value without surprise rewrites. The bar for a refactor should be \"this is genuinely wrong\" not \"this could be slightly better.\"\n\nWhy a budget? Without constraints, agents will use review passes as license for unbounded refactoring. The 20% rule keeps the skill focused: improve what you built, don't rebuild it.\n\nWhy separate simplify from harden? They require different mindsets. Simplify asks \"is this the clearest expression of my intent?\" while Harden asks \"how could this be exploited?\" Conflating them leads to mediocre results on both. Running them sequentially also lets us prioritize security fixes when budget is tight.\n\nWhy the document micro-pass? Agents are terrible at documenting their reasoning unprompted. Humans reviewing agent-generated code consistently report that the biggest friction is understanding why a choice was made. Five comments is a trivial cost for enormous review-time savings.\n\nFuture Considerations\nTeam calibration: Allow teams to weight the review checklist (e.g., \"we care more about injection vectors than naming\")\nDiff-aware context loading: For large codebases, intelligently load only the files and symbols relevant to the diff rather than the full project\nCross-skill composition: Simplify & Harden could feed into a \"PR Description\" skill that uses its summary to auto-generate meaningful PR descriptions" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/pskoett/simplify-and-harden", "publisherUrl": "https://clawhub.ai/pskoett/simplify-and-harden", "owner": "pskoett", "version": "1.0.1", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/simplify-and-harden", "downloadUrl": "https://openagent3.xyz/downloads/simplify-and-harden", "agentUrl": "https://openagent3.xyz/skills/simplify-and-harden/agent", "manifestUrl": "https://openagent3.xyz/skills/simplify-and-harden/agent.json", "briefUrl": "https://openagent3.xyz/skills/simplify-and-harden/agent.md" } }