skill-creation

name	skill-creation
description	Guide for creating AI skills in npx skills@latest format. Use when creating new skills, structuring skill repositories, or packaging skills for AI agent platforms.

What is an AI Skill?

An AI skill is a structured procedure that provides an AI agent with specialized knowledge and capabilities. Skills are packaged in a specific format compatible with AI coding agent platforms like Gemini CLI, Codex, Claude Code, and Copilot.

npx skills@latest Format

Required Structure

skill-name/
├── SKILL.md              # Main skill documentation (required)
├── scripts/              # Optional helper scripts
│   └── script.js/py
├── references/           # Optional reference materials
│   └── reference.md
└── README.md             # Optional skill-specific README

Repository Structure (for publishing)

skills-repo/
├── package.json          # Root package.json for npm
├── README.md             # Installation instructions
└── skills/               # All skills directory
    ├── skill-name-1/
    │   └── SKILL.md
    ├── skill-name-2/
    │   └── SKILL.md
    └── ...

SKILL.md Format

Frontmatter (Required)

---
name: skill-name
description: Brief description of when to use this skill
---

Content Sections

• Purpose: What the skill does
• When to Use: When to activate the skill
• Core Concepts: Key ideas and terminology
• Implementation: How to implement/use the skill
• Examples: Code examples and use cases
• Best Practices: Guidelines for effective use
• Common Gotchas: Common mistakes to avoid
• References: Links to documentation (optional)

SKILL.md Template

---
name: your-skill-name
description: Expert guidance for [topic]. Use when [specific scenarios].
---

## Purpose
[Brief description of what this skill does]

## When to Use
- [Scenario 1]
- [Scenario 2]
- [Scenario 3]

## Core Concepts
- [Concept 1]
- [Concept 2]

## Implementation
[Step-by-step guidance]

## Examples
[Code examples]

## Best Practices
- [Practice 1]
- [Practice 2]

## Common Gotchas
- [Gotcha 1]
- [Gotcha 2]

Creating a New Skill

Step 1: Define the Skill

Identify:

• What problem does it solve?
• When should it be used?
• What knowledge does it provide?
• Who is the target audience?

Step 2: Create the Directory

mkdir skill-name
cd skill-name

Step 3: Create SKILL.md

# Create SKILL.md with frontmatter and content
touch SKILL.md

Step 4: Add Optional Components

# Add scripts if needed
mkdir scripts
# Add references if needed
mkdir references

Step 5: Test the Skill

• Verify frontmatter is valid YAML
• Check content is comprehensive
• Test examples are runnable
• Ensure descriptions are clear

Publishing to npx skills@latest

Step 1: Create Repository

mkdir skills-repo
cd skills-repo
git init

Step 2: Create Root package.json

{
  "name": "@username/skills",
  "version": "1.0.0",
  "description": "Collection of AI skills",
  "main": "index.js",
  "scripts": {
    "add": "node scripts/add-skill.js"
  },
  "keywords": ["ai", "skills", "agent"],
  "repository": {
    "type": "git",
    "url": "https://github.com/username/skills.git"
  },
  "license": "MIT"
}

Step 3: Create README.md

# AI Skills

A collection of AI skills for various platforms.

## Installation

### Using npx
```bash
npx @username/skills@latest add username/skills

Manual Installation

1. Clone the repository
2. Copy skills to your agent's skills directory

Available Skills

### Step 4: Add Skills
```bash
mkdir skills
# Copy your skill directories here

Step 5: Publish to GitHub

git add .
git commit -m "Initial commit"
git push origin main

Step 6: Publish to npm

npm publish

Skill Best Practices

Content Quality

• Be comprehensive but concise
• Provide actionable guidance
• Include working code examples
• Cover edge cases and gotchas
• Keep content up to date

Structure

• Use clear headings and sections
• Organize logically
• Use code blocks for examples
• Include file paths when relevant
• Add tables for comparisons

Frontmatter

• Keep name short and descriptive
• Use kebab-case for names
• Write clear descriptions
• Include activation triggers

Examples

• Make examples runnable
• Use realistic scenarios
• Show common patterns
• Include error handling
• Comment complex code

References

• Link to official documentation
• Include relevant tutorials
• Add community resources
• Cite sources appropriately

Common Skill Types

Technical Skills

• Programming languages (Golang, Python, JavaScript)
• Frameworks (React, Vue, Django)
• Tools (Docker, Kubernetes, Git)
• APIs (REST, GraphQL, gRPC)

Domain Skills

• Security (pentesting, authentication)
• Data (databases, analytics)
• DevOps (CI/CD, infrastructure)
• Design (UI/UX, accessibility)

Process Skills

• Debugging
• Testing
• Documentation
• Code review

Utility Skills

• Time/date handling
• File operations
• System commands
• Data formatting

Skill Examples

Simple Skill (No Scripts/References)

---
name: git-basics
description: Basic Git operations for version control. Use when committing, branching, or merging.
---

## Purpose
Provides guidance for common Git operations.

## When to Use
- Creating commits
- Managing branches
- Merging changes
- Resolving conflicts

## Implementation
[Git commands and workflows]

Complex Skill (With Scripts)

skill-name/
├── SKILL.md
├── scripts/
│   ├── setup.sh
│   └── validate.py
└── references/
    └── best-practices.md

Multi-File Skill

skill-name/
├── SKILL.md
├── scripts/
│   ├── install.js
│   ├── configure.py
│   └── deploy.sh
└── references/
    ├── api-docs.md
    ├── examples.md
    └── troubleshooting.md

Validation Checklist

Before publishing a skill, verify:

• SKILL.md has valid YAML frontmatter
• Name is kebab-case and descriptive
• Description clearly indicates when to use
• Content is comprehensive
• Examples are accurate and runnable
• Code blocks have language specified
• No hardcoded paths or secrets
• Links are valid and accessible
• References are properly credited
• Skill follows npx skills@latest structure

Common Mistakes

Frontmatter Issues

• Missing frontmatter delimiters (---)
• Invalid YAML syntax
• Missing required fields (name, description)
• Using spaces instead of hyphens in names

Content Issues

• Too vague or general
• Missing critical information
• Outdated examples
• Broken code samples
• Incomplete coverage

Structure Issues

• Not following npx skills@latest format
• Missing SKILL.md
• Incorrect directory naming
• Scripts without executable permissions

Testing Skills

Manual Testing

1. Read SKILL.md - is it clear?
2. Try examples - do they work?
3. Check links - are they valid?
4. Verify structure - is it correct?

Automated Testing

# Validate YAML frontmatter
yamllint SKILL.md

# Check markdown syntax
markdownlint SKILL.md

# Test scripts
node scripts/script.js
python scripts/script.py

Skill Maintenance

Updating Skills

• Review quarterly for outdated information
• Update examples when APIs change
• Add new best practices as they emerge
• Fix broken links
• Incorporate user feedback

Deprecating Skills

• Add deprecation notice to SKILL.md
• Update README.md
• Provide migration path
• Remove from repository after grace period

Resources

• npx documentation: https://docs.npmjs.com/cli/v9/commands/npx
• YAML specification: https://yaml.org/spec/
• Markdown guide: https://www.markdownguide.org/
• AI agent platforms documentation