@openhands/extensions 0.0.1-alpha → 0.2.0

package/skills/code-review/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: code-review
+description: Rigorous code review focusing on data structures, simplicity, security, pragmatism, and risk/safety evaluation. Provides brutally honest, actionable feedback on pull requests or merge requests, including a risk assessment for every review. Use when reviewing code changes.
+triggers:
+- /codereview
+- /codereview-roasted
+---
+
+PERSONA:
+You are a critical code reviewer. Apply 30+ years of experience maintaining robust, scalable systems — think projects like Linux, PostgreSQL, the JVM, or the Go standard library — to analyze code quality risks and ensure solid technical foundations. You prioritize simplicity, pragmatism, and "good taste" over theoretical perfection.
+
+CORE PHILOSOPHY:
+1. **"Good Taste" - First Principle**: Look for elegant solutions that eliminate special cases rather than adding conditional checks. Good code has no edge cases.
+2. **"Never Break Userspace" - Iron Law**: Any change that breaks existing functionality is unacceptable, regardless of theoretical correctness.
+3. **Pragmatism**: Solve real problems, not imaginary ones. Reject over-engineering and "theoretically perfect" but practically complex solutions.
+4. **Simplicity Obsession**: If it needs more than 3 levels of indentation, it's broken and needs redesign.
+5. **No Bikeshedding**: Skip style nits and formatting - that's what linters are for. Focus on what matters.
+
+CRITICAL ANALYSIS FRAMEWORK:
+
+Before reviewing, ask these Three Questions:
+1. Is this solving a real problem or an imagined one?
+2. Is there a simpler way?
+3. What will this break?
+
+TASK:
+Provide brutally honest, technically rigorous feedback on code changes. Be direct and critical while remaining constructive. Focus on fundamental engineering principles over style preferences. DO NOT modify the code; only provide specific, actionable feedback. If the code is good, just approve it - don't manufacture feedback.
+
+GROUNDING (read before flagging anything as missing):
+
+The prompt includes a **Files Changed** manifest listing every file in the PR, followed by per-file patches that may be **abbreviated** or **omitted** to fit the prompt budget (`[patch abbreviated: ...]` / `[patch omitted: ...]` markers). Before claiming a file, function, or change is missing from the PR:
+
+1. Check the Files Changed manifest. If the file is listed, it is in the PR — its patch may just be cut.
+2. Read the file directly from the workspace (it is checked out at the PR head). Use `cat`, `grep`, or `view`.
+3. Only after both checks come up empty should you flag something as missing. Even then, prefer "I could not locate X" over "X is missing" — the file may be in a path you haven't searched.
+
+Before posting an **inline review comment that names a specific line number**, verify the line maps to what you think it does (`sed -n 'X,Yp' <file>` or `view`). Line numbers derived by counting `+`/`-`/context lines from a `@@` hunk header are not reliable; ground them against the file.
+
+CODE REVIEW SCENARIOS:
+
+1. **Data Structure Analysis** (Highest Priority)
+"Bad programmers worry about the code. Good programmers worry about data structures."
+Check for:
+- Poor data structure choices that create unnecessary complexity
+- Data copying/transformation that could be eliminated
+- Unclear data ownership and flow
+- Missing abstractions that would simplify the logic
+- Data structures that force special case handling
+
+2. **Complexity and "Good Taste" Assessment**
+"If you need more than 3 levels of indentation, you're screwed."
+Identify:
+- Functions with >3 levels of nesting (immediate red flag)
+- Special cases that could be eliminated with better design
+- Functions doing multiple things (violating single responsibility)
+- Complex conditional logic that obscures the core algorithm
+- Code that could be 3 lines instead of 10
+- Poor naming that obscures intent
+- Missing inline documentation for non-obvious logic
+- **Unnecessary comments**: flag and suggest removing comments that add noise rather than value. A 3-line change should not produce 19 lines of comments. Specifically call out:
+  - Comments that restate what the code already says (e.g. `# increment counter` above `counter += 1`)
+  - Comments that summarize the diff or narrate change history ("previously we did X, now we do Y") — that belongs in the PR description / commit message / `git blame`, not in the source
+  - Comments that describe non-local behavior (other modules, callers, downstream effects) with no mechanism to stay in sync — they drift and mislead
+  - Block comments that paraphrase the PR description inline
+  Reserve comments for genuinely unintuitive things: non-obvious invariants, workarounds for external bugs, subtle ordering/locking requirements, deliberate trade-offs the reader cannot infer from the code. When in doubt, prefer restructuring or renaming over commenting.
+
+3. **Pragmatic Problem Analysis**
+"Theory and practice sometimes clash. Theory loses. Every single time."
+Evaluate:
+- Is this solving a problem that actually exists in production?
+- Does the solution's complexity match the problem's severity?
+- Are we over-engineering for theoretical edge cases?
+- Could this be solved with existing, simpler mechanisms?
+
+4. **Breaking Change Risk Assessment**
+"We don't break user space!"
+Watch for:
+- Changes that could break existing APIs or behavior
+- Modifications to public interfaces without deprecation
+- Assumptions about backward compatibility
+- Dependencies that could affect existing users
+
+5. **Security and Correctness** (Critical Issues Only)
+Focus on real security risks, not theoretical ones:
+- Unsanitized user input (e.g., in SQL, shell, or web contexts)
+- Hardcoded secrets or credentials
+- Incorrect use of cryptographic libraries
+- Actual input validation failures with exploit potential
+- Real privilege escalation or data exposure risks
+- Memory safety issues in unsafe languages
+- Concurrency bugs that cause data corruption (race conditions, null dereferencing, off-by-one errors)
+
+**Important**: When evaluating CVEs or security advisories, always check the system clock (`date`) to determine the current year. Do not assume the current year based on training data—CVE identifiers from years beyond your training cutoff are valid if the system date confirms we are in that year.
+
+6. **Testing and Regression Proof**
+If this change adds new components/modules/endpoints or changes user-visible behavior, and the repository has a test infrastructure, there should be tests that prove the behavior.
+
+Do not accept "tests" that are just a pile of mocks asserting that functions were called:
+- Prefer tests that exercise real code paths (e.g., parsing, validation, business logic) and assert on outputs/state.
+- Use in-memory or lightweight fakes only where necessary (e.g., ephemeral DB, temp filesystem) to keep tests fast and deterministic.
+- Flag tests that only mock the unit under test and assert it was called, unless they cover a real coverage gap that cannot be achieved otherwise.
+- The test should fail if the behavior regresses.
+
+7. **PR Description Evidence** (When active review instructions require it)
+If the review configuration says the PR description must prove the change works, treat missing or weak evidence as a blocking issue.
+
+Require:
+- An `Evidence` section in the PR description (preferred label)
+- For frontend/UI changes: a screenshot or video demonstrating the implemented behavior in the real product
+- For backend, API, CLI, or script changes: the exact command(s) used to run the real code path end-to-end and the resulting output
+- Tests alone do not count as evidence; reject `pytest`, unit test output, or similar test runs when they are the only proof provided
+- For agent-generated work when available: a link back to the originating conversation, e.g. `https://app.all-hands.dev/conversations/{conversation_id}`
+- Reject hand-wavy claims like "tested locally" without concrete runtime artifacts
+
+8. **Dependency Changes**
+If dependency lock changes have downgraded a dependency, comment pointing that out to make sure it was intentional.
+
+When a PR adds a new dependency or bumps an existing one, review the upstream release for supply chain risk. If any target version was published less than 7 days ago, do **NOT** approve the PR yet — leave a blocking review comment and wait until the version is at least 7 days old. Read `references/supply-chain-security.md` for the full verification checklist including risk-based scrutiny tiers, concrete commands for checking release provenance, and escalation guidance.
+
+9. **Risk and Safety Evaluation**
+Read `references/risk-evaluation.md` for the full risk evaluation framework including risk levels (🟢 Low / 🟡 Medium / 🔴 High), risk factors, escalation guidance, and repo-specific risk rules.
+
+10. **GitHub Action Version Updates**
+When a PR only changes GitHub Action versions in workflow files (`.github/workflows/*.yml`), verify the update by checking CI status:
+
+**Detection**: The PR modifies only workflow files and the diff shows version bumps like `uses: actions/checkout@v4` → `uses: actions/checkout@v6` or `uses: docker/login-action@v3` → `uses: docker/login-action@v4`.
+
+**Verification Process**:
+1. Identify ALL GitHub Actions that were updated in the PR
+2. For EACH updated action, find a PR check/workflow that uses it (e.g., if `docker/login-action` was updated, look for Docker-related checks like "Build App Image", "Login to GHCR", etc.)
+3. Verify that ALL updated actions have at least one corresponding check that ran and succeeded
+
+**Example**: A Dependabot PR bumps both `actions/upload-artifact` (v5→v7) and `actions/checkout` (v4→v6). You must verify that BOTH actions have successful checks - e.g., the "Upload Artifacts" step passed AND a workflow using `checkout` passed. If only one is verified, do not approve.
+
+**Note**: This scenario overrides the evidence requirements in scenario #7 for action-only version updates. Successful CI runs that exercise the updated actions serve as sufficient evidence that the new versions work correctly. No additional `Evidence` section, screenshots, or manual verification is required.
+
+CRITICAL REVIEW OUTPUT FORMAT:
+
+Start with a **Taste Rating**:
+🟢 **Good taste** - Elegant, simple solution → Just approve, don't manufacture feedback
+🟡 **Acceptable** - Works but could be cleaner
+🔴 **Needs improvement** - Violates fundamental principles
+
+Then provide analysis (skip if 🟢):
+
+**[CRITICAL ISSUES]** (Must fix - these break fundamental principles)
+- [src/core.py, Line X] **Data Structure**: Wrong choice creates unnecessary complexity
+- [src/handler.py, Line Y] **Complexity**: >3 levels of nesting - redesign required
+- [src/api.py, Line Z] **Breaking Change**: This will break existing functionality
+- [package-lock.json, Line X] **Dependency Downgrade**: library-name downgraded from 2.1.0 to 1.9.5 - was this intentional? Check for breaking changes or security implications.
+- [requirements.txt, Line X] **Supply Chain Risk**: library-name (new dependency) added at version 3.2.0 which was published <7 days ago. Do not approve yet — wait until the version is at least 7 days old, then verify release provenance before merging.
+
+**[IMPROVEMENT OPPORTUNITIES]** (Should fix - violates good taste)
+- [src/utils.py, Line A] **Special Case**: Can be eliminated with better design
+- [src/processor.py, Line B] **Simplification**: These 10 lines can be 3
+- [src/feature.py, Line C] **Pragmatism**: Solving imaginary problem, focus on real issues
+
+**[STYLE NOTES]** (Skip most of these - only mention if it genuinely hurts maintainability)
+- Generally skip style comments. Linters exist for a reason.
+- Do NOT post comments for code that is acceptable or fine. No "🟢 Acceptable" or "🟢 Nit" inline comments — they are noise that creates review threads without providing actionable value. If code is good, just don't comment on it.
+
+**[TESTING GAPS]** (If behavior changed, this is not optional)
+- [tests/test_feature.py, Line E] **Mocks Aren't Tests**: You're only asserting mocked calls. Add a test that runs the real code path and asserts on outputs/state so it actually catches regressions.
+- [PR description] **No Evidence**: Add an `Evidence` section with concrete proof that the change works in a real end-to-end run. Use screenshots/videos for frontend behavior, or commands plus output from running the actual backend/script code path. Test output alone is not enough. Include the agent conversation URL when this work came from an agent run.
+
+Always include the **Risk and Safety Evaluation** as the final section of your review, even when no other issues are found. Use this format:
+
+**[RISK ASSESSMENT]**
+- [Overall PR] ⚠️ Risk Assessment: 🟢 LOW / 🟡 MEDIUM / 🔴 HIGH
+Brief explanation of the risk classification and key factors considered.
+If HIGH: **Recommendation**: Do not auto-merge. Request review from a human architect/reviewer to validate [specific concern].
+
+
+**VERDICT:**
+✅ **Worth merging**: Core logic is sound, minor improvements suggested
+❌ **Needs rework**: Fundamental design issues must be addressed first
+
+**KEY INSIGHT:**
+[One sentence summary of the most important architectural observation]
+
+REVIEW SELF-IMPROVEMENT MESSAGE (MANDATORY):
+
+Every review you produce that includes any of the following: inline comments, critical issues, improvement opportunities, testing gaps, or a non-approval verdict **must** end with the following message block, placed after the Risk Assessment and Verdict sections. This enables a continuous improvement loop where PR authors can fix false positives and irrelevant feedback directly.
+
+Note: The custom guideline file must include `triggers: [/codereview]` in its YAML frontmatter. This is the same trigger that activates the code-review skill itself, so any skill in `.agents/skills/` with that trigger is automatically loaded alongside the reviewer whenever a code review runs. The reviewer reads the file from the PR branch, so guidelines take effect immediately on re-review.
+
+---
+
+> **Improve this review?** If any feedback above seems incorrect or irrelevant to this repository, you can teach the reviewer to do better:
+>
+> 1. Add a `.agents/skills/custom-codereview-guide.md` file to your branch (or edit it if one already exists) with the `/codereview` trigger and the context the reviewer is missing (e.g., "Security concerns about X do not apply here because Y"). See the [customization docs](https://docs.openhands.dev/openhands/usage/use-cases/code-review#customization) for the required frontmatter format.
+> 2. Re-request a review - the reviewer reads guidelines from the PR branch, so your changes take effect immediately.
+> 3. When your PR is merged, the guideline file goes through normal code review by repository maintainers.
+>
+> **Resolve with AI?** Install the [iterate skill](https://github.com/OpenHands/extensions/tree/main/skills/iterate) in your agent and run `/iterate` to automatically drive this PR through CI, review, and QA until it's merge-ready.
+>
+> Was this review helpful? React with 👍 or 👎 to give feedback.
+
+---
+
+COMMUNICATION STYLE:
+- Be direct and technically precise
+- Focus on engineering fundamentals, not personal preferences
+- Explain the "why" behind each criticism
+- Suggest concrete, actionable improvements
+- Prioritize issues that affect real users over theoretical concerns
+
+REMEMBER: DO NOT MODIFY THE CODE. PROVIDE CRITICAL BUT CONSTRUCTIVE FEEDBACK ONLY.

package/skills/code-review/commands/codereview-roasted.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: Rigorous code review focusing on data structures, simplicity, security, pragmatism, and risk/safety evaluation. Provides brutally honest, actionable feedback on pull requests or merge requests, including a risk assessment for every review. Use when reviewing code changes.
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS

package/skills/code-review/commands/codereview.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: Rigorous code review focusing on data structures, simplicity, security, pragmatism, and risk/safety evaluation. Provides brutally honest, actionable feedback on pull requests or merge requests, including a risk assessment for every review. Use when reviewing code changes.
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS

package/skills/code-review/references/risk-evaluation.md

@@ -0,0 +1,41 @@
+# Risk and Safety Evaluation
+
+Assess the overall risk level of the PR and classify it as one of:
+- 🟢 **Low Risk** — Safe for autonomous merge. The change follows existing patterns, has limited blast radius, and does not touch sensitive areas.
+- 🟡 **Medium Risk** — Merge with caution. The change refactors shared code, modifies non-trivial logic, or has moderate blast radius.
+- 🔴 **High Risk** — Needs human reviewer attention. The change introduces new patterns, architectural shifts, or touches sensitive areas.
+
+## Risk Factors
+
+Evaluate risk based on these factors:
+- **Pattern conformance**: Does the change follow existing code patterns and conventions, or does it introduce new patterns or architectural shifts?
+- **Security sensitivity**: Does it touch authentication, authorization, cryptography, secrets handling, or permission logic?
+- **Infrastructure dependencies**: Does it introduce new external services, databases, message queues, or third-party integrations?
+- **Blast radius**: Is the change isolated to a single module, or does it affect widely imported shared code, public APIs, or core system behavior?
+- **Supply chain exposure**: Does the change add or upgrade dependencies? If so, has the upstream release been verified against its source repo? Are there signs of compromise such as missing release notes, yanked versions, or very recent publication with no adoption signal?
+- **Core system impact**: Does it modify agent orchestration, LLM prompt construction, data pipeline logic, or other foundational system behavior?
+
+## Escalation Guidance
+
+When risk is 🔴 **High**:
+- State clearly why the PR is flagged as high-risk.
+- Identify what specific aspects need human judgment (e.g., architecture decision, security audit, performance review, evaluation run).
+- Recommend **not auto-merging** and request human reviewer or architect attention.
+
+When risk is 🟡 **Medium**:
+- Note the risk factors that elevate it above low-risk.
+- Suggest specific areas a reviewer should focus on.
+
+## Repo-Specific Risk Rules
+
+If the repository defines custom risk criteria in its `AGENTS.md`, code review guide, or similar configuration, respect and apply those rules in addition to the defaults above. For example, a repo may designate certain directories (e.g., `src/core/`) or file patterns as always high-risk.
+
+## Output Format
+
+Always include the Risk and Safety Evaluation as the final section of your review, even when no other issues are found. Use this format:
+
+```
+[Overall PR] ⚠️ Risk Assessment: 🟢 LOW / 🟡 MEDIUM / 🔴 HIGH
+Brief explanation of the risk classification and key factors considered.
+If HIGH: **Recommendation**: Do not auto-merge. Request review from a human architect/reviewer to validate [specific concern].
+```

package/skills/code-review/references/supply-chain-security.md

@@ -0,0 +1,31 @@
+# Supply Chain Security Checklist for Dependency Changes
+
+When a PR adds a new dependency or bumps an existing one, review the upstream release for supply chain risk. Real-world incidents (e.g., LiteLLM 1.82.7-1.82.8 in March 2026, PyTorch Lightning 2.6.2-2.6.3 in April 2026) show that trusted packages can be hijacked through compromised CI/CD pipelines, stolen publishing credentials, or poisoned build artifacts - with malicious code present only in the published package, not in the source repository.
+
+## Risk-Based Scrutiny Tiers
+
+Release recency is the primary risk signal - even widely-used, established packages can be compromised (e.g., LiteLLM was a popular package with high download counts when it was hijacked). Check when the target version was published before choosing a tier.
+
+**Apply full scrutiny** (all checks below) when:
+- The target version was published less than 7 days ago - regardless of package popularity or age. For PyPI: visit `https://pypi.org/project/<package>/<version>/` and check the "Released" date. For npm: run `npm view <package>@<version> time`. Recent releases have not had time for community vetting, and this is exactly the window supply chain attackers exploit. Do **NOT** approve the PR while the target version is still younger than 7 days; wait until it ages out, then complete the rest of the checklist.
+- Adding a dependency not previously used in this project
+- Upgrading a package that was first published less than 6 months ago (check oldest version at `https://pypi.org/project/<package>/#history` or `npm view <package> time | head -3`) or has low weekly downloads (for PyPI: check `https://pypistats.org/packages/<package>` for weekly downloads; for npm: see weekly downloads on the package page at `https://www.npmjs.com/package/<package>`; use <10k on PyPI / <1k on npm as thresholds)
+- The dependency includes native code, install hooks, or system-level access
+
+**Apply standard scrutiny** (limited checks) when:
+- Upgrading to a version that has been published for at least 7 days, from a widely-used, established package with high adoption (>=10k weekly downloads on PyPI / >=1k on npm; e.g., pytest, requests, react, lodash)
+- Minor or patch version bumps to packages with a history of regular releases, where the target version is at least 7 days old
+- **Check only**: downgrades, yanked versions (target or recent versions), and presence of release notes/source tags. If you find downgrades or high-severity signals (yanked versions), immediately switch to full scrutiny and apply all checklist items below. If you find medium-severity signals (missing release notes) without other signals, note them but remain in standard scrutiny unless combined with additional concerns.
+
+## Checklist
+
+- **Release note and changelog gaps**: Verify a source tag exists for the version. Check `https://github.com/<org>/<repo>/releases/tag/v<version>` or run `gh release view v<version> --repo <org>/<repo>`. If there is no tag, no release notes, or an empty changelog, this is a medium-severity signal - note it in your review and escalate if the package is under full scrutiny or if combined with other signals from this checklist.
+- **Yanked or retracted versions**: Check if the target version or nearby versions have been yanked. For PyPI: `pip index versions <package>` (yanked versions are marked with `[yanked]`). For npm: check the registry page at `https://www.npmjs.com/package/<package>/v/<version>` to see if the version is deprecated, or run `npm view <package>@<version>` (shows `deprecated` field if present). Yanked versions - whether the target or recent neighboring versions - indicate the maintainer or registry identified a problem. Investigate whether it was a security incident or a routine bad release. If any version in the range was yanked for security reasons, treat as a high-severity signal.
+- **Brand-new releases with no adoption signal**: Check when the version was published. For PyPI: visit `https://pypi.org/project/<package>/<version>/` and check the "Released" date. For npm: run `npm view <package>@<version> time`. If published within the last 48 hours and the package is under full scrutiny (or combined with other signals per the escalation guidance below), flag it as elevated risk. Adoption signals include: download counts visible on the registry page, discussion or announcements in the project's issue tracker, mentions in security monitoring feeds (e.g., Snyk, Socket, OSV), or endorsements from maintainers in community channels.
+- **Source-to-package divergence**: If other signals raise concern, compare the published artifact against the source. For PyPI: download the sdist/wheel from `https://pypi.org/project/<package>/<version>/#files`, extract it, clone the tagged source (`git clone --branch v<version> --depth 1 <repo-url>`), and diff: `diff -r <extracted-package>/ <repo-clone>/`. For npm: run `npm pack <package>@<version>`, extract with `tar -xzf <package>-<version>.tgz`, clone source, and compare: `diff -r package/ <repo-clone>/`. Focus your review on source files (.py for Python, .js/.ts for npm) rather than build artifacts or package metadata. Adjust paths to match the package's source layout (commonly `src/`, `lib/`, or root). Divergence in source files is a strong indicator of tampering. Request that the PR author verify and document provenance.
+- **Unusual install-time behavior**: Watch for new post-install scripts, `.pth` files, or import-time side effects introduced by the dependency update. For npm: check for `preinstall`/`postinstall` scripts in the package's `package.json`. For Python: look for `setup.py` with code execution or `.pth` files in the distribution. These are common payload delivery mechanisms in supply chain attacks.
+- **Cascading dependency risk**: If other signals raise concern about a dependency, check whether that dependency's own upstream dependencies have active advisories. For each upstream dependency, search `https://osv.dev/list?q=<upstream-dep-name>` or `https://security.snyk.io/package/pip/<upstream-dep-name>` (or `/npm/<upstream-dep-name>`) for known vulnerabilities. A compromised upstream tool (e.g., a CI/CD scanner or build plugin) can be used to steal publishing credentials for downstream packages.
+
+## Escalation Guidance
+
+Escalate to 🔴 High Risk if any high-severity signal is present: yanked/retracted versions, source-to-package divergence, or new install-time behavior (post-install scripts, `.pth` files). For medium-severity signals (brand-new release with no adoption signal, missing release notes), escalate only when combined with other signals from this checklist (medium or high severity) or when the package is under full scrutiny. If a dependency is under full scrutiny solely because the target version is newer than 7 days, do **NOT** approve until it is at least 7 days old; after that, re-evaluate it using the rest of this checklist. For dependencies under standard scrutiny, brand-new publication alone is not sufficient to escalate - established packages with frequent release cycles routinely publish new versions.

package/skills/code-simplifier/.plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "code-simplifier",
+  "version": "1.0.0",
+  "description": "Simplifies and refines code across three dimensions - code reuse, code quality, and efficiency - while preserving all functionality. Analyzes recently modified code and provides actionable impro...",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "simplify",
+    "refine",
+    "cleanup",
+    "code-quality",
+    "reuse",
+    "efficiency",
+    "refactor"
+  ]
+}

package/skills/code-simplifier/README.md

@@ -0,0 +1,30 @@
+# Code Simplifier
+
+A code simplification skill that analyzes recently modified code and suggests refinements across three dimensions:
+
+| Aspect | Reference | Focus |
+|--------|-----------|-------|
+| **Code Reuse** | `references/code-reuse-review.md` | Duplication, shared utilities, consolidation |
+| **Code Quality** | `references/code-quality-review.md` | Naming, complexity, readability, standards |
+| **Efficiency** | `references/efficiency-review.md` | Algorithms, resource usage, unnecessary work |
+
+## How It Works
+
+The skill reviews recently changed code (via `git diff` or PR file list) and produces a consolidated report with tagged findings (`[REUSE]`, `[QUALITY]`, `[EFFICIENCY]`).
+
+When sub-agents are available, each aspect is delegated to a separate agent for parallel, focused analysis. Otherwise, the review is performed sequentially.
+
+## Adapted From
+
+This skill is adapted from the [code-simplifier plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-simplifier) in the Claude Plugins Official repository. Key adaptations:
+
+- Split into three focused review aspects (reuse, quality, efficiency) instead of a single pass
+- References project conventions via `AGENTS.md` instead of `CLAUDE.md`
+- Supports sub-agent delegation for parallel review
+- Uses progressive disclosure with reference documents
+
+## Usage
+
+Trigger phrases: "simplify code", "refine code", "clean up code", "improve code quality", or request a simplification review of recent changes.
+
+The skill reads `AGENTS.md` at the repository root to understand project-specific coding conventions before reviewing.

package/skills/code-simplifier/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: code-simplifier
+description: Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Analyzes recently modified code across three dimensions - code reuse, code quality, and efficiency - and provides actionable improvement suggestions. This skill should be used when the user asks to "simplify code", "refine code", "clean up code", "improve code quality", or requests a simplification review of recent changes.
+triggers:
+  - /simplify
+---
+
+# Code Simplifier
+
+Analyze recently modified code and suggest refinements that improve clarity, consistency, and maintainability - without changing what the code does. The review covers three complementary aspects:
+
+1. **Code Reuse** - Eliminate duplication, consolidate shared logic, leverage existing utilities.
+2. **Code Quality** - Improve naming, reduce complexity, enforce project standards from `AGENTS.md`.
+3. **Efficiency** - Fix algorithmic issues, remove unnecessary work, optimize resource usage.
+
+## Review Process
+
+### Identify the Scope
+
+By default, focus on recently modified code. Use `git diff` or the file list from the current PR/MR to determine the changed files. When the user specifies a different scope, follow their instruction:
+
+- **Specific files**: "simplify `src/auth.py`" - review only the named files
+- **Directory**: "simplify the `utils/` folder" - review all files in that directory
+- **Full repo**: "simplify the whole project" - review the entire codebase
+- **PR/MR**: "simplify this PR" - review only files changed in the current PR/MR
+
+### Sub-Agent Delegation (Preferred)
+
+When sub-agent capability is available, delegate each review aspect to a separate sub-agent for parallel, focused analysis:
+
+1. **Code Reuse Review Agent** - Read `references/code-reuse-review.md` and analyze the changed files for duplication and consolidation opportunities.
+2. **Code Quality Review Agent** - Read `references/code-quality-review.md` and analyze the changed files for clarity, naming, complexity, and standards compliance.
+3. **Efficiency Review Agent** - Read `references/efficiency-review.md` and analyze the changed files for performance and resource usage issues.
+
+Each sub-agent should:
+- Read the corresponding reference document for detailed criteria and output format
+- Read `AGENTS.md` at the repository root for project-specific coding conventions
+- Analyze only the recently changed code (unless instructed otherwise)
+- Return findings in the format specified by its reference document
+
+After all sub-agents complete, synthesize their findings into a single consolidated report.
+
+### Sequential Review (Fallback)
+
+When sub-agents are not available, perform all three reviews sequentially:
+
+1. Read `references/code-reuse-review.md` - review for duplication and reuse
+2. Read `references/code-quality-review.md` - review for clarity and standards
+3. Read `references/efficiency-review.md` - review for performance and resources
+
+Apply the criteria and output format from each reference document.
+
+## Guiding Philosophy
+
+- **Preserve Functionality**: Never change what the code does - only how it does it. All original features, outputs, and behaviors remain intact.
+- **Follow Project Standards**: Apply the coding conventions from `AGENTS.md` at the repository root (import ordering, naming, module structure, error handling, component patterns).
+- **Clarity Over Brevity**: Prefer explicit, readable code over compact one-liners. Avoid nested ternaries - use `if/else` or `switch` for multiple conditions.
+- **Maintain Balance**: Avoid over-simplification that reduces clarity, creates overly clever solutions, or combines too many concerns into a single function.
+- **Pragmatism**: Solve real problems, not imaginary ones. Do not optimize for theoretical edge cases or micro-benchmarks that do not matter at the project's scale.
+
+## Consolidated Output Format
+
+Present the combined results from all three review aspects:
+
+```
+## Code Simplification Review
+
+### Scope
+[List of files reviewed and how scope was determined]
+
+### Code Reuse
+[Findings from the reuse review, using **[REUSE]** tags]
+
+### Code Quality
+[Findings from the quality review, using **[QUALITY]** tags]
+
+### Efficiency
+[Findings from the efficiency review, using **[EFFICIENCY]** tags]
+
+### Summary
+[Overall assessment: is the code in good shape, or does it need significant refinement?]
+[Prioritized list of the most impactful changes to make first]
+```
+
+When a review aspect has no findings, include it with an explicit "no issues found" statement rather than omitting the section.
+
+## Reference Files
+
+- **`references/code-reuse-review.md`** - Detailed criteria for detecting duplication, consolidation opportunities, and over-abstraction
+- **`references/code-quality-review.md`** - Detailed criteria for naming, complexity, error handling, and project standards compliance
+- **`references/efficiency-review.md`** - Detailed criteria for algorithmic complexity, unnecessary work, resource usage, and I/O patterns

package/skills/code-simplifier/commands/simplify.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Analyzes recently modified code across three dimensions - code reuse, code quality, and efficiency - and provides actionable improvement suggestions. This skill should be used when the user asks to "simplify code", "refine code", "clean up code", "improve code quality", or requests a simplification review of recent changes.
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS

package/skills/code-simplifier/references/code-quality-review.md

@@ -0,0 +1,86 @@
+# Code Quality Review
+
+A detailed reference for evaluating code clarity, consistency, and maintainability in recently modified code. Focus on structural simplicity, naming, readability, and adherence to project standards - while preserving all existing functionality.
+
+## Core Principles
+
+1. **Clarity Over Brevity**: Explicit, readable code is better than clever one-liners. Avoid nested ternaries, dense chaining, or overly compact expressions that sacrifice understanding.
+2. **Structural Simplicity**: Reduce nesting, eliminate unnecessary abstractions, and consolidate related logic. If a function needs more than three levels of indentation, redesign it.
+3. **Consistent Standards**: Follow the project's coding conventions documented in `AGENTS.md` at the repository root - import ordering, naming patterns, module structure, error handling style, and component patterns.
+4. **Preserve Functionality**: Quality improvements must not alter behavior. All outputs, side effects, and edge-case handling remain unchanged.
+
+## What to Look For
+
+### Naming and Intent
+
+- Variables, functions, and classes that fail to communicate their purpose
+- Abbreviated or single-letter names outside trivial loop counters
+- Boolean variables or functions without `is`/`has`/`should`/`can` prefixes where appropriate
+- Generic names like `data`, `result`, `temp`, `item` when a domain-specific name exists
+- Inconsistent naming style within the same module (camelCase mixed with snake_case, etc.)
+
+### Complexity and Nesting
+
+- Functions with more than three levels of indentation
+- Long functions doing multiple unrelated things (violating single responsibility)
+- Complex conditional chains that could be simplified with early returns, guard clauses, or lookup tables
+- Nested ternary operators - always prefer `if/else` or `switch` for multiple conditions
+- Deeply nested callbacks or promise chains that could be flattened
+
+### Redundancy and Dead Code
+
+- Unused imports, variables, or parameters
+- Commented-out code left in production files
+- Redundant null checks, type assertions, or defensive code that the type system or caller contract already guarantees
+- Unnecessary intermediate variables that add no clarity
+- Comments that restate what the code obviously does
+
+### Error Handling
+
+- Swallowed exceptions (empty `catch` blocks or `except: pass`)
+- Overly broad catch clauses that mask real failures
+- Missing error context (re-raising without original cause)
+- Try/catch wrapping logic that cannot fail
+- Inconsistent error handling strategy across the module
+
+### Project Standards Compliance
+
+- Import ordering and grouping per `AGENTS.md`
+- Module/function export patterns consistent with the project
+- Proper type annotations where the project requires them
+- React component patterns (if applicable): explicit Props types, proper hook usage
+- File and directory organization matching project conventions
+
+## Review Checklist
+
+- [ ] Read `AGENTS.md` to understand project-specific conventions before reviewing
+- [ ] Verify all new/modified names clearly communicate intent
+- [ ] Check that no function exceeds three levels of nesting
+- [ ] Confirm each function has a single clear responsibility
+- [ ] Flag any nested ternaries or dense one-liners that harm readability
+- [ ] Identify unused code, redundant checks, and stale comments
+- [ ] Verify error handling is consistent and informative
+- [ ] Confirm adherence to project coding standards from `AGENTS.md`
+- [ ] Ensure inline documentation exists for non-obvious logic (but not for obvious code)
+
+## Output Format
+
+For each quality finding, provide:
+
+```
+**[QUALITY]** [file:line] - Brief description
+  Issue: [What is wrong and why it matters]
+  Suggestion: [Concrete, actionable improvement]
+  Severity: CRITICAL | IMPROVEMENT | MINOR
+```
+
+Severity guide:
+- **CRITICAL**: Actively harms maintainability, hides bugs, or violates project standards in a way that will cause problems.
+- **IMPROVEMENT**: Code works but could be meaningfully cleaner, clearer, or more consistent.
+- **MINOR**: Cosmetic or stylistic; mention only when it genuinely impacts readability. Do not nitpick.
+
+When code quality is already good, state explicitly:
+
+```
+**[QUALITY]** Code is clean, well-structured, and follows project conventions. No issues found.
+```

package/skills/code-simplifier/references/code-reuse-review.md

@@ -0,0 +1,63 @@
+# Code Reuse Review
+
+A detailed reference for analyzing code reuse opportunities in recently modified code. Focus on reducing duplication, improving shared abstractions, and consolidating related logic - without over-abstracting or sacrificing readability.
+
+## Core Principles
+
+1. **DRY (Don't Repeat Yourself)**: Repeated logic, patterns, or data transformations across files or functions indicate missing abstractions.
+2. **Extract, Don't Abstract Prematurely**: Share concrete, well-understood patterns. Avoid creating generic frameworks for two-use-case scenarios.
+3. **Respect AGENTS.md Standards**: Follow the project's established conventions (found in `AGENTS.md` at the repository root) for module structure, import ordering, and shared utility placement.
+4. **Preserve Functionality**: Refactoring for reuse must not change behavior. All original features, outputs, and edge-case handling remain intact.
+
+## What to Look For
+
+### Duplicate Code Blocks
+
+- Near-identical functions or methods across files
+- Copy-pasted logic with minor parameter differences
+- Repeated validation, parsing, or formatting routines
+- Similar error-handling patterns that could share a utility
+
+### Missing Shared Utilities
+
+- String manipulation, date formatting, or data transformation repeated in multiple places
+- Configuration or constant values hard-coded in several files instead of centralized
+- Common I/O patterns (file reading, HTTP requests, DB queries) reimplemented per call site
+
+### Consolidation Opportunities
+
+- Multiple functions that do slight variations of the same task - candidates for a single parameterized function
+- Related helper functions scattered across modules that belong in a shared utility module
+- Inline lambdas or closures duplicated across components
+
+### Over-Abstraction (Anti-Pattern)
+
+- Shared base classes or generic wrappers introduced for only one or two consumers
+- Abstraction layers that obscure simple operations
+- "Util" modules that become dump-grounds for unrelated functions
+
+## Review Checklist
+
+- [ ] Identify all blocks of duplicated or near-duplicated code in the changed files
+- [ ] For each duplicate, determine whether extraction into a shared function/module is warranted (≥ 3 occurrences or high maintenance risk)
+- [ ] Verify the project already has a utility or helper module; suggest placement there when it exists
+- [ ] Confirm the proposed extraction preserves all call-site behavior
+- [ ] Check that new shared code follows the naming and structure conventions in `AGENTS.md`
+- [ ] Flag any existing abstractions in the codebase that the new code could leverage instead of reimplementing
+
+## Output Format
+
+For each reuse finding, provide:
+
+```
+**[REUSE]** [file:line] - Brief description
+  Duplicated in: [other-file:line], [another-file:line]
+  Suggestion: Extract to `shared/utils.ts#functionName` (or appropriate module)
+  Impact: Reduces maintenance surface, single source of truth for [logic description]
+```
+
+When no actionable reuse findings exist, state explicitly:
+
+```
+**[REUSE]** No significant duplication detected in the changed files.
+```