Pr Review

# 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`.


# Structure Rules (Hard Validation)

These rules are enforced by `scripts/validate_skills.py`. PRs that violate ERROR-level rules will not be merged.

## Directory Structure

Every skill must follow this layout:

```
skills/<skill-name>/
├── SKILL.md                 # Required
├── references/              # Optional
│   └── *.md
└── scripts/                 # Optional
    ├── *.py
    └── requirements.txt     # Required if scripts/ exists
```

- Directory name must be lowercase `kebab-case` (e.g., `gif-sticker-maker`)
- `SKILL.md` is the only required file

## SKILL.md Frontmatter

The file must begin with a valid YAML frontmatter block enclosed by `---` markers.

### Required Fields (ERROR if missing)

| Field | Rule |
|-------|------|
| `name` | Must exist and exactly match the directory name |
| `description` | Must exist and be non-empty |

### Recommended Fields (WARNING if missing)

| Field | Rule |
|-------|------|
| `license` | Should be `MIT` or a license declaration |
| `metadata` | Should include `version`, `category`, and optionally `sources` |

## Secret Scanning

No file in the skill directory may contain hardcoded secrets. The following high-confidence patterns are scanned:

- OpenAI-style API keys: `sk-` followed by 20+ alphanumeric characters
- AWS Access Key IDs: `AKIA` followed by 16 uppercase alph