Claude Code Skills Are Just a YAML Header and a Markdown Body

Today's topic originates from a very real pain point—endless meetings, endless minutes.

Have you ever experienced this scenario: a meeting ends, and the boss, product manager, and developers have all been talking over each other. The recording transcription dumps a block of text thousands of words long into your hands. Then you have to dig out "who said what," "what was decided," "who will execute," and "when it will be completed." This task is highly repetitive, highly structured, yet unavoidable.

Not to mention having to browse TechCrunch, Hacker News, and Reddit daily to follow AI news—the routine is the same, but you have to repeat it every single day.

These are all perfect tasks for Claude Code Skills.

In this article, I'll use two real Skill examples—meeting minutes generation and AI daily news generation—to walk you through how Skills are packaged, and how the underlying "mold" (skill-creator) is designed. By the end, you'll see that the fixed format of a Skill is actually very simple. Once you master it, you can package any repetitive task yourself.

1. First, Look at the Output: What the Two Skills Can Do

1.1 meeting-minutes: Transcription → Structured Minutes

This is the first scenario. You have a transcribed text from a department team-building meeting recording, like this:

Speaker 1 00:22
Today the four of us are here to touch base and have a small meeting. Mainly about our company,
our small department hasn't had a team-building event in a long time...

Speaker 2 00:45
Masks shouldn't be a problem.

Speaker 1 00:48
So, does everyone think we need a team-building event now?

Speaker 2 00:51
I think a team-building event is necessary.

Speaker 3 00:53
Yeah, we need to have some fun, right? The market work pressure is too high.

Nearly 500 lines, four people, chattering about where to go for team building. Manual organization would take at least half an hour.

The output of the meeting-minutes Skill looks like this:

# Meeting Minutes

## I. Basic Meeting Information
| Item | Content |
|------|------|
| Meeting Topic | Department Team-Building Activity Plan Discussion |
| Attendees | Speaker 1 (Department Head/Facilitator), Speaker 2 (Male Colleague Representative)... |

## III. Meeting Content
### Topic 1: Is It Necessary to Organize a Team-Building Event?
**Discussion:**
- Speaker 1 noted the department hasn't had a team-building event in eight months and asked for opinions.
- Speaker 2 believes a team-building event is necessary to enhance colleague friendship and trust.

**Conclusion/Consensus:**
All members unanimously agree that organizing a team-building event is necessary.

## IV. Action Items
| No. | Action Item | Responsible Person | Deadline |
|------|----------|--------|----------|
| 1 | Apply for team-building funds from leadership | Speaker 1 | |
| 2 | Determine specific venue and book it | | |
| 3 | Book a charter bus | | |

Oral transcript → Basic meeting information → Topic discussion + conclusions → Action items → Pending matters → Next meeting arrangements. Fully automated.

1.2 xie-ai-daily: Multi-Source Search → Elegant Daily News

The second scenario is more routine—needing to stay updated on AI industry trends daily but lacking the time to browse websites one by one.

The xie-ai-daily Skill searches TechCrunch, The Verge, Hacker News, and Reddit in parallel, filters 8-15 high-value news items, generates Chinese summaries, tags them with keywords, and finally outputs an HTML page like this:

Dark gradient Header, centered displaying "Xie's AI Daily" and a date badge
Stats bar: Curated X items / Covering X domains / Sourced from X media outlets
Quick filter tag bar (click "OpenAI" to see only relevant cards)
Each news item as a card: source badge + title + Chinese summary + keyword tags + original link
Responsive layout, viewable on mobile

Generate a new HTML file every day, open it, and you have an elegant daily news digest.

Key Point: These two Skills solve the same type of problem—input unstructured data, output structured results in a fixed format. Meeting minutes are like this, and AI daily news is like this.

2. skill-creator: The "Mold" for Making Skills

The two Skills above weren't written out of thin air; they were created using Anthropic's officially provided skill-creator. You could say skill-creator is the "Skill for making Skills."

Let's dissect its internal structure:

skill-creator/
├── SKILL.md              ← Core: Defines how to create/iterate/evaluate/package a Skill from scratch
├── agents/               ← Sub-agents: "Scorers" to help you evaluate
│   ├── grader.md         ← Evaluates if output meets criteria based on assertions
│   ├── comparator.md     ← Blind A/B test comparing which of two Skill versions is better
│   └── analyzer.md       ← Analyzes benchmark data to find statistical blind spots
├── scripts/              ← Automation scripts
│   ├── package_skill.py  ← Package into a .skill file
│   ├── run_eval.py       ← Run evaluation
│   ├── run_loop.py       ← Optimize description trigger accuracy
│   ├── aggregate_benchmark.py ← Aggregate benchmark data
│   └── ...
├── references/           ← Reference documents (loaded on demand, not resident in context)
│   └── schemas.md        ← JSON data structure definitions
├── eval-viewer/          ← Evaluation result visualization
│   ├── generate_review.py
│   └── viewer.html
└── assets/
    └── eval_review.html  ← Trigger word evaluation review page

The core philosophy of skill-creator is the "iterative loop":

Write draft → Run test cases (parallel: with Skill vs without Skill) → 
Score + View output → Collect feedback → Improve Skill → Run tests again → 
Repeat until satisfied → Package .skill file

The most ingenious design in this loop is "parallel comparative evaluation": each test case runs two versions simultaneously—one with your Skill, one without (baseline). Then benchmark data is generated for comparison: How much did the pass rate improve? Did time consumption increase or decrease? How much did token consumption increase?

With data, optimization has a direction.

3. Methodology Summary: The Fixed Format of SKILL.md

Looking at the two outputs (meeting-minutes, xie-ai-daily) and the mold (skill-creator) together, a common skeleton emerges—every Skill consists of the following structure:

skill-name/
├── SKILL.md          ← Required
├── scripts/          ← Optional: Executable scripts
├── references/       ← Optional: Reference documents
└── assets/           ← Optional: Static resources like templates, icons

And SKILL.md itself has only two fixed parts:

Part 1: YAML Frontmatter

---
name: meeting-minutes
description: Generates structured meeting minutes from meeting transcripts. Use this skill when the user provides meeting records, meeting transcripts, recording-to-text content, or mentions keywords like "会议纪要", "整理会议", "meeting minutes", "生成纪要".
---

name: Unique skill identifier, English kebab-case.
description: This is the most important field. Claude decides whether to trigger your Skill based on this text. Clearly state two things: what this Skill does + when to use it. Keywords should be specific, scenarios should be clear.

A counterexample—if the description only says "generate meeting minutes," when a user says "help me organize this meeting recording," Claude might not trigger your Skill. But if you write "when the user mentions keywords like '会议纪要', '整理会议', 'meeting minutes', '生成纪要'," the hit rate significantly increases.

💡 A tip: skill-creator's scripts/run_loop.py is specifically designed to optimize the description—it generates 20 trigger evaluation queries (ones that should trigger + "synonym traps" that shouldn't), automatically iterates 5 rounds, and finds the best description.

Part 2: Markdown Body (Instruction Body)

Everything after the YAML block is the Skill's "expert brain." There's no mandatory format, but five modules have become standard for almost all good Skills:

Module	Purpose	meeting-minutes Example	xie-ai-daily Example
Processing Flow	Step-by-step SOP	Read full text → Clean content → Structured output	Multi-source fetch → Smart filter → Generate summary → Tag → Generate HTML
Output Template	Lock format with code blocks	Markdown tables (Basic Info/Topics/Action Items/Pending Matters)	HTML template (`{{DATE}}` `{{NEWS_CARDS}}` placeholders)
Quality Requirements	Standards for good output	Completeness, Accuracy, Conciseness, Honesty (leave blank if uncertain)	Timeliness, Authority, Diversity, Accuracy, Readability
Examples	Input → Output comparison	A segment of oral transcript → Complete meeting minutes	—
Notes	Edge cases	Mark `[inaudible]` when multiple people speak simultaneously, record each faithfully	—

Summarized in one sentence: Tell the AI what to do first, what to do next, what the output should look like, what counts as good, give an example, and then explain where the pitfalls are.

4. Writing Principles: Less MUST, More Why

skill-creator itself is an excellent writing template; it mentions a very important principle:

"Try hard to explain the why behind everything you're asking the model to do. If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag."

Translation: Don't pressure the AI with screens full of capitalized MUST and NEVER; instead, clearly explain "why doing it this way is important."

For example, when writing quality requirements in meeting-minutes, instead of writing:

MUST NOT add any information not in the original transcript.

Write:

- **Honesty**: When information is uncertain, leave it blank rather than fabricate.

The effect is the same, but the latter allows the AI to "understand" the intent, rather than passively obeying a command. This is like training a new hire—telling them "why you should check this way" is a hundred times more effective than yelling "don't make mistakes."

A few other principles:

Use imperative sentences ("Read the full text," "Output according to the template"), not consultative tone
Keep it under 500 lines, split into references/ as a secondary index if exceeded
Example-driven, one good Input → Output comparison is worth a thousand words

5. The "Input → Output" Loop of the Two Skills

Finally, let's connect this entire system and look at a panoramic view:

                    ┌─────────────────────┐
                    │    skill-creator     │
                    │  (Mold for Skills)   │
                    │                     │
                    │  Define flow → Test  │
                    │  → Score → Improve → Package │
                    └────────┬────────────┘
                             │ Use mold to create
              ┌──────────────┼──────────────┐
              │                             │
              ▼                             ▼
   ┌──────────────────┐          ┌──────────────────┐
   │  meeting-minutes │          │   xie-ai-daily   │
   │──────────────────│          │──────────────────│
   │ Input:             │          │ Input:             │
   │ meeting_content  │          │ WebSearch multi-  │
   │ .txt (transcript) │          │ source results    │
   │                  │          │                  │
   │ Process:             │          │ Process:             │
   │ Read→Clean→Structure │          │ Fetch→Filter→Summarize │
   │                  │          │ →Tag→HTML       │
   │                  │          │                  │
   │ Output:             │          │ Output:             │
   │ meeting_minutes.md │          │ XieAI_Daily-       │
   │ (Structured Markdown) │          │ 2026-07-17.html  │
   └──────────────────┘          └──────────────────┘
              │                             │
              └──────────┬──────────────────┘
                         │ Methodology extraction
                         ▼
              ┌──────────────────┐
              │  readme0717.md   │
              │──────────────────│
              │ SKILL.md Fixed Format: │
              │                  │
              │ 1. YAML Metadata    │
              │   name + desc    │
              │                  │
              │ 2. Markdown Body  │
              │   Flow+Template+Quality   │
              │   +Examples+Notes  │
              └──────────────────┘

Input → Skill → Output → Methodology Extraction, these four stages form a complete learning loop.

Today's Takeaways

Skills solve "repetitive + structured" problems—meeting minutes and AI daily news both fit this characteristic. Once packaged, each invocation takes just seconds.
SKILL.md has only two fixed parts: YAML header (name + description) and Markdown body. Whether the description is well-written directly determines if the AI can trigger your Skill at the right moment.
skill-creator is the "meta-Skill"—it defines the standardized creation process for Skills: capture requirements → write draft → run parallel tests (including baseline) → score → improve → package. This methodology applies to creating any Skill.
Core principles for writing Skills: Explain "why" rather than piling up MUSTs, keep it under 500 lines, be example-driven, use progressive loading (metadata → body → references).
The biggest inspiration from the two practical outputs: An unstructured → structured pipeline can run with just a well-written SKILL.md.

#ClaudeCode #AIAutomation #SkillDevelopment #ProductivityTools #PromptEngineering