Submitting Skills

How to write a SKILL.md, pass verification, and publish your skill to the verified-skill.com registry.

Overview

Every skill on verified-skill.com starts as a SKILL.md file in a public GitHub repository. When you submit, the file goes through automated security scanning and LLM intent analysis before appearing in the registry.

├── FreeNo cost to submit. No approval queue for Tier 1 (Scanned).
├── PublicYour GitHub repo must be public. Private repos are not supported.
└── AutomatedTier 1 scanning is instant. Tier 2 LLM analysis adds 1-2 minutes.
Author + benchmark in Skill Studio first
npx vskill@latest studio opens a localhost IDE with an AI-assisted generator, A/B eval against a blind LLM judge, and a one-click publish that pushes to GitHub and opens the submit form pre-filled. See the Studio section in Getting Started.

SKILL.md format

A skill is a Markdown file with YAML frontmatter. The frontmatter declares metadata; the body contains the prompt instructions your AI agent will follow.

markdown
---
description: Generate responsive React components following accessibility best practices. Use when building UI components, forms, or interactive elements.
model: sonnet
---
 
# React Component Generator
 
You are an expert React developer...
 
## Guidelines
 
- Use functional components with hooks
- Follow WAI-ARIA accessibility standards
- Write TypeScript with proper type annotations
...
Tip
The description field is critical — it determines when your skill triggers and how it appears in search results. Be specific about what the skill does and when to use it.

Frontmatter schema

descriptionrequiredWhat the skill does and when to use it. Used for search and auto-triggering.
modeloptionalPreferred model: opus, sonnet, or haiku. Defaults to the user's active model.
nameoptionalDisplay name. Defaults to the filename without extension.
versionoptionalSemantic version (e.g., 1.0.0). Used for update tracking.
authoroptionalAuthor name or GitHub handle.
tagsoptionalComma-separated tags for categorization.

Submission flow

The end-to-end submission path. The git push is the durable record; the broadcast is an instant-notify optimization that no-ops without an internal key.
1

Create your SKILL.md

Write your skill in a public GitHub repository. The file must be named SKILL.md and placed at the root of the repository or in a subdirectory.

Or run npx vskill@latest studio and use the AI-assisted generator — it scaffolds the frontmatter, body, and benchmark suite for you.

2

Scan locally first

Run the scanner locally to catch issues before submitting.

bash
npx vskill@latest scan ./my-skill
3

Submit to the registry

Submit via the CLI or the web form at verified-skill.com/submit.

bash
npx vskill@latest submit owner/repo
4

Automated verification

The skill goes through Tier 1 static analysis (58 patterns) and Tier 2 LLM intent analysis (6 dimensions). Results appear on your publisher profile.

5

Published to registry

Once verified, your skill appears in the registry. Users can install it with npx vskill@latest install your-skill-name.

Verification timeline

ScannedInstant58 static patterns. Sub-second. Every skill, every time.
Verified1-2 minutesA language model reviews the skill. Runs when Tier 1 passes or has concerns.
CertifiedHuman reviewNeeds a trust score of 80 or more, a model review of 80 or more, matching provenance and a completed human review.

Pre-submission checklist

Self-audit your skill before submitting. If you check all boxes, your skill will almost certainly pass verification.

[ ]SKILL.md has valid YAML frontmatter with a description field
[ ]Skill does exactly what the description says, nothing more
[ ]No references to .env, .ssh, .aws, or credential stores
[ ]No curl, wget, or fetch to external URLs (unless required and documented)
[ ]No sudo, chmod, chown, or privilege escalation
[ ]No role impersonation phrases
[ ]No LLM delimiter tokens
[ ]No rm -rf or writes to system paths
[ ]DCI blocks (if any) use static, project-scoped commands only
[ ]No base64 payloads, hex escapes, or obfuscated strings
[ ]No lifecycle scripts in package.json (preinstall, postinstall)
[ ]Dependencies are well-known packages (no typosquats)
[ ]Code examples in fenced code blocks (triple backtick)
[ ]Repo is public on GitHub
False positives
If you have legitimate reasons to use flagged patterns, document them clearly in your SKILL.md. The Tier 2 LLM analysis takes context into account. See the Security Guidelines for details.

After submission

├── Content changesIf your SKILL.md changes between scan and approval, the submission enters RESCAN_REQUIRED state and must be re-scanned.
├── UpdatesPush the change and run the same vskill submit again: the skill is rescanned and published as a new version. The registry also rescans skills whose source changed, without a resubmit.
├── RejectionsA rejected skill is not a duplicate. Change SKILL.md, push, and submit again for a new scan; the same bytes stay rejected.
├── BlocklistingIf a skill is later found malicious, the author's entire portfolio is flagged for review.
└── AppealsFor DCI false positives and other findings, file a report via the report form.

New versions and private skills

Re-running vskill submit republishes. Raise version in the SKILL.md frontmatter, push, and submit again: the registry rescans the skill and records the new content as a new version. Every published version stays installable, and vskill pin holds an installed skill at one of them so vskill update leaves it alone.

bash
npx vskill@latest submit owner/repo
npx vskill@latest install owner/repo/my-skill@1.0.1
npx vskill@latest pin my-skill 1.0.1

A skill in a private repository is published with --private to an account connected through the GitHub App, never to the public registry. --tenant names the account; install a private version with --tenant and --version, which also pins it.

bash
npx vskill@latest submit owner/private-repo --private --tenant my-team
npx vskill@latest install --tenant my-team my-skill --version 1.0.1
Flags
The CLI reference lists every submit, install and pin flag.
Security Guidelines →Submit now →FAQ →

Related resources