Precise Routing for Every Command: Practical Implementation of Multi-Skill Support in HagiCode Preset Task

A preset packed with multiple commands, yet they all have to share the same skill requirements? This refactor lets each command independently declare its dependent skill, and visualizes this binding on the panel—badges, summaries, one-click installation, all in one smooth flow.

Background

Let me start with some context.

HagiCode's preset task is a plugin-based mini-tool system. Users don't need to manually type commands; just fill in a few fields on the visual panel and click to create an automated task session. Each preset is essentially a directory that typically looks like this:

• manifest.json: preset identity information
• panel.json: visual panel form definition
• commands.json: list of commands to actually execute
• task-preset.json or prompts.json: task parameters and skill requirements

This system is indeed convenient to use, but we quickly ran into an awkward limitation.

In the early versions, skills could only be declared in the requirements array at the preset level. What does this mean? It means all commands within the same preset share the same skill requirements. It might not sound like a big deal, but in practice, you encounter scenarios like this:

A preset has five commands, where the first one wants to use the last30days skill, the third one wants to use ui-master, and the remaining three don't need any skills. This was impossible in the old design. If you wanted different commands to route to different skills, you had to forcibly split these commands into multiple presets, and configuration would bloat immediately.

This is exactly the problem that proposal extend-preset-task-multiple-skills-support aims to solve: let each command independently declare the skill it depends on, and visualize this binding in the UI.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI code assistant project, and the preset task system is precisely its quick action entry point for users. Every change discussed below was refined through actual pitfalls and optimizations—after all, "reading books is no substitute for practicing." The project source code is at HagiCode-org/site, interested readers can go give it a Star first.

Clarifying the Problem First: Why Not a Mapping Table?

Before diving in, the most intuitive solution is: create another commandSkillMappings mapping table to store the "command ID → skill" relationship separately. This sounds clean, separation of concerns and all that.

But on closer reflection, it doesn't hold up.

Each command in commands.json already has an ID, and this ID would need to be copied into the mapping table. Two files, same ID—as soon as someone changes a command and forgets to sync the mapping table, the data drifts apart. This "separation for separation's sake" design has maintenance costs far outweighing the little cleanliness it brings. In the end, it just adds trouble.

So we ultimately chose a more direct path: put an optional skill field directly on the command definition. A command declares which skill it binds to itself, maintained locally, and nothing gets disconnected.

Behind this decision, there's a more important design principle worth pulling out separately.

Core One: Two-Layer Data Responsibility Separation

This is the most critical insight in the entire refactor.

Many people's first reaction is: since commands now have skill, shouldn't we scan each command's skill field when doing requirement check (skill gatekeeper inspection)?

No.

We deliberately split this into two layers:

• skill field in commands.json: only responsible for declaring binding. It tells the system "this command binds to which skill," used for rendering prompt preambles and UI display.
• requirements array in task-preset.json: this is the authoritative enumeration. It's the real gatekeeper, determining which skills a preset needs to satisfy to run.

In other words, skill answers "which to bind, what to render," while requirements answers "whether it's actually allowed to run." These are two separate things, don't mix them together.

The benefit of this split is that the check logic is naturally simple. Because the gatekeeper is always based on preset-level requirements, deduplicated by CacheKey, multiple commands binding the same skill only get probed once, without repeated hits. Command-level skills don't introduce any additional probing overhead.

This principle is also the fundamental reason we rejected the mapping table approach—a mapping table would mislead people into thinking "binding equals gatekeeping," stirring the two layers of responsibilities back together. Outsmarting yourself, plain and simple.

Core Two: What Does a Command Definition Look Like?

The refactored command definition simply adds an optional skill field to the original structure. Taking the last30days bundled preset as an example, its commands.json roughly looks like this:

{
  "$schema": "../../schemas/commands.schema.json",
  "version": "1.1",
  "commands": [
    {
      "id": "research",
      "skill": "last30days",
      "prompt": "调研一下最近30天大家对 {topic} 的真实讨论"
    },
    {
      "id": "summarize",
      "prompt": "把上面的调研结果整理成一份摘要"
    }
  ]
}

Several points to note:

• version upgraded to 1.1, and the corresponding schema also added the optional skill field.
• The first command research binds to the last30days skill, and execution will route to this skill.
• The second command summarize doesn't bind to any skill, it's just a regular instruction taking the default path.
• Note here that no requirement is written in the command. The real gatekeeper is in the requirements of task-preset.json:

{
  "requirements": [
    {
      "key": "last30days",
      "cacheKey": "skill:last30days"
    }
  ]
}

The last30days bound by the research command must appear in this requirements, otherwise there's a problem—which is exactly the hard constraint discussed in the next section. You can't force things.

Core Three: Cross-Validation During Loading

Declaring bindings in data alone isn't enough; someone needs to provide a safety net to prevent "orphan bindings" where a command binds to a skill but it's never declared in requirements from making it to production.

This safety net is ValidateCommandSkills. It runs once during preset package loading, checking each command's skill one by one to see if it can find a corresponding entry in the preset-level requirements. If not found, it judges the package as illegal, directly disables the entire preset, and throws diagnostic code command-skill-not-in-requirements.

Why disable the entire package instead of just skipping that command? Because a preset is a whole, and commands often have dependencies (one command's output feeds into the next). If you silently skip one, the following commands get empty input, and behavior becomes completely unpredictable. After all, you can't read people's minds, and you can't read code's either. Better to let users see explicit errors than to let tasks mysteriously go off the rails halfway. This point can't be sloppy.

This validation is completed during the loading phase, meaning the problem is discovered the moment the preset is registered, not dragged out until the user actually clicks "run" to explode. For user experience, early errors are always better than late errors.

Core Four: Idempotent Splicing of Prompt Preambles

Next is the most subtle link in the execution chain.

When a command binds to a skill, such as last30days, the system needs to "splice" this skill information in front of the command before actual execution, forming a complete single-line instruction to pass to the executor. This process is handled by CombineCommandSkillPrelude.

Let me give a concrete example. The research command's prompt is "调研一下最近30天大家对 {topic} 的真实讨论", and the bound skill is last30days, so the final instruction passed to the executor roughly becomes:

/last30days 调研一下最近30天大家对 {topic} 的真实讨论

That is, the /last30days preamble is added before the prompt. When the executor sees this preamble, it knows to first switch context to the last30days skill.

There's a pitfall here: idempotency.

Why emphasize idempotency? Because in some scenarios, the prompt itself might already carry this skill preamble (for example, the user manually wrote half, or copied it from somewhere else). If the system foolishly splices it again, it becomes /last30days /last30days 调研..., and the executor either errors or behaves abnormally.

So CombineCommandSkillPrelude detects before splicing; if the prefix already exists, it doesn't add it again. This step seems insignificant, but it can block a class of very subtle bugs.

It's worth mentioning that this entire preamble injection logic is completed at the preset definition layer ( BuildCommandPrelude in PresetTaskCatalogProvider ), and the session creation code on the SessionsController side doesn't need to change at all. This is also the benefit brought by separation of concerns—the execution entry remains stable, and the complexity of skill routing is contained within the definition layer.

Core Five: How the Frontend Displays Bindings

With the backend straightening out the data model and execution chain, the final step is to let users "see" this binding in the interface. After all, if users can't perceive a feature, it's essentially not done.

The frontend did three things.

First, add badges to the command selector. In the command-picker, a small badge appears next to each command bound to a skill, indicating which skill it depends on. Users can tell at a glance which command is "skill-enabled" and which is a regular command.

Second, requirement-check summary block. The panel has a dedicated summary area listing all skill requirements the current preset needs to satisfy, and which skill each command binds to. The data for this block comes from the commandSkillsByRequirementKey mapping—grouping and aggregating commands by their bound requirement key, so users can easily compare whether "requirements" match "actual bindings". Trying to draw a tiger and ending up with a dog—something like that—so the aggregation logic needs to be straightforward, not flashy.

Third, one-click installation deep link on failure. If requirement check finds a skill isn't installed, users don't need to go dig through documentation to find the installation entry. The interface directly gives a deep link button; click to jump to the corresponding installation process. This step compresses the distance between "discovering a problem" and "solving a problem" to the shortest possible.

The frontend types are also restrained, the command type just adds a skill?: string, and normalization is done (|| undefined), avoiding empty strings and other boundary values causing trouble in subsequent judgment logic.

Practice: Five Steps to Complete the Refactor

Stringing together the scattered points from before, the entire refactor is actually just five steps:

1. Extend schema: commands.schema.json adds optional skill field, version number upgraded to 1.1.
2. Parse + validate: NormalizeCommands is responsible for parsing command definitions, ValidateCommandSkills does cross-validation, command skills must be findable in preset-level requirements.
3. Inject preamble: BuildCommandPrelude idempotently splices the /skill preamble before commands before execution, no need to modify SessionsController.
4. Migrate bundled preset: last30days and ui-master built-in presets' commands.json get modified, adding the skill field to corresponding commands. Migration only touches commands.json, doesn't touch other files.
5. Frontend visualization: types add field, command-picker adds badges, requirement-check adds summary block, deep link for one-click installation on failure.

A few points to note in practice, listed separately:

• One command can only bind to one skill. This is the current constraint. If a scenario really needs one command to trigger multiple skills, the escape hatch is to declare multiple skills in the preset-level requirements, letting them coexist at the preset level.
• Diagnostic code for validation failure is command-skill-not-in-requirements, search this code directly when troubleshooting.
• Frontend normalization remember || undefined, don't let empty strings sneak into judgment logic.
• When migrating, only touch commands.json, keep requirements unchanged to avoid introducing unexpected changes.
• Backend testing covers three scenarios: command skill in requirements (pass), not in requirements (disable package), multiple commands binding same skill (deduplication normal).

Summary

This multi-skill support refactor for preset task,表面上 just adds a skill field to commands, but it pulls out a design question worth pondering: should binding and gatekeeping be separated?

Our answer is separate. The skill field only manages "which to bind, what to render," while requirements manages "whether it's allowed to run." Once these two layers of responsibilities are mixed together, whether using a mapping table or some other form, subsequent validation, deduplication, and UI display become awkward. After separating, each layer becomes simple: the gatekeeper is always based on one authoritative enumeration, bindings are maintained locally and won't drift, preamble splicing is idempotent and controllable, and the UI just displays already clear data.

Looking back, the entire refactor didn't use any fancy technology, it just relied on cleanly cutting responsibilities and then having each layer provide the safety net it should. After this round of polishing, HagiCode's preset task system can finally route every command precisely to the skill it should go to. In the end, things should have been this simple all along...

References

• HagiCode-org/site: project source code, complete implementation of preset task system is here.
• HagiCode 官网: understand HagiCode's overall capabilities.
• OpenSpec proposal extend-preset-task-multiple-skills-support: original design document for this refactor, containing proposal, design, and tasks.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

• Author: newbe36524
• Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-23-hagicode-preset-task-multiple-skills-support%2F
• License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.