Agent Skill Authoring Standards and Practical Extraction Guide

1. Understanding Agent Skills: Reusable Capability Units, Not Prompts

When developers first work with Agent Skills, they often ask: How do I write an Agent Skill? What mistakes are common? How can I extract truly useful skills from daily work? What should I pay attention to when using them?

To answer these questions, one misconception needs to be corrected first: a Skill is not a temporary prompt, nor is it merely a character setting.

A prompt usually serves a single task, such as “Please help me write product copy.” An Agent Skill is more like a standardized capability unit. It describes when to trigger, which steps to execute, which tools to call, how to handle exceptions, and how to validate the output. Because of this, a Skill can be reused across different tasks and shared within a team.

From an engineering perspective, an Agent Skill usually involves three types of information:

1. Trigger information: When should this Skill be used?
2. Execution information: Once triggered, what workflow should be followed to complete the goal?
3. Constraint information: What is allowed, what is not allowed, and how should the system fall back when something fails?

Therefore, the first step in writing a Skill is not to rush into writing a prompt. Instead, clarify the following questions:

• What high-frequency task does it solve?
• What kinds of inputs are suitable for it?
• In which scenarios should it not be triggered?

Only after these boundaries are clear can a Skill be reused reliably.

Different platforms or tools may have different requirements for Skill file structure, field names, and loading mechanisms. For example, some platforms use YAML metadata plus Markdown instructions, while others may require additional fields or separate configuration files. When implementing a Skill, follow the official specification of the target platform. At the same time, keep the structure clear, the semantics explicit, and permissions minimized.

2. Basic Structure and Authoring Standards for Agent Skills

A well-formed Agent Skill usually consists of two parts: metadata and instruction body.

• Metadata is used for discovery and matching.
• The instruction body is used for execution and constraint.

1. Minimum Field Table

The following fields are commonly recommended when authoring an Agent Skill:

Field	Required?	Format and Length Recommendation	Example	Validation Method
name	Required	Lowercase letters, numbers, and hyphens; recommended 3–64 characters	cover-design-helper	Check for uppercase letters, spaces, Chinese characters, or special symbols
description	Required	Recommended 50–300 characters; explain “what it does” and “when to use it”	Use when the user needs to design social media cover images, choose color schemes, format titles, or get image size recommendations	Check whether it covers at least three typical trigger scenarios
instructions	Required	Structured body; should include steps, boundaries, and exception handling	See examples below	Check whether execution steps, failure handling, or permission notes are missing
version	Recommended	Semantic version, such as 1.0.0	1.2.0	Check whether it matches the change record
tools	As needed	Declare tools or capabilities that need to be called	image_generate, file_read	Check whether they are minimally necessary and whether there are permission risks
permissions	Recommended	Declare permissions such as file writing, command execution, or external access	read_project_files, no_network	Check whether they exceed what the task requires
failure_policy	Recommended	Explain how to notify or degrade when failure occurs	Return a fallback option when a tool call fails	Check whether there is an executable fallback path

For a simple Skill, the minimum required fields should be name, description, and instructions. For production environments, team collaboration, or Skills that call tools, it is recommended to add fields such as version, permissions, and failure_policy to improve maintainability and safety.

2. Basic Example

---
name: cover-design-helper
description: Used to generate social media cover images. Use when the user needs to design a cover, format a title, choose a color scheme, determine image dimensions, or obtain visual design suggestions.
version: 1.0.0
---
# Capability Description
This Skill is designed for social media cover image design. It converts textual content into an executable visual plan.
# Execution Steps
1. Clarify the cover purpose, target platform, and size ratio.
2. Extract the main title and subtitle, and control word count and information hierarchy.
3. Provide suggestions for color scheme, typography, and composition.
4. Output a deliverable design specification or generation prompt.
# Boundary Description
- Do not generate specific copyrighted material.
- Do not directly download unauthorized images from the internet.
- If the user does not provide platform information, ask for the platform or provide common size options.
# Exception Handling
- If necessary information is missing, list the missing items first.
- If the user requests infringing, counterfeit, or misleading cover designs, refuse and explain why.

3. More Complex Example: Tool Calls, Failure Handling, Permission Declaration, and Versioning

When a Skill involves real tool calls, it must clearly define tool scope, inputs and outputs, failure fallback, and permission boundaries.

---
name: report-summary-generator
description: Used to organize project weekly reports, meeting minutes, or code commit records into structured summaries. Use when the user needs to summarize work progress, extract risks, generate a draft weekly report, or organize meeting action items.
version: 1.4.0
tools:
  - read_local_file
  - summarize_text
permissions:
  - read_project_docs
  - no_external_network
  - no_command_execution
failure_policy:
  - If file reading fails, ask the user to check the path or upload the file.
  - If the content is too long, summarize it in sections and then combine the results.
  - If the risk level cannot be determined, mark it as “pending confirmation” and do not guess.
---
# Execution Steps
1. Confirm the input source: weekly report, meeting minutes, commit records, or user-pasted text.
2. Read and clean the content. Remove duplicates, advertisements, and irrelevant noise.
3. Output the summary in four sections: progress, risks, action items, and conclusion.
4. Provide evidence for each risk. If it cannot be determined, mark it as “pending confirmation.”
5. Output a summary of no more than 800 words and include three actionable recommendations.
# Safety Boundaries
- Only read project documents explicitly authorized by the user.
- Do not execute shell commands.
- Do not access external networks.
- Do not output sensitive keys, tokens, personal privacy, or internal credentials.
# Failure Handling
- File not found: Ask the user to provide a path or upload the file.
- Empty text: Explain that no valid content was detected and request additional information.
- Tool call failure: Stop subsequent dependent operations, provide the failure reason, and give suggestions.

This example shows that a complex Skill is not just a list of steps. It must also clarify tool calls, permission scope, failure policy, and version information. This helps reduce the risk of incorrect execution and unauthorized operations.

3. Common Mistakes When Authoring Agent Skills

In practice, a poorly written Skill is usually not caused by poor writing ability, but by a lack of engineering checks. The following are common high-frequency mistakes:

1. Using uppercase letters, spaces, or Chinese characters in name
   Wrong examples: Cover Design Helper, 封面设计助手.
   Recommended format: cover-design-helper.
   Reason: Irregular naming can affect search, reference, and automated matching.

2. Writing only the function in description, without trigger scenarios
   Wrong example: Generate cover image.
   Improved example: Use when the user needs to generate social media covers, design title layouts, choose color schemes, or determine image sizes.
   Reason: The description determines whether the Skill is triggered at an appropriate time.

3. Making description too broad, causing accidental triggering
   For example, “Used to process text.” This description may match translation, summarization, writing, code comments, and many other tasks.
   It should be more specific, such as “Used to organize project weekly reports into structured summaries.”

4. Writing instructions in a conversational way, without clear steps
   For example, “Analyze carefully and then provide the result.” This kind of wording cannot effectively constrain an Agent.
   It should be changed into clear steps: confirm inputs, split the task, check item by item, output the result, and mark uncertainty.

5. Missing exception handling
   If a Skill depends on files, tools, or external data but has no failure fallback, it may produce unpredictable results in abnormal scenarios.

6. Missing permission boundaries
   Especially when file writing, command execution, network access, or database reading is involved, minimal permissions must be declared.

7. Overgeneralization
   If one Skill tries to handle copywriting, translation, summarization, data analysis, and code generation at the same time, its responsibilities become unclear. It is better to focus one Skill on one core task.

8. Describing only the ideal flow, without exceptions
   Real tasks often involve missing parameters, conflicts, timeouts, or format errors. A Skill should clearly state what to do when exceptions occur.

9. No version information
   After a Skill is updated, changes cannot be tracked and rollback becomes difficult. It is recommended to update the version number whenever the Skill is modified.

10. No acceptance criteria
    Whether a Skill is usable should not rely only on subjective judgment. It should have clear pass conditions.

4. Extracting Agent Skills from Real Workflows

Instead of creating a Skill from scratch, a more reliable method is to extract a Skill from real tasks. The core idea is: first let the Agent complete real tasks, then converge the standard during collaboration, and finally solidify the effective workflow into a Skill.

1. Three-Step Extraction Method

Step 1: Start with Real Tasks

Choose a real task that you repeat frequently, for example:

• Organizing project weekly reports every week;
• Converting meeting notes into action items;
• Generating social media summaries for articles;
• Converting requirement documents into test cases;
• Summarizing risks from code commit records.

Do not start with “I want to build an all-purpose Skill.” Start with a specific, repeated, and verifiable task.

Step 2: Converge the Effect Through Collaboration

Assign the task to the Agent and refine the output through multiple rounds of feedback:

• Add input background;
• Specify output format;
• Clarify what should not be included;
• Point out missing items;
• Ask for the basis of judgments;
• Correct errors.

The value of this process is that it gradually makes tacit experience explicit. For example, you may initially only know that “the weekly report should be concise.” After several rounds of feedback, you may find that it actually needs fields such as “progress, risks, action items, owner, and deadline.”

Step 3: Let the Agent Summarize the Methodology

When the output becomes stable, ask the Agent to review the process:

• Which steps are necessary?
• Which judgment criteria appear repeatedly?
• Which mistakes should be avoided?
• Which inputs need to be confirmed in advance?
• Which permissions and boundaries need to be declared?

Then ask the Agent to produce a Skill draft. After that, a human should review, reduce, and supplement the boundaries.

2. Acceptance Criteria

An extracted Skill should not merely “look good.” It should meet the following acceptance conditions:

Acceptance Item	Pass Criteria
Trigger accuracy	It can be correctly triggered in at least three typical scenarios and should not be triggered in irrelevant scenarios
Input compatibility	It can handle common input formats and can ask follow-up questions when input is missing
Output stability	Running the same input multiple times produces a consistent output structure, and key fields are not missing
Boundary clarity	It clearly states which tasks will not be done, which data will not be read, and which tools will not be called
Failure fallback	When tools fail, content is missing, or information is insufficient, there is a clear handling strategy
Permission compliance	Only necessary permissions are requested; file writing, command execution, and network access are not enabled by default
Maintainability	It has a version number, change description, and human review records

3. Failure Fallback Strategies

If a Skill has problems after deployment, handle it in the following ways:

• Trigger failure: Add trigger words and scenarios to the description, and avoid being too abstract.
• Accidental triggering: Narrow the scope of the description and add exclusion instructions such as “Not applicable to …”.
• Unstable output: Add a fixed output template, field order, and length limits to the instructions.
• Tool call failure: Add a failure_policy, such as degrading to text-based suggestions or asking the user to provide data manually.
• Unauthorized operation risk: Immediately tighten permissions, disable unnecessary tools, and require human confirmation.
• Unverifiable results: Add an acceptance checklist or ask the Agent to output the basis for its judgments.

4. Reproducible Example

Suppose you want to extract a “weekly report generation Skill.”

In the first round, you give the Agent a messy meeting record and ask it to summarize it into a weekly report. The result only contains progress, with no risks.

In the second round, you add: “Please output four sections: progress, risks, action items, and deadlines. Mark missing information as pending confirmation.”

In the third round, you notice that it writes subjective guesses as conclusions. You then require: “Do not guess. Any uncertain content must be marked as lacking sufficient evidence.”

After the output becomes stable in the fourth round, you ask the Agent to summarize the rules. The draft is as follows:

• Inputs: meeting records, code commits, task lists.
• Outputs: four-section weekly report.
• Prohibited: guessing information that was not provided.
• Permissions: only read specified documents.
• Exceptions: request additional input when the input is empty.

At this point, a practically usable Skill has been formed.

5. Assisting with Skill Generation, Discovery, and Safe Use

1. How to Search and Match Existing Skills

When faced with many existing Skills, do not collect them blindly. It is recommended to search based on your requirement description:

“I need a Skill that can convert meeting notes into action items. What should I look for?”

Then focus on three points:

1. Whether the description covers your real scenarios;
2. Whether the instructions contain clear steps and boundaries;
3. Whether the permissions exceed the necessary scope.

When matching Skills, avoid accidental triggering. If a Skill’s description is too broad, such as “Process any text task,” it may match your current requirement but also cause incorrect calls in other scenarios. A safer approach is to prioritize Skills with specific descriptions, clear boundaries, and explicit permission declarations.

2. How to Use Assisted Skill Generation

For beginners, assisted generation features can quickly create a skeleton. However, generated results must be manually verified:

• Is the name properly formatted?
• Does the description include trigger scenarios?
• Do the instructions contain execution steps?
• Is exception handling included?
• Are unnecessary permissions requested?
• Does it conform to the field requirements of the target platform?

Treat generated output as a draft, not a final product. Developers still need to supplement business boundaries, permission limits, and acceptance criteria.

3. Security and Permission Considerations

Once an Agent Skill involves real execution, security risks must be considered. Before writing or enabling a Skill, review the following:

• Tool calls: Are unnecessary tools called? Will they produce external side effects?
• File writing: Will existing files be overwritten? Is the directory scope limited?
• Command execution: Are shell commands, scripts, or system commands allowed?
• External access: Will it access public networks, third-party APIs, or unauthorized data sources?
• Sensitive data: Will it read keys, tokens, personal information, or internal documents?
• Human confirmation: Do high-risk operations require user confirmation?
• Least privilege: Grant only the permissions necessary to complete the task.

It is recommended to disable high-privilege capabilities by default, such as file writing, command execution, and network access. Enable them item by item only when the task clearly requires them.

4. Iteration and Version Management

A Skill is not a one-time deliverable. It is recommended to establish a version mechanism:

• Use semantic versioning, such as 1.0.0, 1.1.0, or 2.0.0;
• Record the reason for each modification;
• Keep historical versions for rollback;
• Archive failure cases;
• Periodically revise the description and instructions based on actual usage.

A Skill with a maintenance record is more reliable than one that looks complete but has never been validated.

6. Best-Practice Checklist

Use the following checklist before publishing:

• [ ] Is the name properly formatted?

  Pass criteria: only lowercase letters, numbers, and hyphens; no spaces, Chinese characters, or special symbols.

• [ ] Does the description explain what it does?

  Pass criteria: the core capability can be described in one sentence.

• [ ] Does the description explain when to use it?

  Pass criteria: it covers at least three typical trigger scenarios.

• [ ] Does the description avoid being too broad?

  Pass criteria: it does not easily match unrelated tasks.

• [ ] Are the instructions clearly divided into steps?

  Pass criteria: a reader or Agent can execute them step by step without guessing context.

• [ ] Does it include boundary descriptions?

  Pass criteria: it clearly states which tasks will not be done, which inputs will not be processed, and which risks will be rejected.

• [ ] Does it include exception handling?

  Pass criteria: there are clear fallback strategies for missing input, tool failure, overly long content, and other abnormal situations.

• [ ] Does it declare permissions?

  Pass criteria: only necessary permissions are requested, and high-risk capabilities are not enabled by default.

• [ ] Does it set a version number?

  Pass criteria: each release or modification has a version identifier and change description.

• [ ] Has it been validated with real tasks?

  Pass criteria: it has run stably in at least three real or simulated cases.

7. FAQ

Q1: What is an Agent Skill?

An Agent Skill is a capability unit that encapsulates a repeatable type of task. It usually includes trigger conditions, execution steps, tool calls, permission boundaries, and exception handling. It can be reused by an Agent in appropriate scenarios.

Q2: How do I write an Agent Skill?

Start with the minimum fields: name, description, and instructions. Then add boundaries, exception handling, permission declarations, and a version number. For complex tasks, consider adding tool calls, failure strategies, and acceptance criteria.

Q3: How do I extract a high-quality Skill?

Start with real tasks, let the Agent converge its output through multiple rounds of collaboration, and then ask the Agent to summarize the methodology. Finally, a human should review, simplify, and supplement the boundaries to form a reusable draft.

Q4: What are common mistakes?

Common mistakes include irregular naming, missing trigger scenarios in the description, conversational instructions, missing exception handling, excessive permissions, overly broad descriptions, and lack of version management.

Q5: How do I determine whether a Skill is usable?

Check whether it can be triggered stably in typical scenarios, whether it can handle abnormal inputs, whether its output is stable, whether it respects permission boundaries, and whether it has clear acceptance criteria.

Q6: Should I write my own Skill or use an existing one?

First search for an existing Skill. If its description, boundaries, and permissions meet your requirements, use it. If no suitable option exists, extract a custom Skill from real tasks.

Conclusion

The value of an Agent Skill is not making a prompt longer, but turning real experience into a standardized, reusable, and maintainable capability unit.

Mastering Agent Skills is not just about memorizing field formats. It requires an engineering approach: clarify trigger conditions, write clear execution steps, declare permission boundaries, set failure fallback strategies, and continuously validate through real tasks.

When you can reliably solidify a recurring collaboration workflow into a Skill, and continue to maintain, iterate, and audit it, you move from “using tools” to “managing capabilities.”