AGENT SKILL

pylance-refactoring

Use when the user explicitly asks for the Pylance refactoring skill, or when they want named automated Python refactorings applied to one file, many files, a workspace, a folder subset, or a composed cleanup workflow such as workspace-wide unused-import cleanup, wildcard-import conversion followed by unused-import cleanup, inferred type annotations, or Pylance fix-all.

License 许可
MIT
最近更新
2026-08-31
Stars
★ 1
Forks
0

01 前言 Front Matter

name
pylance-refactoring
description
Use when the user explicitly asks for the Pylance refactoring skill, or when they want named automated Python refactorings applied to one file, many files, a workspace, a folder subset, or a composed cleanup workflow such as workspace-wide unused-import cleanup, wildcard-import conversion followed by unused-import cleanup, inferred type annotations, or Pylance fix-all.

03 SKILL.md 正文

Pylance Refactoring

Use this skill to orchestrate named Pylance automated refactorings across one file, a filtered file set, or a whole workspace. pylanceInvokeRefactoring operates on one file at a time; batch workflows combine it with workspace discovery and per-file reporting.

Verified Tool Facts

  • pylanceInvokeRefactoring takes one fileUri, one refactoring name, and optional mode.
  • mode="update" applies the returned workspace edit; omitted mode defaults to update.
  • mode="edits" returns a WorkspaceEdit without modifying files.
  • mode="string" returns updated content for the target file without modifying files.
  • pylanceWorkspaceRoots returns workspace root URIs, and pylanceWorkspaceUserFiles returns Pylance-visible user Python files for a workspace root.
  • In VS Code-backed Copilot Chat, mode="update" applies a VS Code workspace edit to editor buffers. It does not save files to disk. A terminal reads the on-disk file, so terminal validation can miss refactoring edits until the user or Copilot saves the edited files.

Batch Workflow

  1. Resolve scope. If the user named files, use those files. If the user asked for a folder, package, project, or workspace, get the workspace root with pylanceWorkspaceRoots, then get Pylance-visible files with pylanceWorkspaceUserFiles and filter that list to the requested scope.
  2. Choose the refactoring names from the map below. For composed workflows, run one refactoring pass at a time across the target set.
  3. Preview broad edits when appropriate. For “show me”, “preview”, “what would change”, or ambiguous broad-scope requests, call pylanceInvokeRefactoring with mode="edits" or mode="string" per target file and summarize the files that would change. If the user clearly asked to apply, use mode="update".
  4. Apply per file and track results. Invoke pylanceInvokeRefactoring once per target file. Track changed files, no-op files, and errors separately.
  5. Save before terminal-based validation. After mode="update" in VS Code-backed Copilot Chat, save changed files before running terminal tools, tests, or shell-based inspections that read from disk.
  6. Validate and report. For larger changes, run the most relevant validation available, such as diagnostics or focused tests. Report the refactoring names used, target scope, changed/no-op/error counts, files saved before terminal validation, and any files skipped by the user's filter.

Common Workflows

  • Remove unused imports from the whole workspace: pylanceWorkspaceRoots → pylanceWorkspaceUserFiles → for each target file call pylanceInvokeRefactoring with name="source.unusedImports".
  • Clean imports under a folder: get user files, filter paths to the requested folder such as src/ or tests/, then run source.unusedImports per matching file.
  • Expand wildcard imports, then clean up: run source.convertImportStar across the target files first, then run source.unusedImports across the same target files.
  • Convert imported names to module-qualified imports, then clean up: run source.convertImportToModule, then source.unusedImports if the user asked for cleanup too.
  • Preview workspace cleanup: run the requested refactoring with mode="edits" on each target file, summarize files with edits, then wait for the user to confirm before applying if the request was only a preview.
  • Run Pylance fix-all on a file set: run source.fixAll.pylance per target file. This applies the fixes configured by Pylance settings, so use settings/diagnostics tools when the user asks what fix-all includes.

Refactoring Map

User intent name
Remove unused imports source.unusedImports
Convert absolute/relative import format source.convertImportFormat
Expand from module import * source.convertImportStar
Convert from module import name to module-qualified imports source.convertImportToModule
Rename user modules that shadow standard library modules source.renameShadowedStdlibImports
Add inferable type annotations source.addTypeAnnotation
Apply available Pylance auto-fixes source.fixAll.pylance

Working Rules

  • Treat workspace-wide refactoring as orchestration over many single-file tool calls, not as one bulk API call.
  • Prefer pylanceWorkspaceUserFiles over raw globbing for workspace-wide requests so the target set matches Pylance's user-code view.
  • Preserve the user's scope exactly: all files, selected files, a folder, tests only, src only, changed files only, or explicit exclusions.
  • In VS Code-backed Copilot Chat, do not assume terminal tools can see mode="update" results until files are saved. Save before terminal validation, or use Pylance/editor-visible tools for immediate post-refactor checks.
  • Use this skill for the named refactorings above, not for arbitrary code rewrites.
  • Do not use this for semantic rename, reference search, diagnostics explanation, or signature-impact analysis; use Pylance LSP or signature compatibility tools for those.
  • If pylanceInvokeRefactoring returns no edits for a file, count it as a no-op instead of inventing a manual cleanup.
  • If a later manual edit is needed, keep it separate from the automated refactoring and explain why.
  • After mode="update", do not manually reapply the same refactoring to the same file.

04 同仓库更多 Skills

nguyenhungtran18
nguyenhungtran18/skill-and-tool-tracker

xcode-project-setup

Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).

★ 1
nguyenhungtran18
nguyenhungtran18/skill-and-tool-tracker

writing-skills

Use when creating new skills, editing existing skills, or verifying skills work before deployment

★ 1
nguyenhungtran18
nguyenhungtran18/skill-and-tool-tracker

writing-plans

Use when you have a spec or requirements for a multi-step task, before touching code

★ 1
nguyenhungtran18
nguyenhungtran18/skill-and-tool-tracker

workflow-skill-creator

Distills a completed user workflow or interaction into a reusable agent skill. Use when the user asks to turn their workflow, interaction, or multi-step process into a skill, or when they say "make this a skill", "create a skill from what we just did", "package this workflow" or similar. Do not use for creating skills from scratch without an existing workflow (use a generic skill-creator for that).

★ 1
nguyenhungtran18
nguyenhungtran18/skill-and-tool-tracker

verify-and-stop

Prove existing work meets acceptance conditions without expanding scope. Use for validation-only tasks, completion checks, focused gate runs, and last-mile proof.

★ 1
nguyenhungtran18
nguyenhungtran18/skill-and-tool-tracker

verification-before-completion

Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always

★ 1