Skip to content
skills-il
All courses

Writing Your First Agent Skill

A 6-chapter course for developers on writing an agent skill from scratch. SKILL.md anatomy, the references/ vs scripts/ split, and the 10 most common authoring mistakes.

By skills-il·Version v1.0.9·Last updated: 25-05-2026·GitHub
6 chapters~26 minDevelopersBeginner
Start course
0Write a Review17
Sources (evidence.json)

What you'll learn

  • ✓Understand what a skill really is to the LLM at routing time, and when to pick a skill vs MCP / system prompt / CLI
  • ✓Write a SKILL.md with a description the LLM routes correctly (Use when / Do NOT use for patterns)
  • ✓Know when to keep the minimal frontmatter and when to add a metadata.json sidecar for a catalog
  • ✓Decide between references/ and scripts/ for any supporting content
  • ✓Share your skill via one of four paths: personal local, team handoff, internal catalog, public catalog
  • ✓Run the 10-minute pre-share checklist and avoid the 10 most common authoring mistakes

Who this is for

Developers who know git, Markdown, and JSON, and want to author an agent skill from scratch for personal use, a team, or contribution to a public catalog. No prior experience with the skill format required.

Course curriculum

Click "Start course" to unlock chapters
  1. 1.
    What is a skill, really?
    A skill is the simplest way to teach an AI assistant to handle a specific task: a single Markdown file with YAML frontmatter at the top, optionally accompanied by reference files and executable scripts. The agent reads the file on demand when the description matches the user's request. That is the entire model. Everything else (how you distribute it, how it gets installed, what UI a catalog wraps around it) is built around that one file.
    ~4 min
  2. 2.
    Anatomy of a great SKILL.md
    A great SKILL.md does three things at once: it tells the LLM when to load itself (the description), it teaches the LLM how to perform the task (the body), and it gives the LLM enough examples to handle edge cases without escalating to the user. If any of these three are missing, the skill either does not get loaded (description failure), does the wrong thing (body failure), or asks the user too many clarifying questions (examples failure).
    ~4 min
  3. 3.
    Extending the format (optional)
    The skill format (the spec developed by Anthropic, accepted by Claude Code, Cursor, Windsurf, and Claude Desktop) is intentionally minimal: `SKILL.md` with three frontmatter fields, plus the optional `references/` and `scripts/` subfolders. That is enough for a personal skill, or a skill you share by zipping a folder and sending it to a colleague. But if you want to put your skill in a catalog or expose extra metadata to consumers, you need to extend the spec somehow.
    ~3 min
  4. 4.
    references/ vs scripts/ (when to use which)
    A skill folder can include two optional subfolders: `references/` and `scripts/`. They serve different purposes and choosing the wrong one is a frequent rejection reason. The rule is simple: `references/` for static content the LLM reads, `scripts/` for executable code the LLM runs. The hard part is recognizing which side of the line your content falls on.
    ~4 min
  5. 5.
    Sharing your skill
    You have written SKILL.md, optionally added references/ and scripts/, and the skill works. Now the practical question: how do you actually use it, share it with others, or publish it to a catalog? This chapter covers four scenarios in order of effort.
    ~4 min
  6. 6.
    The 10-minute pre-share checklist
    This chapter is short on purpose. It is the checklist you run BEFORE sharing your skill with anyone (a colleague, a public catalog, or your future self after a long break). Ten minutes spent here saves multiple back-and-forth rounds with reviewers and prevents the most common authoring mistakes.
    ~7 min

Skills to install to act on what you've learned

Reviews (...)

0Write a Review
Found an issue with this course?

Use at your own risk. Terms of Use · Security