Writing a Good Skill

Without skills, a team ends up with everyone reinventing the wheel. Engineers' prompts are scattered everywhere, project managers (PMs)' requirement statements make the agent guess repeatedly, and executives' experience evaporates quietly with personnel turnover. At first glance, engineers, PMs, and executives care about different things. However, when it comes to using agent tools, they all face the same dilemma: experience cannot be accumulated, and quality depends on individuals.

Essence of skills — encapsulating tacit knowledge into code: To understand a skill, you need to understand that it solves a knowledge management problem, not just an AI tool problem.

There is a classic concept in management: tacit knowledge. An engineer knows how to communicate with the agent to obtain high-quality code review. This is tacit knowledge. The engineer can do it, but cannot clearly explain it, and it is difficult to directly teach it to others. In contrast, explicit knowledge is written in documents and can be read and spread.

The goal of knowledge management in an organization is to convert as much tacit knowledge as possible into explicit knowledge. The traditional approach is to write documents, create SOPs, and conduct training. However, these methods have a fatal flaw: documents will expire, SOPs will be bypassed, and the training effect will be difficult to quantify. More importantly, documents describe how people should do things, not how agents should do things. This distinction is critical in today's world where agents are heavily involved in workflows.

Skills are a more thorough solution. It is not a document describing best practices, but rather it directly encodes best practices into the execution path of the agent. When you write the standard framework for competitive product analysis as a skill, anyone in the team can open the agent and say, "Help me analyze this competitive product," and the agent will execute the task according to the verified framework, rather than improvising.

Compared with common prompts, skills have three core differences, as described in Table 1.

This difference means that skills are not just better prompts. They are also a form of institutionalized knowledge storage, which can turn individual wisdom into organizational capabilities.

Case study: How standardization happens

A product team has eight project managers, and competitive product analysis reports are frequently produced in their daily work. Before skills were introduced, the eight project managers had different report styles. Some were good at writing function comparisons, some focused on user experience, and some emphasized business models. The quality of the reports was highly inconsistent, and the executives had to adapt to a new framework each time they read the reports. A seasoned project manager in the team spent two days encapsulating their product analysis framework into a skill. This skill covered four dimensions: function matrix, user journey differences, pricing strategy, and market positioning. Each dimension had a standard analysis perspective and output format.

Three weeks after the skill was launched, the changes were very specific:

• The entire team began using a unified framework for product analysis reports, reducing the average time executives spent reading reports from 20 minutes to 8 minutes.
• The two new project managers were able to produce analysis reports of equivalent quality to those of the experienced project managers within the first week.
• The experience of project managers was no longer "an individual's affair" but became a fundamental capability of the team.

This is the path through which skills enable standardization: instead of relying on training and regulations to constrain people, the best practices are directly embedded into tools, so that each use naturally follows the optimal path.

Understanding a skill does not require reading the code first. It is more like a job description given to the agent: telling it when to start work and how to perform its duties. This section breaks down the three core components of a skill and demonstrates the three-layer architecture of progressive loading.

Three core components of a skill: A simple skill only needs three elements: name, description, and execution instructions.

• Name (skill identifier): A name is the unique ID of a skill, and is also the way it is referenced in the system and logs. The naming principle is simple: verb + noun, clearly expressing what the skill does. "Review-code", "analyze-competitor", and "generate-prd" are good names. "Helper", "assistant", and "tool1" are bad names. Vague names will become a maintenance nightmare in the skill library.
• Description (skill description): The description is the most critical and often underestimated part of a skill. When deciding whether to activate a skill, the agent relies solely on the description. A vague description is useless. If the description fails to trigger the skill in the right scenario, even the most sophisticated execution instructions are useless.
• Execution instructions: specific execution scripts. Instructions are what the agent actually executes after a skill is activated. They can be a structured step-by-step description, or they can include specific analysis frameworks, output format requirements, and ways to handle boundary conditions. The instructions are like a detailed operation manual for the agent. The more specific they are, the more stable the execution will be.

Take a code review skill as an example. The three elements of a complete skill are as follows:

yaml
name: review-code

description: |
  Activate the skill when a user submits a code review request or requests an evaluation of code quality.
  Applicable scenarios include pull request review, single-file code quality check, and quality baseline evaluation before refactoring.
  It is not applicable to code debugging or function development.

instructions: |
  ## Code review procedure
  
  ### 1. Evaluate the overall structure.
  - Whether the module division is clear
  - Whether the naming conventions are consistent
  - Whether the comment coverage meets the requirements
  
  ### 2. Check the following dimensions one by one:
  - **Readability**: Whether the code is easy to understand and whether complex logic is commented.
  - **Security**: Whether there are common vulnerabilities (such as SQL injection and XSS)
  - **Performance**: Whether there are obvious performance issues
  - **Test coverage**: Whether there are tests for key paths
  
  ### 3. Output format
  Output the review report in the following structure:
  - Overall score (1–10)
  - Items that must be modified (Blocker)
  - Items recommended for improvement (Suggestion)
  - Highlights

Three-layer architecture for progressive loading: A crucial engineering decision in skill design is that not all content needs to permanently reside in the context window of the agent. A team may have dozens or even hundreds of skills. If the content of every skill permanently resides in the context, it will cause severe context pollution and performance degradation. Skills adopt a three-layer architecture for progressive loading to address this issue.

• Layer 1: Metadata, which contains only the name and description, with a very small size, and is always within the agent's view. The agent relies on this layer to determine whether there are suitable skills available.
• Layer 2: SKILL.md body, which contains complete execution instructions. The context is read only after the skill is activated (that is, the description is successfully matched). This layer is the main body of the skill and contains all the instructions on how to do something.
• Layer 3: Bundled resources, which are auxiliary materials such as scripts, reference documents, and output templates. These resources are loaded only when needed during execution, preventing unnecessary context consumption.

The advantage of this architecture is that the increase in the number of skills will not linearly increase the context burden of the agent. For example, if a team has 50 skills, the agent's resident context contains only 50 lightweight description abstracts. Only the one or two skills activated for the current task consume the context.

Additional resource types and design principles: In addition to the three basic elements, the third layer of a skill can carry three types of resources, each with its own applicable scenarios.

• Automation scripts: They are suitable for processing fixed, mechanical operations that require no decision-making. For example, a skill for generating API documentation can be accompanied by a script that automatically extracts API information from code comments. The agent can directly invoke this script during execution, eliminating the need to manually describe the extraction logic each time.
• Reference documents: They are suitable for skills that require extensive background knowledge. For example, a compliance check skill can be accompanied by an abstract of the company's compliance manual, and a technical solution review skill can be accompanied by architecture design specifications. It is recommended that a table of contents be added to long reference documents to facilitate targeted retrieval by the agent, instead of scanning the entire document.
• Output templates: They are suitable for scenarios with strict requirements on the output format. For example, a weekly report generation skill can be accompanied by a fixed Markdown template, and a competitive product analysis skill can be accompanied by a standard table structure. Templates can significantly reduce the agent's "freedom" in formatting, making the outputs more consistent.