An agent skill is a reusable prompt that guides an AI agent through a specific task. For code refactoring, a skill works best on existing behavior: the agent can reshape the code rather than invent the logic. section 2.5 section 4.3
Write rules at the level of precision an agent needs. For narrative code, define what counts as a meaningful chunk, when extraction helps, and how to classify narrative levels. Extraction should reduce cognitive load, not merely create more methods or force readers to navigate between them. section 2.5
Extract a method only when it earns its place. Do not extract a method only to satisfy a narrative level. Narrative levels describe useful structure; they are not a quota system. If a caller is already short, readable, and at one clear level of abstraction, keep the story there. Extract a method when **any** of these holds: 1. The caller would exceed its chunk budget without the extraction. 2. The group names a cohesive business concept that the individual names cannot convey alone. 3. The extraction keeps the caller at a uniform level of abstraction. 4. The expression is complex, repeated, or hides intent that a name would reveal. Hard blockers (if any, DO NOT extract): 1. Caller is already within budget and readable. 2. Extraction does not make the caller easier to read. 3. The extracted body contains only one simple chunk. 4. The extracted method merely groups already clear calls and adds no domain concept.
These extraction rules combine positive reasons to extract with blockers that protect an already readable caller. section 2.5
A more involved skill can analyze the code, detect signals, refactor, review, and report. The review catches later changes that weaken earlier decisions; the report gives a human reviewer the signals, choices, simplifications, and tradeoffs needed to approve or refuse the proposal. section 4.3
Guard data-model changes
A clarity-of-intent skill can look for ambiguous primitive values, scattered validation, and unnecessary mutation, then consider more explicit data models. A signal alone does not justify a change. Public API contracts, generated models, and persisted structures need special care because a model change may break a contract. section 4.3
Focus a bundled skill
Claude Code includes a /simplify skill for existing code. It looks for complexity such as duplication or unnecessary nesting and can suggest performance or memory improvements. A request can narrow its focus to memory efficiency or removing duplication. section 3.2.3
Keep the human judgment in the loop: a lower complexity score or a stricter narrative structure is not automatically clearer. Use a skill’s rules to guide improvement, not as a quota for extracting methods. section 2.5 section 3.2.3





