Best practices for skill creators

This is how to write clearly defined skills that are appropriate for the task!

 

Start with practical expertise.

A common mistake in skill creation is asking LLMs to generate skills without providing specific domain context—relying solely on the LLM's general training knowledge. The result is vague, generic processes ('handle errors appropriately', 'follow best practices for validation') instead of specific API patterns, exceptions, and project conventions that make skills valuable.

Effective skills are built upon practical expertise. The key is to provide specific field context into the skill development process.

Extracted from a real-world task.

Complete a practical task within a conversation with an agent, providing context, input, and preferences throughout the process. Then, extract a reusable template to create a skill. Pay attention to:

• The steps that worked - the sequence of actions that led to success.
• The edits you made – the places where you instructed the agent's approach (e.g., 'use library X instead of Y', 'check exception Z')
• Input/Output Format - What does input and output data look like?
• The context you provided —specific project events, conventions, or constraints that the agent is unaware of.

Compiled from existing project documents.

Once you have a body of existing knowledge, you can feed it into an LLM and ask it to synthesize a skill. A data path skill synthesized from your team's actual incident reports and operating manuals will perform better than one synthesized from a generic article on 'data engineering best practices,' because it captures your schema, failure modes, and recovery processes. The key is project-specific documentation, not generic references. Good sources include:

 

• Internal documents, operating manuals, and style guides.
• API specifications, schema, and configuration files.
• Provide feedback on the code and troubleshooting tools (record common concerns and expectations of the reviewers).
• Version control history, especially bug fixes and patches (reveals patterns through what actually changed).
• Real-world error scenarios and how to resolve them.

Refine through practical implementation.

The first draft of a skill often needs refinement. Run the skill with real-world tasks, then feed the results—everything, not just the errors—back into the creation process. Ask yourself: what caused the false positives? What was missed? What can be eliminated?

Even a single trial run followed by revisions can significantly improve quality, and complex fields often benefit from multiple such runs.

♦ Read the agent's execution trail, not just the final output. If the agent wastes time on inefficient steps, common causes include overly vague instructions (the agent tries several approaches before finding one that works), instructions that don't apply to the current task (the agent still follows them), or too many options provided without a clear default option.

To adopt a more structured approach to the iterative process, including test cases, validation, and scoring.

Use context wisely.

Once a skill is activated, its entire SKILL.md file is loaded into the agent's context window along with conversation history, system context, and other active skills. Every word in your skill competes for the agent's attention with everything else in that window.

Add what the agent is missing, ignore what is already known.

Focus on what the agent wouldn't know without your skills: project-specific conventions, industry-specific processes, unclear exceptions, and specific tools or APIs to use. You don't need to explain what PDFs are , how HTTP works, or what database migration entails.

 

 ## Trích xuất văn bản từ PDF File PDF (Portable Document Format) là một định dạng file phổ biến chứa văn bản, hình ảnh và các nội dung khác. Để trích xuất văn bản từ PDF, bạn cần sử dụng thư viện. pdfplumber được khuyến nghị vì nó xử lý tốt hầu hết các trường hợp.  ## Trích xuất văn bản từ PDF Sử dụng pdfplumber để trích xuất văn bản. Đối với tài liệu được scan, hãy sử dụng pdf2image với pytesseract. ```python import pdfplumber with pdfplumber.open("file.pdf") as pdf: text = pdf.pages[0].extract_text() ```

Ask yourself about each item: 'Would the agent make a mistake doing this without instructions?' If the answer is no, eliminate it. If you're unsure, double-check. And if the agent handled the entire task well without that skill, then that skill might not be valuable.

Design coherent units

Deciding what a skill should include is similar to deciding what a function should do: You want it to encompass a coherent unit of work that integrates well with other skills. Skills that are too narrow force multiple skills to be loaded for a single task, leading to wasted resources and instruction conflicts. Skills that are too broad become difficult to trigger correctly. A skill for querying a database and formatting results might be a coherent unit, while a skill that also includes database administration might be trying to do too much.

Aiming for a moderate level of detail.

Overly comprehensive skills can do more harm than good – the agent will struggle to extract relevant information and may pursue inefficient paths due to instructions that don't apply to the current task. Concise, step-by-step instructions with practical examples are often more effective than overly detailed documentation. When you find yourself dealing with numerous exceptions, consider whether most of those cases could be handled better by the agent's judgment.

The structure of major skills is revealed gradually.

The recommended specifications suggest keeping SKILL.md under 500 lines and 5,000 tokens – only the core instructions the agent needs for each run. When a skill truly requires more content, move detailed references to separate files in the references/ directory or similar folders.

It's important to tell the agent when to load each file. 'Read references/api-errors.md if the API returns a status code other than 200' is more useful than the general statement 'see references/ for details'. This allows the agent to load the context on demand rather than right from the start, which is how incremental disclosure is designed to work.

 

Adjusting control

Not every part of a skill needs the same level of detail. Adjust the specificity of the instructions to match the sensitivity of the task.

The right balance between specificity and vulnerability.

Allowing agents freedom of action when multiple valid methods and tasks permit variation is important. For flexible instructions, explaining the reasoning can be more effective than rigid directives – an agent that understands the purpose behind the instruction will make better context-dependent decisions. Code review skills can describe what to look for without specifying precise steps:

## Quy trình kiểm tra code 1. Kiểm tra tất cả các truy vấn cơ sở dữ liệu xem có lỗi tấn công SQL injection hay không (sử dụng truy vấn tham số hóa) 2. Xác minh kiểm tra xác thực trên mọi endpoint 3. Tìm kiếm các điều kiện tranh chấp trong những đường dẫn code đồng thời 4. Xác nhận thông báo lỗi không làm lộ thông tin nội bộ

Provide specific guidance when activities are susceptible to disruption, consistency is important, or a particular sequence needs to be followed:

## Di chuyển cơ sở dữ liệu Chạy chính xác chuỗi lệnh sau: ```bash python scripts/migrate.py --verify --backup ``` Không được sửa đổi lệnh hoặc thêm các flag bổ sung.

Most skills require a combination of many factors. Adjust each part independently.

Provides default settings, not menus.

When multiple tools or methods might be effective, choose a default setting and briefly mention the alternatives instead of presenting them as equally good options.

 Bạn có thể sử dụng pypdf, pdfplumber, PyMuPDF hoặc pdf2image.  Sử dụng pdfplumber để trích xuất văn bản: ```python import pdfplumber ``` Đối với các file PDF được scan cần nhận dạng ký tự quang học (OCR), hãy sử dụng pdf2image với pytesseract.

Prioritize process over claims.

A skill should teach learners how to approach a group of problems, not how to create a product for a specific case. Compare:

 Kết nối bảng `orders` với bảng `customers` dựa trên `customer_id`, lọc theo điều kiện `region = 'EMEA'`, và tính tổng cột `amount`.  1. Đọc lược đồ từ `references/schema.yaml` để tìm các bảng liên quan 2. Kết nối các bảng bằng cách sử dụng quy ước foreign key `_id` 3. Áp dụng bất kỳ bộ lọc nào từ yêu cầu của người dùng dưới dạng mệnh đề WHERE 4. Tổng hợp các cột số khi cần và định dạng thành bảng markdown

This doesn't mean skills can't include specific details—output formatting templates, constraints like 'never output personally identifiable information,' and tool-specific instructions are all valuable. The point is that the approach should be general even when individual details are very specific.

Effective guidance templates

These are reusable techniques for structuring skill content. You don't need every skill – use only those that are relevant to your tasks.

Important notes

The most valuable content in many skills is the list of unforeseen problems—specific environmental facts that contradict reasonable assumptions. This isn't general advice ('handle errors appropriately') but rather specific remedies for mistakes the agent would make if not instructed otherwise:

 

## Những điểm cần lưu ý - Bảng `users` sử dụng xóa mềm. Các truy vấn phải bao gồm `WHERE deleted_at IS NULL` nếu không kết quả sẽ bao gồm các tài khoản đã bị vô hiệu hóa. - ID người dùng là `user_id` trong cơ sở dữ liệu, `uid` trong dịch vụ xác thực, và `accountId` trong API thanh toán. Cả ba đều tham chiếu đến cùng một giá trị. - Endpoint `/health` trả về mã trạng thái 200 miễn là máy chủ web đang chạy, ngay cả khi kết nối cơ sở dữ liệu bị ngắt. Sử dụng `/ready` để kiểm tra đầy đủ tình trạng hoạt động của dịch vụ.

Store common errors (gotchas) in the SKILL.md file so the agent can read them before encountering a situation. A separate reference file is also useful if you tell the agent when to load it, but for unclear issues, the agent might not recognize the trigger.

♦ When the agent makes a mistake that you need to fix, add a bug fix to the gotchas. This is one of the most direct ways to improve skills through iterative practice.

Output format template

When you need the agent to produce output in a specific format, provide a template. This is more reliable than describing the format in prose, as agents match patterns well to specific structures. Short templates can be stored directly in SKILL.md; for longer templates or templates only needed in certain cases, store them in the assets/ directory and reference them from SKILL.md so they are only loaded when needed.

## Cấu trúc báo cáo Sử dụng template này, điều chỉnh các phần khi cần thiết cho phân tích cụ thể: ```markdown # [Tiêu đề phân tích] ## Tóm tắt [Tổng quan một đoạn về các phát hiện chính] ## Các phát hiện chính - Phát hiện 1 kèm dữ liệu hỗ trợ - Phát hiện 2 kèm dữ liệu hỗ trợ ## Kiến nghị 1. Kiến nghị cụ thể có thể thực hiện 2. Kiến nghị cụ thể có thể thực hiện ```

Checklist for a multi-step workflow

A clear checklist helps the implementer track progress and avoid missing steps, especially those involving dependencies or validation checks.

## Quy trình xử lý biểu mẫu Tiến độ: - [ ] Bước 1: Phân tích biểu mẫu (chạy `scripts/analyze_form.py`) - [ ] Bước 2: Tạo ánh xạ trường (chỉnh sửa `fields.json`) - [ ] Bước 3: Xác thực ánh xạ (chạy `scripts/validate_fields.py`) - [ ] Bước 4: Điền biểu mẫu (chạy `scripts/fill_form.py`) - [ ] Bước 5: Kiểm tra kết quả (chạy `scripts/verify_output.py`)

Validation loop

Instruct the agent to self-validate its job before proceeding. The model is: Perform the job, run the validator (a script, reference checklist, or self-check), fix any issues, and repeat until the validation process is successful.

## Quy trình chỉnh sửa 1. Thực hiện chỉnh sửa 2. Chạy kiểm tra hợp lệ: `python scripts/validate.py output/` 3. Nếu kiểm tra hợp lệ thất bại: - Xem lại thông báo lỗi - Khắc phục sự cố - Chạy kiểm tra hợp lệ lại 4. Chỉ tiếp tục khi kiểm tra hợp lệ thành công

References can also serve as a 'verification tool' – guiding the agent to check their work against the references before completion.

Plan - Verify - Execute

For batch or destructive operations, have the agent create an intermediate plan in a structured format, verify it against the correct information source, and only then execute it.

## Điền biểu mẫu PDF 1. Trích xuất các trường biểu mẫu: `python scripts/analyze_form.py input.pdf` → `form_fields.json` (liệt kê tên, loại và trạng thái bắt buộc của từng trường) 2. Tạo `field_values.json` ánh xạ từng tên trường với giá trị tương ứng 3. Xác thực: `python scripts/validate_fields.py form_fields.json field_values.json` (kiểm tra xem mọi tên trường có tồn tại trong biểu mẫu, loại tương thích và không thiếu các trường bắt buộc) 4. Nếu xác thực thất bại, hãy sửa đổi `field_values.json` và xác thực lại 5. Điền biểu mẫu: `python scripts/fill_form.py input.pdf field_values.json output.pdf`

The crucial component is step 3: A validation script checks the plan (field_values.json) against the correct data source (form_fields.json). Errors like 'Field 'signature_date' not found - available fields: customer_name, order_total, signature_date_signed' provide the agent with enough information to self-correct.

Package reusable scripts.

When iterating through the development of a skill, compare the agent's execution trace across test cases. If you notice the agent automatically regenerating the same logic each time—building graphs, parsing a specific format, validating output—that's a sign that you need to write a script that has been tested once and package it in the scripts/ directory.