How do I install the Macro To Micro skill?

Run npx skillmds@latest add shalomb/macro-to-micro in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Macro To Micro safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Macro To Micro?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Macro To Micro free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Macro To Micro?

shalomb (@shalomb) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Macro To Micro by shalomb — Agent Skill

Name: Macro To Micro
Author: shalomb

Macro To Micro

Use this skill to orchestrate deep codebase exploration and complex structural refactoring by chaining Codemap, LSP Code Analysis, and AST Grep. Trigger this when asked to "safely refactor across the codebase", "trace this bug to its source", "explore the architecture of this subsystem", or whenever a task requires understanding the impact of a change before making it. This acts as a high-road strategy guide over basic grep/read commands.

shalomb 725c55e 2 files · 5.6 KB Updated Sep 17, 2026

File contents

Macro to Micro: Structural Codebase Mastery

This is a higher-order orchestrator skill that formalizes the "Macro to Micro" toolchain. It teaches you how and when to hand off context between three powerful semantic tools:

Codemap (The Macro View): Treats code as a graph of files.
LSP Code Analysis (The Meso View): Treats code as a graph of symbols.
AST Grep (The Micro View): Treats code as syntax trees.

The Articulation Strategy

Do not blindly use grep_search or read_file on large unfamiliar codebases. Follow this hand-off chain:

Identify the Blast Radius (Codemap)
- Find the files that matter and their dependencies.
- Output: A list of target files and "hub" files (highly imported files that are dangerous to change).
Trace the Logic (LSP)
- Take the files from step 1 and use lsp reference and lsp definition to understand exactly how data flows between them.
- Output: An understanding of the exact semantic contract (function signatures, usages) that needs to be altered.
Execute the Transformation (AST Grep)
- Take the semantic understanding from step 2 and use sg run to perform a surgical, syntax-aware rewrite across all affected files simultaneously.

Reference Workflows

Detailed recipes for specific scenarios are available in the references:

references/workflows.md: Step-by-step guides for the "Safe Hub Refactor" and the "Mystery Bug Hunt".

Core Principles

Never skip the Macro step: If you are asked to change a "core" or "utils" file, use Codemap to check its fan-out first.
Never use sed for code: If you need to rename a parameter across 20 files, use AST Grep or LSP Rename. Text replacement destroys comments and strings.
Don't read massive files: If a file is 2,000 lines long, use lsp outline to see its structure before blindly jumping in.

Safe Refactoring Checklist

Before executing any structural refactor (safe rename or move):

codemap --deps . — understand the full dependency graph
Identify hub files in scope — they need extra care
codemap --diff — see what's already changed on this branch
All tests pass before starting

Safe rename pattern

Add the new name alongside the old (alias or wrapper)
Update all callers to use the new name
Remove the old name
Full test suite

Safe move pattern

Create new file with the same public API
Re-export from old location temporarily
Update all importers to use the new path
Remove old file and re-export

---name: macro-to-microdescription: Use this skill to orchestrate deep codebase exploration and complex structural refactoring by chaining Codemap, LSP Code Analysis, and AST Grep. Trigger this when asked to "safely refactor across the codebase", "trace this bug to its source", "explore the architecture of this subsystem", or whenever a task requires understanding the impact of a change before making it. This acts as a high-road strategy guide over basic grep/read commands.---# Macro to Micro: Structural Codebase MasteryThis is a higher-order orchestrator skill that formalizes the "Macro to Micro" toolchain. It teaches you how and when to hand off context between three powerful semantic tools:1. **Codemap (The Macro View):** Treats code as a **graph of files**.2. **LSP Code Analysis (The Meso View):** Treats code as a **graph of symbols**.3. **AST Grep (The Micro View):** Treats code as **syntax trees**.## The Articulation StrategyDo not blindly use `grep_search` or `read_file` on large unfamiliar codebases. Follow this hand-off chain:1. **Identify the Blast Radius (Codemap)** * Find the files that matter and their dependencies. * *Output:* A list of target files and "hub" files (highly imported files that are dangerous to change).2. **Trace the Logic (LSP)** * Take the files from step 1 and use `lsp reference` and `lsp definition` to understand exactly how data flows between them. * *Output:* An understanding of the exact semantic contract (function signatures, usages) that needs to be altered.3. **Execute the Transformation (AST Grep)** * Take the semantic understanding from step 2 and use `sg run` to perform a surgical, syntax-aware rewrite across all affected files simultaneously.## Reference WorkflowsDetailed recipes for specific scenarios are available in the references:* **[references/workflows.md](references/workflows.md)**: Step-by-step guides for the "Safe Hub Refactor" and the "Mystery Bug Hunt".## Core Principles* **Never skip the Macro step:** If you are asked to change a "core" or "utils" file, use Codemap to check its fan-out first.* **Never use `sed` for code:** If you need to rename a parameter across 20 files, use AST Grep or LSP Rename. Text replacement destroys comments and strings.* **Don't read massive files:** If a file is 2,000 lines long, use `lsp outline` to see its structure before blindly jumping in.## Safe Refactoring ChecklistBefore executing any structural refactor (safe rename or move):- [ ] `codemap --deps .` — understand the full dependency graph- [ ] Identify hub files in scope — they need extra care- [ ] `codemap --diff` — see what's already changed on this branch- [ ] All tests pass before starting### Safe rename pattern1. Add the new name alongside the old (alias or wrapper)2. Update all callers to use the new name3. Remove the old name4. Full test suite### Safe move pattern1. Create new file with the same public API2. Re-export from old location temporarily3. Update all importers to use the new path4. Remove old file and re-export

Frequently asked questions