PaperlayerView exact revision on arXiv

Source-linked AI summary

Adaptive Skill Granularity for Coding Agents: Runtime Routing and Macro-to-Micro Recovery

Dingxuan Zhang, Yanhui Jiang, Jun Wang, Hefeng Zhou

arXiv:2610.31461v1cs.AIcs.SE

TL;DR

Skill retrieval does not resolve how an agent should execute after selecting a relevant skill. Adaptive Skill Granularity combines runtime routing with macro-to-micro recovery, and the reported results show that routing and selective recovery address the trade-offs of fixed execution granularity.

  • Problem

    Prior work largely treats skill use as retrieval or composition, leaving runtime choice among primitive actions, macro skills, and recoverable execution as an additional control problem.

    Source: §1 · p. 2

  • Method

    Adaptive Skill Granularity uses a feature-based controller to select execution granularity and a finite-state executor to handle observable macro failures through recovery.

    Source: §1 · p. 2, §3.2 · p. 5

  • Results

    Runtime routing and recovery mitigate fixed granularity’s robustness–efficiency trade-off, with downgrade especially useful for early macro failures and less useful when late-failing macros have already completed required edits.

    Source: §5.9 · pp. 13–14, §6 · p. 14

  • Takeaways & Limitations

    The results suggest that adaptive routing and selective recovery offer a better balance of reliability and efficiency than fixed granularity or unconditional fallback alone.

    Source: §5.9 · p. 14, §6 · p. 14

    The macro-evolution loop is conceptualized as an extension, and its end-to-end empirical evaluation is left to future work.

    Source: §4.7 · p. 9

Abstract

from arXiv · show

Reusable skills allow large language model agents to package task-specific procedures, tool affordances, and execution guidance into modular units. Prior work has largely studied how agents retrieve, compose, or synthesize skills before execution. In coding agents, however, execution poses an additional runtime control problem: the same task may be solved through primitive tool calls, macro skills, or hybrid execution that starts with a macro and falls back to micro-level recovery. We introduce Adaptive Skill Granularity, a framework that treats skill granularity as an action-abstraction policy conditioned on task structure, execution state, and macro-skill failures. The system combines a feature-based granularity controller and a finite-state recovery executor. We evaluate the framework with a deterministic coding-agent protocol using verifier-defined success, total cost, and process metrics such as macro adoption, failure recovery, route match, and transition correctness. Results show that fixed macro execution is efficient when applicable but brittle under mismatch, while runtime routing and explicit macro-to-micro recovery improve robustness and recover controlled macro failures that fixed-granularity execution leaves unresolved. Our findings suggest that skill libraries for coding agents should be treated not only as retrievable resources, but also as controllable, verifiable, and recoverable execution abstractions.

1 Introduction

Skill retrieval does not settle how finely a coding agent should act during execution. Adaptive Skill Granularity treats this as runtime control, combining a feature-based controller with explicit recovery and evaluating both outcomes and execution process.

1 Introduction

  • Skill retrieval alone leaves unresolved whether the next coding actions should be primitive tools, macro skills, or controlled macro-to-micro recovery.A macro may mismatch a simple fix, while a module move may benefit from combined operations; failed or partial macros require recovery during execution.Source: §1 · p. 2
  • Adaptive Skill Granularity makes granularity a runtime control variable, allowing micro, macro, or hybrid execution based on task and execution context.Hybrid mode downgrades to micro tools after an observable macro failure.Source: §1 · p. 2
  • The architecture combines a feature-based granularity controller with a finite-state recovery executor for runtime execution abstraction.The paper formulates this separately from ordinary skill retrieval, which selects skills to expose rather than deciding the abstraction level of actions.Source: §1 · p. 2
  • GranBench-Code evaluates verifier-defined success and total cost alongside process metrics, in a pilot comparing fixed-granularity, routed, and recovery-enabled agents.The paper specifies unconstrained and LLM-router baselines for the full study.Source: §1 · p. 2

2 Related Work

Related work primarily addresses skill representation, acquisition, retrieval, composition, or planning-level abstraction. This paper instead focuses on controlling execution granularity at runtime and validating skills and agent behavior.

Agent skills and routing

  • Prior skill systems study reusable procedural artifacts, runtime metadata, skill formation, and retrieval or composition, whereas this work controls execution granularity at runtime.Examples include Formal Skill [25], SkillCraft [2], and SkillRouter, Graph-of-Skills, Skill Is Not Document, and SkillWeaver [6] [13] [20] [26].Source: §2 · p. 3

Action abstraction, monitoring, and repair

  • Classical temporal abstractions and hierarchical LLM methods inform the framing, but this work uses an inspectable controller rather than learning a hierarchical policy or refining plans.Its downgrade mechanism also relates to execution monitoring and recovery and automated program repair.Source: §2 · p. 3

Skill evolution and coding-agent evaluation

  • The macro-evolution loop requires replay, deterministic validation, documented side effects, and fallback behavior, while the evaluation protocol measures correctness and process behavior.This work targets uneven skill-injection gains and higher costs reported for abstraction-level and context mismatch in SWE-Skills-Bench [7].Source: §2 · p. 3

3 Problem Formulation

The formulation treats coding-agent execution as a repository-level trajectory in which granularity controls the actions available to the agent. It separates skill retrieval from runtime action control and recovery, and evaluates policies against verifier-defined success, cost, and process measures.

3.1 Agentic Execution Substrate

  • A coding-agent episode is modeled as execution over a repository, with a task comprising a prompt, initial workspace, metadata, and deterministic validator.Runs produce trajectories of skill actions; primitive skills include inspection, search, editing, syntax checks, and tests, while macros bundle multiple primitive operations.Source: §3.1 · pp. 3–4
  • Each action transforms the workspace and yields observations that record workspace changes, validation failures, and macro-specific failure signals.These observations expose runtime state for control after skill retrieval.Source: §3.1 · p. 4

3.2 Granularity as Action-Abstraction Control

  • A granularity mode constrains the admissible action set; the three modes are micro, macro, and hybrid execution.The action envelope is tied to execution history, and the downstream agent selects its next action only from that active envelope.Source: §3.2 · pp. 4–5
  • Hybrid execution may start with macro actions and transition to primitive actions after observable failure or validation, instantiated here as a one-way macro-to-micro downgrade.Richer policies could also escalate or alternate between modes, but are treated as extensions rather than part of this instantiation.Source: §3.2 · p. 4
  • The pre-execution controller selects an initial strategy from features extracted from the prompt, metadata, and initial workspace.Its output includes the initial mode, whether macro-failure recovery is enabled, and an explanation or confidence record.Source: §3.2 · p. 4
  • A recovery transition updates the effective mode after a macro failure, making recovery an explicit state transition rather than an informal retry.The transition can downgrade to micro execution when recovery is enabled or terminate with macro failure when it is disabled.Source: §3.2 · p. 5

3.3 Retrieval, Granularity, and Objective

  • Skill retrieval selects skills but does not decide whether execution uses primitive actions, macro actions, or a recoverable mixture.Granularity control is a runtime policy over admissible actions and recovery transitions, not merely a ranking of skill descriptions.Source: §3.3 · p. 5
  • The objective combines verifier-defined success with cost and unrecovered-failure penalties, and reports success, trajectory length, token cost, and process metrics.G-score compares cost among policies with similar success, with token cost normalized to the micro-only baseline.Source: §3.3 · p. 5

4 Adaptive Skill Granularity

Adaptive Skill Granularity routes coding-agent execution among micro, macro, and hybrid modes, validates the final workspace, and uses execution logs to support evaluation and future updates. Its auditable design combines pre-execution features, explicit macro contracts, and event-driven recovery.

4 Adaptive Skill Granularity

  • The online framework selects a micro, macro, or hybrid mode, restricts execution accordingly, and validates the final workspace; offline logs support evaluation, router updates, and macro-skill decisions.The framework also uses logs for confidence reporting and future macro-skill mining.Source: §4 · p. 5, Figure 1 · p. 6

4.1 Design Invariants

  • Routing uses only pre-execution evidence, recovery follows observable events, and success requires the deterministic validator to pass on the final workspace.The controller may inspect task metadata and the initial fixture, but not current-run verifier outcomes.Source: §4.1 · p. 6

4.2 Algorithmic Contract

  • The controller produces a decision tuple specifying the selected mode and strategy, whether macro recovery is enabled, and the reason; the executor switches to micro tools after an enabled macro failure or terminates otherwise.Transitions are recorded in the trajectory log.Source: §4.2 · pp. 6–7

4.3 Complexity Features

  • Pre-execution complexity features cover source paths and file counts, prompt entities, AST size and depth, imports, dependencies, and text-task and refactor-task flags.These features avoid execution-derived information so routing does not leak validation outcomes into the decision.Source: §4.3 · p. 7

4.4 Granularity Controller

  • A heuristic router provides a reference baseline, while learned routers use prior execution logs to select micro or macro mode and optionally enable hybrid fallback.The learned router is a depth-4 decision tree serialized to JSON for deterministic, auditable runtime traversal without online retraining.Source: §4.4 · p. 7

4.5 Macro-Skill Interface

  • A macro skill has an explicit contract covering applicability, allowed side effects, internal verification, observable failure classes, and the intended micro-level fallback.The prototype uses three constrained macros for module inspection, verified replacement, and moving a module while updating imports.Source: §4.5 · pp. 7–8

4.6 FSM Recovery Executor

  • The recovery executor treats macro failure as a state transition and, when recovery is enabled, continues with primitive tools from the current workspace; recovery counts only after validated success.Failures include precondition mismatch, partial side effect, validation failure, tool-schema failure, and executor exception.Source: §4.6 · pp. 8–9, Figure 2 · p. 8

4.7 Macro Evolution Loop

  • The paper leaves end-to-end empirical evaluation of macro-skill acquisition to future work and proposes admitting generated macros only after historical replay, documented side effects, and a precise fallback or declared unrecoverable failure class.The proposed gate is intended to preserve controllable and verifiable execution invariants.Source: §4.7 · p. 9

5 Experiments

The experiments use GranBench-Code, a deterministic coding benchmark organized around task families and isolated workspaces. A shared execution harness exposes tool actions and evaluates final workspaces with task-specific validators.

5.1 Benchmark Design

  • GranBench-Code groups tasks into simple, medium, refactor, and recovery families, with controlled failure injection in the recovery family.Each task supplies an isolated workspace, source files in a failing or stale state, task metadata, and a deterministic validator.Source: §5.1 · p. 9

5.2 Execution Harness

  • The execution harness preserves a pristine before snapshot for auditing while agents act on a disposable after workspace through single JSON-formatted actions or termination signals.Prompts provide task descriptions, workspace context, active tools, and routing decisions.Source: §5.2 · pp. 9–10
  • All variants share underlying tool implementations and differ only in exposed action spaces; task-specific validators determine success on the final workspace.Run logs track tool use, routing, validation, and total token consumption.Source: §5.2 · p. 10

5.3 Baselines

The baselines compare fixed micro and macro execution, pre-execution heuristic or learned routing without recovery, and recovery-enabled hybrid execution. Evaluation prioritizes verifier-defined success and cost while also tracking execution behavior.

5.3 Baselines

  • The comparison includes fixed micro and macro variants without recovery, heuristic and learned pre-execution routing without recovery, and heuristic or learned routing with macro-to-micro recovery.E-FSM-Downgrade enables the downgrade transition, while F-Learned-Full uses both learned routers.Source: §5.3 · p. 10

5.4 Metrics

  • Validated success rate is the primary metric, and cost per solved task aggregates token costs across all runs, including failures.The G-score is also reported to assess the success-cost trade-off.Source: §5.4 · p. 10
  • Process metrics include mean trajectory length, macro adoption, failure recovery, routing alignment with the rule, and transition correctness.These are reported alongside success and cost to characterize policy performance, efficiency, and execution behavior.Source: §5.4 · p. 10

5.5 Fixed vs. Adaptive Skill Granularity

Across 12 mixed tasks, fixed micro execution is robust but costly, while fixed macro execution reduces costs but is less robust; heuristic routing attempts to balance the trade-off but can misclassify tasks.

5.5 Fixed vs. Adaptive Skill Granularity

  • Pure micro execution achieves perfect success at the highest token and step costs, while pure macro execution significantly reduces costs but succeeds on fewer tasks.Heuristic routing attempts to balance these extremes but misclassifies some tasks based on structural features.Source: Table 2 · p. 11, §5.5 · p. 11

5.6 Dynamic Recovery after Macro Failure

Dynamic recovery handles early macro failures, while learned routing improves mode selection over heuristics. Late failures expose the cost of unconditional downgrade when the macro has already completed useful work.

5.6 Dynamic Recovery after Macro Failure

  • For late failures, no-recovery passed validation after the macro had updated the workspace, while unconditional downgrade added tokens and execution steps unnecessarily.This timing difference motivates a more selective recovery policy.Source: §5.6 · p. 11, Table 3 · p. 11
  • For early injected failures, FSM downgrade recovered all tasks by falling back to micro tools, whereas no recovery halted progress.The recovery benchmark covered 7 tasks.Source: Table 3 · p. 11, §5.6 · p. 11

5.7 Learning Better Mode Routing

  • The learned router achieved 100% success on 12 tasks, correcting heuristic misclassifications by routing complex synchronization tasks to primitive execution.It was trained offline on historical execution logs.Source: Table 4 · p. 12, §5.7 · p. 12

5.8 End-to-End Adaptive Skill Granularity

Combining learned mode routing with learned recovery preserves recovery performance while reducing unnecessary execution cost. Hybrid routing also supports recovery for high-risk structural changes such as module moves and import rewrites.

5.8 End-to-End Adaptive Skill Granularity

  • The learned full controller matched FSM downgrade’s perfect success under early faults at lower token cost, while skipping unnecessary fallback under late faults.Under late faults, the recovery router reduced both transition rate and token consumption compared with unconditional downgrade.Source: §5.8 · p. 12
  • For module_move_refactor, hybrid routing enabled recovery when strict no-recovery execution failed, complementing learned mode selection with selective fallback.Learned selection avoids unsuitable macro execution; selective recovery limits fallback to cases where it is needed.Source: §5.8 · p. 12
  • The framework achieved consistently high task success while reducing execution cost under realistic failure scenarios.The reported overall result combines adaptive mode selection with selective recovery.Source: §5.8 · p. 12

5.9 Results Analysis

Evaluation results show a robustness–efficiency trade-off for fixed granularity and timing-dependent costs for recovery. Learned routing and selective recovery address unsuitable macro use and unnecessary fallback in the evaluated settings.

5.9 Results Analysis

  • Micro execution achieved perfect success at the highest step and token costs, while macro execution was more efficient but less robust and heuristic routing offered only a partial compromise.The fixed-granularity comparison is on the mixed benchmark.Source: §5.9 · pp. 12–13
  • Under early injected faults, no-recovery failed completely while FSM downgrade recovered all tasks at additional execution cost; under late faults, no-recovery succeeded more cheaply after macros completed required edits.These outcomes show why recovery value depends on failure timing.Source: §5.9 · p. 13, Table 5 · p. 13
  • The learned full controller matched FSM downgrade’s perfect success under early faults at lower execution cost, and avoided unnecessary recovery under late faults while preserving full success.Figure 3 separates micro success, macro success, hybrid-recovery success, and terminal failure.Source: §5.9 · pp. 13–14, Figure 3 · p. 13
  • Overall, adaptive routing and recovery mitigate fixed granularity’s robustness–efficiency trade-off, while selective recovery avoids the overhead of always-on downgrade.The evaluation motivates routing and recovery based on task structure and runtime failure signals.Source: §5.9 · pp. 13–14

6 Conclusion

The conclusion frames skill granularity as a runtime execution choice beyond retrieval, with micro tools, macro skills, and macro-to-micro recovery as available modes. The authors identify broader task sets, repositories, failure modes, and models as future evaluation scope.

6 Conclusion

  • Adaptive Skill Granularity addresses the execution choice left unresolved by skill retrieval, enabling runtime use of micro tools, macro skills, or macro execution followed by micro recovery.The conclusion reports micro execution as robust but costly and macro execution as more efficient but more sensitive to task mismatch and failure timing.Source: §6 · p. 14
  • The authors state that future work will extend GranBench-Code across broader task sets, repositories, failure modes, and models.Source: §6 · p. 14

Disclosure of Interests

Related papers

Loading 2610.31461v1…