The basic structure of a Skill folder:

skill-name/
├── SKILL.md           # Required file: Must include metadata + instructions
├── scripts/           # Optional file: Executable code scripts, e.g., Python, Bash, and JavaScript
├── references/        # Optional file: Documents, e.g., detailed technical references, detailed rule documents
├── assets/            # Optional file: Templates, resources, e.g., document templates, configuration templates, diagrams, examples
└── ...                # Other folders/files can be added

SKILL.md Format Specification

The SKILL.md file must strictly follow the structure of YAML Frontmatter (metadata) + Markdown Body (content).

Metadata

Field	Required	Description and Specification
name	Required	Unique identifier for the skill, must match the Skill folder name!. Usually uses lowercase letters and hyphens (e.g., `pdf-form-filler`). Maximum 64 characters. Only lowercase letters, numbers, and hyphens. Must not start or end with a hyphen.
description	Required	The core of the core. Use 1-2 sentences to describe the skill's function, applicable scenarios, and trigger conditions. AI determines whether to load the skill based solely on this. Maximum 1024 characters. Non-empty.
version	Optional	Version number (e.g., `1.0.0`), used for managing iterations.
author	Optional	Author or team name.
allowed-tools	Optional	Defines the list of tools the skill can automatically use (e.g., `Bash`, `Read`), without needing user confirmation each time.
license	Optional	License name or reference to bundled license file. (Open-source license, commercial license, etc.)
metadata	Optional	Arbitrary key-value mapping for additional metadata.
compatibility	Optional	Maximum 500 characters. Describes what environmental conditions this Skill requires. e.g., docker xx version, python 3.11+

Brief example:

SKILL.md

---
name: skill-name
description: A description of what this skill does and when to use it.
---

---
name: meeting-auditor
description: Used to analyze business meeting recording transcripts, extract key decisions, and audit budget risks according to compliance manuals. Triggered when the user asks to "check meeting minutes compliance" or "summarize and audit the meeting."
version: 1.0.0
---

Example with optional fields:

SKILL.md

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
compatibility: Requires Python 3.14+ and uv
metadata:
  author: example-org
  version: "1.0"
---

Body Instructions

In the Markdown body, you need to construct the AI's "chain of thought" and "action guide" from the following aspects:

1. Role Definition

Clearly tell the AI what its identity is now.

Description Aspect: Give the AI a specific expert persona.
Example: "You are a rigorous financial auditor" or "You are a senior Python code review expert."

2. Core Instructions & Steps

This is the main body of the document, must use imperative sentences (command tone), clearly and step-by-step describe the operational process.

Description Aspect:
- Task Decomposition: Decompose complex tasks into steps 1, 2, 3.
- Logical Judgment: Tell the AI how to choose in different situations (e.g., "If the PDF has a password, first call the decryption script; if not, read directly").
- Tool Invocation: Clearly indicate when to run scripts in scripts/ or consult documents in references/.

3. Output Format

Specify the content format the AI ultimately presents to the user.

Description Aspect:
- Structure: e.g., "Must include: Summary, Risk Points, Recommended Actions three parts".
- Style: e.g., "Use tables to display data comparison" or "Code blocks must include comments".

4. Examples

Provide cases for "Few-Shot Prompting" to help the AI understand intent.

Description Aspect:
- Input/Output Pairs: Show an example of a user question and the standard answer format you expect.
- Trigger Word Examples: Clearly list which user statements will trigger this skill (e.g., "Help me package this project").

5. References & Assets

Guide the AI on how to use external files within the skill package.

Description Aspect:
- When to Read: e.g., "Before performing the audit, you must first read references/compliance_rules.md".
- How to Use: e.g., "Use assets/template.pptx as the template for generating the report".

SKILL Template

---
name: [Skill Identifier Name]
description: [One-sentence description of function + trigger scenario + core value]
version: 1.0.0
---

# [Skill Name]

## Role Definition
You are a [Specific Role], skilled in [Core Capability].

## Core Instructions
Please strictly follow the steps below to execute the task:
1. **Analyze Intent**: [Step description]
2. **Consult Materials**: If necessary, read `references/[file name]` to get detailed information.
3. **Execute Operation**: Run `scripts/[script name]` to process data.
4. **Output Result**: Generate the answer according to the output format requirements below.

## Output Format
- Must include: [Element A], [Element B]
- Style: [Professional/Humorous/Concise]

## Examples
**User Input**: [Example question]
**Your Answer**: [Example answer]

## Error Handling
If encountering [some error], please [perform some action].

3. Creating a SKILL

Manually Creating a SKILL

Create a SKILL folder and name it xxx-xxx (e.g., testcase-creator)

Create the SKILL.md file

Write metadata [name must match the folder name]

---
name: testcase-creator
description: Analyze from the perspective of a professional software test engineer based on PRD requirement documents, and generate test cases.
---

Write body instructions (case example below ↓ )

# Instructions:
  You are a project weekly report generation assistant. Your task is to collect this week's project progress from multiple data sources and generate a structured weekly report.

## Core Process

1. **Collect Data**
    - Ask the user for this week's time range (default: this Monday to Sunday)
    - Read the project git log, extract this week's commit records
    - Check if there are issue or todo files, extract relevant progress
    - Check if there are problems.md/json, growth.md/json, knowledge.md/json files in the project directory
    - If the project does not have the above files, ask the user if there is additional content to add

2. **Process Data**
    - Use scripts/git-analyzer.py to analyze git commits, extract key information
    - Use scripts/todo-parser.py to parse todo/issue, organize completion status
    - Use scripts/user-content-parser.py to parse user content files (problems, growth, knowledge) in the project
    - Use scripts/data-aggregator.py to aggregate all data, supports --project-dir parameter to specify project directory
    - Refer to references/data-extraction.md for detailed data extraction methods

3. **Organize Weekly Report Structure**
    - Refer to references/report-structure.md for the standard structure of the weekly report
    - Organize data into the following modules:
    - Data Statistics (number of commits, participants, completed items, etc.)
    - This Week's Progress (feature development, bug fixes, technical improvements)
    - Problems Encountered This Week
    - Personal Growth This Week
    - Related Knowledge Sharing
    - Next Week's Plan
    - Risks and Issues

4. **Generate Report**
    - Refer to references/template-filling.md for template filling logic
    - Use assets/report-template.html as the template
    - Fill structured data into the template
    - Generate an HTML format weekly report file: weekly-report-YYYY-MM-DD.html
    - Use scripts/html-to-pdf.py to convert HTML to PDF
    - Generate a PDF format weekly report file: weekly-report-YYYY-MM-DD.pdf

## Weekly Report Content Description

Users need to provide the following content (three methods supported):

**Method 1: Provide files in the project (Recommended)**
- **Problems Encountered This Week**: Create a `problems.md` or `problems.json` file in the project root directory
- **Personal Growth This Week**: Create a `growth.md` or `growth.json` file in the project root directory
- **Related Knowledge Sharing**: Create a `knowledge.md` or `knowledge.json` file in the project root directory

JSON format must conform to the structure definition in user-input.json. Markdown format must include corresponding titles and content.

**Method 2: Provide via user-input.json file**
- Define problems, growth, knowledge fields in user-input.json

**Method 3: Provide via conversation**
- If no files are provided in the project, ask the user for input according to the rules

Content Description:
- **Problems Encountered This Week**: Technical difficulties, blocking issues encountered during development, including problem description, type, solution, lessons learned
- **Personal Growth This Week**: Technologies learned, capability improvements, experience summaries, including category, content, impact
- **Related Knowledge Sharing**: Technical knowledge points worth recording, best practices, learning resources, including title, content, resource links

## Usage Instructions

Users can directly say: "Help me generate this week's weekly report", or provide a specific time range.

## Notes

- If the project is not a git repository, skip git log analysis
- If there are no issue or todo files, remind the user to manually input key progress
- Need to install Chrome or use a browser to manually generate PDF
- Output both HTML and PDF formats simultaneously

Create resource folders and put resources (e.g., references, scripts, assets, etc.) into the SKILL folder testcase-creator

Automatically Creating a SKILL

Automatic creation here means letting AI create the SKILL we want based on Anthropic's official SKILL.md for creating SKILLs

Import Anthropic's official SKILL.md for creating SKILLs
1. Go to the Anthropic official website: https://github.com/anthropics/skills/tree/main/skills
2. Download the skills/skill-creator) file
3. Move the skill-creator folder to the AI's SKILL folder, so the agent gets this SKILL (if you don't know how to move, refer to Applying SKILL below)
Use skill-creator to create the desired SKILL
1. Enter in the agent input box: /skill-creator Use this to create a SKILL, the requirement is: xxxxx

4. Applying a SKILL

Global Application

Global application means: Install this SKILL into the agent's own SKILLS folder. Scope: Global scope, as long as this agent is used, it has this SKILL.

Prepare a SKILL folder (e.g., the previously created testcase-creator)
Download an agent to your local computer (e.g., opencode, cursor, etc.)
Open the agent's SKILLS folder
1. The location of the SKILLS folder varies for different agents
Put the SKILL folder into the agent's SKILLS folder
Restart the agent, and it will load this SKILL

Project Application

Project application means: Install the SKILL into the current project's SKILLS folder. Scope: Project scope, only the agent started under the current project has this SKILL capability.

Prepare a SKILL folder (e.g., the previously created testcase-creator)
Download an agent to your local computer (e.g., opencode, cursor, etc.), using opencode as an example below
Create a project demo1
1. Under the demo1 directory, create a folder .opencode
2. Under the folder .opencode, create a folder skills
  
  Why .opencode, refer to the notes below
3. Put the testcase-creator folder into the folder skills
Restart the agent under the project directory, and it will load this SKILL

That is, under the demo1 folder, enter the command line, type opencode, and it will restart the project-level agent

Notes: The project directory creation methods for different agents are as follows ↓

5. SKILL Principle: Progressive Disclosure

"Progressive Disclosure" is actually the core design philosophy behind Agent Skills, a cognitive architecture that allows AI to simulate the "thinking efficiency" of a human expert.

It can be understood as "expert mindset loaded on demand".

Imagine a senior lawyer's brain stores vast amounts of legal knowledge. But in daily chat, she won't actively recite the entire Civil Code; only when you consult about a specific contract dispute will she instantly mobilize relevant legal provisions, precedents, and litigation strategies, forming a "temporary expert thinking module" for your problem. This process of "mobilization" rather than "full disclosure" is progressive disclosure.

Skill Structure & Composition

In the technical implementation of Agent Skills, this concept is subtly mapped to a three-layer dynamic loading mechanism, and the synergy of these three layers realizes a complete "cognitive takeover" chain:

Metadata Layer, is "Identification and Triggering"

This is the "characteristic signal" exposed by the Skill, used to be scanned and matched by the Agent's intent recognition system. When a user expresses intent, the Agent is not searching for "tools", but performing domain recognition, loading the "business cards" (name and one-sentence description) of all Skills into memory.

This is like a lawyer remembering that she specializes in "contract review", "intellectual property", and "marriage law" domain labels. The cost is extremely low, but a global cognitive map is established.

Instruction Layer, is "Thinking and Planning"

Once matched, the loaded core instructions are not mechanical steps, but the injection of a "professional thinking framework". It re-plans the Agent's thinking path, switching the general problem-solving mode to the domain expert's SOP. At this moment, the Agent's "thinking" is temporarily reshaped, from "how should I answer" to "according to the best practices of this domain, I should follow the following process".

The detailed steps, rules, and best practices in the skill are the carriers of procedural knowledge. Once loaded, it re-plans the Agent's thinking chain for solving the current problem, defining "what to think first, what to do next, how to judge".

This is like a lawyer judging that this matter falls under the "contract review" category, then activating the complete SOP for reviewing contracts in her mind: first look at the subject terms, then liability for breach of contract, then dispute resolution methods... At this point, the professional thinking framework is fully injected.

Resource Layer, is "Execution and Verification"

By calling scripts and documents, fast reflex arcs (scripts handle deterministic links) and external memory (reference materials provide key basis) are equipped to ensure the efficient and accurate execution of the thinking map.

When instructions advance to the point where calculation, formatting, or checking key specifications is needed, scripts are automatically called (deterministic execution) or references are read (fact-checking), ensuring that the output of expert thinking possesses both flexibility and certainty.

17810161757791