Skill writing tutorial
A beginner-friendly tutorial for writing Agent Skills: decide whether a skill is needed, write the minimum SKILL.md, add resources, audit, verify, and iterate. It is rewritten around a practical learning path and expanded with Fluxly installation, audit, search, and detail-page experience.
Why skills exist
A skill solves the problem of explaining, correcting, and re-supplying the same workflow again and again. It is not a prompt bookmark; it is a reusable playbook for an agent with trigger boundaries, execution order, resources, verification, and stop conditions.
Repeated workflows with easy-to-miss steps
Reports, file conversion, CI triage, code review, design QA. If you explain the same long workflow a third time, turn it into a skill.
Private context and fixed acceptance criteria
Team rules, schemas, templates, scripts, output contracts, and verification commands belong in a skill because they standardize execution.
One-off, low-risk, already reliable tasks
For temporary Q&A, simple rewriting, or open-ended ideation without fixed resources, a normal prompt is lighter.
The minimum runnable model
The smallest skill is a folder with SKILL.md. The frontmatter name identifies it, description is the trigger surface, and the body is read only after activation. Beginners should get this file right before adding scripts or long references.
---
name: commit-message-helper
description: Draft 3 Conventional Commit candidates from the current repository's staged git diff.
Use when the user asks to write, polish, or choose a commit message for staged changes.
Do not use for general Git questions or Conventional Commit explanations.
---
1. Run `git diff --staged --stat` and `git diff --staged`.
2. If there is no staged diff, stop and say no staged diff is available.
3. Use only the staged diff to identify type, subject, and optional scope.
4. Output exactly 3 candidates as `type(optional-scope): subject`.
5. Keep each subject under 72 characters and do not end with a period.
6. Add scope only when paths or diff make it obvious.
7. Never run `git add`, `git commit`, `git push`, or edit files.
Trigger tests:
- Should trigger: "write 3 commit messages for staged changes".
- Should not trigger: "what Conventional Commit types exist?"
- Should stop: `git diff --staged` is empty.- Use lowercase kebab-case for name.
- description says what it does, when to use it, and when not to use it.
- The body contains only post-trigger actions, evidence, stop conditions, and output format.
Discover and reuse high-quality skills first
Do not start from a blank file by default. Official examples and maintained repositories offer strong structure references, but you must audit before installing; stars and screenshots are only discovery signals.
Official examples, active repos, and similar task histories.
Read SKILL.md, references, scripts, assets, and dependency notes.
Run in a low-risk sandbox and inspect trigger, output, and side effects.
Keep the structure; replace business rules, acceptance criteria, and language preferences.
Audit before installing
- Read SKILL.md, references, scripts, assets, and dependency notes completely.
- Check for hard-coded secrets, private paths, log uploads, callbacks, or credential reads.
- Check whether scripts delete files, change global config, use network, commit, publish, or run dangerous commands.
- Confirm trigger rules, stop rules, negative examples, verification, and output format have no obvious gaps.
Skill folder anatomy
A good skill separates always-read instructions from branch-specific resources. SKILL.md stays readable; long references, scripts, and templates live in their own directories.
| Path | Required | Role |
|---|---|---|
SKILL.md | Required | Core instructions: frontmatter, trigger boundary, workflow, stop conditions, output contract. |
references/ | Optional | Long references: API docs, schemas, standards, glossaries, review checklists. Load only when needed. |
scripts/ | Optional | Deterministic scripts: validators, converters, batch jobs, repetitive commands. |
assets/ | Optional | Reusable output assets: templates, images, sample files, prompt snippets. |
agents/openai.yaml | Optional | Codex UI metadata, default prompt, tool dependencies, and display policy. |
Core mechanism: progressive disclosure
Startup index
The agent sees only name, description, and path at startup; description must be short, precise, and triggerable.
Load after match
After a request matches the description, the agent loads full SKILL.md. The body executes; it does not advertise itself.
Expand during execution
References and scripts are loaded only for the branch that needs them, keeping context small.
Skill vs Prompt, Tool, MCP, and Subagent
| Concept | Practical test |
|---|---|
提示词 | Prompt: one-off instruction, usually copied and pasted, no bundled files. |
AGENTS.md | Project/global collaboration contract, persistent but not task-packaged. |
Skill | Reusable playbook and toolkit for a task family, with references/scripts/assets. |
工具 / MCP | Tool / MCP: callable capability such as files, browser, GitHub, database; not the workflow itself. |
子代理 | Subagent: a worker with separate context, useful for parallel research, independent validation, or review. |
Modern workflow: AI drafts, humans own boundaries
Tools like skill-creator can draft folders and SKILL.md, but a draft is not a working skill. You own real tasks, trigger boundaries, negative examples, acceptance criteria, and risk limits; AI organizes them into reviewable files.
You provide
- When it should and should not trigger.
- Real task traces, inputs, failure cases, existing scripts.
- What success looks like and what verification must run.
- Which actions require confirmation and which are forbidden.
AI can draft
- SKILL.md steps, stop rules, and output template.
- Suggested split across references, scripts, and assets.
- Trigger tests, negative tests, and verification checklist.
- Iterative rewrites backed by verifiable evidence.
Extract from real traces, not imagination
- Run the workflow once in real files, environment, and goals.
- Record assumptions, tool order, recovery steps, verification commands, and final output.
- Extract a reviewable workflow outline before writing the final skill.
- Add boundaries, risks, negative examples, and acceptance criteria.
- Generate the final SKILL.md and regression-test with real prompts.
Quality bar for stable skills
Real, repeated, error-prone task with fixed resources or acceptance criteria.
description states what it does, when to use it, and when not to use it.
Few strong branches tied to user confirmation, files, schemas, tests, diffs, or external evidence.
SKILL.md stays short, continuous, executable; long material goes to references, repeated action to scripts.
Destructive actions, publishing, push, credentials, global config, and external side effects need stop rules.
Validate with should-trigger, should-not-trigger, should-stop, and with/without comparisons.
Routing should be few, strong, and verifiable
Routing lets an agent choose branches. Branches are not bad; weak judgments and delayed feedback are. When low-risk execution can produce evidence, execute first and let evidence decide.
Few branches
Keep only decisions that change execution. Put naturally inferred details in examples or references.
Strong evidence
Bind branches to files, diffs, tests, structured checks, user confirmation, or external evidence.
Short feedback
When low-risk checks can produce evidence, run them before selecting the next branch.
Iterate in use, but do not overfit
One failure is a clue, not a new rule. Compare several real examples, find the shared failure mode, then update description, SKILL.md, scripts, or references.
Common skill types
PDF / DOCX / PPTX / XLSX
Wrap tool choice, format pitfalls, render checks, and templates.
CI / 安全 / 部署 / 代码评审
Encode log order, approval boundaries, verification commands, and stop rules.
搜索 / 引用 / 证据链
Fix source priority, filtering criteria, citation format, and uncertainty labels.
设计 / 截图 / 响应式
Capture UI standards, browser checks, screenshots, and layout risks.
Runbook / 评审 / 文档
Encode team preferences, roles, output formats, and lessons learned.
日报 / 长文 / 发布清单
Standardize topic selection, material prep, style, and pre-publish checks.
Practice: draft your first minimum skill
A commit message helper is a good first exercise: small, frequent, evidence-bound, and easy to validate. The goal is not pretty text; it is trigger scope, evidence source, side-effect boundary, output contract, and stop condition.
Exercise requirements
- Trigger only for writing, polishing, or choosing commit messages for staged changes.
- Use only the current repository staged git diff as evidence.
- Output 3 Conventional Commit candidates; subject under 72 characters.
- Do not run git add, git commit, git push, or edit files.
Checklist
- Does description exclude general Git Q&A?
- Does it hard-stop when staged diff is empty?
- Is scope emitted only when paths or diff support it?
- Does it include trigger, non-trigger, and stop tests?
Common mistakes and reusable structures
Beginner skills usually fail because boundaries are loose, evidence is thin, or the body is scattered. Use these checks before publishing.
Writing a skill like a prompt collection
“Analyze carefully and improve quality” does not make an agent reliable. A skill needs triggers, inputs, steps, verification, and stop conditions.
Over-broad description causing false triggers
description is a startup index, not marketing copy. It must say when to use and when not to use it, especially near-miss tasks.
Stuffing long references into SKILL.md
Long bodies dilute execution. Keep stable rules in SKILL.md; move API docs, glossaries, templates, and examples into references or assets.
No negative examples or stop rules
“What to do” is not enough. Deletion, publishing, commits, credentials, global config, and external side effects need explicit stop rules.
Three skill directions to practice
If you are unsure where to start, practice with these three directions: clarify, decompose, and preserve preferences. Together they cover three common skill values.
- $task-clarifier Turns vague requests into goals, constraints, risks, and next confirmations; useful before the task is fully shaped.
- $task-forest Splits complex work into parallel or sequential branches for multi-stage projects, long investigations, and broad refactors.
- $user-profile-keeper Captures long-term preferences, collaboration style, and output standards for workflows that must remember user taste.
Install and share after writing
After writing a skill, test it in your local user directory before moving it into a repo or team scope. Before sharing, prepare a README, trigger tests, negative tests, safety notes, and changelog.