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.
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 Agent | Performs tasks autonomously | Testing Agent |
| Skill | Teaches the agent how to perform tasks | Playwright Testing Skill |
| Tool | Allows the agent to perform an action | Terminal, browser |
| MCP | Connects agents to external systems and data | GitHub MCP |
| Memory | Retains useful context | Previous project preferences |
| Workflow | Defines multiple steps to complete a task | Build, 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 Folder | Purpose |
|---|---|
| SKILL.md | Main instructions for the AI agent. |
| references/ | Additional technical documentation. |
| scripts/ | Executable helper scripts. |
| assets/ | Templates and other resources. |
| agents/openai.yaml | Optional 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 Practice | Explanation |
|---|---|
| One Skill, one responsibility | Avoid combining unrelated workflows. |
| Good description | Define when the Skill should trigger. |
| Clear instructions | Use numbered steps. |
| Separate references | Keep lengthy documentation outside SKILL.md. |
| Use scripts where useful | Automate deterministic operations. |
| Define output format | Tell the agent what files or results to produce. |
| Add safety rules | Restrict destructive or unrelated operations. |
| Test the Skill | Verify it with multiple prompts. |
How to Test Whether a Skill Works
- Positive test: A task that should trigger the Skill.
- Negative test: An unrelated task that should not trigger the Skill.
- Boundary test: A task that partially matches the description but is outside its intended scope.
Example: Playwright Testing Skill
| Prompt | Expected Behaviour |
|---|---|
| Create a Playwright API test | Trigger |
| Create a Java Stream example | Do not trigger |
| Explain what Selenium is | Usually 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.
| Requirement | Recommended Approach |
|---|---|
| Teach an agent how to write tests | Skill |
| Connect agent to GitHub | MCP or integration |
| Execute commands | Terminal tool |
| Connect to databases | Database tool or MCP |
| Reuse a predefined workflow | Skill |
| Share packaged workflows and integrations | Plugin |
| Store long-term context | Memory |
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
-
Beginner - Understand Skills
Learn SKILL.md, YAML frontmatter, descriptions and instructions.
-
Intermediate - Build Skills
Create Playwright, Java, REST Assured and database Skills.
-
Advanced - Scripts and References
Add Python, JavaScript and TypeScript scripts, templates and reference documents.
-
Expert - Multiple Skills
Create a QA automation agent that selects specialized Skills.
-
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.

No comments:
Post a Comment