mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-02 21:34:30 +08:00
f5e63fd06a
* @W-22252932 [Meta Skill] Skill Creator * @W-22252932 [Meta Skill] Skill Creator * @W-22252932 [Meta Skill] Skill Creator * @W-22252932 [Meta Skill] Skill Creator * @W-22252932 [Meta Skill] Skill Creator * @W-22252932 [Meta Skill] Skill Creator * @W-22252932 [Meta Skill] Skill Creator * @W-22252932 [Meta Skill] Skill Creator
130 lines
3.9 KiB
Markdown
130 lines
3.9 KiB
Markdown
# Validation Rules Reference
|
|
|
|
Complete reference for all validation checks enforced by `scripts/validate-skills.ts`.
|
|
The validator runs structure checks first (before reading SKILL.md), then content checks.
|
|
|
|
## Structure Checks
|
|
|
|
These run on every entry in `skills/` before SKILL.md is read.
|
|
A fatal error aborts all content checks for that entry.
|
|
|
|
### 1. Entry Must Be a Directory
|
|
|
|
- **Severity**: Error (fatal)
|
|
- **Rule**: No loose files in `skills/` — only directories.
|
|
- **Fix**: Move the file into a skill directory or remove it.
|
|
|
|
### 2. Must Contain SKILL.md
|
|
|
|
- **Severity**: Error (fatal)
|
|
- **Rule**: Every skill directory must have a `SKILL.md` file.
|
|
- **Fix**: Create `SKILL.md` with proper frontmatter and body.
|
|
|
|
### 3. Name Must Be Kebab-Case
|
|
|
|
- **Severity**: Error
|
|
- **Pattern**: `^[a-z0-9]+(-[a-z0-9]+)*$`
|
|
- **Allowed**: lowercase letters, digits, hyphens
|
|
- **Not allowed**: uppercase, underscores, dots, spaces
|
|
- **Examples**:
|
|
- `generating-apex` (valid)
|
|
- `Generating-Apex` (invalid — uppercase)
|
|
- `generating_apex` (invalid — underscore)
|
|
|
|
### 4. Name <= 64 Characters
|
|
|
|
- **Severity**: Error
|
|
- **Rule**: Directory name must not exceed 64 characters.
|
|
|
|
### 5. Gerund First Word
|
|
|
|
- **Severity**: Warning (not blocking)
|
|
- **Rule**: First word of the skill name should end in `-ing`.
|
|
- **Rationale**: Convention for consistency (e.g., `generating-`, `building-`, `deploying-`).
|
|
- **Examples**:
|
|
- `generating-apex` (pass)
|
|
- `agentforce-development` (warning — "agentforce" doesn't end in -ing)
|
|
|
|
### 6. No Nested Skills
|
|
|
|
- **Severity**: Error
|
|
- **Rule**: No subdirectory of a skill may contain its own `SKILL.md`.
|
|
- **Fix**: Flatten nested skills to be siblings under `skills/`.
|
|
|
|
## Content Checks
|
|
|
|
These run after SKILL.md is read successfully.
|
|
|
|
### 7. Valid YAML Frontmatter Block
|
|
|
|
- **Severity**: Error (fatal)
|
|
- **Rule**: SKILL.md must start with `---\n...\n---` YAML frontmatter.
|
|
- **Fix**: Add frontmatter between `---` delimiters at the top of the file.
|
|
|
|
### 8. JSON-Compatible YAML
|
|
|
|
- **Severity**: Error
|
|
- **Rule**: Frontmatter must parse with `js-yaml` JSON_SCHEMA.
|
|
- **Common cause**: Unquoted values containing `: ` (colon + space).
|
|
- **Fix**: Wrap values in single or double quotes.
|
|
```yaml
|
|
# BAD
|
|
description: Primary skill: generates Apex classes
|
|
|
|
# GOOD
|
|
description: "Primary skill: generates Apex classes"
|
|
```
|
|
|
|
### 9. `name` Matches Directory
|
|
|
|
- **Severity**: Error
|
|
- **Rule**: The `name` field in frontmatter must exactly match the directory name.
|
|
- **Fix**: Ensure `name: generating-apex` if the directory is `skills/generating-apex/`.
|
|
|
|
### 10. `description` Present and Non-Empty
|
|
|
|
- **Severity**: Error
|
|
- **Rule**: Frontmatter must include a `description` field with content.
|
|
|
|
### 11. Body Non-Empty
|
|
|
|
- **Severity**: Error
|
|
- **Rule**: There must be content after the frontmatter block.
|
|
|
|
### 12. Description >= 20 Words
|
|
|
|
- **Severity**: Error
|
|
- **Rule**: Description must contain at least 20 words.
|
|
- **Rationale**: Short descriptions don't provide enough trigger context.
|
|
|
|
### 13. Description <= 1024 Characters
|
|
|
|
- **Severity**: Error
|
|
- **Rule**: Description must not exceed 1024 characters.
|
|
|
|
### 14. Description Contains "use"
|
|
|
|
- **Severity**: Error
|
|
- **Rule**: Description must include the word "use" (case-insensitive).
|
|
- **Rationale**: Enforces trigger/activation language.
|
|
- **Fix**: Include phrases like "Use when...", "Use this skill for...", "Used to...".
|
|
|
|
### 15. Body <= 500 Lines
|
|
|
|
- **Severity**: Warning (not blocking)
|
|
- **Rule**: Skill body should be under 500 lines for context efficiency.
|
|
- **Fix**: Extract detailed content into `references/` with conditional load instructions.
|
|
|
|
## Running Validation
|
|
|
|
```bash
|
|
# Validate all skills
|
|
npm run validate:skills
|
|
|
|
# Validate only changed skills (CI mode)
|
|
npm run validate:skills -- --changed --base=origin/main
|
|
|
|
# Validate a specific skill (filter output)
|
|
npx tsx scripts/validate-skills.ts 2>&1 | grep -A5 "<skill-name>"
|
|
```
|