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

> Discover the quality standards for agent skills in the Awesome-Agent-Skills repository. Learn about contribution requirements like public availability, naming, descriptions, token limits, and scoped tools.

- Repository: [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)
- Tags: best-practices
- Published: 2026-04-22

---

**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`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/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`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/README.md) or dedicated [`SKILL.md`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/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`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/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`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/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`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/README.md)

```markdown
- **[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`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/skill.json) Adhering to Quality Criteria

```json
{
  "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`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/CONTRIBUTING.md) enforce public availability, provenance naming, concise descriptions, and proven community adoption.
- **Technical quality criteria** in [`README.md`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/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`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/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`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/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.