Creating a Skill for an AI Agent: Introduction

Education
1

What is a skill?

A skill is a small, reusable package that teaches an AI agent how to perform a specific task consistently. It usually combines focused instructions with optional scripts, templates, and reference material. Think of it as an operational playbook that the agent can discover and apply when the task matches.

How does an agent use a skill?

  1. The agent identifies that a user’s request matches the skill’s purpose.
  2. It reads the skill’s SKILL.md instructions before acting.
  3. It follows the prescribed workflow and uses any bundled resources or scripts.

The skill should be narrow enough that its trigger is unambiguous. For example, “create an Obsidian Canvas” is a better skill scope than “help with notes.”

What does a skill look like?

At minimum, a skill is a directory containing a SKILL.md file:

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

SKILL.md should include:

  • A clear name and one-sentence description.
  • When the agent should and should not use it.
  • The required workflow, in order.
  • Any safety rules, inputs, outputs, and validation steps.
  • Pointers to scripts or references, rather than copying large content into the main file.

Example:

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Agent to follow.

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

Where should a skill live?

Choose the location based on who should use the skill: keep personal workflows in your home directory, commit team workflows to the repository, and use a plugin when you need broader distribution.

  • Codex: use .agents/skills/<name>/SKILL.md in a repository, or ~/.agents/skills/<name>/SKILL.md for personal skills.
  • Claude Code: use .claude/skills/<name>/SKILL.md in a repository, or ~/.claude/skills/<name>/SKILL.md for personal skills.
  • OpenCode: use .opencode/skills/<name>/SKILL.md or its compatible .claude/skills and .agents/skills locations; global skills can also live in ~/.config/opencode/skills.

There is no single local path shared by all three tools: .agents/skills works with Codex and OpenCode, while .claude/skills works with Claude Code and OpenCode. Use a self-contained folder per skill and keep it close to the code, tools, and documentation it depends on.

Read more:

What should become a skill?

A skill is a good fit when the work is repeated, has a recognizable trigger, and benefits from the same process, knowledge, or output format each time. Typical examples include release-note drafting, document generation that follows a template, a domain-specific review checklist, or a workflow that reliably uses the same tools.

Do not create a skill for a one-off task, a vague request with no stable workflow, or instructions that should apply to every task. Put always-on project rules in AGENTS.md, CLAUDE.md, or the equivalent platform instruction file instead. Use a script or hook when the task must run deterministically on an event.

How do I create one?

1. Initialize the skill

Start with one repeated task, a clear outcome, and a precise trigger. You can create the first draft in either way:

  • Use a coding agent: ask it to create the skill from your description. In Codex, invoke the built-in $skill-creator; it will gather the scope, trigger, and resource needs.
  • Create it manually: make the skill folder and write a minimal SKILL.md with a name, description, instructions, and expected output.

Keep the first version small. Add a script, template, or reference only when it removes real repetition.

2. Iterate with the agent

Treat a skill as a tested workflow, not a one-time prompt. Repeat this loop until the outcome meets expectations:

  1. Ask an agent to use the skill on a representative task.
  2. Inspect the result and compare it with the expected outcome.
  3. Give the agent specific feedback on what was missing, incorrect, or unnecessary.
  4. Update the skill and run the test again.

Keep skills focused, explicit, and easy to inspect. A short skill that reliably handles one workflow is more useful than a broad skill with vague guidance.

Read more:

How to share

Useful resources

Highly recommend to read this: Agent Skills Overview - Agent Skills

Guides

Reference docs

Examples

3 Likes
2

@su.tian.22 Thanks a lot for teaching us! @Yu_Group please read it and begin to contribute skills to CompositesAI.

1 Like
3

Thanks for sharing this post along with resources, Dr. Su.

Could you also share the workflow for integrating existing skills into CompositesAI using OpenCode? I have a couple of skill.md files and would like to migrate them from Claude to CompositesAI.

4

Right now such process has not been set up yet. You can put your skills in a repo and share it with me. I will manually install them for now.

1 Like
5

@Yu_Group All, the following skills have been installed on the msg server:

  • airfoil-tools — Find, inspect, prepare, and plot airfoil coordinate data.
  • cross-sectional-analysis — Create and analyze composite beam cross-sections with PreVABS/VABS.
  • cscan-cai-strength-predictor — Predict compression-after-impact strength from ultrasonic C-scan images.
  • g-k-orthotropic-conversion — Convert between energy release rate G and fracture toughness K for orthotropic materials.
  • opensg-dehomogenization — Recover local strains and stresses from OpenSG models.
  • opensg-homogenization — Calculate effective beam, plate, or solid properties with OpenSG.
  • sg-mesh-gmsh — Build composite laminate, unit-cell, and RVE meshes using Gmsh.
  • swiftcomp-homogenization — Calculate homogenized composite properties using SwiftComp.
  • textile-unit-cell — Create woven textile unit cells and voxel meshes using TexGen.
  • woven-thermal-conductivity — Predict effective thermal conductivity of woven composites.
  • openwebui-artifacts — Publish generated files and previews to Open WebUI.

You can now use these skills through the model “(dev) CompositesAI”. This model is open to Prof. Yu’s group but not general public. This is mainly for testing and debugging. If you cannot see this model in your account, please let me know. I will add your account to this group.

4 Likes