Best Practices for Developing AI Skills: A Case Study of the Baibu Detail Assistant

Background

Since Anthropic introduced the Skill concept, the team has built over 50 Skills covering various scenarios. Existing documentation describes the SKILL.md format but provides little guidance on iterative development.

Industry Best Practices

Progressive Disclosure

Skills are loaded in three layers: L1 metadata (name, description), L2 SKILL.md body (main commands), and L3 auxiliary resources (references, scripts). Only the required layer is loaded to stay within token limits.

Control Tuning

Match instruction freedom to task fragility, as Anthropic calls "matching instruction freedom to task fragility". Keep prompts concise and let the model focus on essential actions.

MiniMax Skills

MiniMax provides an open‑source repository with standardized Skill templates, a one‑PR‑one‑purpose policy, and industrial‑grade tooling for scalable Skill production.

Skill Design Patterns

Six workflow structures were identified, including decision‑tree, linear, and loop‑iteration patterns. Selecting the appropriate pattern (e.g., decision‑tree for diverse inputs with mutually exclusive logic) is the first step in designing a Skill.

Architecture Design

A bridge script ( xiaomi.py) decouples the local Skill from the remote Agent. The local part handles data collection, product queries, and result rendering, while the remote Agent performs heavy analysis such as log search and embedding extraction. This separation allows frequent remote updates without redeploying the local Skill.

Each session generates a random sessionId (e.g., session-8a2b3c4d) that is reused for subsequent calls, enabling the Agent to retain context across interactions.

Development Efficiency

Use the strongest LLM to author Skills directly, reducing iteration cycles.

Adopt small, single‑purpose commits in the skills/ directory; minimal diffs let AI reviewers pinpoint regressions.

Apply a monorepo approach to keep local and remote code visible to the same Coding Agent, preventing context pollution.

Runtime Optimization

Output raw tool results ("original‑text‑out") without summarisation to preserve information and avoid token waste.

Prefer HTML reports for dense information; the Skill returns a file path (e.g., file:///tmp/bybt_search_xxx.html) that the user can open in a browser.

Proactively ask clarification questions when required inputs are missing, and widen search scopes only when the user opts in.

Conclusion

The quality ceiling of a Skill is determined by context engineering rather than markdown craftsmanship. Empowering the Agent to write and modify its own Skills creates a meta‑capability that transforms developers into reviewers and context providers, enabling faster, more reliable AI‑driven workflows.