From Repetitive Work to Verifiable Workflows: A Complete Agent Skills Design Guide

Claude Code / Codex Compatible: Full Version of Skill Creation Prompts for Beginners to Use Directly

Want to try creating Agent Skills.

But as soon as you open Claude or Codex, you often get stuck on the very first sentence.

"I don’t know what instructions to give."
"I don’t know what to write in SKILL.md."
"Even if I write many rules, I’m worried whether they will really follow them."
"Fundamentally, I also don’t know to what extent of specifications I need to consider."

This is very normal.

When beginners create a Skill, they don’t need to consider YAML, evaluation metrics, trigger conditions, validation scripts, sub-agent design, etc., from the very beginning.

Just answering four things first is enough.

1 . What are the things you do repeatedly?

1 . What are the standards of success

1 . What failures do you want to avoid

1 . Are there any references close to the ideal

The remaining parts can be left to Claude or Codex, letting it complete them in the role of a ‘skill designer’.

As of July (2026年), both Codex and Claude Code have adopted the Agent Skills mechanism centered around SKILL.md, loading scripts, references, templates, etc., as needed. In Codex, you first look at the name and description of the Skill, and only read the main text if deemed necessary. Claude Code is the same; the main text of the Skill is only read when it is used. What really matters is not writing longer and longer prompts, but clearly designing the trigger conditions, execution process, validation methods, and termination conditions.

First, run the following prompt as-is.

Chapter one: Complete Skill Creation Prompt for Beginners

Paste the following content into the normal chat of Claude Code or Codex.

In Codex, you can also call $skill-creator first and then paste. Codex’s official Skill creator will also confirm "what the skill does", "when it is triggered", and "whether it includes a script", but the following prompt is the full version, additionally including quality evaluation and loop engineering.

You are the world’s top
"Agent Skills Architect"
"Workflow Engineer"
"Evaluator Designer".

I am a beginner learning to create Agent Skills.
Even if I don’t understand professional terminology and file structures, please create a Skill that can actually be used in Claude Code or Codex.

Don’t just stop at explanations; if there are file operation tools available, please actually create the Skill folder and the necessary files.

If you are in an environment where files cannot be created, please output the full content according to the file names without omitting anything.

■ Skill I want to create

Skill I want to create:
[Write here in one sentence]

Usage environment:
[Codex / Claude Code / Both / Not sure]

The goal you want to achieve with this skill:
[Write within your known scope. If unknown, write ‘Leave it to you’]

Examples of requests that might actually be made:
[ 1 〜 3 items. If unknown, write ‘Leave it to you’]

Failures that must be absolutely avoided:
[For example: articles that seem AI-generated, templated design, buttons that only look clickable but can’t be clicked, claiming completion without testing, etc.]

Reference examples, resources, websites, articles, code that are close to ideal:
[Write them if available. If none, write ‘None’]

Quality Level:
[Simple / Practical Quality / Highest Quality / Unknown]

Unclear Items:
[All can be delegated to complete]

■ Rules for Beginners

1 . If information is insufficient, please ask up to seven questions at once.

2 . For items I answer with ‘Don’t know’ or ‘Leave it to you,’ please provide three options and recommend the most replicable plan among them.

3 . For items that can proceed even without my response, please use reasonable default values and record them as assumptions in assumptions.md.

4 . When using professional terminology, please include a one-line explanation in parentheses to help beginners understand.

5 . For irreversible operations such as charging, publishing, deploying, deleting data, or changing authentication information, do not execute them automatically.

6 . When dealing with services, APIs, or libraries that change frequently, please check the current official documentation. Do not rely solely on past memory to determine standards.

■ Essential Steps for Skill Design

Please be sure to follow the order below.

Step 1 : Summary of intents

Please convert my vague request into the following content.

• Purpose of the skill
• Target users
• Input
• Output
• Success criteria
• Absolute conditions
• Things not to do this time
• Expected failures
• Necessary tools
• Operations requiring manual approval

Please create the following content.

• brief.md
• acceptance-criteria.md
• assumptions.md

Steps 2 : Design of trigger conditions

Please clarify when the skill should and should not be used.

description should include the following content.

• The function of the Skill
• The purposes for which users use it
• Situations where it should be triggered even if the user does not say the Skill name
• Similar requests that should not trigger it
• Important target files, formats, task names

The description should be concise, placing the important uses at the beginning. Do not just write "improve quality" or "be helpful".

STEP 3 : Rule priority order

Please divide all instructions into the following three stages.

A. HARD GATES
Conditions that absolutely must not be violated. If violated, the entire deliverable will be judged as unqualified.

B. DEFAULTS
Basically follow the default values. If there is a clear reason on the project, changes can be made.

C. PREFERENCES
Preferences set for better outcomes. Optimization is done after satisfying HARD GATES and DEFAULTS.

Not only write "must," "absolute," "high quality,"
but also convert possible content into tests, commands, JSON judgments, and check items.

Steps 4 : Design of the skill structure

In principle, please consider the following.

<skill-name>/
├── SKILL.md
├── USAGE.md
├── references/
│ ├── domain-knowledge.md
│ ├── quality-rubric.md
│ └── failure-patterns.md
├── templates/
│ ├── brief-template.md
│ └── scorecard-template.json
├── evals/
│ ├── trigger-evals.json
│ └── output-evals.json
└── scripts/
└── necessary verification scripts

However, please do not create unnecessary files.

In SKILL.md, only write the necessary core processes each time.
For detailed knowledge, long examples, API specifications, and style guides, please put them in references.

For each reference, please clearly write in SKILL.md:
"When to read"
"What to judge by reading"

If the same decisive handling is rewritten by AI each time, move it to scripts.

Steps 5 : Create SKILL.md

SKILL.md should be based on the following structure.

• Tasks
• When to Use
• When Not to Use
• Input
• Required Context
• Instruction Priority
• Workflow
• Hard Threshold
• Quality Standards
• Verification
• Fix Loop
• Stop Conditions
• Completion Report
• Supporting Files

Skill names should only use lowercase letters, numbers, and hyphens.
Please ensure the folder name matches the name.

Please do not let the main SKILL.md become too large,
ideally keep it under five hundred lines, 000 and fewer than about five tokens.

STEP 6 : Iterative Engineering

Do not set Skill as a process that ends after one generation.

Please include the following loop.

1 . Plan 2 . Build 3 . Run 4 . Observe 5 . Score 6 . Repair 7 . Retest 8 . Stop or continue

However, please do not use excessive loops in simple tasks.

As an initial value, iterate up to three times.
End under the following circumstances.

• Passed all HARD GATES
• Exceeded the passing score
• Recently 2 round showed no significant improvement
• The same mistakes were repeated twice
• Reached the cost or time limit
• Requires human judgment

Please use the highest-rated checkpoint instead of the last version.

STEP 7 : Separate the generation role from the evaluation role

For complex or subjective deliverables, separate the generation role from the evaluation role.

Generation role:
Produce the deliverable.

Evaluation role:
Check the deliverable from a clean context, do not give lenient scores, and provide specific evidence.

The evaluation results should include the following content:

• criterion_id
• expected
• observed
• passed
• evidence
• severity
• likely_cause
• minimal_fix
• retest_method

Evaluators should, whenever possible, not only run the source code but also execute the actual deliverables.

For web pages, operate the browser;
for applications, check the UI, API, and saved state;
for games, perform actual gameplay;
for videos, check the timeline and rendering;
for articles, verify facts, tone, and emotional curve.

Steps 8 : Verify the script

Content that can be mechanically determined,
please verify with a script instead of relying on the impressions of an LLM.

Example:

• File existence
• JSON validity
• Forbidden strings
• Virtual implementation
• Type errors
• Test results
• Broken links
• Image dimensions
• Contrast
• Text overflow
• Output format
• Required fields

Please follow the following items when creating scripts.

• No dialogue input required
• Provide –help
• Display error reasons and how to fix them
• If possible, output JSON to stdout
• Output diagnostic information to stderr
• Will not be damaged even if re-executed
• Provide –dry-run for destructive operations
• Return meaningful exit codes

STEP 9 : Trigger evaluation

Please create at least the following in trigger-evals.json.

• Examples that should be triggered: 8 ~ 10 items
• Similar examples that should not be triggered: 8 〜 10 items

Please change the way of expression.

• Polite request
• Colloquial
• Short sentence
• Long sentence
• Request with typos
• Request without mentioning the skill name
• Request hidden in multiple steps

Not only include obviously irrelevant examples,
but also include examples with similar keywords that should use other skills.

Step 10 : Output evaluation

Please create at least 3 records in output-evals.json.

• Normal cases
• Ambiguous cases
• Boundary or failure cases

Please include the following content for each case.

• prompt
• expected_output
• input_files
• assertions
• hard_gates
• human_review_points

If possible, compare Skill vs. no Skill, or old version vs. new version in a clean context.

For subjective quality, conduct a blind test comparison, hiding which is the new version.

Steps 11 : Improvement

Please make up to three rounds of improvements to the Skill based on the evaluation results.

When making improvements, do not just add special rules for failure cases. Please categorize the root cause of the failures into one of the following items.

• Trigger
• Situation
• Process
• Tool
• Verification
• Evaluator
• Stop conditions
• Memory

In addition to adding instructions, please also consider removing unnecessary instructions.

Steps 12 : Complete the report

Finally, please report the following to beginners.

1 . Name of the created Skill 2 . Save location 3 . Folder structure 4 . This skill can do things you can do 5 . Examples of triggered requests 6 . Example of a request that does not trigger 7 . Manual call methods 8 . Initial testing method 9 . Verification results 10 . Limitations still exist 11 . Files to review for the next improvement

Don’t just say "Done"—show the verification orders and evidence you have executed.

About what to write in this prompt

You really can just write a single sentence.

For example, if you want to create a Japanese writing skill that feels human, you could write like this.

Skill you want to create:
A writing skill that can preserve the fluctuations and emotions of human writing in Japanese note articles or X posts

Usage environment:
Codex

Goal you want to achieve with this skill:
You want the content to be easy to read, but not appear too AI-generated or overly neat

Examples of actual requests you might make:
"Write this experience into a note article"
"Change this text to language that matches my style"

Errors to absolutely avoid:
Consecutive identical endings, excessive bullet points, abstract theories, false experiences

Reference examples close to ideal:
Provide your past articles afterward

Quality level:
Highest quality

If other things are unclear, you can write like this at the end.

Nothing else is unclear.
Please choose the composition that is most suitable for beginners, safest, and repeatable.

At this point, you can start Skill design.

Chapter Two: How to Save and Invoke a Skill

The storage locations of Claude Code and Codex are slightly different.

Codex

If it is for project-specific use, place it in the following location.

Project/
└── .agents/
└── skills/
└── SkillName/
└── SKILL.md

If you want to use it in all your projects, place it in the following location.

~/.agents/skills/SkillName/SKILL.md

In Codex, you can explicitly specify skills in the prompt, or select skills from $ in the CLI and IDE. Automatic triggering is determined by description matching.

Claude Encoding

If it is for a specific project, please put it in the following location.

project/
└── .claude/
└── skills/
└── skill-name/
└── SKILL.md

If you want to use it in all of your projects, please put it in the following location.

~/.claude/skills/skill-name/SKILL.md

In Claude Code, in addition to being able to execute manually through /skill-name, it will also automatically load if the description and request content match.

For example, if the skill name is human-japanese-writer, it can be called like this in Claude Code.

/human-japanese-writer

Please turn the following memo into a note article.
…

It is explicitly stated in Codex as follows.

Using $human-japanese-writer,
please turn the following memo into a note article.
…

In the initial stage, do not rely solely on automatic triggers; explicit calls make it easier to confirm whether it is running.

Chapter Three: A Skill Is More Than a Long Prompt

The difference between a strong Skill and a weak Skill is not in the number of articles.

A weak Skill is written like this.

Please create a high-quality website.
Please use modern and sophisticated design.
Please implement responsive design.
Make sure to conduct testing.

Otherwise, words like "high-quality," "modern," "exquisite," and "test" all seem correct, but when actually implemented, there is no evaluation standard.

On the other hand, strong skills see it this way.

1 . Define what emotions the website will bring to whom 2 . Decide on the visual identity 3 . Compare two to three different design directions 4 . Record the reasons for selection 5 . Create static completed layouts 6 . Operate in the browser 7 . Check 375 px, 768 px, 1440 Three widths in px 8 . Evaluate design quality, originality, accuracy, and functionality separately 9 . Only fix failed projects 10 . Use the highest-rated version

The essence of Skill is not to "give the correct answer."

It is to prevent the model from skipping the process close to the correct answer.

Chapter Four: An Eight-Layer Skill Design

1 . Trigger router — when to use

Skill is meaningless if it is not triggered before the content.

When Agent Skills starts, it does not read the full content of all Skills at once. Initially, it mainly looks at the name and description and only loads the necessary Skills. This mechanism is called Progressive Disclosure, which is a design of "only revealing detailed information when needed".

Therefore, the following description is weak.

description: Supports website creation.

It is unclear what it can do, when to use it, and where the boundaries are.

An example of improvement is as follows.

description: >
Use this skill when creating or redesigning production-quality websites that require original visual guidance, responsive implementation, browser validation, accessibility checks, and iterative design reviews. Suitable for landing pages, brand sites, product sites, portfolios, and web applications focused on visual quality. Not suitable for backend-only work, minor text edits, or isolated functional features.

The description must include at least "what to do" and "when to use it." According to Agent Skills specifications, the maximum length of the description is one, 024 character, and the Skill name consists of lowercase letters, numbers, and hyphens, matching the parent folder name.

In addition, trigger tests also need to be created.

In the official Skill creation guide, it is recommended to create about eight to 10 triggering requests and non-triggering requests respectively, and mix the use of colloquial language, typos, implicit expressions, short sentences, and long sentences. It is not just a simple matter of using unrelated requests as negative examples; what is more important are "near examples," that is, cases where the keywords are similar but belong to different tasks.

2 . Intent compiler — converts vague requests into contracts

Assume a non-engineer would make requests like this.

Create a fashionable appointment app.
It should be easy to use and also include AI.

If we start implementing like this, deviations are almost certain to occur.

First, transform it into the following content.

Target users:
Owners and customers of small salons

Most important process:
Customers look up available times, make reservations, and receive confirmation emails

Role of AI:
Suggest candidate times based on desired conditions

Success criteria:
The reservation is saved, still exists after reloading, and can be confirmed in the admin interface

Not included this time:
Payment, multiple locations, advanced CRM

Absolute condition:
Duplicate reservations are not allowed

Regard this conversion process as an Intent Compiler.

An excellent Skill does not directly convert a user’s sentence into code.

It will first convert it into brief.md or acceptance-criteria.md.

Having only this intermediate artifact makes it less likely for the model’s understanding to change during the process.

3 ．Context Loader — only reads the necessary knowledge

Do not stuff all kinds of information into the main body of the Skill.

In the standard specifications for Agent Skills, it is recommended that the main SKILL.md be less than five hundred lines, about five, 000 Fewer than this number of tokens, and it is recommended to separate detailed information into references/.

The incorrect way of writing is like this.

Please read the references as needed.

Don’t know when you should read what content.

The improved example is as follows.

Only when creating or modifying the Japanese copy,
read references/japanese-voice.md.
It is used to determine sentence endings, rhythm, emotional expression, and prohibited expressions.

Only read references/security.md when changing authentication or permission handling.
Determine the authentication boundaries, permission checks, and handling of confidential information.

Only read references/transitions.md when creating multi-scene videos.
Determine the methods and timing of scene transitions.

When conditions are clear, the model will only read the necessary context.

In Codex, introducing a large number of Skills will make the initial Skill list occupy context space, so descriptions may be shortened, or some Skills may be omitted from the initial list. Therefore, important uses should be placed at the beginning of the description.

4 · Rule Compiler — Change request to check

The following rules are weak.

Virtual implementation is prohibited.

The model may judge purely cosmetic buttons as "completed."

In strong Skills, it will be converted as follows.

HARD GATE: DISPLAY_ONLY_FEATURES

It is considered unqualified if any of the following conditions are met.

• Main buttons that do not change state when clicked
• API calls returning hard-coded success values
• Saving does not reflect in the database or persistent storage
• TODO, FIXME, mock, placeholder still exist in main features
• UI exists but the usage process cannot be completed

Verification: 1 . Use automated scripts to search for TODO, FIXME, mock, placeholder 2 . Operate main buttons in a real browser 3 . Check API responses 4 . Reload after saving 5 . Confirm persistent state

Rules are divided into three stages.

HARD GATES

Violation results in failure.

Example:

• Build failure

• Major features not working

• Content inconsistent with facts

• Leakage of personal information

• Does not meet contrast standards

• Release without approval

DEFAULTS

Generally comply.

Example:

• Maintain the existing tech stack

• Do not add new dependencies

• Mobile first

• Complete one feature at a time

PREFERENCES

Make improvements if possible.

Example:

• Unique animations

• More memorable copy

• Advanced micro-interactions

If every rule is written as ‘absolute,’ the truly critical ones will be drowned out.

5 ．Maker——the role of creator

The Maker creates artifacts.

However, do not let the Maker create a large application all at once from beginning to end.

First, break it down into meaningful units.

Function one: Member registration
Function two: Login
Function three: Create appointment
Function four: Appointment list
Function five: Admin interface

For each function, confirm the completion criteria.

Completion criteria for the appointment creation function:

• Can select date and time
• Cannot select past dates and times
• Cannot overlap with existing appointments
• Show confirmation page after saving
• Appointment remains even after reloading
• Can verify status in API and database

In Anthropic’s long-term application development experiments, the Planner, Generator, and Evaluator are separated, and what to create and what to test are confirmed before implementation. The Evaluator uses Playwright to actually operate the UI and verify API and database status. This is done to avoid implementations that look good from source code inspection but do not work internally.

6 – Checker — evaluates from different perspectives

It is not enough to let the generated model score itself.

A newly created model understands its own intentions.

"It should actually work"
"Not a big problem"
"Users probably won’t mind"

Therefore, it is easy to make lenient judgments.

The Checker starts in a clean context whenever possible.

Evaluation results should include evidence, not impressions.

{
"criterion_id": "BOOKING-004",
"expected": "After saving a booking, it will be displayed even after reloading",
"observed": "It displays immediately after saving, but disappears after reloading",
"passed": false,
"evidence": "After reloading, GET /api/bookings returns []",
"severity": "High",
"likely_cause": "Data is only saved in the frontend state",
"minimal_fix": "Connect the POST handling to save to the database, then fetch again via GET",
"retest_method": "After creating a booking, reload the page and check the UI, API, and database"
}

The parts that can be handled by scripts are left to mechanical judgments.

Only the subjective parts are given to the LLM.

Even in the official evaluation guidelines for Agent Skills, it is recommended to use validation scripts for JSON validity, the number of files, number of lines, image dimensions, etc., while the "feel" of articles or designs is better assessed through manual review or blind testing.

7 ．Repair Loop — only fix the failed parts

Do not remake all the content just because the evaluation is low.

For example, suppose the website’s evaluation is as follows.

Design quality: 88 Uniqueness: 74 Precision: 91 Functionality: 95

What is needed is not a complete overhaul of the entire page.

Identify the reasons for low uniqueness.

• Structure of the key visual centered specification
• Purple gradient and white cards
• Using default icons without modification
• No brand-specific photography guidelines

Only fix that part.

If the same problem occurs twice, stop detailed fixes and change direction.

Now stop tweaking the current direction.
Change the layout structure, image guidelines, and typography logic.

Then, what is retained is not the final version, but the version with the highest evaluation.

Design is not necessarily better the more times it is repeated. Later designs may have more decorations, and sometimes the mid-stage version is actually better.

8 ．Durable memory — keep the state beyond the conversation

Do not rely solely on the model’s memory to complete long-term work.

state.json
feature-ledger.json
decisions.md
scorecard.json
failures.json
CHANGELOG.md

Save the state in these files.

{
"current_phase": "Maintenance",
"best_checkpoint": "Iteration-2",
"best_score": 88 ,
"failed_criteria": [
"Design-Originality-02"
],
"attempts": {
"Design-Originality-02": 1 },
"next_action": "Replace generic hero composition"
}

The Subagent feature of Codex also demonstrates a design that suppresses context pollution by not sending a large number of exploration logs or test logs to the main conversation, but instead only returning summaries from professional agents. However, because each Subagent uses its own model and tools, token consumption will increase compared to running individually.

Therefore, it is not necessary to make all Skills use multiple agents.

Chapter Five: Choose One of Three Loop Intensities

The suitable work level constitutes Level 1 Minor modifications, short sentences, simple conversion execution + self-check Level 2 Practical articles, web pages, implementation of single functions Maker + Checker + 1 〜 3 Round modification Level 3 High-value applications, games, videos, complex MCP linkage Planner + Maker + Evaluator + real-environment verification

Complexity does not necessarily make it better.

In Anthropic’s experiments, although the Planner・Generator・Evaluator structure helps improve quality, it significantly increases costs compared to running them individually. Additionally, it was confirmed that as the model’s own capabilities improve, the previously necessary segmented sprint structure sometimes becomes unnecessary. The Evaluator does not need to be activated every time; it only becomes truly valuable when the task exceeds the model’s ability to handle it independently and stably.

Beginner’s initial Level 2 is sufficient.

Chapter Six: A General-Purpose SKILL.md Template

The following content can be adapted for various fields.

---

name: your-skill-name
description: >
Use this skill when the user wants to achieve [purpose] and the task requires [specialized engineering, verification, or target format]. It is used for [representative use cases].
Even if the user does not directly name the Skill, it can be used as long as [implicit goals] are described. Do not use it for [similar but out-of-scope work].
compatibility: Designed to be compatible with Codex and Claude Code Agent Skills clients.
metadata:
version: " 1.0.0 "

Task

Transform the user’s request into a validated, usable result for:

• Primary user: [Target]
• Primary outcome: [Outcome]
• Quality level: [Quality]
• Main risks to prevent: [Failure]

Do not claim completion based solely on source inspection when the artifact can run, present, open, play, or be otherwise tested.

When to use

Use this skill in the following situations:

• [Trigger condition one]
• [Trigger condition two]
• [Implicit trigger conditions]
• When the target task is part of multiple steps

When not to use

Do not use this skill in the following situations:

• [Not applicable one]
• [Not applicable two]
• [Situations where adjacent skills are more appropriate]

Input

Collect or infer:

• Goals
• Audience
• References
• Required output
• Constraints
• Quality standards
• Deadlines or execution budget
• Irreversible operations

If missing details will not hinder safe progress, choose a reasonable default and record it inassumptions.md.

Clarification is only required when missing information would substantially change the outcome, cause safety risks, incur costs, publish content, delete data, or make irreversible decisions.

Instruction Priority

Follow instructions in the following order:

1 . Hard requirements 2 . Acceptance criteria for specific tasks 3 . Project practices and source materials 4 . Default values 5 . Preferences

Never compromise hard requirements for higher subjective scores.

Necessary context

Please read the project description and existing documents first.

Load supporting reference materials only when conditions are met:

• Read when [condition]references/domain-knowledge.md.
• Read before subjective evaluationreferences/quality-rubric.md.
• Read during maintenance or when a known fault occursreferences/failure-patterns.md.

By default, do not load every reference.

Workflow

Stage 0 : Compile intention

Create or update:

–brief.md–acceptance-criteria.md–assumptions.md

Define the criteria for success before generating the final results.

Phase 1 : Check

Inspect the current project, existing outputs, tools, constraints, and relevant source materials.

Do not replace existing conventions without a clear reason.

Phase 2 : Plan

Develop the minimal plan that can produce complete and testable results.

For subjective work, when the choice of direction has a substantial impact on quality, produce 2 – 3 A truly different direction. Choose one and record the reason.

Phase 3 : Build

Handle one meaningful, testable unit at a time.

Keep work behavior outside the current unit.

When version control is available, create checkpoints before making large-scale or high-risk changes.

Phase 4 : Run

Use artifacts in their actual medium as much as possible.

Example:

• Web: Launch and browse in a browser
• App: Test user interface, API, and persistent state
• Game: Play the core loop
• Video: Check the timeline and rendered frames
• Writing: Compare with source and voice reference

Phase 5 : Verification

First, run deterministic checks.

Then usereferences/quality-rubric.mdto perform subjective review.

Each pass item must include observable evidence.

Phase 6 : Fix

Only fix failed or returned criteria.

Do not rewrite unrelated work sections.

After failing the same standard twice, stop repeating the same approach and change the basic strategy.

Phase 7 : Retest

Rerun the failed checks and all related regression checks.

Updatescorecard.json.

Phase 8 : Stop

Stop when any of the following occurs:

• All difficult levels are completed and the target score is reached
• Improvement stagnates within two rounds
• Maximum number of iterations reached
• Cost or time budget reached
• Requires manual approval

Use the highest scoring valid checkpoint, instead of automatically using the latest one.

Difficulty Levels

The result fails if any of the following applies:

• [Absolute condition one]
• [Absolute condition two]
• [Absolute condition three]
• Claiming completion without necessary verification
• Failed verification is hidden or described as passed
• Performing unauthorized irreversible operations

Quality standards

Score for each category from 0 To 100 :

• Accuracy: [Definition]
• Completeness: [Definition]
• Usability: [Definition]
• Originality or Style: [Definition]
• Skill: [Definition]

Minimum overall score: 85

Failures to meet mandatory thresholds cannot be offset by a high average score.

Assessment result format

Return:

{
  "overall_score": 0,
  "hard_gates_passed": false,
  "criteria": [
    {
      "criterion_id": "",
      "score": 0,
      "passed": false,
      "expected": "",
      "observed": "",
      "evidence": "",
      "severity": "",
      "likely_cause": "",
      "minimal_fix": "",
      "retest_method": ""
    }
  ],
  "best_checkpoint": "",
  "next_action": ""
}

Supporting Scripts

Usage: Available scripts:

• Sliptz/Verification.* — outgoing mine verification

• Script/Check.* — Artifact Detection

• Script/Academic.* — Score Summary

Run script with non-interactive parameters.

Unless otherwise explicitly defined in the script documentation, non-zero exit codes are considered failures.

Completion Report

Report:

1 . What was created or changed

1 . Location of the output

1 . Assumptions made

1 . Validation commands run

1 . Results and evidence

1 . Remaining limitations

1 . Selected Best Checkpoint

This is a general form that does not easily break the standard specifications.

Specific to Claude Codecontext: fork,allowed-tools, dynamic scene injection, etc., are only added when needed by Claude-specific Skills. In Codex, you can useagents/openai.yamlto set UI information, implicit trigger strategies, dependent tools, etc. In the first few general Skills, do not overuse platform-specific features, as this makes them easier to operate.:contentReference[oaicite: 13 ]{index= 13 }

---

Chapter Seven: Create a Skill from a Successful Conversation

In fact, there is a stronger method than thinking about a skill from scratch.

First, have Claude or Codex actually complete a task.

This conversation includes the following.

• The initial vague request
• Conditions added along the way
• Mistakes made by the AI
• Human corrections
• The method that ultimately succeeded
• Personal preferences
• On-site specific considerations

Turn this conversation into a skill.

この会話で行った作業を分析し、
再利用可能なAgent Skillへ変換してください。

単に会話を要約するのではなく、
次のものを抽出してください。

1. 最初の依頼には含まれていなかったが、
   成功に必要だった追加情報

2. 私が途中で修正した内容

3. AIが合理的に推測すると間違える、
   この分野またはプロジェクト固有のGotcha

4. 毎回再利用できる工程

5. 自動化できる検証

6. 参考資料へ分離すべき知識

7. 良い出力例と悪い出力例

8. Skillが発火すべき依頼と、
   発火してはいけない近接依頼

9. 成功条件、HARD GATES、終了条件

10. 今回の一例だけに過剰適合しないために、
    一般化すべき原則

一般的すぎる助言は除外してください。

例：
「高品質にする」
「適切にエラー処理する」
「ベストプラクティスに従う」
だけでは不十分です。

現実の作業で得られた、
具体的な手順、判断基準、失敗条件、検証方法を優先してください。

現在の会話だけでは足りない部分は、
推測と事実を分けてassumptions.mdへ記録してください。

完成後は、SkillありとSkillなしで評価できる
trigger evalsとoutput evalsも作ってください。

In the official Agent Skills guide, it is also emphasized that skills should not be written solely based on general knowledge, but should be extracted from practical operations, API specifications, review comments, past modifications, failure cases, etc., to ensure professionalism.

Chapter Eight: Add-On Instructions for Different Skill Types

Please add the following content to the end of the initially displayed complete prompt.

A. Natural Japanese Writing Skill

Additional Requirement: Japanese Writing

In this skill, please do not interpret "humanistic" as a typo or random expression.

Please design "humanistic" as the following elements.

• Specificity of observation
• Variation in sentence length
• Distribution at the end of sentences
• Balance between Chinese characters and hiragana
• Rhythm according to emotions
• Assertion and reservation
• Distance from the reader
• Leaving spaces without over-explaining
• Conciseness of emphasizing sentences
• Vocabulary unique to the individual

Please divide the article creation into the following steps.

1 . Organizing facts and claims 2 . Reader’s emotional curve 3 . Composition 4 . Converting to sound 5 . Eliminating AI-style uniformity 6 . Preservation of facts 7 . Confirmation of assumed reading rhythm

Please add a mechanism to check the following items.

• Consecutive occurrences of the same sentence ending
• Consecutive sentences of the same length
• Overuse of conjunctions
• Excessive use of abstract words
• Unfounded emotions
• Fabricated experiences
• Unnatural bullet points
• Articles that try to explain everything
• Overuse of headings
• Formulaic AI expressions

If there are samples of your own articles, please create a voice-profile.md.

But do not directly copy a large amount of your original words; please abstract its characteristics.

In the final evaluation, please rate authenticity, voice, rhythm, specificity, emotional shifts, and distance from the reader separately.

B. Vibe Coding Skill for Non-Engineers

Additional Requirement: Vibe Coding for Non-Engineers

Do not start writing code immediately based solely on the user’s vague request.

Please first create the following.

• product-brief.md
• user-journeys.md
• acceptance-criteria.md
• out-of-scope.md
• feature-ledger.json

Do not use technical terms; write specifications based on features the user can realistically implement.

For example:

Bad specification:
"Implement CRUD API"

Good specification:
"The administrator can add products,
and the products will remain even after the page is reloaded,
and will be displayed in the product list of regular users"

Please complete one feature at a time.

Please check the UI, API, saved state, and error state of each feature.

Please set the following as HARD GATE.

• Main buttons are just for appearance
• Data is only stored in state
• API returns fixed values
• Authentication and permissions are only displayed in the UI
• Error states are not implemented
• Claimed completion without testing
• TODO, FIXME, mock, placeholder remain in main features

The final report should be written in language that even non-engineers can understand, explaining:
"What can be done"
"How to test"
"What cannot be done yet"

C. Web Production Skill Aiming at 1000万-Yen Quality

" 1000 "Quality worth ten thousand yen per order" cannot be guaranteed by skill alone.

High-end web production includes business understanding, customer research, brand strategy, shooting, copywriting, design, implementation, verification, and project management.

However, you can approach that production process.

Additional requirement: Advanced web design

Before writing HTML or components,
be sure to go through the Visual Identity Gate.

Please define the following in DESIGN.md.

• Brand purpose
• Target customers
• Emotion
• Brand promise
• Differences from competitors
• Role of color
• Typography
• Photo or illustration guidelines
• White space
• Layout principles
• Action principles
• Expressions not to use

Do not automatically move to the next step without reason.

• Purple gradient
• White card arrangement
• Centered hero section
• Generic SaaS layout
• Raw UI library defaults
• Meaningless halo effects
• Overly rounded corners
• Stock photos used without purpose

Before implementation, please create 2 〜 3 different art directions (Art Direction).

Not just the color is different,
please change the composition, density, layout, images, and the logic of movement.

Evaluation criteria:

• Design quality: whether it works as a whole world
• Originality: whether there is a unique judgment
• Craftsmanship: text arrangement, white space, color, precision
• Functionality: whether the purpose can be achieved without confusion

Please focus on evaluating design quality and originality.

Please check the following content in the browser.

• 375 px
• 768 pixels
• 1440 Pixels
• Long articles
• Short articles
• Empty state
• Error state
• Keyboard operation
• Focus display
• Menu
• Form
• Primary CTA
• Broken link
• Contrast
• Horizontal scrolling
• Overflow

Do not judge qualification based solely on static images; please interact with the page.

In Anthropic’s frontend experiments, design quality, originality, accuracy, and functionality are also distinguished, and Evaluators assess actual pages in loops using Playwright. In particular, the evaluation not only considers the basic accuracy that models are good at but also highly values design quality and originality, attempting to depart from general AI design.

D. Application production skills

Additional conditions: Application production

Please design with a focus on user state transitions, rather than the number of pages.

Please define the following content.

• User Type
• Permissions
• Input
• Save State
• Asynchronous Processing
• Failure
• Retry
• Empty State
• Loading
• Audit
• Notification
• Session

Please verify the main functions from the following four aspects.

1 . UI 2 . API 3 . Database or persistent state 4 . Log or error

Do not use ‘page display’ as the completion criterion.

Example:

Completion criteria for the settings change feature:

• Users with permission can make changes
• Users without permission cannot make changes
• Values remain after saving and reloading
• API responds correctly
• Database values are updated
• Recovery method is displayed on failure

If adding AI functionality,
consider whether you can operate the application’s own features through the tool, rather than just making an interface that looks like a chat box.

E. Game development skills

Additional criteria: Game development

Please first complete the smallest "playable vertical slice" work, rather than accumulating content first.

Please first define the following.

• Pillars of the game
• 30 – Core loop in seconds
• Player goals
• Failure
• Rewards
• Learning
• Tension and release
• Retry
• 1 – Play duration

Please divide the evaluation into three categories.

Technical checker:

• Crashes
• Frame rate
• Input
• Collision detection
• Save
• Reproducibility

System checker:

• Difficulty
• Economy
• Strategy monotony
• Deadlock
• Reward balance

Feel Checker:

• Input lag
• Hit feeling
• Sound effects
• Camera
• Indicators
• Retry speed
• Whether you want to play again

Please use a fixed seed or fixed input sequence to create tests for comparing before and after modifications.

Do not approve just because the screenshots look good; please actually play through the core loop.

F. HyperFrames Video Editing Skills

Additional Requirement: HyperFrames Video Production

Before writing HTML, be sure to create DESIGN.md or visual-style.md first.

Please carry out the project in the following order.

1 . What
What to let the audience experience

2 . Structure
Scenes, composition, tracks, materials

3 . Timing
Size, rhythm, turning points, emotional peaks

4 . Layout
Complete the Hero Frame for each scene in static form

5 . Animate
Based on the completed positions, add entrances and movements

Before the static layout is completed,
do not use animation to cover positions.

Please set the following content as a HARD GATE.

• Do not write HTML without visual verification
• Do not use Math.random or rely on time-based content
• Do not use infinite loops
• Do not forget to register the timeline
• Do not let the same property of the same element conflict
• Do not use jump cuts without transitions in multiple scenes
• Do not ignore text overflow
• Do not ignore contrast warnings
• Do not say it’s complete before the final rendering is confirmed

After completion, please perform the following actions.

• npx hyperframes lint
• npx hyperframes validate
• npx hyperframes inspect
• Animation map
• Draft render
• Final render

Please divide the evaluation roles into three categories.

Story Inspector:
Story, information density, promise at the beginning, emotional peaks, aftertaste

Visual Inspector:
Typography, composition, line of sight, color, action hierarchy

Technical Inspector:
Timeline, media, overflow, contrast, certainty, rendering

Only modify the failed scenes.

Even in the core skills of HyperFrames, the production process is organized in the order of What, Structure, Timing, Layout, Animate. First determine the visual identification, then statically create the most prominent Hero Frame element, and then add animation.

In addition, decisiveness, limited repetition, timeline registration, scene switching, overflow, contrast, animated maps, etc., are defined as validation items.

G. Video Generation MCP · Script Making Skills

Additional Conditions: Video Generation MCP and Script Making

Please do not directly send a user’s sentence to the video generation model.

Please carry out the following transformations.

Purpose
→ Commitment to the audience
→ Emotional changes
→ Rhythm table
→ Scene objectives
→ Camera specifications
→ Provider adapter
→ MCP tool calls

Please separate the specific specifications of the video model from story and camera design.

General lens specifications should include the following contents.

• shot_id
• story_purpose
• duration
• subject
• action
• environment
• camera
• composition
• lighting
• palette
• motion
• continuity_in
• continuity_out
• negative_constraints
• acceptance_criteria
• reference_assets
• seed or ID used for reproduction

Please create an adapter for each video provider to convert the generic Shot Spec.

Please separate volatile information, such as model names, duration, resolution, reference images, API specifications, etc., into references or MCP Resources.

Please confirm the composition first using cheap keyframes, low resolution, and short duration.

Continuity Checker please confirm the following.

• Face
• Costume
• Props
• Screen direction
• Lighting
• Time of day
• Camera speed
• Character’s intention
• The role of the shot in the story

Only regenerate the failed shots.

Do not redo the entire image every time.

Please do not assume the quality has improved just by adding cinematic, masterpiece, 8 and K and other adjectives in the prompt.

Please structure the subject’s verbs, camera, composition, lighting, coherence, and prohibited conditions.

Chapter Nine: Prompt for Improving an Existing Skill

Skills are not finished just because they are created once.

Please use the following content to make improvements based on the execution results.

Please improve the following Agent skills based on actual evaluation results.

Input:

• Current SKILL.md
• Reference materials
• Scripts
• Trigger evaluation results
• Output evaluation results
• Execution logs
• Failed assertions
• Manual review
• Tokens and execution time
• Comparison results with previous version

Improvement process:

1 . Classify failures to the next step

• Triggers
• Context
• Programs
• Tools
• Verification
• Evaluators
• Stop conditions
• Memory

2 . Identify the root cause, not the symptoms

3 . Determine which of the following is necessary

• Modify description
• Clarify steps
• Add references
• Delete references
• Create script
• Modify tests
• Strict evaluator
• Modify end conditions
• Split skill into two
• Remove instructions

4 . Only add the specific words of failed tests to the description to avoid overfitting

5 . Consider not only adding instructions, but also deleting them

6 . Save the old version

7 . Evaluate the new version in a different, clean context

8 . Confirm in held-out tests that were not used for learning as well

9 . Do not use the final version,
use the version with the highest score on the validation set

Output:

• failure-analysis.md
• proposed-changes.md
• Updated Skill
• changelog.md
• regression-evals.json
• Comparison between old and new versions

Even in the official evaluation guidelines, it is recommended to conduct each test by separating into Skill vs. no Skill, or old version vs. new version, using a clean context, and comparing specific assertions, evidence, tokens, and execution time.

Chapter Ten: Prompt for Fixing a Skill That Does Not Trigger

The content of the skill is excellent, but it will not be called.

This problem is very common.

Please improve the description of the skill from the perspective of trigger accuracy.

Please create the following content.

1 . ten tasks that should trigger 2 . ten similar tasks that should not trigger 3 . Reasons for their respective classifications 4 . Shortcomings of the existing description 5 . Parts of the existing description that are too broad 6 . Three improved description schemes 7 . Expected advantages and false trigger risks of each scheme

Please mix the following content during testing.

• Requests that clearly state the skill name
• Requests that do not state the skill name
• Conversational language
• Typos
• Single-sentence requests
• Overlong background explanations
• Requests hidden within multiple steps
• Other tasks using the same keywords

If possible, perform each request three times and record the trigger rate.

Please divide the test into training 60% and validation 40% .

Improvement descriptions should only use training results, and the final solution should be chosen based on validation results.

Do not automatically adopt the final solution; please use the solution that scored highest in validation.

The official guide of Agent Skills also introduces methods such as trying the same request multiple times, measuring trigger rates, separating Train and Validation, and choosing explanations with better Validation scores instead of the final solution.

Chapter Eleven: Have the Model Create Validation Scripts

If you want to follow the rules, you should convert feasible parts into code as much as possible.

Please analyze the rules of this Skill,
and extract the content that does not rely on LLM subjectivity and can be verified by a machine.

Please categorize each rule as follows.

A. Fully machine-verifiable
B. Partially machine-verifiable
C. Requires human or LLM evaluation

For A and B,
please create the minimal necessary verification scripts.

Script requirements:

• No dialogue input
• Has –help
• Display usage examples when parameters are insufficient
• Specifically show error reasons
• Output JSON to stdout
• Output diagnostic logs to stderr
• 0 Indicates success
• Non-zero indicates failure
• Can be executed again
• Use –dry-run if possible
• Avoid large output
• Can locate the failure position
• Clear dependencies
• Fixed version
• Additional testing

In SKILL.md, please specify when each script is executed and what needs to be fixed if it fails.

In the Agent Skills script design guide, it is also recommended to use non-interactive mode, explicit –help, specific error messages, structured output, idempotency, Dry Run, safe default values, and meaningful exit codes.

Chapter Twelve: What to Do in the First Thirty Minutes

1 . Choose only one task

Do not create an all-purpose Skill from the beginning.

Bad examples:

Creating a Skill that handles articles, web pages, apps, games, and videos at the highest quality

Good examples:

Creating a Skill to make note articles from your voice memos

Creating a Skill for brand design and browser verification when making LPs

Creating a Skill to verify HyperFrames subtitles and layout

A Skill should have one core responsibility.

2 ．Paste the original complete prompt

Parts that are not understood can all be "handled".

3 ．Confirm the folder has been created

The following content is sufficient to run.

skill-name/
└── SKILL.md

In the Agent Skills specification, the minimum required file is SKILL.md; scripts/, references/, and assets/ are optional. There is no need to create a large number of files at the beginning.

4 ．Manual invocation

At first, do not wait for automatic triggers.

If it’s Claude Code:

/Skill Name

If it’s Codex:

$skill-name

5 · Tested through three tasks

Normal Task

Fuzzy Task

Possibly Failing Task

For example, if it’s a writing skill:

Normal:
Turn this memo into a note article

Fuzzy:
Make it feel like it could be read

Boundary:
Where facts are lacking, appropriately write experiential stories

In the third task, observe whether it is possible to confirm or make clear assumptions without fabricating.

6 . Only correct one mistake

Do not aim for a perfect score at the beginning.

The article is good, but the sentence endings are too uniform

Then just improve the sentence ending check.

The webpage is beautiful, but it scrolls horizontally on mobile

Then just improve the responsive check.

When adding a large number of rules at once, you won’t know which change took effect.

Chapter Thirteen: Common Mistakes

Mistake one. Only writing abstract words

High-quality
Natural
Beautiful
Easy-to-use
Professional

These are not goals, but impressions.

Turn them into observable states.

Error two. Only add prohibitions

Absolutely do not~
Be sure to~

With only prohibitions, you don’t know how to judge.

Things to avoid
Principles for substitutes
Testing methods
Exceptional conditions

All must be written.

Error three. Put all content into SKILL.md

When a large number of reference materials are put into the main text, all of it enters the context each time.

Keep only the core process, and move the details to references/.

Error four. Only keep the good examples

If there are only good examples, it’s unclear where to consider something a failure.

examples/good/
examples/bad/

Prepare these, and write down the reasons for failure.

Failure five. Thinking it’s finished just by looking at the source code

Run what can be run.

Open what can be opened.

Play what can be played.

Render what can be rendered.

Failure six. Redo everything each time

Only correct the failed conditions.

Limit the scope of corrections.

Failure seven. Infinite loop

Decide the maximum number of times, passing score, improvement range, and cost limit.

Looping doesn’t mean the longer it runs, the better it gets.

Failure eight. Creating an all-purpose Skill

With an all-purpose Skill, the trigger conditions and evaluation methods become blurred.

For articles, web, applications, games, videos, divide Skills by domain while maintaining a common Loop Core.

Chapter Fourteen: Pre-Release Checklist

Skill Body

• Whether the name consists only of lowercase letters, numbers, and hyphens

• Whether the folder name matches the name

• Whether the description includes what it does and when to use it

• Whether boundaries that should not be triggered are clear

• Whether the main Skill has become too large

• Whether detailed information is read only when needed

• Whether it contains specific judgments or precautions, rather than general statements

Project

• Were success criteria defined before production

• Are HARD GATES, DEFAULTS, and PREFERENCES distinguished

• Was the physical object confirmed after creation

• Were generation roles and evaluation roles distinguished as needed

• Is there evidence for failure conditions

• Were only the failed parts corrected

• Are there termination conditions

• Was the best version saved

Evaluation

• Are there regular cases

• Are there ambiguous cases

• Are there any boundary cases

• Are there examples that should be triggered

• Are there near examples that should not be triggered

• Are there cases with no Skill, or comparisons with older versions

• Are the content that can be machine-determined scripted

• Has a subjective quality blind comparison been conducted

• Is manual review retained

• Does it comply with Token and time increases

Conclusion: Things that should be indicated at the beginning of Skill creation

Beginners do not need to write a perfect SKILL.md from the start.

You only need to communicate the following to the AI.

What I am repeating.
What counts as success if it can be done.
What kind of failure to avoid.
What is close to ideal.

Convert this information into the next step through Skill prompt creation.

Vague request
↓
Purpose
↓
Trigger condition
↓
Success contract
↓
Process
↓
HARD GATES
↓
Validation
↓
Evaluation
↓
Revision
↓
Re-validation
↓
End
↓
Learning

A truly useful Skill will not just command the model to "try harder".

• Cannot start hastily

• Cannot end without validation

• Failures cannot be hidden

• The same modifications cannot be repeated endlessly

• The same failures will not be forgotten next time

Build such an environment.

A Skill is not merely a clever prompt.

It is more like a small working system that allows AI to consistently reproduce high-quality results.

Truly turn this long template into your own Skill

Reading up to this point, the most common reaction is to copy the entire template into the project.

Wait a moment.

The value of a template is to help you see what parts a complete system might have. It does not require every skill to have the same complex organizational structure.

A safer starting point is to begin with repeated failures.

Find a task you have done multiple times. Put the most recent successful result and one failed result together, and clearly write down what the inputs are, what counts as completion, which types of errors must never occur, and which commands or evidence can be used to verify it.

Then, only write the rules that allow this task to be reliably repeated.

Describes being responsible for enabling the agent to discover it at the right time. The main text is responsible for defining the work sequence and hard gates. Reference documents preserve domain knowledge. Scripts are responsible for checks suitable for deterministic execution. Examples are responsible for informing maintainers which requests should trigger it, and which requests, although similar in keywords, do not belong to it.

Return to the eight-layer structure above and decide which layers belong in the main Skill and which should move into references, templates, or validation scripts.

When the task is vague, intention compilation is required.

When there is a lot of information, context loading on demand is required.

When output easily appears complete but is actually unusable, Maker and Checker need to be separated.

When failure can be locally repaired, a repair loop should be designed.

If the process spans multiple sessions, write the state outside the session.

Without these issues, there is no need to force them in just to make the architecture look advanced.

Do not confuse Codex’s AGENTS.md with Skills. AGENTS.md is used to tell Codex how to understand the repository, run tests, and follow project conventions. A Skill is more like a specialized workflow that can be invoked repeatedly. The two can work together, but their responsibilities are different.

To check whether a Skill is truly useful, you can perform a set of neighbor tests.

Give it a request that should clearly trigger it.

Give it an obviously irrelevant request.

Then give it another request that contains the same keywords but actually belongs to a different task.

The third type is the one that is really prone to problems.

Skills triggered solely by keywords often get exposed here.

After running, don’t just look at whether the final copy looks good. Keep track of what the agent read, what it called, whether the tests passed, how many rounds of fixes were made, and why it stopped. Codex provides verifiable evidence through terminal logs and test results. This kind of evidence is much more reliable than simply stating that it is completed.

When wrapping up, any Skill that can write files, execute commands, or touch external systems must have its permissions and stopping conditions specified upfront. Even after generating code, manual review and verification are still required; the agent’s completion declaration cannot be taken as proof of delivery.

A good Skill will not make the prompt appear grander.

It will make failures occur earlier, clearer, and easier to fix.