How to Publish a Skill
Ship your QA expertise to 30+ AI agents in 2 minutes. Create a SKILL.md, validate, publish.
TL;DR — Publish in 30 seconds
# 1. Create SKILL.md (see template below)
# 2. Validate
npx @qaskills/skill-validator validate ./SKILL.md
# 3. Login + publish
npx @qaskills/cli login
npx @qaskills/cli publish ./SKILL.md
# Done! View at qaskills.sh/skills/<username>/<slug>Need detail? Scroll for the full walkthrough, frontmatter reference, FAQ, and troubleshooting.
Create a SKILL.md file
Every QA skill is a single SKILL.md file with YAML frontmatter and markdown instructions. Create a GitHub repository with your skill or keep it local.
---
name: My Playwright Skill
description: Custom Playwright patterns for my team
version: 1.0.0
author: your-username
license: MIT
tags: [playwright, e2e, testing]
testingTypes: [e2e, visual]
frameworks: [playwright]
languages: [typescript, javascript]
domains: [web]
agents: [claude-code, cursor, github-copilot]
---
# My Playwright Skill
## Instructions
When writing Playwright tests, follow these patterns:
- Always use Page Object Model
- Use `getByRole` and `getByTestId` locators
- Write fixtures for test setup
...Validate your skill
Use the QA Skills validator to check your SKILL.md against the schema. This ensures your frontmatter is correct and all required fields are present.
npx @qaskills/skill-validator validate ./SKILL.md
# Output:
# Frontmatter is valid
# Name: My Playwright Skill
# Version: 1.0.0 (semver ok)
# Testing types: e2e, visual
# Frameworks: playwright
# Agents: 3 supported
# Content length: 2,400 tokens
# All checks passedPublish to QASkills.sh
Use the CLI to publish your skill to the directory. You'll need to sign in with your QASkills.sh account first.
# Sign in (opens browser)
npx @qaskills/cli login
# Publish from your skill repository
npx @qaskills/cli publish ./SKILL.md
# Output:
# Authenticated as your-username
# Validating SKILL.md...
# Publishing "My Playwright Skill" v1.0.0
# Published! View at qaskills.sh/skills/your-username/my-playwright-skillTrack & improve
Monitor your skill's performance in the dashboard. See install counts, quality scores, and community feedback. Update your skill by publishing new versions.
# Update your skill (bump version in frontmatter first)
npx @qaskills/cli publish ./SKILL.md
# Output:
# Updated "My Playwright Skill" to v1.1.0
# 234 total installs | Quality score: 88/100SKILL.md Frontmatter Reference
| Field | Required | Description |
|---|---|---|
name | Required | Display name of your skill (1-100 chars) |
description | Required | Short description (10-500 chars) |
version | Required | Semantic version (e.g. 1.0.0) |
author | Required | Your QASkills.sh username |
license | Required | License identifier (e.g. MIT, Apache-2.0) |
tags | Optional | Keyword tags for discovery |
testingTypes | Required | e2e, unit, api, performance, security, etc. |
frameworks | Optional | playwright, cypress, jest, pytest, etc. |
languages | Required | typescript, javascript, python, java, etc. |
domains | Optional | web, mobile, api, etc. |
agents | Optional | Supported agents (auto-detected if omitted) |
Tips for a High Quality Score
Be specific and opinionated
Don't just restate documentation. Share real-world patterns, naming conventions, and project structure decisions.
Include code examples
AI agents learn best from concrete examples. Show complete test files, not just snippets.
Cover edge cases
Address common mistakes, anti-patterns, and gotchas. This is where expert knowledge shines.
Keep it focused
One skill per concern. A Playwright E2E skill shouldn't also cover API testing — make separate skills instead.
Frequently Asked Questions
How long does it take to publish a skill?
Under 2 minutes once your SKILL.md is written. CLI handles validation, upload, and indexing. Skill appears on qaskills.sh within 30 seconds.
Do I need a GitHub repository?
No. Publish a single SKILL.md from anywhere on disk. A GitHub repo helps with version control and the install fallback chain.
Is publishing free?
Yes. Free for open-source MIT/Apache-licensed skills. Premium paid skills require a creator account.
Which AI agents support QASkills.sh skills?
30+ agents: Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, Codex, Aider, Continue, Zed, Bolt, Gemini CLI, Amp, and more. CLI auto-detects installed agents.
How is the quality score calculated?
Weighted from install count (30%), retention (25%), review rating (20%), content depth (15%), update recency (10%). Score 80+ surfaces on leaderboard.
Can I update a published skill?
Yes. Bump version in frontmatter, run publish again. All installed copies get update notifications.
Troubleshooting
| Issue | Fix |
|---|---|
npx command not found | Install Node.js >= 20 from nodejs.org. npm ships with Node. |
Validation fails: "name too long" | Title must be 1-100 characters. Shorten or split into multiple skills. |
Login opens browser but never returns | Allow popups for qaskills.sh. If headless, use --token flag with a personal access token from /dashboard/tokens. |
Publish hangs | Check QASKILLS_API_URL env var. Default is https://qaskills.sh. Network behind proxy needs HTTPS_PROXY set. |
See Real Published Skills
Learn from skills already on the directory. Each one follows the same SKILL.md format you're writing now.