Claude Code Skills: Turning AI Prompts into Repeatable, Verifiable Workflows
Let AI Stop "Going by Gut Feeling" — Practice and Thoughts on Claude Code Skills
Starting from a real project directory, let's talk about what Skills are, how to use them, and why they are the most underestimated capability in AI programming.
Introduction: When AI Develops "Muscle Memory"
When collaborating with AI, we most often encounter two kinds of frustration:
- Having to teach it from scratch every time — Clearly, we just processed an identical meeting minutes format last week, and this time it has forgotten the format again.
- It understands, but the output is slightly off — The summary was written, the HTML was generated, but the layout is messy, tags are inconsistent, and there's information overload.
Skills were born to solve these two types of problems. They make AI behavior reproducible, verifiable, and iterable.
This article deconstructs the design philosophy of Skills starting from the .claude/skills/ directory of a real project.
1. What Exactly Are Skills?
My .claude/skills/ directory contains two Skills:
skills/
├── meeting-minutes/ # Meeting minutes generation
│ └── SKILL.md
└── tian-ai-daily/ # Tian Tian Daily AI News Overview
├── SKILL.md
└── templates/
└── daily-template.html
Each Skill is essentially a Markdown document — a "Standard Operating Procedure" written for the AI to read.
The reason this document is "useful" lies in its design approach.
2. Dissecting a Skill: Taking meeting-minutes as an Example
Opening meeting-minutes/SKILL.md, its structure is as follows:
2.1 Header: Precise Trigger Conditions
---
name: meeting-minutes
description: >
Generates structured meeting minutes from meeting transcripts or audio transcription text.
Triggers when the user provides meeting audio transcriptions, meeting text records, meeting notes,
or requests "generate meeting minutes", "organize meeting records", "meeting minutes".
---
Key Design: The content of the description is entirely focused on trigger conditions.
This is a verified best practice — if the description writes "this skill will first clean the text, then extract key information, and finally output according to a template", the AI might directly follow the description's summary to do the work, skipping the detailed instructions in the body. The more the description resembles an "index", the more likely the AI is to read the full body carefully.
2.2 Body: Recipe-like Steps
Step 1: Read through the full text, clean up irrelevant content
Step 2: Identify key information
Step 3: Output according to the template
Each step is an actionable verb: Identify → Extract → Output. Do not write vague instructions like "you should understand the meeting content", but write "leave uncertain content blank, prefer leaving it blank over fabricating".
2.3 Bottom Line: The Principle of Leaving Blank Over Making Up
The most core sentence in the Skill is:
Leave uncertain content blank, prefer leaving it blank over fabricating. Fabricated information is more harmful than missing information.
This is the safety boundary drawn for the AI. Without this rule, the AI tends to "reasonably speculate" when information is insufficient — and speculation in meeting minutes is an accident.
3. Looking at a More Complex Skill: ai-daily
ai-daily/SKILL.md demonstrates an advanced usage of Skills: workflow orchestration + template separation.
3.1 Five-Step Workflow
| Step | Content | Tool |
|---|---|---|
| Step 1 | Search multiple news sources in parallel | WebSearch × 5 |
| Step 2 | Intelligent filtering (keep/discard criteria) | Rule Engine |
| Step 3 | Generate Chinese summary (50-100 characters) | AI Summary |
| Step 4 | Apply HTML template to generate page | Read template → Replace placeholders |
| Step 5 | Output confirmation | File path + statistics |
Each step has a specific criteria table. For example, the filtering criteria for Step 2:
Keep (meets any):
- Major releases or updates from top AI companies
- Important model/tool releases from the open-source community
- Significant changes in AI policy and regulation
- Financing/M&A exceeding $100 million
Discard:
- Pure opinion/commentary articles
- Minor patch version updates
- News older than 48 hours
Each step is an executable and verifiable conditional judgment.
3.2 Template Separation
SKILL.md is only 124 lines, but it references templates/daily-template.html (374 lines). Why not write the HTML in the body?
Because HTML is heavy reference content — it doesn't need the AI to re-understand it every time, only to read and replace. After separation:
- SKILL.md remains lean, allowing the AI to quickly scan the workflow
- The template file is maintained independently; changing the template doesn't require touching the workflow
This is exactly the core principle of Skill design: the body talks about workflow and judgment, attachments hold "ready-to-use" materials.
3.3 Real-world Output
ai-daily-2026-07-17.html is the output of one actual run of this Skill — a beautifully styled HTML page with a purple gradient header and 12 news cards, each with tags and source links. This is the meaning of a Skill's existence: to make every output reach the same standard.
4. Three Core Principles of Skill Design
From the practice of these two Skills, three principles are distilled:
Principle 1: Trigger > Workflow
The description field of a Skill only writes "when to use it", not "what it will do".
- ✅ Good description:
Triggers when the user provides meeting audio transcriptions or meeting text records - ❌ Bad description:
This skill first cleans the text, then extracts key information, and finally generates meeting minutes according to a template
The reason is counter-intuitive: upon seeing a bad description, the AI will directly follow the description to do the work, skipping the skill body. The more the description resembles a "table of contents", the more likely the AI is to read the full skill carefully.
Principle 2: Standards > Judgment
AI's judgment is unreliable, especially when information is incomplete. A good Skill replaces AI judgment with explicit rules:
| Scenario | Vague Instruction | Explicit Standard |
|---|---|---|
| Filtering news | "Pick the important ones" | "Keep if it meets any keep criteria" |
| Summary length | "Write it short" | "50-100 Chinese characters" |
| Uncertain information | "Reasonably speculate" | "Leave blank, never fabricate" |
Principle 3: Template > Generation
Letting AI "create" an output format from scratch every time inevitably leads to inconsistent results. A good Skill provides templates or examples:
meeting-minutesprovides a complete output template (table structure, field order, placeholder rules)tian-ai-dailyprovides a reusable HTML template (374 lines of complete styling + placeholder markers)
Templates change the AI's role from "designer" to "filler" — the latter has a much lower error probability than the former.
5. When Is It Worth Writing a Skill?
Not all repetitive tasks are worth turning into a Skill. My criteria are:
| Worth Writing a Skill | Not Worth Writing a Skill |
|---|---|
| Same pattern used 3+ times | One-off task |
| Strict output format requirements | Flexible format, anything goes |
| Requires filtering/screening/judgment criteria | Only needs to execute fixed commands |
| Other team members will also use it | Personal preference used only by you |
| Steps are easily missed or distorted | Steps are simple, impossible to get wrong |
Taking meeting-minutes as an example: the minutes format requirement is consistent for every meeting, but the input format varies greatly across meetings (audio transcription, handwritten notes, oral summaries). This constitutes a typical scenario of "high repetition + variable input + strict output" — the perfect condition for a Skill.
6. Limitations and Future of Skills
The current limitations of Skills are equally noteworthy:
- Static documents — Skills do not evolve automatically. Every workflow change requires manually updating SKILL.md.
- Stateless — Skills cannot "remember" preferences or user feedback from the last use.
- Discovery mechanism relies on keyword matching — If the description is not written precisely, the AI might never actively load it.
- No verification loop — There is no automatic check mechanism for whether a Skill was executed correctly.
But these limitations are also where the elegance of Skills lies: it is simple enough to have zero barrier to entry. One Markdown file + one directory can change AI behavior from "random improvisation" to "precise execution".
7. Conclusion
Returning to the initial question: What are Skills?
It is a Markdown file — that is its form.
But its real function is: to translate your expectations of "how AI should work" into executable, non-distorting instructions for the AI.
When you find yourself repeatedly correcting the same AI mistake, or starting every conversation with "Same as last time, but..." — that is the moment you need to write a Skill.