The life agentic

Skills

In agentic tools, a skill is a reusable instruction pack: a playbook, checklist, or workflow that the tool can load when needed.

Skills matter because they let you stop repeating the same long instructions in every session. Instead of pasting the same review checklist or writing guide over and over, you can turn it into a skill.

This page uses Claude Code as the main concrete example because its skill system is well documented. OpenCode also supports skills, but the exact discovery locations, frontmatter, and invocation flow differ.

Intended learning outcomes covered on this page

After working through this page, students should be better able to:

When a skill is a good idea

Create a skill when you keep repeating the same procedure, for example:

Use the right layer

A useful rule in Claude Code is:

If something should be loaded in every Claude Code session, it probably belongs in CLAUDE.md. If it is a reusable playbook you only need sometimes, it probably belongs in a skill.

Contrast with AGENTS.md and memory

Keep one repository and one task fixed:

Explain code in a beginner-friendly way, and run pytest -q before finishing if code changed.

If the repository should always prefer beginner-friendly explanations and always run pytest -q after code changes, that belongs in AGENTS.md.

If you want a reusable procedure for one kind of task, such as explain code to beginners with an analogy, a flow walkthrough, and one likely misconception, that belongs in a skill.

If the instruction is tool-specific, such as use plan mode in Claude Code, it belongs in a tool-specific always-loaded file rather than in a skill or AGENTS.md.

If the information is temporary, such as the current student already understands loops but not decorators, that is session context or memory, not a skill.

Where skills live

In Claude Code, the main locations are:

Personal skills follow you across projects. Project skills travel with the repository and help your teammates too.

OpenCode also supports skills, but it documents more locations, including .opencode/skills/<skill-name>/SKILL.md, ~/.config/opencode/skills/<skill-name>/SKILL.md, and compatible .claude/skills/... or .agents/skills/... directories.

A minimal example

A skill is a directory containing SKILL.md. For example:

~/.claude/skills/explain-code/SKILL.md

---
name: explain-code
description: Explain code with an analogy and a small ASCII diagram. Use when the user asks how code works.
---

When explaining code:

1. Start with a short analogy.
2. Draw a small ASCII diagram.
3. Walk through the flow step by step.
4. Mention one likely mistake or misconception.

In Claude Code, the name becomes the slash command, so you can invoke this skill with /explain-code.

How skills are used

In Claude Code, a skill can be used in two ways:

In OpenCode, agents discover available skills through the skill system and load them when relevant, but the documented mechanics are not the same slash-command flow as Claude Code.

That means a good description matters. It tells the tool when the skill should be loaded.

Good habits for writing skills

For example, deployment or commit skills are often better as manual-only commands, while explanation or review skills often benefit from automatic invocation.

Be careful with third-party skills

Public skill directories can be useful, but read skills before you install them.

A skill is not just metadata. It is a package of instructions that can influence what an agent does, which tools it uses, and what files it touches. Treat third-party skills with the same caution you would use for shell scripts or other workflow automation.

Why students should care

Skills are one of the easiest ways to go from “chatting with a tool” to building a repeatable workflow.

Once you notice that you keep giving the same instructions again and again, that is often the signal that you should create a skill instead.

Next step

This site is open source. Improve this page.