Saturday, November 21, 2026

AI Agent Skills - Complete Guide

AI Agent Skills - Complete Guide to Creating, Using and Managing Skills with Examples

AI Agent Skills are reusable instructions, workflows, knowledge, and sometimes scripts that teach an AI agent how to perform a particular task consistently.

Think of a Skill as a reusable capability that you give to an AI agent.

AI Agent Skills - Complete Guide to Creating, Using and Managing Skills with Examples


Use following gitHub repository to use existing skills :

1. https://github.com/github/awesome-copilot

2. https://github.com/anthropics/skills


1. What Are AI Agent Skills?

An AI agent can use different capabilities to complete a task. Skills provide specialized instructions that guide the agent through a particular workflow.

AI Agent Architecture

  • AI Agent: Understands the user's request and decides what to do.
  • Skills: Provide reusable instructions and workflows.
  • Tools: Allow agents to interact with browsers, terminals and APIs.
  • Knowledge: Provides documents and reference information.
  • Scripts: Provide reusable executable code.

Simple Example

Suppose you ask an AI agent to create a Playwright API automation test using TypeScript.

Without a Skill, you may need to explain the project structure, API configuration, test naming conventions, assertions, test data management and error handling.

With a Playwright API Testing Skill, the agent can follow predefined instructions automatically.

2. Skills vs Agents vs Tools vs MCP

These concepts are related, but they serve different purposes.

Concept Purpose Example
AI AgentPerforms tasks autonomouslyTesting Agent
SkillTeaches the agent how to perform tasksPlaywright Testing Skill
ToolAllows the agent to perform an actionTerminal, browser
MCPConnects agents to external systems and dataGitHub MCP
MemoryRetains useful contextPrevious project preferences
WorkflowDefines multiple steps to complete a taskBuild, test, report

Example: A Playwright Testing Agent uses a Playwright Skill, executes commands through a terminal tool and accesses GitHub through an MCP connection.

3. How to Create an AI Agent Skill

The Agent Skills format is an open standard. It uses a folder containing a SKILL.md file and optional supporting resources.

Standard Folder Structure

playwright-testing/
|
|-- SKILL.md
|
|-- references/
|   |-- playwright-guide.md
|   |-- best-practices.md
|
|-- scripts/
|   |-- generate-test.ts
|
|-- assets/
|   |-- test-template.ts
|
|-- agents/
    |-- openai.yaml
File or FolderPurpose
SKILL.mdMain instructions for the AI agent.
references/Additional technical documentation.
scripts/Executable helper scripts.
assets/Templates and other resources.
agents/openai.yamlOptional ChatGPT/Codex interface metadata.

You do not need all these folders. A simple Skill can contain just SKILL.md.

Step 1: Create Your First Skill

Let's create a Skill that teaches an AI agent to write Playwright automation tests using TypeScript.

playwright-testing/
    SKILL.md

Step 2: Write the Skill Instructions

---
name: playwright-testing
description: Create, update, debug and review Playwright automation tests using TypeScript. Use when users request Playwright UI testing, API testing, fixtures, page objects, mocking, assertions or test automation.
---

# Playwright Testing Skill

## Purpose

Help developers create reliable Playwright automation
tests using TypeScript.

## Technology

- Playwright
- TypeScript
- Node.js
- Playwright Test Runner

## Project Structure

Use the following structure when creating a new framework:

tests/
  ui/
  api/
  fixtures/
  pages/
  test-data/
  utils/

playwright.config.ts

## Instructions

1. Inspect the existing project before modifying files.
2. Check whether Playwright is already installed.
3. Reuse the existing configuration where possible.
4. Use TypeScript for all test files.
5. Use async/await.
6. Use meaningful test descriptions.
7. Prefer getByRole(), getByText() and getByTestId().
8. Avoid fixed timeouts.
9. Use fixtures for reusable setup.
10. Use Page Object Model for large applications.
11. Keep test data separate from test implementation.
12. Use expect() for assertions.
13. Run the tests after creating them.
14. Fix errors and report the results.

## API Testing

Use Playwright request fixtures for API tests.

Example:

import { test, expect } from '@playwright/test';

test('GET users', async ({ request }) => {
  const response = await request.get('/api/users');

  expect(response.status()).toBe(200);
});

## Output Requirements

When creating tests, provide:

- File names
- Complete TypeScript code
- Required configuration
- Execution commands
- Expected results

Do not modify unrelated project files.

The description helps the agent decide when this Skill should be used.

4. How to Use a Skill with an AI Agent

After creating a Skill, make it available to the AI agent. Different platforms use different folder conventions and invocation methods.

OpenAI Codex

Use a local Skill in Codex CLI or IDE extension. Put project-specific Skills in the following location:

.agents/skills/playwright-testing/SKILL.md

Explicit invocation example:

$playwright-testing

The agent can also select Skills based on their descriptions.

Claude Code

Create the Skill under:

.claude/skills/playwright-testing/SKILL.md

Invoke it using:

/playwright-testing

GitHub Copilot

Skills can be placed in a compatible Copilot environment at:

.github/skills/playwright-testing/SKILL.md

Use agent mode to work with relevant Skills.

ChatGPT

In ChatGPT Work, Skill Creator can be invoked with:

@skill-creator

In the ChatGPT desktop app, you can also explore Skills through the Skills sidebar. Standalone Skill availability differs between desktop, Codex and web experiences.

Step 3: Ask the Agent to Execute a Task

Use the playwright-testing skill.

Create a Playwright API testing framework
using TypeScript.

Requirements:
1. Create GET, POST, PUT and DELETE tests.
2. Use fixtures.
3. Keep test data in separate JSON files.
4. Add reusable API methods.
5. Generate an HTML report.
6. Execute the tests and fix failures.

Important: A Skill does not automatically give an agent access to a browser, terminal, database or external API. The relevant tools and permissions must also be available.

5. Different Practical AI Agent Skill Examples

Example 1: Playwright UI Automation Skill

Objective: Teach the agent to create UI automation tests.

Skill name: playwright-ui-testing

Instructions:

  • Use TypeScript.
  • Follow Page Object Model.
  • Create reusable fixtures.
  • Use locators correctly.
  • Implement assertions.
  • Handle dynamic elements.
  • Capture screenshots on failure.
  • Generate HTML reports.

Example Agent Prompt

Use playwright-ui-testing.

Create a login test for my application.

Include:
- LoginPage.ts
- login.spec.ts
- login test data
- Positive and negative scenarios
- Execution commands

Example 2: REST Assured API Testing Skill

Objective: Generate Java REST Assured API tests following consistent standards.

Skill name: rest-assured-testing

---
name: rest-assured-testing
description: Create, debug and maintain Java REST Assured API automation frameworks, including HTTP methods, JSON, XML, authentication, schemas and reporting.
---

# REST Assured Testing Skill

## Technology

- Java
- Maven
- REST Assured
- TestNG
- Jackson
- JSON Schema Validator

## Rules

1. Use Maven for dependency management.
2. Use reusable request specifications.
3. Keep endpoints in a separate class.
4. Store test data separately.
5. Use POJOs for complex JSON payloads.
6. Validate status codes and response bodies.
7. Use JsonPath for JSON validation.
8. Use XmlPath for XML validation.
9. Support Basic and Bearer authentication.
10. Generate test reports.

## Example

given()
    .baseUri("https://api.example.com")
.when()
    .get("/users")
.then()
    .statusCode(200);

## Output

Provide:
- Maven dependencies
- Project structure
- Java source files
- TestNG test classes
- Execution commands

Example Agent Prompt

Use rest-assured-testing.

Create a complete API automation framework
with GET, POST, PUT, PATCH and DELETE.

Include:
- Maven pom.xml
- Request specification
- API endpoints
- POJO classes
- TestNG tests
- JSON validation
- HTML reports

Example 3: Java Code Review Skill

Objective: Review Java code and identify potential problems.

Skill name: java-code-review

---
name: java-code-review
description: Review Java code for bugs, performance, readability, exception handling, OOP design and Java best practices.
---

# Java Code Review

When reviewing Java code:

1. Check compilation errors.
2. Identify NullPointerException risks.
3. Review exception handling.
4. Check collections and streams.
5. Identify performance issues.
6. Review synchronization and concurrency.
7. Check naming conventions.
8. Suggest improvements.

## Output format

1. Issue
2. Why it is a problem
3. Corrected code
4. Explanation
5. Best practice

Example Agent Prompt

Use java-code-review.

Review my Employee.java file.

Check:
- Comparable and Comparator
- Stream API
- Null handling
- Sorting performance
- Exception handling

Suggest corrected code.

Example 4: HTML Blogger Post Generator Skill

Objective: Generate SEO-friendly HTML articles following predefined publishing rules.

Skill name: blog-html-generator

---
name: blog-html-generator
description: Create SEO-friendly technical blog posts in HTML for Blogger, including Java, Selenium, Playwright and API testing tutorials.
---

# Blogger HTML Generator

## Rules

1. Generate only HTML body content.
2. Do not include html, head or body tags.
3. Use semantic HTML elements.
4. Include one H1 heading.
5. Use H2 and H3 headings.
6. Include practical code examples.
7. Add comparison tables where useful.
8. Include frequently asked questions.
9. Use beginner-friendly English.
10. Include relevant internal links when supplied.
11. Avoid inline JavaScript.
12. Use pre and code tags for examples.

## Output

Return complete HTML body content.

Example Agent Prompt

Use blog-html-generator.

Create an SEO-friendly article:

Topic: Java Stream API Complete Guide

Include:
- Introduction
- Stream operations
- Filter and map
- Sorting
- GroupingBy
- Collectors
- Real-world examples
- FAQ

Return only HTML body content.

Example 5: Database Testing Skill

Objective: Teach an agent to generate database automation tests.

Skill name: database-testing

  • Use Python or Java as specified by the user.
  • Connect to MySQL or PostgreSQL.
  • Execute SELECT queries.
  • Validate row counts.
  • Compare API response data with database data.
  • Validate inserts and updates.
  • Handle transactions.
  • Never hardcode database passwords.
  • Never execute destructive queries without explicit authorization.

Example Agent Prompt

Use database-testing.

Create database validation tests.

Requirements:
1. Connect to MySQL.
2. Execute SELECT queries.
3. Validate employee records.
4. Compare database values with API responses.
5. Generate an HTML test report.

Example 6: GitHub Actions CI/CD Skill

Objective: Automate CI pipeline creation and troubleshooting.

Skill name: github-actions

  • Create YAML workflow files.
  • Configure Node.js or Java.
  • Install dependencies.
  • Run automated tests.
  • Support parallel execution.
  • Upload reports as artifacts.
  • Handle environment variables through secrets.
  • Explain pipeline failures.

Example Agent Prompt

Use github-actions.

Create a CI pipeline for my Playwright project.

Requirements:
- Run on every pull request.
- Execute tests in parallel.
- Use Chromium.
- Generate HTML report.
- Upload the report as an artifact.

6. Advanced Example: Create a Skill with Scripts

Not every Skill needs to contain only instructions. You can also provide executable scripts to help the AI agent perform repeatable tasks.

Folder Structure

playwright-quality-check/
|
|-- SKILL.md
|
|-- scripts/
|   |-- validate-tests.js
|
|-- references/
    |-- testing-rules.md

SKILL.md

---
name: playwright-quality-check
description: Validate Playwright TypeScript test files, detect common automation problems and run quality checks before test execution.
---

# Playwright Quality Check

## Workflow

1. Inspect the Playwright project.
2. Find all test files.
3. Check for fixed waitForTimeout calls.
4. Check for missing assertions.
5. Check for duplicate test titles.
6. Check for hardcoded credentials.
7. Run the validation script.
8. Report the findings.

## Script execution

Execute:

node scripts/validate-tests.js

## Safety

Do not modify test files automatically.
First report the issues and request approval
before applying changes.

scripts/validate-tests.js

const fs = require('fs');
const path = require('path');

const testDirectory = './tests';

function scanDirectory(directory) {

    if (!fs.existsSync(directory)) {
        console.log('Test directory not found');
        return;
    }

    const files = fs.readdirSync(directory);

    for (const file of files) {

        const fullPath = path.join(directory, file);

        if (fs.statSync(fullPath).isDirectory()) {
            scanDirectory(fullPath);
            continue;
        }

        if (!file.endsWith('.spec.ts')) {
            continue;
        }

        const content = fs.readFileSync(fullPath, 'utf8');

        console.log(`Checking: ${fullPath}`);

        if (content.includes('waitForTimeout')) {
            console.log('WARNING: Fixed timeout detected');
        }

        if (!content.includes('expect(')) {
            console.log('WARNING: No expect assertion detected');
        }
    }
}

scanDirectory(testDirectory);

Now the agent can follow your instructions and execute the validation script, provided it has terminal access.

Important Distinction

  • Instructions: Tell the agent what to do.
  • Scripts: Perform deterministic operations.
  • References: Provide additional knowledge.
  • Tools: Provide access to external capabilities.

A script is optional. Use one only when it provides a real benefit.

7. How to Create Multiple Skills for One AI Agent

This is useful when you work across several automation technologies.

Instead of creating one huge Skill, create multiple specialized Skills.

QA Automation AI Agent Architecture

  • QA Automation AI Agent: Main agent that understands the task.
  • Playwright Skill: UI and API tests.
  • Java Skill: Java automation.
  • REST Assured Skill: API validation.
  • Database Skill: SQL validation.
  • Reporting Skill: HTML and Allure reports.
  • CI/CD Skill: GitHub Actions.

Suggested Project Structure

qa-automation-agent/
|
|-- .agents/
|   |-- skills/
|       |
|       |-- playwright-testing/
|       |   |-- SKILL.md
|       |
|       |-- java-automation/
|       |   |-- SKILL.md
|       |
|       |-- rest-assured-testing/
|       |   |-- SKILL.md
|       |
|       |-- database-testing/
|       |   |-- SKILL.md
|       |
|       |-- reporting/
|       |   |-- SKILL.md
|       |
|       |-- github-actions/
|           |-- SKILL.md
|
|-- app/
|-- tests/
|-- reports/
|-- README.md

Example: Let the Agent Choose the Correct Skill

You can give the agent a task without mentioning a Skill name.

Create a REST API automation framework
using Java, REST Assured and TestNG.

The agent can identify that the rest-assured-testing Skill is relevant from its description.

Another example:

Create a UI automation framework
using Playwright and TypeScript.

The agent can select playwright-testing.

This is called implicit Skill invocation.

8. AI Agent Skills Best Practices

Best PracticeExplanation
One Skill, one responsibilityAvoid combining unrelated workflows.
Good descriptionDefine when the Skill should trigger.
Clear instructionsUse numbered steps.
Separate referencesKeep lengthy documentation outside SKILL.md.
Use scripts where usefulAutomate deterministic operations.
Define output formatTell the agent what files or results to produce.
Add safety rulesRestrict destructive or unrelated operations.
Test the SkillVerify it with multiple prompts.

How to Test Whether a Skill Works

  1. Positive test: A task that should trigger the Skill.
  2. Negative test: An unrelated task that should not trigger the Skill.
  3. Boundary test: A task that partially matches the description but is outside its intended scope.

Example: Playwright Testing Skill

PromptExpected Behaviour
Create a Playwright API testTrigger
Create a Java Stream exampleDo not trigger
Explain what Selenium isUsually do not trigger

Also check whether the agent actually followed the instructions, not just whether it selected the Skill.

9. Skills vs MCP vs Plugins: When Should You Use Each?

These are complementary technologies.

RequirementRecommended Approach
Teach an agent how to write testsSkill
Connect agent to GitHubMCP or integration
Execute commandsTerminal tool
Connect to databasesDatabase tool or MCP
Reuse a predefined workflowSkill
Share packaged workflows and integrationsPlugin
Store long-term contextMemory

Practical Example

Suppose you want an agent to execute Playwright tests and publish the results.

  • Skill: Defines how to execute and validate tests.
  • Terminal: Runs npx playwright test.
  • GitHub integration: Reads and updates pull requests.
  • MCP: Connects to additional services if needed.
  • Memory: Retains relevant project context.

A Skill itself is not a replacement for MCP or an external integration.

10. Create Your First Skill on Windows

Let's create a reusable Playwright Skill using PowerShell.

Step 1: Create the Folder

mkdir .agents\skills\playwright-testing

Step 2: Create the SKILL.md File

New-Item .agents\skills\playwright-testing\SKILL.md

Step 3: Open It in VS Code

code .agents\skills\playwright-testing\SKILL.md

Step 4: Add the Skill Instructions

Add the Playwright Skill instructions from Example 1.

Step 5: Open Your Project Using Codex

Use the Skill list or explicitly invoke:

$playwright-testing

Step 6: Test the Skill

Use playwright-testing.

Inspect my existing project and create
a reusable Playwright API testing framework.

If you change the Skill and it does not appear, restart Codex and verify the folder location.

11. Learning Roadmap for AI Agent Skills

  1. Beginner - Understand Skills

    Learn SKILL.md, YAML frontmatter, descriptions and instructions.

  2. Intermediate - Build Skills

    Create Playwright, Java, REST Assured and database Skills.

  3. Advanced - Scripts and References

    Add Python, JavaScript and TypeScript scripts, templates and reference documents.

  4. Expert - Multiple Skills

    Create a QA automation agent that selects specialized Skills.

  5. Professional - Build and Distribute

    Test Skills, version-control them, share them with a team and package them into plugins where supported.

Recommended Official Resources

12. Frequently Asked Questions

1. What is an AI Agent Skill?

An AI Agent Skill is a reusable package of instructions, resources and optional scripts that teaches an AI agent how to perform a particular task.

2. Is SKILL.md mandatory?

Yes. In the Agent Skills format, SKILL.md is the required main instruction file. Supporting folders and files are optional.

3. Can one AI agent use multiple Skills?

Yes. One agent can use multiple specialized Skills, such as Playwright testing, Java automation, API testing and database validation.

4. Can Skills contain Python or JavaScript scripts?

Yes. Skills can include executable scripts. The agent needs suitable tool access and permissions to execute them.

5. What is the difference between a Skill and an MCP server?

A Skill provides reusable instructions and knowledge, while an MCP server exposes tools and resources that an agent can access through the MCP protocol.

6. Can Skills be reused across projects?

Yes. You can keep Skills in a shared location or distribute them to different projects, provided the target AI platform supports the format and location.

7. Can an AI agent automatically select a Skill?

Yes. Compatible agents can select Skills based on the task and the Skill description. You can also explicitly invoke a Skill.

8. Can I create a Skill without programming?

Yes. You can create a basic Skill using only Markdown instructions. Programming is optional and mainly useful for reusable scripts and automation.

9. Are Skills and AI agents the same?

No. An AI agent performs tasks, while a Skill teaches the agent how to perform a particular task or workflow.

10. Can I create my own QA Automation AI Agent?

Yes. You can combine specialized Skills for Playwright, Selenium, Java, REST Assured, Robot Framework, database testing, reporting and CI/CD to create a QA Automation Agent.

Conclusion

AI Agent Skills make AI agents more consistent, reusable and effective. Instead of repeatedly explaining the same instructions, you can create specialized Skills and reuse them across projects.

Start with a simple SKILL.md file, add supporting references and scripts when required, and gradually build a multi-skill AI agent for your automation and software development tasks.

No comments:

Post a Comment