What Quality Standards Must Agent Skills Meet for Inclusion in the Awesome-Agent-Skills Repository?

Agent skills must satisfy strict contribution requirements and technical quality criteria—including public repository availability, provenance naming, concise descriptions, token limits, and scoped tools—to be listed in the Awesome-Agent-Skills repository.

The Awesome-Agent-Skills repository curates a collection of high-quality, community-adopted agent skills for platforms like Claude Code, Codex, Gemini CLI, Cursor, and OpenCode. Maintainers enforce rigorous standards to ensure every listed skill is discoverable, safe, and valuable. This article details exactly what quality standards agent skills must meet for inclusion, drawing directly from the repository's source files.

Contribution Requirements: The Gate-Keeping Rules

Before any skill appears in the master list, submitters must satisfy the requirements defined in CONTRIBUTING.md. These rules filter out incomplete, unmaintained, or speculative projects.

Public Repository with Working Code and Documentation

The skill must reside in a public repository that contains functional code and adequate documentation—typically a README.md or dedicated SKILL.md file. Private repositories or placeholder projects are rejected.

Author or Organization Prefix in the Skill Name

Provenance matters. The skill name must include an author or organization prefix (e.g., anthropics/pdf, voltagent/web-search). This naming convention prevents collisions and establishes clear ownership.

Concise Description: 10 Words or Fewer

The entry in the master README.md must include a description of 10 words or fewer that clearly states the skill's purpose. Brevity improves scannability and reduces cognitive load for developers browsing the list.

Real-World Community Adoption

The repository rejects newly created skills—those less than approximately three hours old. The skill must already have real-world usage within the community. This requirement prevents the list from filling with experimental or abandoned experiments.

Technical Quality Criteria: Ensuring Consistency and Safety

Beyond contribution requirements, every skill must meet four technical quality criteria defined in README.md. These standards guarantee consistent discoverability, maintainability, and runtime safety across all listed skills.

Description: Third-Person, Keyword-Rich, Purpose-Driven

Skill descriptions must be written in third person, explicitly stating what the skill does and when to use it. Authors should include specific keywords that agent systems can match against—preferring precise terms like "PostgreSQL migration" over vague phrases like "database stuff."

Progressive Disclosure: Token Limits and Lazy Loading

Metadata overhead must stay minimal. The top-level metadata should remain under approximately 100 tokens, and the skill body itself should not exceed 500 lines. Large resources—such as documents, schemas, or datasets—must be loaded on demand rather than inlined into the skill definition. This approach reduces memory footprint and improves startup performance.

No Absolute Paths: Portability Across Environments

Hard-coded, machine-specific paths (e.g., /Users/alice/projects/skill/) are strictly prohibited. Authors must use relative paths or well-known environment variables such as $HOME, $PROJECT_ROOT, or $XDG_CONFIG_HOME. This requirement ensures skills function correctly across different developer machines, CI environments, and deployment targets.

Scoped Tools: Explicit Tool Declaration

Skill definitions must declare only the tools they genuinely require. The repository explicitly rejects wildcard tool declarations such as "tools": ["*"]. Authors should list each required tool explicitly (e.g., "tools": ["file-system", "http", "git"]). This scoping reduces the attack surface and prevents accidental or malicious operations outside the skill's intended scope.

Code Examples: Implementing the Standards

The following examples demonstrate how to satisfy both contribution requirements and technical quality criteria in practice.

Example 1: Proper Entry in README.md

- **[anthropics/pdf](https://github.com/anthropics/skills/pdf)** - Extract text, create PDFs, and handle forms

This entry passes inspection because:

• The repository is public and contains documentation.
• The name includes the organization prefix (anthropics).
• The description is 9 words, written in third person, and contains searchable keywords (Extract text, PDFs, forms).

Example 2: Minimal skill.json Adhering to Quality Criteria

{
  "name": "anthropics/pdf",
  "description": "Extract text from PDFs and generate new PDF files",
  "metadata": {
    "tokens": 78,
    "maxLines": 420
  },
  "tools": ["file-system", "http"],
  "paths": {
    "entry": "src/index.ts",
    "assets": "$PROJECT_ROOT/assets"
  }
}

This configuration satisfies all technical quality criteria:

• Description: Third-person, keyword-rich, purpose-driven.
• Progressive disclosure: tokens field shows 78 tokens (under ~100 limit); maxLines at 420 (under 500 limit).
• No absolute paths: Uses $PROJECT_ROOT environment variable.
• Scoped tools: Explicitly lists file-system and http only; no wildcard.

Summary

Agent skills must satisfy dual-layer quality standards to appear in the Awesome-Agent-Skills repository:

• Contribution requirements in CONTRIBUTING.md enforce public availability, provenance naming, concise descriptions, and proven community adoption.
• Technical quality criteria in README.md ensure consistent metadata, portability, progressive disclosure, and minimal attack surface through scoped tools.

These standards collectively guarantee that every listed skill is discoverable, safe, portable, and valuable across the diverse ecosystem of agent platforms.

Frequently Asked Questions

What happens if my skill is less than three hours old?

Submission will be rejected. The Awesome-Agent-Skills repository requires real-world community adoption before inclusion. Skills must demonstrate existing usage rather than being freshly created experiments.

Can I use a wildcard to declare all available tools?

No. The quality criteria explicitly prohibit wildcard tool declarations such as "tools": ["*"]. You must list each required tool individually to reduce attack surface and ensure precise operational scope.

How strict is the 10-word description limit in the README entry?

Strict. The CONTRIBUTING.md file specifies that descriptions must be 10 words or fewer. This brevity improves scannability and fits the curated list format. However, your internal skill.json description can be more detailed for agent consumption.

What environment variables should I use instead of absolute paths?

Use well-known variables such as $HOME, $PROJECT_ROOT, or $XDG_CONFIG_HOME. The quality criteria prohibit hard-coded paths like /Users/alice/ to ensure skills function across different machines and deployment environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}