An AI skill is a reusable prompt or instruction set that guides an AI agent through a defined task. For code improvement, it is most reliable on existing behavior: the agent reshapes an established implementation rather than inventing business logic. A useful skill makes its quality standard operational by stating what to inspect, which changes are allowed, how to check them, and what to report for human review. section 2.5 section 4.3
Write rules at the level an agent can apply consistently. Vague advice such as “find meaningful units” needs boundaries and counterexamples. A narrative-code skill, for example, defines a chunk as a recognizable step, specifies when extracting a method reduces cognitive load rather than adding navigation cost, and classifies the resulting methods by narrative level. Rules are guidance, not quotas: a readable caller should not be fragmented merely to satisfy a structural target. section 2.5
Structure a multi-step refactoring skill as a controlled workflow:
- Analyze the code before changing it, building a higher-level view of the relevant model or behavior. section 4.3
- Detect concrete signals or opportunities, such as unclear data concepts, unnecessary nesting, or duplication. section 3.2.3 section 4.3
- Refactor toward the named goal while preserving deliberate boundaries, especially public API contracts, generated models, and persisted structures. section 4.3
- Review and audit the result, then report signals, choices, simplifications, and tradeoffs so a developer can approve or reject the change. section 2.5 section 4.3
A focused simplification skill
A simplification skill can inspect existing code for duplication and unnecessary nesting, then suggest performance or memory improvements. Its request can be narrowed to a goal such as memory efficiency or removing duplication. Treat its output as a proposal: structural metrics can identify taxing methods, but they do not decide whether a stream, loop, extraction, or other rewrite is clearest. section 3.2.3
Before making changes, identify the data the code is really manipulating. Ask: - What is the central data concept? - Which values represent identity, state, unit, range, or category? - Which values come from outside the system, and which are internal? - Which values are temporary, derived, or persisted? - Which values drive behavior? - Which values naturally belong together? - Which values are part of a public contract or generated model that cannot be changed directly?
Use these analysis questions to give a data-modeling skill the context needed before it proposes changes. section 4.3
The reusable heuristic is simple: make the task narrow, turn judgment into explicit decision rules, preserve nonnegotiable boundaries, and require an audit plus a readable rationale. Skills support craft judgment; they do not replace it. Over-refactoring for a score or pattern can make code harder to follow. section 2.5 section 3.2.3
