Quality Guidelines (Soft Review)

These guidelines are not enforced by automated tooling. Reviewers should check these during manual PR review and flag violations as suggestions.

1. Skill Scope — Avoid Overlap

Before approving a new skill, check existing skills for functional overlap.

If the new skill's capability is a subset of an existing skill, suggest extending the existing one instead
If there is partial overlap, the PR description must clearly explain the boundary
Example: a voice synthesis skill should clarify how it differs from frontend-dev's TTS capabilities

2. Description Quality

The description field in SKILL.md is what the agent uses to decide whether to activate the skill. A good description must include:

What the skill does
When to use it (trigger conditions)
Keywords or phrases that should activate it

Bad: "A skill for making PDFs" Good: "Generate, fill, and reformat PDF documents. Use when the user asks to create, modify, or design any PDF file. Triggers: PDF, .pdf, document generation."

3. File Size Awareness

Skills are loaded into the agent's context window. Every token counts.

Individual .md files should stay focused and concise
If a reference document exceeds ~500 lines, consider splitting it into parts
Do not embed large data blobs (base64 images, full API responses) in Markdown
Prefer linking to external resources over inlining lengthy content

4. Credential Handling

The validation script only blocks high-confidence secret patterns (OpenAI keys, AWS keys, JWT tokens). Reviewers should additionally check for:

API keys or passwords assigned directly in code (e.g., api_key = "abc123...")
Credentials passed as plain string arguments instead of environment variable reads
Example keys that look realistic enough to be mistaken for real ones
Scripts that lack a clear error message when a required env var is missing

If a skill involves external APIs, verify that SKILL.md documents the required environment variables.

5. Script Quality

If the skill includes helper scripts in scripts/:

Scripts should have a shebang line (#!/usr/bin/env python3)
A requirements.txt should be present listing all dependencies if external libraries are needed.
Errors should produce clear messages, not raw tracebacks

6. Language

SKILL.md content and code should be written in English
Reference docs are recommended to be in English

7. README Sync

When a new skill is added, both README.md and README_zh.md should be updated with the new skill in the table. Community-submitted skills should set the Source column to Community.

2.6 KiB Raw Blame History