# Best Practices for SKILL Encapsulation

To achieve a better user experience, this document provides recommendations from two aspects: product design and SKILL encapsulation.

# I. Product Design

The following uses a coffee ordering SKILL as a reference case to outline the core design points under this pattern:

  • Dialogue captures the user's vague intent: When users express unstructured needs such as "I'd like something refreshing" or "What do you recommend lately," the AI handles understanding and recommendation, then guides them to atomic components for confirmation and ordering;
  • Content can be modified via natural language: Users can directly modify specifications, time, location, and other enumerated values or explicitly defined entity fields without leaving the conversation;
  • Historical data and personal assets are queryable and actionable: The core demand in high-frequency consumption scenarios is efficiency. Commands like "Order the same one I had last time" or "Redeem a coupon with points" can be executed, significantly improving usage efficiency;
  • Service processes update dynamically in real time: Order or service atomic components should update dynamically as status progresses, rather than displaying statically, to prevent users from missing critical updates.

# II. SKILL Encapsulation

# 1. Information Sources and Division of Responsibilities

When the Mini-Program AI decides which atomic interface to call, what parameters to generate, and what content to reply with, it synthesizes multiple contextual information sources to make judgments. These information sources differ in weight and responsibility; placing content in the wrong location will significantly reduce accuracy.

# 1.1 Attention Weight

Information Source Attention Description
Content returned by atomic interface ★★★★★ Closest to the current decision point; the model reads it as "facts + actions." Incorrect phrasing here will cause the model to deviate from the conventions in SKILL.md
description in atomic interface declaration (mcp.json) ★★★★ Affects whether the model "selects this interface"; vague descriptions make it easy for the model to choose incorrectly
inputSchema.description in atomic interface declaration (mcp.json) ★★★★ Affects "how the model fills in parameters"; this is the core location for field-level constraints, more effective than writing lengthy text in SKILL.md
SKILL.md ★★★ Suitable for business process orchestration, cross-interface rules, intent routing, and general specifications

# 1.2 Content Division of Responsibilities

Information Source What to Write
Content returned by atomic interface The result of this call and the next action
description in atomic interface declaration The interface's own functionality, when to call it, and inapplicable scenarios
inputSchema.description in atomic interface declaration Parameter semantics, value sources, and default handling
SKILL.md Business process orchestration, cross-interface rules, intent routing, and general specifications

# 1.3 Common Misplacements

  • Writing "the interface's own functionality" in SKILL.md: Long text expands and easily becomes inconsistent with mcp.json. The interface list in SKILL.md should only contain "preconditions + upstream/downstream relationships";
  • Writing "business rules spanning multiple interfaces" in a single interface's description: This only takes effect when that interface is called; the model cannot read it when making decisions about other interfaces. It should be written in SKILL.md;
  • Writing "interface functionality descriptions" in content: Content only carries the result of this call and the next action; functionality descriptions belong in description.

# 2. General Writing Principles

The following principles apply to all the above information sources:

  • Write the same constraint in only one place: Duplicate writing easily causes conflicts due to inconsistent wording;
  • Place hard constraints in higher-weight locations: Constraints that can be strongly validated at the code level based on rules should prioritize code validation;
  • Provide an executable exit: Writing only "don't do X" without writing "what should be done" leaves the model without an exit. Every prohibition should be paired with a clear alternative action.

The platform's rule requirements for SKILL are as follows:

  • Must not contain jailbreak content: Do not write statements such as "ignore instructions" or "you are now" that attempt to override AI behavior;
  • Must not write incorrect interface names: Interfaces required to be called in SKILL must not be inconsistent with registered method names, including case sensitivity;
  • Must not hard-code reply formats: Must not require user-facing replies to use tables, only JSON, or apply fixed templates; must not simultaneously limit the number of reply sentences and the only content allowed to be retained;
  • Must not hinder answer presentation: Must not prohibit user-facing replies from using Markdown, must not require omitting key information users need such as names, times, prices, and addresses, and must not require step-by-step listing of internal call flows.

# 3. Atomic Interface Declaration (mcp.json)

# 3.1 Interface description

  • Use semantic names for interface names: Recommend using "verb + noun" in lowerCamelCase, e.g., searchDrinks is better than search for clearer semantics;
  • The first sentence should declare the "business object," not the "input parameters":
    • Counter-example: "Search product list by keyword, temperature, cup size (beverages only)..." — The first sentence emphasizes input parameters, and "product" is too broad semantically; the model may mistakenly match other product categories;
    • Recommended: "Search beverages. Retrieve by keyword, temperature, cup size..." — The first sentence first identifies the business object, then describes input parameter dimensions;
  • Do not write internal implementation details: Implementation details do not help the model select interfaces and crowd out the truly important "usage boundary" information;
  • Single responsibility, non-overlapping descriptions: Avoid containment relationships between interfaces; descriptions should target the model rather than users, and concise wording suffices;
  • Unified naming for fields with the same name: Fields with the same meaning should be consistent across different interfaces, e.g., always use drinkId for beverage ID, not mixing in itemId.

# 3.2 Field description

Input parameter field selection: Prefer passing IDs over natural language. For example, pass storeId for stores rather than province/city/street, and pass drinkId for beverages rather than beverage names or categories. This way the model does not need to repeatedly extract and match from natural language, resulting in fewer parameter ambiguities and faster, more stable reasoning.

description writing: The following provides examples for two typical field types.

Regular fields: When giving examples, provide multiple different samples (to avoid being treated as default values), and pair with clear default handling. A single example is easily treated by the model as the "standard answer" — when the user only says "I'd like something to drink," the model may directly copy that example.

// Counter-example: only one example, and no default handling specified
"keyword": { "description": "Beverage keyword, e.g., 'latte'" }

// Recommended: diverse examples + default handling
"keyword": {
  "description": "Beverage keyword, e.g., 'latte', 'americano', 'milk tea'. When the user has not specified a particular beverage, do not fill in this field; instead, route to the beverage recommendation interface."
}

ID-type fields: Declare the value source interface. Business IDs are easily fabricated by format; the source must be explicitly declared in the description.

// Counter-example
"drinkId": { "description": "Beverage ID" }

// Recommended
"drinkId": {
  "description": "Unique beverage identifier, taken from the original drinkId value returned by the upstream interface searchDrinks or getRecommendedDrinks. Do not infer from the user's natural language (e.g., 'that latte'), and do not use example values. When no available drinkId exists in context, call searchDrinks first."
}

# 4. Content Returned by Atomic Interface

Content directly targets the Mini-Program AI, carrying the result of this call and constraining the next action.

# 4.1 General Rules

Input validation: Parameters generated by the Mini-Program AI are not guaranteed to be correct; atomic interfaces need to validate types and validity (e.g., whether drinkId exists).

Return content: Both structuredContent and content are provided to the Mini-Program AI — the former carries structured data (card display content), the latter carries result descriptions and decision constraints; the two should avoid duplication. Content needed for rendering but not for the Mini-Program AI to understand (such as image URLs and backend redundant fields) is passed through _meta.

Error handling: Return clear error reasons and next-step guidance:

  • Missing information: "Missing delivery address; user needs to provide it";
  • No results: "No related beverages found; try different keywords."

# 4.2 Fact + Action Two-Part Structure

Content should first state the objective status of this return, then give the next action. When there is only action without facts, the model may misinterpret "display card" as "prepare to call the next interface" and skip waiting for user confirmation.

// Counter-example: action only, missing facts
"Next, be sure to display the order confirmation card to the user."

// Recommended: facts + action
"An order has been generated based on the selected specifications. Please display the order confirmation card and guide the user in one sentence to review and place the order."

# 4.3 Failure / Empty Results

The content for failure or empty result branches should include three things:

  1. State specific facts: Write the cause of the problem clearly, e.g., no beverage named "Christmas Limited Edition" was matched in the beverage library;
  2. Provide a next-step exit: What should be done next;
  3. Indicate actions that should not be taken: E.g., prohibit repeated attempts to call this atomic interface. This item must appear paired with item 2; do not write only a prohibition without providing an exit.

Example:

No match found for "Christmas Limited Edition"; fallback data for "Store's Best-Selling Beverages" has been attached.
Please first tell the user "No 'Christmas Limited Edition' was found," and guide the user to choose from the following store best-selling beverages.
Do not call this interface again with the same keyword.

# 5. SKILL.md

mcp.json describes "how a single interface is used"; SKILL.md describes "how the entire business runs": business processes, interface dependencies, and cross-interface constraints.

# 5.1 Business Process

Clarify the "user intent → atomic interface → user action → atomic interface" flow to help the model understand the overall orchestration. Writing points:

  • Use interface names for nodes; interface names must be completely consistent with the atomic interfaces in mcp.json (including case);
  • Branch from user intent entry points; each branch corresponds to a typical expression type (vague / specific keywords / specific scenario);
  • Mark user action nodes (e.g., "user selects a certain item," "user confirms") to distinguish who triggers the next step;
  • Mark fallback branches, e.g., scenarios like "when X is absent, go through the fallback interface first, then return to the main flow after completion."

# 5.2 Interface Dependencies

The business process describes the overall direction, while the dependency table lists trigger preconditions by interface dimension, helping the model quickly determine whether current conditions are met before calling.

# 5.3 Business Constraints

Strong constraints that take effect across multiple interfaces are written in SKILL.md. Common types:

  • Output format: When cards must be displayed, and when plain text is allowed;
  • Execution order: Action-type interfaces must confirm successful execution; before being called, do not claim to the user that "it has been completed for you";
  • Concurrency vs. serialization: E.g., order payment atomic interfaces should not be concurrent; the next request must wait until the previous one ends (success, failure, or cancellation);
  • Data sources: Business IDs should be taken from real returns of upstream interfaces; do not infer from user language or fabricate.

When users perform operations on atomic cards and half-screen pages, a message is sometimes automatically sent uplink to the conversation area. This message is directly displayed to end users and is essentially a conversation content sent by the system on behalf of the user; issues such as unnatural expression and a strong system feel should be avoided.

# 6.1 Basic Principles

  • From the user's perspective: Copy should be expressed in the user's tone, avoiding the feeling that "the system is speaking for me";
  • Accurate operational semantics: Copy should accurately reflect the actual operation the user just completed; do not expand, reduce, or distort user intent;
  • Natural conversation continuity: After entering the conversation flow, the copy should be naturally carried forward by subsequent services, without causing semantic abruptness or process fragmentation;
  • Concise and clear dialogue: Avoid system broadcast feel, technical description feel, and field concatenation feel; control the amount of information to reduce interference with conversation reading experience.

# 6.2 Specific Writing Principles

Principle Description
From the user's perspective Messages should be expressed from the user's perspective; first person may be used; other persons are generally not recommended
No uplink of system messages Even abnormal system messages caused by user operations must not be sent uplink; they need to be converted into user operations
Natural language expression Express in natural language; abandon technical description formats such as field listings and encoding
Use everyday language On the basis of accurate meaning, prioritize everyday colloquial language and avoid overly professional terminology
Limited to information the user has explicitly expressed Information is limited to what can be derived from the user's current operation; do not arbitrarily add preferences or demands the user has not stated
Describe the current operation Focus on the current operation; do not describe other steps or predict future operations in advance
Sufficient but not overloaded information Retain only essential information that can advance the current conversation or help the model understand; secondary information may be omitted
Concise but unambiguous While streamlining copy length, ensure clear meaning; in multi-choice scenarios, avoid vague referential words like "this one" or "that one"
Handle sensitive information Privacy information such as ID numbers and phone numbers must not be displayed in plain text; desensitize or use vague expressions when necessary
Other general copy specifications No typos, no grammatical errors, correct sentence segmentation, correct use of spaces and punctuation, etc.
© FinClip with ❤ , Since 2017