1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
#!/usr/bin/env python3
"""
Validate a Pi skill directory for Agent Skills + README requirements.
Usage:
python3 scripts/validate_skill.py <skill_directory>
Requires PyYAML. On Arch Linux, install it with:
sudo pacman -S python-yaml
"""
from __future__ import annotations
import re
import sys
from pathlib import Path
import yaml
MAX_NAME_LENGTH = 64
MAX_DESCRIPTION_LENGTH = 1024
ALLOWED_FRONTMATTER_FIELDS = {
"name",
"description",
"license",
"compatibility",
"metadata",
"allowed-tools",
"disable-model-invocation",
}
NAME_PATTERN = re.compile(r"^[a-z0-9-]+$")
FRONTMATTER_PATTERN = re.compile(r"^---\n(.*?)\n---", re.DOTALL)
INSTALLATION_HEADING = re.compile(r"^#{1,6}\s+installation\b", re.IGNORECASE)
def read_frontmatter(skill_md: Path) -> tuple[dict | None, str | None]:
content = skill_md.read_text()
if not content.startswith("---"):
return None, "No YAML frontmatter found"
match = FRONTMATTER_PATTERN.match(content)
if not match:
return None, "Invalid frontmatter format"
try:
frontmatter = yaml.safe_load(match.group(1))
except yaml.YAMLError as exc:
return None, f"Invalid YAML in frontmatter: {exc}"
if not isinstance(frontmatter, dict):
return None, "Frontmatter must be a YAML mapping"
return frontmatter, None
def validate_readme(readme_path: Path) -> tuple[list[str], list[str]]:
errors: list[str] = []
warnings: list[str] = []
if not readme_path.exists():
return ["README.md not found"], warnings
content = readme_path.read_text().strip()
if not content:
return ["README.md is empty"], warnings
lines = readme_path.read_text().splitlines()
installation_index = None
for idx, line in enumerate(lines):
if INSTALLATION_HEADING.match(line.strip()):
installation_index = idx
break
if installation_index is None:
errors.append("README.md is missing an Installation section")
else:
summary_lines = [
line.strip()
for line in lines[:installation_index]
if line.strip() and not line.strip().startswith("#")
]
if not summary_lines:
warnings.append("README.md has no summary text before Installation")
return errors, warnings
def validate_frontmatter(frontmatter: dict, skill_dir: Path) -> tuple[list[str], list[str]]:
errors: list[str] = []
warnings: list[str] = []
keys = set(frontmatter.keys())
unknown = sorted(keys - ALLOWED_FRONTMATTER_FIELDS)
if unknown:
warnings.append(f"Unknown frontmatter field(s): {', '.join(unknown)}")
name = frontmatter.get("name")
if not isinstance(name, str) or not name.strip():
errors.append("Missing or invalid 'name' in frontmatter")
else:
normalized = name.strip()
parent_dir = skill_dir.name
if normalized != parent_dir:
errors.append(
f"Frontmatter name '{normalized}' does not match directory '{parent_dir}'"
)
if len(normalized) > MAX_NAME_LENGTH:
errors.append(
f"Name is too long ({len(normalized)}). Max {MAX_NAME_LENGTH}."
)
if not NAME_PATTERN.match(normalized):
errors.append(
"Name must be lowercase letters, digits, and hyphens only"
)
if normalized.startswith("-") or normalized.endswith("-"):
errors.append("Name must not start or end with a hyphen")
if "--" in normalized:
errors.append("Name must not contain consecutive hyphens")
description = frontmatter.get("description")
if not isinstance(description, str) or not description.strip():
errors.append("Missing or invalid 'description' in frontmatter")
else:
desc = description.strip()
if len(desc) > MAX_DESCRIPTION_LENGTH:
errors.append(
f"Description is too long ({len(desc)}). Max {MAX_DESCRIPTION_LENGTH}."
)
allowed_tools = frontmatter.get("allowed-tools")
if allowed_tools is not None and not isinstance(allowed_tools, str):
warnings.append("'allowed-tools' should be a space-delimited string")
compatibility = frontmatter.get("compatibility")
if compatibility is not None and not isinstance(compatibility, str):
warnings.append("'compatibility' should be a string")
license_value = frontmatter.get("license")
if license_value is not None and not isinstance(license_value, str):
warnings.append("'license' should be a string")
metadata = frontmatter.get("metadata")
if metadata is not None and not isinstance(metadata, dict):
warnings.append("'metadata' should be a mapping")
disable_invocation = frontmatter.get("disable-model-invocation")
if disable_invocation is not None and not isinstance(disable_invocation, bool):
warnings.append("'disable-model-invocation' should be a boolean")
return errors, warnings
def validate_skill(skill_path: Path) -> tuple[list[str], list[str]]:
errors: list[str] = []
warnings: list[str] = []
if not skill_path.exists():
return [f"Skill directory not found: {skill_path}"], warnings
if not skill_path.is_dir():
return [f"Skill path is not a directory: {skill_path}"], warnings
skill_md = skill_path / "SKILL.md"
if not skill_md.exists():
errors.append("SKILL.md not found")
return errors, warnings
frontmatter, frontmatter_error = read_frontmatter(skill_md)
if frontmatter_error:
errors.append(frontmatter_error)
return errors, warnings
fm_errors, fm_warnings = validate_frontmatter(frontmatter, skill_path)
errors.extend(fm_errors)
warnings.extend(fm_warnings)
readme_errors, readme_warnings = validate_readme(skill_path / "README.md")
errors.extend(readme_errors)
warnings.extend(readme_warnings)
return errors, warnings
def main() -> None:
if len(sys.argv) != 2:
print("Usage: scripts/validate_skill.py <skill_directory>")
sys.exit(1)
skill_path = Path(sys.argv[1]).resolve()
errors, warnings = validate_skill(skill_path)
if warnings:
print("Warnings:")
for warning in warnings:
print(f" - {warning}")
print()
if errors:
print("Errors:")
for error in errors:
print(f" - {error}")
sys.exit(1)
print("Skill is valid!")
sys.exit(0)
if __name__ == "__main__":
main()
|