Getting Started with Agent Skills

AI coding agents are only as useful as the context you give them. Feed too little and they generate generic code that ignores your architecture. Feed too much — a 500-line style guide, every ADR, every naming convention — and you burn through the context window before the real work begins, leaving the model slower and less accurate.

The real problem is not what to tell the agent. It is when. Your deployment checklist is irrelevant when you are writing a unit test. Your frontend component rules should not be loaded when you are tuning a SQL query. Static system prompts cannot make that distinction.

Agent Skills solve this with on-demand context loading: the agent reads only a short description for each skill at startup, then pulls the full instructions only when your task actually calls for them.

What are Agent Skills?

Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. The agentskills.io specification is standardizing this so skills remain portable across different AI products.

At its core, a skill is a folder containing a SKILL.md file. This file has YAML frontmatter (name and description) followed by the instructions that tell the agent how to perform a specific task. Skills can also bundle scripts, reference materials, and templates.

my-skill/
├── SKILL.md            # Required: metadata + instructions
├── scripts/            # Optional: executable code
├── references/         # Optional: documentation
├── assets/             # Optional: templates, resources
└── ...

Where skills live

The directory depends on which AI tool you're using:

Tool	Skills directory
Cursor	.cursor/skills/<skill-name>/SKILL.md
Claude Code	.claude/skills/<skill-name>/SKILL.md
GitHub Copilot	.github/skills/<skill-name>/SKILL.md
Antigravity	.antigravity/skills/<skill-name>/SKILL.md
Generic (agentskills.io)	.skills/<skill-name>/SKILL.md

Why not AGENTS.md or rules?

AGENTS.md/Claude.md/Cursor rules all solve the same problem: telling the agent how to behave. The difference is when the context loads.

AGENTS.md is read at the start of every session. Every token in that file counts against your context window for every task, whether you're writing docs, debugging a race condition, or refactoring a database layer.

Skills load on demand. The agent reads only the metadata (name and description) at startup. The full skill body is fetched only when your prompt matches the description. This means:

• A 500-line deployment checklist skill costs near-zero tokens until you ask about deployments.
• You can maintain 50+ skills without bloating every conversation.
• Skills are portable: the same .cursor/skills/ folder works in Cursor today and any future tool that adopts the agentskills.io spec.
• Skills can bundle executable scripts and reference files that load incrementally during execution.

The right mental model: AGENTS.md is a standing order, a skill is a specialist you call when you need them.

How the agent discovers and uses a skill

The agent works in three stages:

Stage 1 — Discovery: When the agent starts, it scans the skills directory and reads only the YAML frontmatter (name and description) from every SKILL.md. This is a tiny token cost even with dozens of skills.

Stage 2 — Activation: When you send a prompt, the agent compares your request against the description of each skill. If it matches, the full SKILL.md body is loaded and injected into the LLM context alongside your prompt.

Stage 3 — Execution: The LLM now has the skill instructions and follows them. If the skill references scripts or resource files, those are fetched or run on demand as the task progresses.

Creating a custom skill

First create the directory and file:

mkdir -p .agent/skills/frontend-component
touch .agent/skills/frontend-component/SKILL.md

The SKILL.md needs YAML frontmatter for discovery, followed by the instructions:

---
name: frontend-component
description: Use this skill when building or modifying a UI component.
---

# Frontend component skill example

1. Use our internal CSS Modules system. Do not use Tailwind CSS.
2. Ensure every interactive element includes an `aria-label`.
3. Read `tokens.json` in this directory to get the exact hex codes for our brand colors before styling.
4. After implementation, run `npm run lint:css` to verify compliance.

The description field is what the agent pattern-matches against your prompt at discovery time. Make it specific. "Use this skill when building or modifying a UI component" is better than "frontend skill" because the agent needs enough context to trigger it correctly and to not trigger it when it's irrelevant.

How skills are invoked

Skills can be triggered in two ways: explicitly by the user or automatically by the agent.

Manual invocation with /

Most AI tools support a slash-command shortcut. Type / followed by the skill name and the agent immediately loads that skill's full body, regardless of whether your prompt text would have matched it automatically.

/frontend-component Build the UserCard component
/test Write tests for the payment module
/seo-blog Add meta tags to the about page

This is useful when you know exactly which workflow you want. The agent skips the pattern-matching step and jumps straight to execution. It is also a good safety net for skills with broad descriptions that might not trigger consistently.

Automatic discovery

When you write a natural-language prompt without a slash command, the agent compares your request against the description field of every skill in the directory. If the description is a strong semantic match, the skill activates automatically.

# User types:
"I need to build a responsive navigation bar"

# Agent matches description:
"Use this skill when building or modifying a UI component."

# → SKILL.md body is loaded automatically

The quality of the description determines how reliable automatic discovery is. A vague description like "frontend skill" will either fire too broadly or miss the right moments. A precise description scoped to a specific action prevents unintended activations.

Invocation mode	When to use
/skill-name prompt	You know exactly which skill applies
Natural language	Conversational workflows where the agent picks the right tool

Example: an SEO skill for website development

Here is a practical skill you would add when building or maintaining a content-heavy website. Save it at .github/skills/seo-blog/SKILL.md (or the equivalent path for your tool):

---
name: seo-blog
description: Use this skill when adding, reviewing, or optimising SEO metadata for a web page or blog post, including meta tags, Open Graph tags, structured data, and sitemap entries.
---

# SEO skill

## Checklist for every page

1. **Title tag** — 50-60 characters, primary keyword near the front.
2. **Meta description** — 120-158 characters, includes the keyword and a clear value statement.
3. **Open Graph tags** — og:title, og:description, og:image (1200×630 px), og:url.
4. **Twitter/X card** — twitter:card, twitter:title, twitter:description, twitter:image.
5. **Canonical URL** — set link rel="canonical" on every page to prevent duplicate indexing.
6. **Structured data** — add JSON-LD Article schema for blog posts, WebPage for static pages.
7. **Sitemap** — verify the page is included in sitemap.xml with the correct lastmod date.
8. **Image alt text** — every img tag must have a descriptive alt attribute.

## Naming conventions

- Slug format: kebab-case, maximum 5 words, keyword first. Example: spring-boot-caching-guide.
- Keep slugs stable after publication; redirects cost crawl budget.

## Validation

After making changes, run:
  npm run build && npx lighthouse http://localhost:3000/your-page --only-categories=seo

Target score: 95 or above. Fix any flagged issues before merging.

Invoke this skill manually when writing a new post (/seo-blog Add metadata to the Java caching guide) or let it fire automatically whenever your prompt mentions SEO, meta tags, or Open Graph.

Creating skills for each stage of SDLC

Here are a few examples of skills you can create for each stage of SDLC:

Brainstorming and definition (/spec)

Instruct the agent to interview you before writing code. It clarifies edge cases, API boundaries, and performance constraints, then outputs a strict technical specification.

Planning (/plan)

The agent takes the specification and breaks it down into small, verifiable units, mapping out exact file changes.

Coding (/frontend or /backend)

Enforce use of specific internal component libraries and architectural rules. This prevents the LLM from generating generic, outdated solutions.

Testing (/test)

Instruct the agent to write unit tests, run the test suite via a shell command, and debug failures before finalizing the feature.

Security risks

Treat skills like third-party dependencies. Because Agent Skills give LLMs the ability to execute scripts and read files, a malicious .py script could exfiltrate environment variables or run destructive bash commands.

⚠️ Always audit skills from external sources before adding them to your .agent/skills directory. Check network access settings if you run agents in a sandbox.

Skill repositories

Instead of writing everything from scratch, there are many open source repositories that we can use to get started. I have used few from the below recently.

• addyosmani/agent-skills: Production-grade engineering skills enforcing the Test Pyramid and trunk-based development.
• anthropics/skills: The official Anthropic repository demonstrating progressive disclosure with workflows for MCP servers and PDFs.
• VoltAgent/awesome-agent-skills: Community curation of custom agent skills and framework-agnostic tools.

Start with the Anthropic examples to understand baseline capabilities, then layer in the engineering constraints from Addy Osmani's repository.

🔗 Blog 🔗 LinkedIn 🔗 Medium 🔗 Github