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
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
|
name: Release Agent Plugin
on:
push:
branches:
- "**"
workflow_dispatch:
permissions:
contents: write
concurrency:
group: agent-plugin-release-${{ github.sha }}
cancel-in-progress: false
jobs:
build-and-release:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install Python dependencies
run: |
python -m pip install --upgrade pip
pip install jsonschema pyyaml
- name: Install Agent Plugin Validator
env:
APV_VERSION: "1.4.0"
shell: bash
run: |
set -euo pipefail
asset="apv_${APV_VERSION}_linux_amd64.tar.gz"
base_url="https://github.com/rchaganti/agent-plugins-validator/releases/download/v${APV_VERSION}"
curl --fail --silent --show-error --location --remote-name "${base_url}/${asset}"
curl --fail --silent --show-error --location --remote-name "${base_url}/checksums.txt"
grep " ${asset}$" checksums.txt | sha256sum --check -
tar -xzf "$asset"
sudo install -m 0755 apv /usr/local/bin/apv
apv --version
- name: Build portable plugin package
shell: python
run: |
import json
import shutil
from pathlib import Path
# Load plugin manifest to determine package name
manifest_path = Path("plugin.json")
if not manifest_path.is_file():
raise FileNotFoundError("Missing root plugin.json manifest")
with open(manifest_path, "r", encoding="utf-8") as f:
manifest = json.load(f)
plugin_name = manifest.get("name", "agent-plugin")
package_dir = Path("dist") / plugin_name
if package_dir.exists():
shutil.rmtree(package_dir)
(package_dir / "skills").mkdir(parents=True)
# Copy root plugin metadata
shutil.copy2("plugin.json", package_dir / "plugin.json")
for optional_file in ["mcp.json", "LICENSE", "LICENSE.md", "README.md", "CHANGELOG.md"]:
if Path(optional_file).is_file():
shutil.copy2(optional_file, package_dir / optional_file)
# Dynamically discover and package all skills containing a SKILL.md
ignored_dirs = {"dist", "release", ".git", ".github", "node_modules", "skills"}
discovered_skills = []
for item in sorted(Path(".").iterdir()):
if item.is_dir() and item.name not in ignored_dirs and not item.name.startswith("."):
skill_md = item / "SKILL.md"
if skill_md.is_file():
target_skill_dir = package_dir / "skills" / item.name
shutil.copytree(
item,
target_skill_dir,
ignore=shutil.ignore_patterns(
"__pycache__", "*.pyc", ".pytest_cache", "demo_output", "raw_recordings", "audio_output", ".git*"
),
)
discovered_skills.append(item.name)
if not discovered_skills:
raise ValueError("No valid skill directories containing SKILL.md found in repository")
print(f"Successfully packaged {len(discovered_skills)} skills into {package_dir}: {', '.join(discovered_skills)}")
- name: Validate Agent Plugin manifests with APV
shell: bash
run: |
package_dir="$(find dist -mindepth 1 -maxdepth 1 -type d | head -n 1)"
apv validate "$package_dir"
- name: Validate portable package layout and containment
shell: python
run: |
import yaml
from pathlib import Path
package_dir = next(Path("dist").iterdir())
if not package_dir.is_dir():
raise FileNotFoundError("Package directory not found in dist/")
# Validate root manifest exists
manifest_file = package_dir / "plugin.json"
if not manifest_file.is_file():
raise FileNotFoundError("Missing plugin.json at plugin root")
# Validate all packaged skills
skills_dir = package_dir / "skills"
if not skills_dir.is_dir():
raise FileNotFoundError("Missing skills/ directory in built package")
skills = [d for d in skills_dir.iterdir() if d.is_dir()]
if not skills:
raise ValueError("No skill directories found under skills/")
for skill_dir in skills:
skill_entry = skill_dir / "SKILL.md"
if not skill_entry.is_file():
raise FileNotFoundError(f"Missing SKILL.md entrypoint in {skill_dir.name}")
# Validate YAML frontmatter
text = skill_entry.read_text(encoding="utf-8")
if not text.startswith("---"):
raise ValueError(f"SKILL.md in {skill_dir.name} is missing YAML frontmatter")
parts = text.split("---", 2)
if len(parts) < 3:
raise ValueError(f"Invalid YAML frontmatter structure in {skill_entry}")
fm = yaml.safe_load(parts[1]) or {}
if "name" not in fm or "description" not in fm:
raise ValueError(f"SKILL.md in {skill_dir.name} requires 'name' and 'description' fields in frontmatter")
# Validate containment (symlinks and paths must stay within plugin root)
for path in package_dir.rglob("*"):
if path.is_symlink() and package_dir not in path.resolve().parents:
raise ValueError(f"Package path escapes plugin root: {path}")
print(f"Verified package layout, frontmatter, and containment for {len(skills)} skills.")
- name: Create release archives and checksums
id: package
shell: bash
run: |
set -euo pipefail
package_name="$(basename "$(find dist -mindepth 1 -maxdepth 1 -type d | head -n 1)")"
short_sha="${GITHUB_SHA::12}"
artifact_name="${package_name}-${short_sha}"
mkdir -p release
tar -czf "release/${artifact_name}.tar.gz" -C dist "$package_name"
(
cd dist
zip -qr "../release/${artifact_name}.zip" "$package_name"
)
(
cd release
sha256sum "${artifact_name}.tar.gz" "${artifact_name}.zip" > SHA256SUMS
)
echo "package_name=${package_name}" >> "$GITHUB_OUTPUT"
echo "artifact_name=${artifact_name}" >> "$GITHUB_OUTPUT"
echo "release_tag=agent-plugin-${GITHUB_SHA}" >> "$GITHUB_OUTPUT"
- name: Upload workflow artifact
uses: actions/upload-artifact@v4
with:
name: ${{ steps.package.outputs.artifact_name }}
path: |
release/*.tar.gz
release/*.zip
release/SHA256SUMS
if-no-files-found: error
- name: Create or update commit release
env:
GH_TOKEN: ${{ github.token }}
RELEASE_TAG: ${{ steps.package.outputs.release_tag }}
shell: python
run: |
import json
import os
import subprocess
from pathlib import Path
package_dir = next(Path("dist").iterdir())
# Extract metadata from plugin.json
with open(package_dir / "plugin.json", "r", encoding="utf-8") as f:
manifest = json.load(f)
plugin_name = manifest.get("name", "agent-plugin")
version = manifest.get("version", "1.0.0")
desc = manifest.get("description", "")
# Extract MCP servers from mcp.json if present
mcp_servers = []
mcp_file = package_dir / "mcp.json"
if mcp_file.is_file():
with open(mcp_file, "r", encoding="utf-8") as f:
mcp_data = json.load(f)
for s_name, s_cfg in mcp_data.get("mcpServers", {}).items():
s_type = s_cfg.get("type", "unknown")
s_target = s_cfg.get("url") or s_cfg.get("command") or ""
mcp_servers.append(f"- `{s_name}` ({s_type}): `{s_target}`")
# Extract packaged skills
skills = [d.name for d in (package_dir / "skills").iterdir() if d.is_dir()]
commit_sha = os.environ.get("GITHUB_SHA", "unknown")
ref_name = os.environ.get("GITHUB_REF_NAME", "main")
release_tag = os.environ.get("RELEASE_TAG", f"agent-plugin-{commit_sha}")
short_sha = commit_sha[:12]
notes_lines = [
f"Portable Agent Plugin build for commit `{commit_sha}` on `{ref_name}`.",
"",
f"- **Agent Plugins Spec Version**: `1.0.0`",
f"- **Plugin Name**: `{plugin_name}` (v{version})",
f"- **Description**: {desc}",
"",
f"### 📦 Bundled Skills ({len(skills)})"
]
for s in sorted(skills):
notes_lines.append(f"- `{s}`")
if mcp_servers:
notes_lines.extend(["", "### 🔌 Configured MCP Servers"] + mcp_servers)
notes_lines.extend([
"",
"Both `.tar.gz` and `.zip` archives contain the standard portable plugin layout. Verify downloads with `SHA256SUMS`."
])
notes_path = Path("release_notes.md")
notes_path.write_text("\n".join(notes_lines), encoding="utf-8")
# Check if release exists
view_cmd = ["gh", "release", "view", release_tag]
result = subprocess.run(view_cmd, capture_output=True, text=True)
if result.returncode == 0:
edit_cmd = [
"gh", "release", "edit", release_tag,
"--title", f"Agent Plugin {short_sha}",
"--notes-file", str(notes_path),
"--prerelease=false"
]
subprocess.run(edit_cmd, check=True)
upload_cmd = ["gh", "release", "upload", release_tag] + [str(p) for p in Path("release").iterdir()] + ["--clobber"]
subprocess.run(upload_cmd, check=True)
else:
create_cmd = [
"gh", "release", "create", release_tag,
"--target", commit_sha,
"--title", f"Agent Plugin {short_sha}",
"--notes-file", str(notes_path)
] + [str(p) for p in Path("release").iterdir()]
subprocess.run(create_cmd, check=True)
|
Comments
Comments Require Consent
The comment system (Giscus) uses GitHub and may set authentication cookies. Enable comments to join the discussion.