Skills: Reusable Task Methods

Describe the current task

Of course, Prompts and Skills are not mutually exclusive. Prompts tell the large model or Agent which material to process this time and what temporary requirements exist, while Skills provide the established methods for this type of task. The same Skill facing different inputs still needs Prompts to explain the current objective. Not every Prompt is worth turning into a Skill. For a one-time task where the objective is still changing, it's more appropriate to run it with a Prompt first. Only when similar tasks repeatedly appear and the processing method gradually stabilizes should it be consolidated into a Skill.

Difference Between Skills and Workflows

A Workflow is a set of operational arrangements for organizing multiple task nodes, typically specifying sequential order, conditional branches, data passing, and failure handling. It answers how multiple stages connect.

For example, a weekly report workflow could be:

Read raw data → Clean fields → Generate charts → Write analysis → Export weekly report

A Skill focuses on how a capability unit should be completed. Each of the above steps can be provided by a Skill, or completed by scripts, manual operations, or other tools. The difference between the two isn't about which is fixed and which is flexible, but about different focus objects:

• Workflows mainly organize task nodes, order, branches, and data passing;
• Skills mainly encapsulate the knowledge, rules, resources, and tool usage methods needed to complete a type of task.

A Skill can contain fixed steps as well as conditional judgments. A Workflow can also call an Agent at a certain node, letting the Agent decide the next step based on the actual situation. For example, a meeting minutes Skill can handle different processing based on input:

• When there's no meeting transcript in the input, stop generation and request supplementary materials;
• When the original text explicitly states a responsible person, directly write them into the action item;
• When the original text has no responsible person, mark it as pending confirmation;
• When multiple materials contradict each other, list the conflicts without deciding which is correct;
• When the user only requests action items, omit the complete meeting summary.

In real systems, Skills and Workflows are often used in combination: Workflows handle connecting multiple stages, while Skills ensure that a specific stage is completed following stable methods.

Difference Between Skills and MCP

MCP is the Model Context Protocol, used to provide external tools, resources, and prompt templates to Agents in a unified manner. It answers how Agents connect and call external capabilities. Through MCP, Agents can connect to databases, knowledge bases, project management systems, map services, or other business systems. But a successful connection only means the Agent can use a capability, not that it already knows how to complete a business task. Suppose an Agent can already read a project management system; it still needs to know:

• Which project to query;
• What time range to calculate;
• Which statuses count as completed;
• Which fields contain sensitive information;
• What format to use for the project report;
• Whether confirmation is needed before creating, modifying, or deleting records.

These task rules are better written into Skills. The relationship between the two can be summarized as: MCP provides a standard way to connect external tools and data, while Skills describe how to use these capabilities to complete a type of task.

A Skill can guide an Agent to call MCP tools, or not use MCP at all. An MCP service can also be used by multiple Skills. When sending messages, modifying records, deleting data, incurring costs, or publishing publicly, Skills should clearly specify confirmation points and cannot assume execution is allowed just because a tool is connected.

Basic Composition of a Skill

A complete Skill needs both content that describes the task method and files that carry this content. For the task itself, trigger conditions, input, execution steps, tools and resources, output, and exception handling should be clearly written. For file organization, at minimum an entry file SKILL.md is needed, and more complex Skills may include reference materials, templates, scripts, and test cases. Using a meeting minutes Skill as an example, a complete directory can be organized as follows:

meeting-notes/
├── SKILL.md                         # Entry: name, description, input, steps, and acceptance criteria
├── references/
│   ├── terms.md                     # Glossary and content classification rules
│   └── privacy-rules.md             # Sensitive information and masking requirements
├── assets/
│   └── meeting-template.md          # Minutes output template
├── scripts/
│   └── clean-transcript.py          # Clean timestamps and repeated verbal tics
└── tests/
    ├── normal-case.md                # Test case with complete information
    ├── boundary-case.md              # Cases with missing information or conflicts
    └── failure-case.md               # Cases that cannot continue processing

Among these, SKILL.md is the entry point for the entire directory. The Agent first learns from here what tasks the Skill is suitable for, what input is needed, and what steps to follow. Further, based on other constraints, additional tools or code can be supplemented. As in the directory organization above, when encountering professional terms or privacy requirements, you can read the references/ directory for related information; during result generation, you can apply templates from assets/; for mechanical operations like text cleaning that need to be completed stably, you can run programs from scripts/. tests/ is mainly for verification after development and revision, not content that needs to be loaded every time a task is executed.

When multiple Skills exist simultaneously, the large model typically first compares each Skill's name and description, then selects the smallest set most relevant to the current intent. For example, organizing a meeting transcript into minutes and exporting an action item table may require both the meeting minutes Skill and the table processing Skill; if only text organization is requested, there's no need to load the table capability.

Below we introduce from the perspectives of trigger conditions, input checking, execution steps, tools and resources, and output control:

Trigger conditions are what allow the Skill to help the large model find the current needed capability among many Skills, mainly reflected in the name and description at the beginning of SKILL.md. Using the meeting minutes Skill as an example, name is the Skill's identifier name, typically using lowercase letters, numbers, and hyphens, and should match the directory name. It should be brief and clear so that both humans and systems can distinguish this capability. For example:

name: meeting-notes

description explains what this Skill can do and when it should be used. After the large model reads the user's task, it will compare the task intent with the names and descriptions of installed Skills; only when a match is found will it continue loading the complete SKILL.md. The meeting minutes Skill's description can be written as:

description: Organize meeting transcripts, chat records, or scattered notes into structured meeting minutes. Use when the user requests generating meeting summaries, extracting conclusions, action items, or pending questions.

Don't stuff irrelevant keywords to increase trigger probability. If the description is too broad, the Agent will misuse it in unrelated tasks; if too narrow, it may not be found when actually needed.

Input checking refers to what the Agent or large model needs to know when starting to execute a Skill: what's needed, which materials are required, which are optional, and how to handle missing key information. After selecting a Skill, the next step isn't immediately generating results but checking whether materials are sufficient. Using the meeting minutes Skill as an example, the input section can be specified as follows:

• Required input: At least one of meeting transcripts, chat records, or meeting notes;
• Optional input: Meeting name, time, participant list, and minutes template;
• Input boundaries: File names and user summaries cannot substitute for the original meeting text;
• Missing handling: When there's no meeting transcript, stop generation and request the user to provide materials.

Only after the input check passes does the Agent formally begin processing the task. Execution steps should clearly describe the complete sequence from reading materials to delivering results: what each step processes, what intermediate results are obtained, and where to go when encountering different situations.

Execution steps explain what to do, while tools and resources explain what specifically is used to accomplish it. Tools are responsible for executing actions, such as reading files and running scripts; resources provide rules and templates, such as glossaries, privacy requirements, and minutes formats. Both need to specify concrete names and usage timing.

After completing processing, the Agent needs to know how to deliver. The output control stage requires not just generating meeting minutes but also explaining the structure, format, and completion standards.

Exception handling runs through input, execution, tool invocation, and output checking—it's not something added at the end. It determines whether the Agent continues, degrades, stops, or requests user confirmation when encountering problems.

How to Design a Skill

The previous sections have explained how Skills are discovered, how they execute, and what parts a complete capability needs to include. Now let's apply these concepts to the meeting minutes case.

The core of designing a Skill isn't first creating directories or writing a long Prompt, but organizing human work experience into methods that the Agent can execute and check. This process can be divided into six steps: selecting tasks suitable for encapsulation, defining objectives and boundaries, reviewing human methods, rewriting experience into rules, writing the first executable version, and then running through the shortest closed loop.

Using Skills in ModelScope

The previous sections completed the design of the meeting minutes Skill. Below we implement this capability in a ModelScope Notebook, using travel expense reimbursement and client reception office meetings as examples to organize meeting records into confirmed items, action items, and pending items.

Experiment Task and Environment Preparation

This experiment uses Qwen3-4B for reasoning. First, run the following code to check the current Python and dependency package versions.

Creating and Installing the Meeting Minutes Skill

The previous sections explained the composition of a Skill. Here we directly write the meeting minutes rules into files. This experiment only requires an entry file and an output specification.

Loading Skills and Reading Reference Files

After files are prepared, use ms-agent's SkillLoader to load the local directory, reading the name, description, version, and resource paths.

Deploying the Model and Configuring the Inference Interface

This experiment uses the ModelScope community's Qwen/Qwen3-4B, deployed as an OpenAI-compatible interface through ms-swift.

Calling Skills Through Office Conversations

Below we use an administrative meeting record for calling. The materials include two confirmed arrangements, specific tasks for two responsible persons, and one item still requiring confirmation.

Checking and Debugging the Calling Process

After calling is complete, check whether the entry and output specification were read, and whether failure reasons can be reported when reading fails.

Skill Testing and Versioning

After one call is completed, you also need to check the Skill's reliability with different materials. Below we prepare fixed cases to verify information extraction and exception handling, and save results alongside the Skill version.

Preparing Test Cases

Cases need to record both input and expected behavior simultaneously. Normal cases check information extraction, boundary cases check handling of uncertain information, failure cases check whether they can stop and explain reasons, and unrelated tasks check for false triggering.

Defining Check Conditions

After cases are prepared, write "correct completion" requirements into executable checks. Use check_output() to verify model return results.

Running Tests and Analyzing Results

run_suite() runs cases sequentially, creating a new conversation each time, saving results and tool records, then calling check_output() to generate a problem list.

Modifying Skills and Comparing Versions

Keep version 1.0.0, create candidate version 1.0.1 in a new directory, and add responsible person judgment rules. Load and test both versions separately for comparison.

Saving Versions and Rollback

Each version needs to save complete files and test records. This experiment records the file manifest and hashes in release-manifest.json, while also saving change descriptions, configurations, and reports.

All experimental data and code for this chapter can be found at:

https://modelscope.cn/gallery/liucong/0e182f07-3330-40cc-ba59-173b7cc609b7