Amazon Quick Create SKILL Complete Guide

This article uses a real case — the full story of how the "SEO Checkup" skill came to be — to summarize the work required to create a SKILL, the commands used, and the pitfalls encountered. Suitable for anyone who wants to solidify their repetitive workflows into reusable skills.

1. What is a SKILL and why create one

A SKILL is a reusable capability package that solidifies a set ofmulti-step workflowsOnce built, a single sentence triggers the entire process — no need to re-explain every time.

A SKILL is essentially a folder:

skill-name/
├── SKILL.md          ← 核心：流程说明 + 触发词 + 输入 + 经验
├── scripts/          ← 可选：可复用的代码脚本
│   └── *.py
└── evals/            ← 可选：测试用例
    └── evals.json

Signals that something is suitable for a SKILL: you do it repeatedly, it has ≥2 steps, it has a clear output, and it still works when you swap the object (URL/client/project).

2. The overall process of creating a SKILL (5 steps)

Creating a skill itself is guided by a "meta-skill." The core is these 5 steps:

III. Step-by-step breakdown: what to do at each step

Step 1: First run through the workflow (most important)

Don't rush to build a skill. First take a real requirement and do it end to end, for example: "Help me check the SEO of this webpage." During this process:

• Clarifyinputwhat it is (one URL? a batch of URLs?)
• Clarifyoutputwhat it is (a report? what format?)
• Record what capability was used at each step (open webpage, run code, generate Excel...)

Practical lesson: our SEO skill was distilled only after genuinely auditing multiple pages of a company's official website and repeatedly adjusting the report format. Along the way, the user kept raising requirements (add Bing standards, verify official sources, change to an execution matrix, split into two phases...), and all of these became the most valuable parts of the skill.

Step 2: Confirm the skill skeleton

Tell the AI clearly (or let it suggest):

Step 3: Extract session data

This step is done automatically by the tool: it scans the session you just ran successfully, extracts the list of tools used, and generates a SKILL.md skeleton with YAML frontmatter. You only need to provide what was defined in Step 2: skill name, trigger words, inputs, display name, icon.

Instructions:extract_session_data

Step 4: Write SKILL.md (core creation)

On top of the skeleton, complete the following sections:

① frontmatter (file header)

---
name: seo-audit-skill
display_name: 「SEO 体检」
description: "一句话说清楚它做什么、什么时候该触发"
icon: "🔍"
trigger: SEO体检 audit 网站优化 网站SEO
inputs:
  - name: page_url
    description: "要体检的页面网址"
    required: true
scripts: [seo_audit.py, seo_matrix.py]
---

② Overview

2–3 sentences clearly stating what it does and when to use it.

③ Workflow (step-by-step)

Label each step with its mode (deterministic fixed action / agentic requires judgment), inputs, outputs, verification method, and what to do on failure.Explain more "why" and write fewer rigid "must/forbidden" rules—the AI executing the skill responds better to "reasoning."

④ Output

Define clearly what the final output looks like and its format.

⑤ Lessons Learned (experience)

This is the watershed of skill quality, in four parts:

• Do: which practices work
• Don't: which pitfalls to avoid
• Common Failures: common mistakes + how to handle them
• When to Ask the User: when to stop and ask a human

Real-world lessons: our skill's Lessons section is full of real pitfalls we've hit—don't use \uXXXX escapes in Chinese, use utf-8-sig when writing CSV to prevent Excel garbled text, an abnormally high image alt missing rate is mostly lazy-loading false positives (mark as "to verify" rather than directly judging as missing), some domains block bulk crawling and require browser verification… These "hard-won" lessons make the skill run more reliably next time.

⑥ Scripts (optional but strongly recommended)

If the workflow contains repeated code, extract it into a script and place it in scripts/, reference it in SKILL.md. We built "page signal collection JS" and "multi-page matrix generation" as two scripts to ensure the output format is consistent every time.

Step 5: Save + Test

• Save instructions:save_skill(skill name + full SKILL.md + scripts)
• Generate tests:generate_skill_evals(automatically create a few test cases)
• Thenrun it for real onceto verify — we tested both single-page and multi-page scenarios to confirm it can identify real issues (e.g., catching several 404 broken links, finding mismatches between social share titles and page titles).

IV. How to Iterate and Distribute After Creation

Iterative improvement

Instructions:load_skill_for_improvement. Skills aren't built in one shot. After using it a few times, improve as needed:

• modify the workflow, add output formats, adjust trigger words
• When saving,use the same skill nameto overwrite in place (the old version is automatically backed up)

In practice: we iterated this skill many rounds — added Bing standards, changed the execution matrix format, split into two phases, added dual Excel+Markdown output, fixed column name alignment with samples, and finally renamed it. Every round was load_skill_for_improvement → modify → save_skill overwrite.

Rename

Change the name and display_namein the frontmatter, use the new name save_skill, then delete the old skill folder.

Package and distribute

Compress the entire skill folder into a zip to back it up, migrate it to another computer, or share it with colleagues (place it in their skills directory).

Cross-tool porting

If you want to use it in another AI tool (ChatGPT/Claude/Gemini), you need to "de-platformize": rewrite proprietary tool names as generic capability descriptions ("open a webpage", "run code"), and embed the scripts as self-contained Markdown so the whole thing can be pasted as a system prompt/custom instruction.

V. Common Commands Quick Reference

6. Pitfall checklist (from real-world mistakes)

1. Get it working first, then solidify— Don't write a skill out of thin air.
2. Only put variables in the input— Hardcode fixed values into the workflow.
3. Lessons Learned must capture real experience— This is the key to whether a skill gets "steadier the more you use it."
4. Extract repeated code into scripts— Ensures consistent output format and saves tokens.
5. Always test after saving— Actually run it once on a single page + multiple pages to verify it can identify real issues.
6. Encoding pitfalls(if involving Chinese/code generation): write files with encoding="utf-8", use utf-8-sig for CSV, don't use \uXXXX escaping, use built-in CID fonts for Chinese in PDF.
7. Iterate by overwriting with the same name——name stays unchanged, old versions are automatically backed up.

Conclusion

The essence of creating a SKILL is:Package a successful workflow—along with its judgments and lessons—into a capability you can "redo with one sentence next time." A well-made skill doesn't just record the steps; it records the experience of "how to do this right."

Do the thing beautifully first, then make it reusable—that's the entire philosophy of creating a SKILL.