Working with Agent Skills: A Practical Guide

• Development
• Agent
• Skills

Learn how agent skills work, how they differ from traditional agent files, and how to use them to create reusable, domain-specific AI workflows.

We have come a long way in the world of AI. We've seen chat-based interfaces, MCP servers, and agent markdown files (AGENTS.md, CLAUDE.md). Now, we have a new concept called agent skills.

What are agent skills?

Claude's initiative, Agent Skills, refers to special markdown files that extend an agent's capabilities. They provide domain-specific knowledge to an agent and can be reused across projects to supply context and best practices.

How are skills different from regular MD files?

Unlike regular agent files like AGENTS.md and CLAUDE.md, which are referenced on every prompt to provide context, skills are loaded on demand when needed.

They don’t provide full project context like regular agent files. Instead, they are used for domain-specific tasks such as:

• Design guidelines for creating unique frontends
• Following React best practices when writing code
• etc.

Skills are portable and can be reused across projects.

You don’t need to provide the same guidelines or best practices to your agents in every project. Instead, you can reuse the same SKILL files across projects, and they will work out of the box.

How to create agent skills?

To start working with agent skills, follow this folder structure:

1. For a single skill:

root/
  ├── .agents/
  │   └── skills/
  │       └── frontend-design/
  │           └── SKILL.md
  ├── /public
  ├── /src

2. For multiple skills:

root/
  ├── .agents/
  │   └── skills/
  │       ├── frontend-design/
  │       │   └── SKILL.md
  │       ├── composition-patterns/
  │       │   ├── SKILL.md
  │       │   └── metadata.json
  │       └── react-best-practices/
  │           └── SKILL.md
  ├── /public
  ├── /src

Skill folders can also contain additional files besides SKILL.md, such as metadata.json, to provide references to agents.

Breaking down the SKILL.md structure

Here is the basic structure of a SKILL.md file according to Claude’s documentation:

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---
 
# My Skill Name
 
[Add your instructions here that Agent will follow when this skill is active]
 
## Examples
 
- Example usage 1
- Example usage 2
 
## Guidelines
 
- Guideline 1
- Guideline 2

If you want to dive deeper into the structure of a SKILL.md file, you can refer to the official Claude documentation.

You don’t always have to create SKILL files yourself, you can also use ones from open-source GitHub repositories.

Open-source agent skills

Here are some open-source agent skills you can use in your projects:

• Agent skills from Anthropic
• Agent skills from Vercel

How to use agent skills in your projects?

Using skills is simpler than you might think. Once you have created the SKILL.md file, you just need to instruct your agent to perform a specific task.

For example, let’s create a landing page for a custom SaaS.

We’ll use the frontend-design skill from Claude Code for this demo, and we’ll use Antigravity as our IDE with the model Claude Sonnet 4.6 (Thinking). Since we are using a skill designed for Claude, using a Claude model makes more sense.

Why? While preparing this demo, I tried using other models like Gemini 3.1 High with the frontend-design skill, but the results were not as good. So, I recommend using this skill with a Claude model.

Step 1: Add a SKILL file to your project

• Copy the frontend-design skill file from the official Claude Code skills repository.
• Create a new file at .agents/skills/frontend-design/SKILL.md.
• Paste the copied file into SKILL.md. You can modify it based on your needs.

Step 2: Prompt your agent to perform the task

Choose your agent and write a clear, purposeful prompt. Weak prompts may not produce the desired results, so make sure your intent is well-defined.

Let’s ask it to build a landing page for a URL shortener app:

I built a URL shortener web application where users can convert long URLs into short, shareable links. I want to generate a landing page to promote this app.

Here’s how the agent began processing the request:

As shown in the response, it first referenced the SKILL file before generating any output.

Here’s the chat response:

And here’s the generated landing page:

You can explore the source code and view the live preview of this output.

Remarks:

Design: I found it to be a solid homepage design and a good starting point for many developers.

Responsiveness: The page worked well on desktop and tablet devices, but it was not as polished on mobile.

Code quality: Since the skill file didn’t specify using React and Tailwind, the agent generated everything in a single page.tsx file with inline styling.

Despite these limitations, the result was quite good for a first attempt without modifying the skill file. With better instructions, you can easily guide the agent to follow your preferred coding style.

I hope this gives you a clear idea of how to use agent skills effectively.

Conclusion

Agent skills can significantly improve how we guide agents for domain-specific tasks. While frontend design often requires iterations, other skills like react-best-practices or deployment-guides can produce excellent results.

I hope this article helped you understand how to leverage agent skills. If you have any suggestions or improvements, feel free to share them.

Keep nerding...