New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Refactor Design Report

by penwyp in penwyp/ClaudePreference

Produce a professional, code-grounded refactor or implementation design report from identified technical problems, product gaps, review findings, architecture concerns, or frontend-backend contract…

MITAuto-check passedProduct & Project Management

Install Refactor Design Report

skills CLI
$ npx skills add penwyp/ClaudePreference --skill refactor-design-report -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install penwyp/ClaudePreference refactor-design-report --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/penwyp/ClaudePreference.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/refactor-design-report .claude/skills/refactor-design-report && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
refactor-design-report
GitHub stars
136
Token cost
~1.4k tokens
SKILL.md length
505 words
Files
2
Skills in repo
7
Repo updated
First seen
Licence
MIT

At a glance

Produce a professional, code-grounded refactor or implementation design report from identified technical problems, product gaps, review findings, architecture concerns, or frontend-backend contract…

  • Works in 7 steps: Normalize the request. → Locate the real implementation. → Define the target semantics. → …
  • Codex is asked to turn bugs
  • SKILL.md covers Purpose, Workflow, Report Format and Review Rules, plus 1 more section
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Refactor Design Report is an agent skill from penwyp/ClaudePreference. Produce a professional, code-grounded refactor or implementation design report from identified technical problems, product gaps, review findings, architecture concerns, or frontend-backend contract issues. Use when Codex is asked to turn bugs, missing protections, design gaps, API/UI mismatches, or desired behavior changes into a detailed backend/frontend/系统改造方案, persistent design document, implementation plan, test matrix, rollout plan, or acceptance criteria.

Its SKILL.md is about 1.4k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files (for example `agents/openai.yaml`).

It sits in Product & Project Management, covering Refactoring, Code review and Planning. The repository describes itself as: A comprehensive collection of development workflow commands for Claude Code. The licence is MIT.

When your agent uses it

  • Codex is asked to turn bugs
  • Missing protections
  • API/UI mismatches
  • Desired behavior changes into a detailed backend/frontend/系统改造方案

Example prompts

  • “/refactor-design-report”

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

  1. Normalize the request.
  2. Locate the real implementation.
  3. Define the target semantics.
  4. Design the backend.
  5. Design the frontend.
  6. Define verification.
  7. Provide implementation order.

What it can do on your machine

Read from SKILL.md and the folder at commit a5eea54. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Refactor Design Report loads about 1.4k tokens when it runs. Until then it costs about 122 tokens; SKILL.md has 505 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~122
When it runs · the whole SKILL.md, loaded when a task matches
~1.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from penwyp/ClaudePreference at commit a5eea54, republished under its MIT licence (© penwyp). 505 words, ~1,408 tokens.

Download SKILL.mdSave it as .claude/skills/refactor-design-report/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
refactor-design-report
description
Produce a professional, code-grounded refactor or implementation design report from identified technical problems, product gaps, review findings, architecture concerns, or frontend-backend contract issues. Use when Codex is asked to turn bugs, missing protections, design gaps, API/UI mismatches, or desired behavior changes into a detailed backend/frontend/系统改造方案, persistent design document, implementation plan, test matrix, rollout plan, or acceptance criteria.

Refactor Design Report

Purpose

Create a durable engineering report that turns concrete problems into an executable design. Ground the report in the current code and contracts first, then describe the target model, backend changes, frontend changes, validation strategy, implementation order, and acceptance criteria.

Workflow

  1. Normalize the request.

    • Extract the concrete issues, desired behavior, affected user flows, and any stated constraints.
    • Separate current defects from desired future capabilities.
    • If the user says to persist the result, write a focused design document in the appropriate docs location; otherwise provide the report in the reply.

  2. Locate the real implementation.

    • Find entry points before designing: API definitions, handlers, service methods, data models, workflow runners, frontend request builders, UI components, tests, and docs.
    • Prefer real call paths over keyword-level guesses.
    • Identify what is already implemented, what is only documented, and what is missing.

  3. Define the target semantics.

    • Name the core concepts and states precisely.
    • State invariant rules as hard requirements, not suggestions.
    • Resolve ambiguous user-facing terms into exact technical meanings.
    • Decide which behavior belongs in backend hard validation, frontend guidance, workflow preflight, and tests.

  4. Design the backend.

    • Cover API/proto/schema changes, storage changes, service validation, workflow/runtime changes, error types, idempotency, locking, and retry behavior.
    • Put hard safety rules in backend paths that cannot be bypassed by the UI.
    • Include both precheck-time and execution-time validation when state can change between submit and execution.

  5. Design the frontend.

    • Cover UI state, available actions, disabled states, warnings, confirmations, request shape, response handling, and stale precheck protection.
    • Ensure user wording matches the actual backend semantics.
    • Prevent users from selecting impossible or unsafe combinations; still rely on backend validation as final authority.

  6. Define verification.

    • Include unit tests for pure rules.
    • Include service/integration tests for API behavior.
    • Include frontend tests for UI gating and user guidance.
    • Include E2E matrix cases for the highest-risk flows.

  7. Provide implementation order.

    • Sequence changes from contracts and data model through backend, frontend, generation, tests, and rollout.
    • Call out generated code, migrations, docs, and compatibility choices explicitly.
Show full SKILL.md (170 more words)Show less

Report Format

Use this structure unless the user asks for a different format:

markdown
# <Short Design Title>

## Scope

Briefly state the problems being solved and the explicit constraints.

## Current State

Describe the current implementation with concrete evidence. Include file references when working in a local repository.

## Target Semantics

Define terms, invariants, state transitions, and user-visible meanings.

## Data Model And Contracts

Describe API, schema, storage, event, or protocol changes. Include example payloads when helpful.

## Backend Design

Describe validation rules, service flow, workflow/runtime changes, errors, locking, retries, and persistence.

## Frontend Design

Describe UI controls, dynamic options, copy, warnings, confirmations, request building, and response handling.

## Workflow / Runtime

Describe job phases, command generation, preflight checks, async behavior, and failure handling.

## Compatibility And Rollout

State whether backward compatibility is required. If not, say what can be deleted or replaced.

## Test Plan

List backend unit tests, service/API tests, frontend tests, and E2E matrix.

## Implementation Order

Give numbered steps that an engineer can execute.

## Acceptance Criteria

List observable conditions that must be true when the work is complete.

## Open Questions

Only include questions that block implementation or materially change the design.

Review Rules

  • Lead with findings and decisions, not background.
  • Do not invent product-specific facts. If a fact must come from code, inspect the code.
  • Distinguish confirmed evidence from inference.
  • Prefer backend hard validation for safety, frontend guidance for ergonomics, and workflow preflight for race-prone runtime state.
  • Do not hide known gaps. Label them as current gaps, target behavior, or out of scope.
  • Use concrete error names, request fields, state names, and test names when designing implementation details.
  • Avoid vague advice such as "add checks" or "improve UI"; specify where the check lives, what it reads, what it rejects, and how the user sees it.

Output Quality Bar

The report is complete when another engineer can implement from it without reconstructing the reasoning. It should include:

  • The exact current problem.
  • The exact target behavior.
  • Backend enforcement points.
  • Frontend user guidance and blocking behavior.
  • Contract and persistence changes.
  • Runtime race protections.
  • Tests that prove the behavior.
  • Clear acceptance criteria.

© penwyp, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in skills/refactor-design-report of penwyp/ClaudePreference.

  • SKILL.md
  • agents/openai.yaml

Open the folder on GitHubat commit a5eea54

Compare with similar skills

Refactor Design Report next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Refactor Design Report compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Refactor Design Report this skillpenwyp/ClaudePreference136—~1.4kAutomated safety check: PassMIT
Visual Dashboarddanielvm-git/bigpowers257—~478Automated safety check: PassMIT
Dough Execute Planterryyin/lizard2.5k—~4.3kAutomated safety check: PassCustom licence
QA Releasejitpass/jit162—~1.1kAutomated safety check: PassCustom licence
Spec WorkflowTencentCloudBase/CloudBase-AI-Toolkit1.1k2 repos~1.3kAutomated safety check: PassMIT
AI Code Reviewpony-maggie/code_minions156—~381Automated safety check: PassNone

Similar skills

  • Visual Dashboard

    danielvm-git/bigpowers

    Start a browser-based dashboard that visualizes architecture, implementation plans, and project status.

    257 GitHub stars~478 tokensUpdated 17 days ago
    Product & Project ManagementAuto-check passed

  • Dough Execute Plan

    terryyin/lizard

    Executes one selected story or bounded retrospective correction through an executable plan, or one authorized planless slice from a selected simple story or a contextual instruction, with…

    2.5k GitHub stars~4.3k tokensUpdated 2 days ago
    Product & Project ManagementAuto-check passed

  • QA Release

    jitpass/jit

    Run jit's pre-release QA — a team of QA-engineer subagents (functionality, integrations, UX, bug-hunting, code review) that exercise a release candidate on this real Mac and hand back a consolidated…

    162 GitHub stars~1.1k tokensUpdated 3 days ago
    Product & Project ManagementAuto-check passed

  • Spec Workflow

    TencentCloudBase/CloudBase-AI-Toolkit

    A skill your agent uses when medium-to-large changes need explicit requirements, technical design, and task planning before implementation, especially for multi-module work, unclear acceptance…

    1.1k GitHub starsUsed in 2 repos~1.3k tokens
    Product & Project ManagementAuto-check passed

  • AI Code Review

    pony-maggie/code_minions

    Structured review of a diff against a ticket's acceptance criteria.

    156 GitHub stars~381 tokensUpdated 4 mo ago
    Product & Project ManagementAuto-check passed

  • Reviewer

    aiskillstore/marketplace

    Read-only code reviewer for agent-flow. An agent skill from aiskillstore/marketplace.

    430 GitHub starsUsed in 1 repo~1.3k tokens
    Product & Project ManagementAuto-check passed

More from penwyp/ClaudePreference

  • Local Project Runtime

    penwyp/ClaudePreference

    Diagnose and stabilize local project setup after clone or checkout.

    136 GitHub stars~1.1k tokensUpdated 4 mo ago
    Auto-check: notes

  • Image Converter

    penwyp/ClaudePreference

    Convert images between common formats on macOS, especially SVG/PNG/ICO/ICNS/JPEG/WebP/PDF, using installed local tools such as ImageMagick, rsvg-convert, sips, qlmanage, and iconutil.

    136 GitHub stars~955 tokensUpdated 4 mo ago
    Auto-check passed

  • Explain

    penwyp/ClaudePreference

    Analyze a code snippet, file path, symbol name, or the current conversation context against the local repository and explain what it does in the project.

    136 GitHub stars~1.2k tokensUpdated 4 mo ago
    Auto-check passed

  • Doc Code Review Report

    penwyp/ClaudePreference

    Review text input or documents against the local codebase and produce a structured review report with findings and refactor suggestions.

    136 GitHub stars~1.5k tokensUpdated 4 mo ago
    Auto-check passed

  • Browser Flow Fallbacks

    penwyp/ClaudePreference

    Diagnose flaky browser automation flows (login, OAuth, signup, multi-step forms).

    136 GitHub stars~1.1k tokensUpdated 4 mo ago
    Auto-check passed

  • Develop Review Gate

    penwyp/ClaudePreference

    适用于这类请求：直接在当前 checkout 完成开发、固定做两轮自我 review/refactor、先把最终 review 结果给人类确认、确认后再继续改动、提交或进入下一步。用户可能会说："先开发再自审两轮"、"先 review 两次再给我确认"、"不要开 worktree，直接改"、"先输出 review 结论不要继续"、"做完先停在 gate"。

    136 GitHub stars~846 tokensUpdated 4 mo ago
    Auto-check passed

Categories

Questions about Refactor Design Report

What does Refactor Design Report do?

Produce a professional, code-grounded refactor or implementation design report from identified technical problems, product gaps, review findings, architecture concerns, or frontend-backend contract…. Refactor Design Report is an agent skill from penwyp/ClaudePreference. Produce a professional, code-grounded refactor or implementation design report from identified technical problems, product gaps, review findings, architecture concerns, or frontend-backend contract issues.

When should I use Refactor Design Report?

Refactor Design Report fits situations like: Codex is asked to turn bugs; missing protections; API/UI mismatches; desired behavior changes into a detailed backend/frontend/系统改造方案.

How do I install Refactor Design Report in Claude Code?

Run `npx skills add penwyp/ClaudePreference --skill refactor-design-report -a claude-code`. Or copy the skill folder (skills/refactor-design-report in penwyp/ClaudePreference) into .claude/skills/refactor-design-report in your project. Claude Code loads it when a task matches its description.

How do I install Refactor Design Report in Codex?

Run `npx skills add penwyp/ClaudePreference --skill refactor-design-report -a codex`. Or copy the skill folder (skills/refactor-design-report in penwyp/ClaudePreference) into .agents/skills/refactor-design-report in your project. Codex loads it when a task matches its description.

Can I use Refactor Design Report in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add penwyp/ClaudePreference --skill refactor-design-report -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/refactor-design-report, .gemini/skills/refactor-design-report, .github/skills/refactor-design-report and .opencode/skills/refactor-design-report in your project.

What does Refactor Design Report need to run?

SKILL.md names no scripts, command-line tools or credentials: Refactor Design Report is instructions for the agent only.

Does Refactor Design Report access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Refactor Design Report safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Refactor Design Report use?

Refactor Design Report is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Refactor Design Report use?

About 1.4k tokens (SKILL.md is roughly 5.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Refactor Design Report?

Skills that share tags, products or a category with Refactor Design Report: Visual Dashboard (danielvm-git/bigpowers, 257 stars), Dough Execute Plan (terryyin/lizard, 2.5k stars), QA Release (jitpass/jit, 162 stars) and Spec Workflow (TencentCloudBase/CloudBase-AI-Toolkit, 1.1k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Refactor Design Report?

penwyp (a GitHub user) maintains it in penwyp/ClaudePreference, which has 136 GitHub stars. The repository holds 7 skills in this directory. The repository was last updated on May 27, 2026.

Source: penwyp/ClaudePreference on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.