AI Agent Skills: How to Build & Use Custom Skills for 16+ AI Tools
Imagine writing a set of instructions once and having it work across Claude Code, Cursor, OpenAI Codex, Gemini CLI, VS Code, and a dozen more AI tools. That's exactly what Agent Skills deliver — and they're rapidly becoming the "npm packages" of AI-assisted development.
Announced by Anthropic on December 18, 2025, Agent Skills is an open standard that lets you package expertise, workflows, and automation into portable directories that any compatible AI tool can load and execute. As of March 2026, 16+ major AI tools have adopted the standard — from coding assistants to autonomous agents.
This isn't a proprietary feature locked to one vendor. It's an industry-wide shift in how we customize and extend AI tools. Think of it like this: if AI coding assistants are the new IDEs, Agent Skills are the extensions marketplace — except one extension works everywhere.
Whether you're a solo developer wanting your AI to follow your team's coding standards, or a platform architect building reusable automation, this guide covers everything you need to know about Agent Skills in 2026.
What You'll Learn
- What Agent Skills are and why they matter as an open standard
- The complete list of 16+ tools that support skills
- The SKILL.md specification — every field, every option
- How to create your first skill from scratch, step by step
- Claude Code's advanced skill features — bundled skills, locations, subagents
- How skills work across Cursor, Codex, Gemini CLI, and VS Code
- 5 practical skill recipes you can copy and use today
- Skills management with skills.sh — the "npm for agents"
- Security risks: 341 malicious skills discovered and how to protect yourself
What Are Agent Skills?
Agent Skills is "a simple, open format for giving agents new capabilities and expertise." That's the official description from agentskills.io, and it captures the idea perfectly.
At the most basic level, a skill is just a directory containing a SKILL.md file. That markdown file tells an AI agent what the skill does, how to use it, and what rules to follow. It can optionally include scripts, reference documents, and static assets.
The Core Idea: Write Once, Works Everywhere
Before Agent Skills, customizing AI tools meant writing tool-specific configuration. Your Cursor rules didn't work in Claude Code. Your Codex setup didn't transfer to Gemini CLI. Every tool had its own format, its own conventions, its own limitations.
Agent Skills changes that. One skill directory, one SKILL.md file, and it works across every tool that supports the standard. As of March 2026, that's 16+ tools and growing.
Progressive Disclosure
One of the smartest design decisions in the spec is progressive disclosure. When an AI agent starts up, it doesn't read every skill's full content. It only loads the name and description from the YAML frontmatter.
The agent scans those short descriptions to understand what skills are available. Only when a skill is actually needed — either triggered by the user or matched by the agent — does it load the full SKILL.md content, scripts, and references.
This means you can have dozens or even hundreds of skills installed without any performance penalty. The agent stays fast at startup and only pulls in what it needs, when it needs it.
The Directory Structure
Every skill follows this structure:
my-skill/
├── SKILL.md # Required — the skill definition
├── scripts/ # Optional — executable scripts
├── references/ # Optional — documentation, examples
└── assets/ # Optional — images, templates, configs
The SKILL.md file is the only required component. Everything else is optional and loaded on demand. This keeps simple skills simple — a single markdown file is all you need to get started.
Which Tools Support Agent Skills?
The adoption of Agent Skills has been remarkable. Within three months of the December 2025 announcement, 16+ major AI tools added support. Here's the complete list as listed on agentskills.io:
| Tool | Category | Developer |
|---|---|---|
| Claude Code | CLI Coding Agent | Anthropic |
| Claude (web/mobile) | AI Assistant | Anthropic |
| Cursor | AI Code Editor | Anysphere |
| OpenAI Codex | CLI Coding Agent | OpenAI |
| Gemini CLI | CLI Coding Agent | |
| Junie | IDE Agent | JetBrains |
| GitHub Copilot | AI Pair Programmer | GitHub |
| VS Code | Code Editor | Microsoft |
| OpenHands | Autonomous Agent | Open Source |
| OpenCode | CLI Coding Agent | Open Source |
| Amp | AI Coding Agent | Sourcegraph |
| Goose | AI Agent | Block |
| Firebender | AI Coding Tool | Firebender |
| Letta | Agent Framework | Letta |
| Mux | AI Agent | Coder |
| Autohand | AI Agent | Autohand |
This isn't just Anthropic's ecosystem. When Google's Gemini CLI, OpenAI's Codex, JetBrains' Junie, and GitHub Copilot all adopt the same standard, you know it's become the real deal. Agent Skills is to AI tools what package.json is to Node.js — the universal format everyone agrees on.
The breadth of adoption means a skill you write today will work across CLI agents, IDE extensions, web interfaces, and autonomous agent frameworks. That's unprecedented interoperability in the AI tooling space.
The SKILL.md Format: Specification Deep Dive
Let's get into the technical details. Every skill starts with a SKILL.md file. This file has two parts: YAML frontmatter and markdown content.
YAML Frontmatter
The frontmatter is enclosed in --- delimiters at the top of the file. Here are all the fields:
| Field | Required | Constraints | Description |
|---|---|---|---|
name | ✅ Yes | Max 64 chars, lowercase + hyphens only | Unique identifier for the skill |
description | ✅ Yes | Max 1024 chars | What the skill does — this is what agents read at startup |
license | No | SPDX identifier | License for the skill (e.g., MIT, Apache-2.0) |
compatibility | No | List of tool names | Which tools this skill is designed for |
metadata | No | Key-value pairs | Custom metadata (author, version, tags, etc.) |
allowed-tools | No | List of tool names | Restrict which tools the skill can access |
A Complete Example
Here's what a well-structured SKILL.md looks like:
---
name: code-review
description: "Performs thorough code review with focus on security vulnerabilities, performance issues, and adherence to team coding standards. Outputs structured feedback with severity levels."
license: MIT
compatibility:
- claude-code
- cursor
- codex
metadata:
author: your-team
version: 1.0.0
tags:
- code-quality
- security
- review
allowed-tools:
- read
- write
- exec
---
# Code Review Skill
## When to Activate
Activate this skill when the user asks for:
- Code review or PR review
- Security audit of code
- Performance review
- Style/standards compliance check
## Review Process
### Step 1: Understand Context
- Read the files being reviewed
- Check for a .codestyle or .eslintrc config
- Identify the language and framework
### Step 2: Security Review
- Check for SQL injection vulnerabilities
- Look for XSS attack vectors
- Verify input validation
- Check authentication/authorization patterns
### Step 3: Performance Review
- Identify N+1 query patterns
- Check for unnecessary re-renders (React)
- Look for memory leaks
- Verify proper cleanup in useEffect hooks
### Step 4: Output Format
Structure feedback as:
| Severity | Issue | File:Line | Suggestion |
|----------|-------|-----------|------------|
| 🔴 Critical | ... | ... | ... |
| 🟡 Warning | ... | ... | ... |
| 🔵 Info | ... | ... | ... |
The Description Field Is Everything
The description field is the most important part of your frontmatter. Remember progressive disclosure — this is the only thing the agent reads at startup. If your description doesn't clearly communicate what the skill does and when to use it, the agent will never activate it.
Write descriptions like you're writing a function docstring. Be specific about the trigger conditions and the output format. Avoid vague descriptions like "helps with coding" — instead say "performs security-focused code review with structured severity-rated output."
The Markdown Body
Below the frontmatter, the markdown body contains the actual instructions. This is free-form markdown — write it however makes sense for your skill. The agent reads this when the skill is activated.
Best practices for the body:
- Start with activation conditions — when should the agent use this skill?
- Break into clear steps — agents follow sequential instructions well
- Include examples — show the expected output format
- Specify constraints — what should the agent NOT do?
- Use tables for structured data — agents parse tables accurately
Creating Your First Skill: Step by Step
Let's build a real skill from scratch. We'll create a "commit-message" skill that generates conventional commit messages based on staged changes.
Step 1: Create the Directory
mkdir -p my-project/.claude/skills/commit-message
For project-specific skills, the .claude/skills/ directory is the conventional location. This keeps skills version-controlled alongside your code.
Step 2: Write the SKILL.md
Create .claude/skills/commit-message/SKILL.md:
---
name: commit-message
description: "Generates conventional commit messages from staged git changes. Analyzes diffs, categorizes changes (feat/fix/refactor/docs/test/chore), and writes clear, descriptive commit messages following the Conventional Commits specification."
license: MIT
metadata:
author: your-name
version: 1.0.0
---
# Commit Message Generator
## When to Activate
Use this skill when:
- User asks to "commit" or "write a commit message"
- User says "what changed" after making edits
- User asks to "save my work" in a git repo
## Process
### Step 1: Get the Diff
Run `git diff --staged` to see what's been staged.
If nothing is staged, run `git diff` and ask the user if they want to stage all changes.
### Step 2: Analyze Changes
Categorize each change:
- **feat**: New feature or capability
- **fix**: Bug fix
- **refactor**: Code restructuring without behavior change
- **docs**: Documentation only
- **test**: Adding or updating tests
- **chore**: Build, CI, dependencies, config
### Step 3: Determine Scope
Look at which files/directories changed to determine the scope:
- `src/auth/*` → scope is `auth`
- `tests/*` → scope is `tests`
- Multiple directories → omit scope or use the primary one
### Step 4: Write the Message
Format: `type(scope): short description`
Rules:
- Lowercase first letter after colon
- No period at the end
- Max 72 characters for the subject line
- Use imperative mood ("add" not "added")
If the change is complex, add a body:
```
feat(auth): add OAuth2 support for Google login
- Implement Google OAuth2 flow with PKCE
- Add token refresh logic
- Create new GoogleAuthProvider class
- Update login page with Google button
```
### Step 5: Present and Confirm
Show the generated message and ask:
"Ready to commit with this message? (y/n/edit)"
Step 3: Add Optional Scripts
Skills can include executable scripts. Let's add a helper script that validates commit messages:
mkdir -p .claude/skills/commit-message/scripts
Create scripts/validate-commit.sh:
#!/bin/bash
# Validates a commit message against Conventional Commits format
MSG="$1"
PATTERN="^(feat|fix|refactor|docs|test|chore|style|perf|ci|build|revert)(\(.+\))?: .{1,72}$"
if echo "$MSG" | head -1 | grep -qP "$PATTERN"; then
echo "✅ Valid conventional commit message"
exit 0
else
echo "❌ Invalid format. Expected: type(scope): description"
exit 1
fi
Step 4: Add Reference Documents
If your skill needs context documents, add them to references/:
mkdir -p .claude/skills/commit-message/references
Create references/commit-conventions.md with your team's specific conventions, examples of good and bad commits, or any additional context the agent should know.
Step 5: Test It
Open your project in any supported tool — Claude Code, Cursor, Codex, Gemini CLI — and make some code changes. Then ask: "Write a commit message for my changes."
The agent should detect the commit-message skill from its description, activate it, and follow the process you defined. If it doesn't activate, check your description — it might not be matching the user's intent clearly enough.
Final Directory Structure
.claude/skills/commit-message/
├── SKILL.md
├── scripts/
│ └── validate-commit.sh
└── references/
└── commit-conventions.md
That's it. One directory, one SKILL.md file, and your AI assistant now generates perfect commit messages in any tool that supports Agent Skills.
Claude Code Skills Deep Dive
While Agent Skills is an open standard, Claude Code — as the originator — has the most mature implementation with several advanced features. Let's explore what makes Claude Code's skill support special.
Skill Locations and Priority
Claude Code loads skills from four locations, in priority order:
| Priority | Location | Path | Use Case |
|---|---|---|---|
| 1 (Highest) | Enterprise | Managed by org admin | Company-wide standards and policies |
| 2 | Personal | ~/.claude/skills/ | Your personal workflow preferences |
| 3 | Project | .claude/skills/ | Project-specific standards and automation |
| 4 (Lowest) | Plugin | Installed via skills.sh or manually | Community and third-party skills |
Higher-priority skills override lower-priority ones when there's a conflict. This means an enterprise admin can enforce coding standards that individual developers or community skills can't override — a critical feature for teams.
Bundled Skills
Claude Code ships with several powerful built-in skills that showcase what's possible:
/simplify — Parallel Code Review
The /simplify skill spawns 3 parallel review agents that simultaneously analyze your code from different angles: readability, performance, and correctness. Each agent works independently and reports back with findings. The results are merged into a unified review.
This is a great example of the subagent pattern — one skill coordinating multiple AI agents working in parallel. It's significantly faster than sequential review because all three analyses happen simultaneously.
/batch — Parallel Worktree Agents
The /batch skill is Claude Code's power tool for large-scale changes. It spawns 5 to 30 worktree agents, each working on a separate git worktree. This lets you make changes across dozens of files simultaneously without conflicts.
Common use cases include: migrating an entire codebase from one API to another, updating test files across a monorepo, or applying a refactoring pattern across hundreds of files. Each agent works on its own branch and the results are merged back.
/debug — Interactive Debugging
The /debug skill activates an interactive debugging workflow. It reads error messages, traces through the code, forms hypotheses, and proposes fixes. It's particularly good at tracing through stack traces and identifying the root cause of issues.
Invoking Skills
In Claude Code, you can invoke skills in two ways:
- Explicitly — Type
/skill-nameto directly invoke a skill. For example,/simplifytriggers the parallel review. - Auto-loaded — Skills are automatically activated when the agent determines they're relevant based on your request and the skill's description.
The auto-loading is powered by progressive disclosure. Claude Code reads all skill descriptions at startup, then matches them against your requests. If you ask "review this PR for security issues," it'll automatically activate any skill whose description mentions code review or security analysis.
Advanced Features
Subagent Execution
Skills can spawn subagents — separate AI instances that work on subtasks. The /simplify and /batch skills both use this pattern. You can build your own multi-agent skills by including subagent instructions in your SKILL.md.
A typical subagent pattern looks like: the parent skill defines the overall workflow, breaks it into subtasks, spawns agents for each subtask, and then aggregates the results. This is powerful for any task that can be parallelized.
Dynamic Context Injection
Skills can dynamically inject context into the agent's working memory. This means a skill can load relevant documentation, configuration files, or codebase context on the fly. Instead of front-loading everything, the skill fetches what it needs as it progresses through its workflow.
Tool Restriction
The allowed-tools frontmatter field lets you restrict which tools a skill can access. This is a security feature — you can create a "read-only review" skill that's only allowed to read files but never write or execute commands. This is especially important for skills from untrusted sources.
The /hooks Menu
Claude Code's /hooks menu lets you set up triggers that automatically invoke skills based on events. For example, you can hook a commit-message skill to run every time you're about to commit, or trigger a code review skill whenever a new file is created. Hooks turn skills from on-demand tools into automated workflows.
Practical Claude Code Skill Tips
- Keep personal skills generic — Put language-agnostic preferences in
~/.claude/skills/ - Keep project skills specific — Put project-specific conventions in
.claude/skills/ - Version control project skills — Commit
.claude/skills/to your repo so the whole team benefits - Use tool restrictions — Always set
allowed-toolsfor community skills - Test incrementally — Start with a simple skill and add complexity gradually
Skills Across Other Tools
While Claude Code has the most features, Agent Skills work great across the broader ecosystem. Here's how skills integrate with other major tools.
Cursor
Cursor, the AI-powered code editor, reads skills from the .claude/skills/ directory in your project. If you've been using Cursor's own .cursorrules file, you can migrate those rules into a proper Agent Skills format and they'll work in both Cursor AND every other supporting tool.
The key benefit for Cursor users is portability. Instead of maintaining separate .cursorrules and Claude Code configurations, you maintain one set of skills that works everywhere. Cursor's agent mode respects the full SKILL.md specification including frontmatter fields and the scripts directory.
OpenAI Codex
OpenAI Codex adopted Agent Skills as its customization format, which was a significant endorsement from Anthropic's biggest competitor. Codex reads skills from the standard locations and supports the full SKILL.md specification.
For Codex users, skills provide a much richer customization mechanism than simple system prompts. You can include scripts, reference documents, and structured workflows. The progressive disclosure model works well with Codex's context management.
Gemini CLI
Google's Gemini CLI supports Agent Skills with full specification compliance. Skills are loaded from the project's .claude/skills/ directory (yes, the directory is still called .claude — it's part of the standard, not a brand reference).
Gemini CLI's implementation is notable for its fast skill loading — Google optimized the progressive disclosure mechanism to handle large skill libraries efficiently. If you have dozens of skills installed, Gemini CLI's startup time is barely affected.
VS Code
VS Code supports Agent Skills through its AI features and GitHub Copilot integration. Skills placed in your project's .claude/skills/ directory are automatically picked up by VS Code's AI assistant.
This is particularly powerful because VS Code is the most popular code editor in the world. Skills that work in VS Code reach the largest possible audience of developers. If you're publishing community skills, VS Code compatibility should be a priority.
JetBrains (Junie)
JetBrains' AI agent, Junie, supports Agent Skills across all JetBrains IDEs — IntelliJ, WebStorm, PyCharm, and more. This brings skills to the enterprise Java, Python, and web development ecosystems where JetBrains dominates.
Cross-Tool Compatibility Tips
| Best Practice | Why |
|---|---|
| Stick to the core spec fields | Some tools ignore non-standard frontmatter |
| Use portable shell scripts (bash/sh) | Not all tools support every scripting language |
| Don't assume tool-specific features | Subagents work in Claude Code but may not in all tools |
| Test in at least 2-3 tools | Catches compatibility issues early |
Use the compatibility field | Helps agents know if the skill was tested for their platform |
5 Practical Skill Recipes
Theory is great, but let's build real skills. Here are five production-ready skill recipes you can drop into any project today.
Recipe 1: Code Review Skill
A comprehensive code review skill that checks security, performance, and style.
---
name: code-review
description: "Performs comprehensive code review covering security vulnerabilities, performance bottlenecks, code style violations, and architectural concerns. Outputs structured feedback with severity levels and specific fix suggestions."
license: MIT
metadata:
version: 1.0.0
tags: [review, security, performance]
allowed-tools:
- read
- exec
---
# Code Review Skill
## Activation
When user asks for: code review, PR review, "check my code", security review, or performance review.
## Review Checklist
### Security (Priority 1)
- [ ] SQL injection — parameterized queries used?
- [ ] XSS — user input escaped in output?
- [ ] CSRF — tokens present on mutations?
- [ ] Auth — routes protected? Roles checked?
- [ ] Secrets — no hardcoded keys, tokens, passwords?
- [ ] Dependencies — known vulnerabilities?
### Performance (Priority 2)
- [ ] N+1 queries — batch loading used?
- [ ] Unnecessary re-renders (React/Vue)?
- [ ] Large bundle imports — tree-shaking possible?
- [ ] Database indexes — queries hitting indexes?
- [ ] Memory leaks — cleanup on unmount/close?
### Code Quality (Priority 3)
- [ ] Functions under 50 lines?
- [ ] Clear naming — no abbreviations?
- [ ] Error handling — try/catch, error boundaries?
- [ ] Type safety — TypeScript types accurate?
- [ ] Tests — new code covered?
## Output Format
### Summary
One paragraph: overall assessment, critical issues count.
### Findings Table
| Severity | Category | File:Line | Issue | Fix |
|----------|----------|-----------|-------|-----|
| 🔴 Critical | Security | ... | ... | ... |
| 🟡 Warning | Performance | ... | ... | ... |
| 🔵 Suggestion | Quality | ... | ... | ... |
### Verdict
- ✅ APPROVE — no critical issues, minor suggestions only
- ⚠️ REQUEST CHANGES — critical or multiple warning issues
- 🔴 BLOCK — security vulnerability or data loss risk
Recipe 2: Testing Automation Skill
Automatically generate test files for new or modified code.
---
name: test-generator
description: "Generates comprehensive test suites for new or modified code. Supports Jest, Vitest, Pytest, and Go testing. Creates unit tests, integration tests, and edge case tests with proper mocking and assertions."
license: MIT
metadata:
version: 1.0.0
tags: [testing, automation, tdd]
---
# Test Generator Skill
## Activation
When user asks to: write tests, add test coverage, "test this", create test file, or TDD workflow.
## Process
### Step 1: Detect Framework
Read project config to determine test framework:
- `jest.config.*` → Jest
- `vitest.config.*` → Vitest
- `pytest.ini` or `pyproject.toml` → Pytest
- `*_test.go` files → Go testing
### Step 2: Analyze Target Code
Read the file(s) to test. Identify:
- Exported functions/classes
- Input types and edge cases
- Dependencies to mock
- Error paths
- Side effects
### Step 3: Generate Test Structure
```
describe('[ModuleName]', () => {
describe('[functionName]', () => {
it('should handle normal input', () => {});
it('should handle edge case: empty input', () => {});
it('should handle edge case: null/undefined', () => {});
it('should throw on invalid input', () => {});
it('should handle async errors', () => {});
});
});
```
### Step 4: Write Assertions
- Test return values, not implementation
- Mock external dependencies (API calls, DB, file system)
- Cover happy path, error path, and edge cases
- Minimum 80% branch coverage target
### Step 5: Verify Tests Pass
Run the test suite to confirm all tests pass. Fix any failures before presenting results.
## Rules
- Match existing test patterns in the project
- Use the project's assertion style (expect vs assert)
- Don't test private/internal functions directly
- Always include at least one edge case test per function
Recipe 3: Documentation Generator Skill
Generate and maintain documentation from code.
---
name: doc-generator
description: "Generates and updates project documentation from code. Creates README sections, API docs, JSDoc/docstrings, architecture docs, and changelog entries. Keeps documentation in sync with code changes."
license: MIT
metadata:
version: 1.0.0
tags: [documentation, readme, api-docs]
---
# Documentation Generator Skill
## Activation
When user asks to: write docs, update readme, document API, add JSDoc, generate changelog, or "explain this codebase."
## Documentation Types
### 1. README Generation
Analyze the project and generate/update README.md:
- Project title and description
- Installation steps (from package.json scripts)
- Usage examples (from test files or examples/)
- API reference (from exported functions)
- Configuration (from config files)
- Contributing guidelines
### 2. API Documentation
For each exported function/class:
```typescript
/**
* Brief description of what it does.
*
* @param paramName - Description with type info
* @returns Description of return value
* @throws ErrorType - When this error occurs
* @example
* const result = myFunction('input');
* // result: expected output
*/
```
### 3. Architecture Documentation
Generate ARCHITECTURE.md:
- High-level system diagram (text-based)
- Directory structure with descriptions
- Data flow between components
- Key design decisions and trade-offs
### 4. Changelog Entry
For recent changes, generate CHANGELOG.md entry:
```markdown
## [version] - YYYY-MM-DD
### Added
- New feature description
### Changed
- What changed and why
### Fixed
- Bug fix description
```
## Rules
- Use the project's existing documentation style
- Don't remove existing documentation — augment it
- Include code examples for every public API
- Keep language clear and concise — no jargon without explanation
Recipe 4: Security Audit Skill
Deep security analysis focused on OWASP top 10 and common vulnerabilities.
---
name: security-audit
description: "Performs deep security audit of codebase focusing on OWASP Top 10, dependency vulnerabilities, secrets exposure, authentication/authorization flaws, and injection attacks. Generates detailed security report with remediation steps."
license: MIT
metadata:
version: 1.0.0
tags: [security, audit, owasp, vulnerabilities]
allowed-tools:
- read
- exec
---
# Security Audit Skill
## Activation
When user asks for: security audit, vulnerability scan, "is this secure?", penetration test review, or OWASP compliance check.
## Audit Process
### Phase 1: Dependency Scan
Run the appropriate dependency audit:
- Node.js: `npm audit` or `yarn audit`
- Python: `pip-audit` or `safety check`
- Go: `govulncheck ./...`
- Ruby: `bundle audit`
Report: critical, high, medium, low vulnerability counts.
### Phase 2: Secrets Detection
Search for exposed secrets:
- API keys (patterns: `sk-`, `pk_`, `api_key=`)
- Passwords in code or config
- Private keys (`.pem`, `.key` files)
- Environment files committed to git (`.env` in tracked files)
- Database connection strings with credentials
### Phase 3: OWASP Top 10 Review
| OWASP | What to Check |
|-------|--------------|
| A01 Broken Access Control | Route protection, role checks, IDOR |
| A02 Cryptographic Failures | Weak hashing, plaintext storage, HTTP |
| A03 Injection | SQL, NoSQL, OS command, LDAP injection |
| A04 Insecure Design | Missing rate limiting, no input validation |
| A05 Security Misconfiguration | Debug mode in prod, default credentials |
| A06 Vulnerable Components | Outdated dependencies (Phase 1) |
| A07 Auth Failures | Weak passwords, missing MFA, session issues |
| A08 Data Integrity | Deserialization, unsigned updates |
| A09 Logging Failures | No audit trail, sensitive data in logs |
| A10 SSRF | Unvalidated URLs, internal network access |
### Phase 4: Report Generation
## Security Audit Report
**Risk Level: [CRITICAL/HIGH/MEDIUM/LOW]**
### Executive Summary
One paragraph overview of security posture.
### Critical Findings
Each finding includes:
1. **Vulnerability** — what's wrong
2. **Location** — file and line number
3. **Impact** — what an attacker could do
4. **Remediation** — exact code fix
### Dependency Vulnerabilities
Table of vulnerable packages with fix versions.
### Recommendations
Prioritized list of security improvements.
Recipe 5: Codebase Onboarding Skill
Help new developers understand an unfamiliar codebase quickly.
---
name: codebase-onboarding
description: "Helps developers understand unfamiliar codebases by analyzing project structure, key files, architecture patterns, data flow, and conventions. Generates a comprehensive onboarding guide tailored to the specific project."
license: MIT
metadata:
version: 1.0.0
tags: [onboarding, documentation, architecture]
allowed-tools:
- read
- exec
---
# Codebase Onboarding Skill
## Activation
When user says: "explain this codebase", "I'm new here", "how does this project work?", "onboard me", or "what does this repo do?"
## Onboarding Process
### Step 1: Project Overview
Read and summarize:
- README.md — what the project does
- package.json / pyproject.toml / go.mod — dependencies and scripts
- .env.example — configuration requirements
- Dockerfile / docker-compose.yml — deployment setup
### Step 2: Architecture Map
Analyze the directory structure and create a map:
```
project/
├── src/
│ ├── api/ → REST/GraphQL endpoints
│ ├── services/ → Business logic
│ ├── models/ → Database models/schemas
│ ├── utils/ → Shared utilities
│ └── config/ → Configuration management
├── tests/ → Test suites
├── scripts/ → Build and deployment scripts
└── docs/ → Documentation
```
For each major directory, explain its purpose and key files.
### Step 3: Key Files Tour
Identify and explain the most important files:
1. Entry point (main.ts, app.py, main.go)
2. Router/routes definition
3. Database configuration
4. Authentication setup
5. Key business logic modules
### Step 4: Data Flow
Trace a typical request through the system:
```
Request → Router → Middleware → Controller → Service → Repository → Database
↓
Response ← Controller ← Service ← Repository ← Database
```
### Step 5: Development Workflow
From project config, determine:
- How to install dependencies
- How to run locally
- How to run tests
- How to build for production
- How to deploy
### Step 6: Conventions and Patterns
Identify:
- Naming conventions (files, variables, functions)
- Error handling patterns
- Logging patterns
- Testing patterns
- Git branch/commit conventions
## Output
Present as a structured "Onboarding Guide" with clear sections and code examples. The developer should be able to start contributing after reading it.
Skills Management with skills.sh
As the Agent Skills ecosystem has grown, managing skills needed its own tooling. Enter skills.sh — essentially the "npm for agents."
skills.sh is a command-line tool that lets you discover, install, update, and manage Agent Skills from community repositories. Think of it like how npm manages JavaScript packages, but for AI agent skills.
Core Capabilities
| Command | What It Does |
|---|---|
skills search [query] | Search community skill repositories |
skills install [name] | Install a skill to your project or personal directory |
skills update [name] | Update an installed skill to the latest version |
skills list | List all installed skills |
skills remove [name] | Remove an installed skill |
skills publish | Publish your skill to the community repository |
Official Examples
Anthropic maintains an official collection of example skills on GitHub at github.com/anthropics/skills. This repository includes reference implementations for common use cases and serves as the best resource for learning skill patterns and best practices.
The community has also contributed hundreds of skills for specific frameworks (React, Django, Rails), languages (TypeScript, Python, Rust, Go), and workflows (CI/CD, deployment, monitoring). Before building a skill from scratch, check if someone's already published one that does what you need.
Publishing Your Skills
If you've built a useful skill, consider publishing it. The process is straightforward: make sure your SKILL.md has complete frontmatter (especially name, description, and license), test it across at least two tools, and publish via skills.sh. The community benefits from every shared skill — and with the security practices we'll cover next, you can publish responsibly.
Security: The Supply Chain Risk
With great ecosystem growth comes great security responsibility. In February 2026, security researchers at prplbx.com published findings that sent a wake-up call through the Agent Skills community.
341 Malicious Skills Found
By February 3, 2026, researchers had identified 341 malicious skills on community hubs. These skills contained hidden payloads ranging from data exfiltration to credential theft. The attack surface is real and growing.
This is the same pattern we've seen with npm packages, PyPI packages, and VS Code extensions. Whenever there's a popular ecosystem with easy publishing, bad actors show up. Agent Skills are no different — and in some ways the risk is higher because skills can bundle executable scripts that run with the AI agent's permissions.
The Attack Surface
A malicious skill can:
- Execute arbitrary scripts — Skills can include scripts/ that the agent runs
- Exfiltrate code — A skill with read access can send your code to external servers
- Inject backdoors — A "code generation" skill could insert vulnerabilities into your code
- Steal credentials — Scripts can read environment variables, config files, SSH keys
- Poison the model's context — Subtle prompt injection in the SKILL.md itself
How to Protect Yourself
| Practice | Why |
|---|---|
| Read every SKILL.md before installing | Understand what the skill does and what tools it uses |
| Audit all files in scripts/ | These are executable — treat them like any code dependency |
| Use allowed-tools restrictions | Limit what community skills can access |
| Prefer skills from known publishers | Check the author's reputation and other published skills |
| Pin versions | Don't auto-update skills without reviewing changes |
| Use enterprise-level skill management | For teams, maintain an approved skills list |
The bottom line: treat third-party skills like you treat third-party npm packages. Audit before installing. Restrict permissions. Keep an eye on what's running.
How Serenities AI Works with Agent Skills
At Serenities AI, we've embraced the Agent Skills ecosystem as a core part of our platform. Our integrated environment — combining app building (Vibe), automation (Flow), database (Base), and storage (Drive) — creates unique opportunities for skills.
When you build apps with Serenities AI's Vibe, you can use Agent Skills to standardize your team's coding patterns, automate testing workflows, and enforce security practices across every project. Because Serenities AI integrates app building, automation, and data in one platform, skills can orchestrate workflows that span code generation, database setup, and automation configuration — all in one place.
Our platform supports the full Agent Skills specification. Drop your skills into the standard .claude/skills/ directory, and they work seamlessly with Serenities AI's AI-powered development tools. The integration means skills aren't just coding instructions — they can trigger Flows, query Base tables, and manage Drive assets as part of their workflows.
If you're building AI-powered apps, the combination of a fully integrated platform and the portable skills ecosystem means you set up your development standards once and they follow you everywhere. Check out serenitiesai.com to see how skills fit into the bigger picture.
Frequently Asked Questions
1. Do Agent Skills work with every AI tool?
As of March 2026, Agent Skills are supported by 16+ tools including Claude Code, Claude (web/mobile), Cursor, OpenAI Codex, Gemini CLI, Junie (JetBrains), GitHub Copilot, VS Code, OpenHands, OpenCode, Amp, Goose (Block), Firebender, Letta, Mux (Coder), and Autohand. The standard is open, so any tool can add support. Check agentskills.io for the latest list of compatible tools.
2. What's the difference between Agent Skills and .cursorrules or CLAUDE.md?
Agent Skills is the standardized, portable evolution of tool-specific configuration files. While .cursorrules only works in Cursor and CLAUDE.md is specific to Claude Code, Agent Skills work across all 16+ supporting tools. They also offer more structure — YAML frontmatter for metadata, progressive disclosure for performance, and a directory structure for scripts and references. If you're still using tool-specific configs, migrating to Agent Skills gives you cross-tool compatibility for free.
3. Are Agent Skills safe to install from community repositories?
You should exercise caution. Security researchers found 341 malicious skills on community hubs by February 2026. The risk is similar to installing npm packages from unknown publishers. Always read the SKILL.md before installing, audit any scripts in the scripts/ directory, use the allowed-tools field to restrict permissions, and prefer skills from verified publishers. For teams, maintain an approved skills list and use enterprise-level skill management.
4. Can I use Agent Skills for non-coding tasks?
Absolutely. While the ecosystem started in coding, Agent Skills can instruct agents on any task — writing documentation, generating reports, managing project workflows, analyzing data, or even creative writing. The SKILL.md format is just structured instructions for an AI agent. Any task you can describe in a step-by-step process can become a skill. Claude (web/mobile) support means skills aren't limited to code editors.
5. How do I share skills across my team?
The easiest way is to commit your .claude/skills/ directory to your git repository. Every team member who clones the repo gets the same skills automatically. For organization-wide skills that should apply across all projects, use the personal skills directory (~/.claude/skills/) or enterprise-managed skills. You can also publish skills to community repositories via skills.sh for broader sharing. For enterprise deployments, tools like Claude Code offer managed skill distribution where admins push approved skills to all developers.
Next Steps
Agent Skills are still early — the standard is barely three months old — but the trajectory is clear. With 16+ tools already on board and a growing community of skill publishers, this is becoming the foundational layer of AI-assisted development.
Here's how to get started today:
- Create one skill — Pick your most repetitive workflow and turn it into a SKILL.md
- Test it across tools — Try your skill in at least two different AI tools
- Browse community skills — Check github.com/anthropics/skills for inspiration
- Install skills.sh — Set up the package manager for your skills workflow
- Share what you build — The ecosystem grows when developers contribute back
The "npm packages of AI coding" era is here. The question isn't whether you'll use Agent Skills — it's which skills you'll build first.