Claude Skill

large-file-refactor

Imported from paulrberg/agent-skills/skills/large-file-refactor.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download PaulRBerg-agent-skills-skills_large-file-refactor-47581b8.zip · 6 KB

Install

skills CLI npx skills add https://github.com/PaulRBerg/agent-skills/tree/main/skills/large-file-refactor
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install paulrberg-agent-skills@llmmart
Git git clone https://github.com/PaulRBerg/agent-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole paulrberg/agent-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Large File Refactor

This skill is coordination-exempt: skip the ai-coord gate for its declared work.

If a slash or dollar invocation already added these instructions to the conversation, follow them directly. In that case, do not invoke this skill again through a skill tool.

Use LOC thresholds to discover candidates, then decide whether a split is justified by cohesion, coupling, ownership, and change risk. Source files match above 1000 LOC. Test files use a relaxed 2000 LOC discovery threshold.

Arguments

  • path: Optional file or directory to scan. Default: current working directory.
  • --include-generated: Include generated, vendored, dependency, and build-output paths that are skipped by default.

Workflow

  1. Resolve the skill directory, then run the helper from the target repository:

    uv run "<skill-dir>/scripts/large-file-refactor.py" [path] [--include-generated]
    
  2. Preserve the helper's Markdown table as the exhaustive report. Do not omit matching rows, even when the refactor plan only covers a subset.

  3. If the helper reports no threshold matches, stop after the report. A match is a candidate, not proof that the file should be split.

  4. Draft a refactor plan for the 3 largest files only, unless the user explicitly requested another count.

  5. For each candidate, rank split value by mixed responsibilities, change frequency/risk, coupling, and testability. Use whichever semantic symbol/reference tooling is available. When Serena is installed, prefer it:

    • Inspect symbol overviews, references, imports, and relevant history.
    • Use the evidence to choose extraction boundaries, target module names, migration order, and test coverage.
  6. This workflow defaults to a report and plan. Implement only when the user's request already authorizes execution or the user subsequently approves it. Do not require a separate request for an unchanged, already authorized outcome.

Refactor Plan Format

For each selected file, include:

  • Current role: the file's apparent responsibility and why line count is a symptom.
  • Semantic pass: the exact symbol/reference/history inspection to run before moving code.
  • Split proposal: 2-5 target modules or files with responsibilities.
  • Migration order: small, reviewable steps that preserve public behavior.
  • Verification: narrow tests, type checks, builds, or smoke checks that prove the split.

Lead each plan with one explicit verdict: ### ✂ Split justified, ### 🧱 Keep intact, or ### ⚠️ Generated — change the generator. Use a compact evidence table for repeated criteria. When proposing a split, show the source and target modules as a tree only when it clarifies ownership.

If a selected file is generated or vendored because --include-generated was used, plan against the generator, schema, or upstream source instead of hand-splitting generated output.

Guard Rails

  • Treat the table as the source of truth for size ranking only. Rank refactor priority separately.
  • Keep the plan cohesive. Do not split solely to reduce line count.
  • Prefer existing project module boundaries and naming conventions.
  • Report when the helper used its portable LOC estimate instead of tokei.

Completion

Complete with the exhaustive threshold report plus evidence-ranked plans only for candidates whose cohesion or change risk justifies a split. Lead with ### 🔎 Large-file scan — <candidate count>, state when a large file should remain intact and why, and surface the portable-LOC fallback as ⚠️ Approximate counts when used. Keep the helper's exhaustive table, paths, LOC values, and commands exact and undecorated.

Files (agent-skills)
  • agents
    • openai.yaml 43 B
      Loading…
  • scripts
    • large-file-refactor.py 14.7 KB
      Loading…
  • SKILL.md 3.9 KB
    ---
    argument-hint: "[path] [--include-generated]"
    coordination: exempt
    disable-model-invocation: true
    name: large-file-refactor
    description:
      Discover large source-file refactor candidates and propose split plans based on cohesion and risk, using available
      semantic tooling.
    ---
    
    # Large File Refactor
    
    This skill is coordination-exempt: skip the ai-coord gate for its declared work.
    
    If a slash or dollar invocation already added these instructions to the conversation, follow them directly. In that
    case, do not invoke this skill again through a skill tool.
    
    Use LOC thresholds to discover candidates, then decide whether a split is justified by cohesion, coupling, ownership,
    and change risk. Source files match above 1000 LOC. Test files use a relaxed 2000 LOC discovery threshold.
    
    ## Arguments
    
    - `path`: Optional file or directory to scan. Default: current working directory.
    - `--include-generated`: Include generated, vendored, dependency, and build-output paths that are skipped by default.
    
    ## Workflow
    
    1. Resolve the skill directory, then run the helper from the target repository:
    
       ```sh
       uv run "<skill-dir>/scripts/large-file-refactor.py" [path] [--include-generated]
       ```
    
    2. Preserve the helper's Markdown table as the exhaustive report. Do not omit matching rows, even when the refactor plan
       only covers a subset.
    
    3. If the helper reports no threshold matches, stop after the report. A match is a candidate, not proof that the file
       should be split.
    
    4. Draft a refactor plan for the 3 largest files only, unless the user explicitly requested another count.
    
    5. For each candidate, rank split value by mixed responsibilities, change frequency/risk, coupling, and testability. Use
       whichever semantic symbol/reference tooling is available. When Serena is installed, prefer it:
    
       - Inspect symbol overviews, references, imports, and relevant history.
       - Use the evidence to choose extraction boundaries, target module names, migration order, and test coverage.
    
    6. This workflow defaults to a report and plan. Implement only when the user's request already authorizes execution or
       the user subsequently approves it. Do not require a separate request for an unchanged, already authorized outcome.
    
    ## Refactor Plan Format
    
    For each selected file, include:
    
    - Current role: the file's apparent responsibility and why line count is a symptom.
    - Semantic pass: the exact symbol/reference/history inspection to run before moving code.
    - Split proposal: 2-5 target modules or files with responsibilities.
    - Migration order: small, reviewable steps that preserve public behavior.
    - Verification: narrow tests, type checks, builds, or smoke checks that prove the split.
    
    Lead each plan with one explicit verdict: `### ✂ Split justified`, `### 🧱 Keep intact`, or
    `### ⚠️ Generated — change the generator`. Use a compact evidence table for repeated criteria. When proposing a split,
    show the source and target modules as a tree only when it clarifies ownership.
    
    If a selected file is generated or vendored because `--include-generated` was used, plan against the generator, schema,
    or upstream source instead of hand-splitting generated output.
    
    ## Guard Rails
    
    - Treat the table as the source of truth for size ranking only. Rank refactor priority separately.
    - Keep the plan cohesive. Do not split solely to reduce line count.
    - Prefer existing project module boundaries and naming conventions.
    - Report when the helper used its portable LOC estimate instead of `tokei`.
    
    ## Completion
    
    Complete with the exhaustive threshold report plus evidence-ranked plans only for candidates whose cohesion or change
    risk justifies a split. Lead with `### 🔎 Large-file scan — <candidate count>`, state when a large file should remain
    intact and why, and surface the portable-LOC fallback as `⚠️ Approximate counts` when used. Keep the helper's exhaustive
    table, paths, LOC values, and commands exact and undecorated.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.