@teevee98/synapse-hub 4.1.4 → 4.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. package/.agents/rules/git-push-protocol.md +2 -2
  2. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +52 -3
  3. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +55 -5
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +62 -67
  5. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +54 -4
  6. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +62 -12
  7. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +55 -8
  8. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +60 -12
  9. package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
  10. package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
  11. package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
  12. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +54 -91
  13. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +59 -11
  14. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +50 -4
  15. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +55 -9
  16. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +55 -9
  17. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +55 -8
  18. package/.agents/skills/02-test-design/review-spec/SKILL.md +50 -6
  19. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +50 -4
  20. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +56 -5
  21. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +53 -7
  22. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +86 -36
  23. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +54 -6
  24. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +50 -6
  25. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +50 -3
  26. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +63 -14
  27. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +51 -5
  28. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +54 -4
  29. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +51 -5
  30. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +53 -6
  31. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +54 -8
  32. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +60 -24
  33. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +52 -6
  34. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +56 -10
  35. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +58 -12
  36. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +58 -12
  37. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +53 -5
  38. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +56 -5
  39. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +53 -4
  40. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +58 -5
  41. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +57 -11
  42. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +83 -34
  43. package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
  44. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +55 -10
  45. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +49 -6
  46. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +52 -7
  47. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +55 -10
  48. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +51 -5
  49. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +54 -17
  50. package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
  51. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +50 -4
  52. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +53 -7
  53. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +50 -4
  54. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +58 -13
  55. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +51 -5
  56. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +57 -10
  57. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +50 -4
  58. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +50 -4
  59. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +55 -9
  60. package/.cursor/rules/synapse-qa.mdc +20 -7
  61. package/.cursorrules +19 -5
  62. package/.windsurfrules +18 -3
  63. package/AGENTS.md +51 -59
  64. package/CLAUDE.md +38 -24
  65. package/LICENSE +5 -5
  66. package/NOTICE +1 -1
  67. package/README.en.md +4 -4
  68. package/README.md +4 -4
  69. package/agentskills.json +1 -1
  70. package/docs/ARCHITECTURE.en.md +2 -2
  71. package/docs/ARCHITECTURE.md +11 -2
  72. package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
  73. package/docs/CLI_REFERENCE.en.md +6 -4
  74. package/docs/CLI_REFERENCE.md +1 -1
  75. package/docs/CONTRIBUTING.en.md +1 -1
  76. package/docs/CONTRIBUTING.md +2 -2
  77. package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
  78. package/docs/TOOL_CATALOG.md +6 -2
  79. package/docs/research/agent_skill_training_analysis.md +1 -1
  80. package/package.json +1 -1
  81. package/plugin.json +1 -1
  82. package/skills_manifest.json +320 -55
  83. package/synapse.config.json +1 -1
  84. package/templates/ai_bridges/CLAUDE.md +29 -26
  85. package/templates/ai_bridges/copilot-instructions.md +14 -5
  86. package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
  87. package/templates/ai_bridges/windsurfrules +14 -3
  88. package/templates/ui/index.html +2 -2
  89. package/tools/TOOLS_RUNBOOK.md +1 -1
  90. package/tools/TOOL_CATALOG.json +63 -3
  91. package/tools/__init__.py +1 -1
  92. package/tools/api_fuzzer.py +447 -132
  93. package/tools/author_integrity.py +121 -11
  94. package/tools/benchmark_swarm_context.py +130 -22
  95. package/tools/break_ui_generator.py +233 -0
  96. package/tools/browser_helpers.js +2 -2
  97. package/tools/check_version_sync.py +18 -50
  98. package/tools/cli.py +110 -19
  99. package/tools/core/bm25_retriever.py +218 -0
  100. package/tools/core/i18n.py +5 -5
  101. package/tools/core/provider_usage_adapter.py +383 -0
  102. package/tools/core/token_estimator.py +81 -15
  103. package/tools/count_tokens.py +7 -2
  104. package/tools/coverage_reporter.py +245 -0
  105. package/tools/dashboard_generator.py +8 -8
  106. package/tools/db_sandbox.py +290 -9
  107. package/tools/distill_log.py +1 -1
  108. package/tools/distill_skill.py +206 -0
  109. package/tools/git_pre_commit_guard.py +202 -1
  110. package/tools/humanize_linter.py +3 -0
  111. package/tools/mcp_docx_server.py +1 -1
  112. package/tools/mcp_excel_server.py +1 -1
  113. package/tools/mcp_server.py +104 -16
  114. package/tools/micro_mutator.py +114 -15
  115. package/tools/pentest_scope_guard.py +674 -58
  116. package/tools/perf/benchmark_perf_runner.py +42 -0
  117. package/tools/project_state.py +29 -5
  118. package/tools/reversible_sandbox.py +58 -13
  119. package/tools/rules_router.py +473 -60
  120. package/tools/security_scanner.py +80 -0
  121. package/tools/senior_code_review.py +14 -0
  122. package/tools/skill_canonical_digest.py +302 -0
  123. package/tools/skill_profiles.py +77 -7
  124. package/tools/slide_deck_exporter.py +477 -0
  125. package/tools/sync_agent_rules.py +187 -61
  126. package/tools/sync_skills_manifest.py +166 -0
  127. package/tools/task_memory_manager.py +275 -0
  128. package/tools/ui_server.py +3 -1
  129. package/tools/update_sentinel.py +3 -3
  130. package/tools/validate_host_interop.py +485 -0
  131. package/tools/validate_skills_schema.py +575 -0
  132. package/tools/verify_all.py +668 -44
  133. package/tools/welcome_page.py +2 -2
@@ -0,0 +1,575 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thįŗæ Vị (@TeeVee98). All rights reserved.
3
+ # SPDX-License-Identifier: MIT
4
+ # Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
5
+
6
+ """
7
+ tools/validate_skills_schema.py — Standalone Skill Schema & Policy Validator
8
+ Validates all skills against:
9
+ - Layer 1: Upstream Schema Conformance (Agent Skills Specification v1.0)
10
+ - Layer 2: Synapse Policy Extensions (Policies, 5 Sections, Code Blocks, Links & Pinning)
11
+ """
12
+
13
+ import sys
14
+ import re
15
+ import json
16
+ import argparse
17
+ import importlib.util
18
+ from dataclasses import dataclass
19
+ from pathlib import Path
20
+ from typing import Dict, Any, List, Tuple, Optional
21
+
22
+ # Enforce UTF-8 stdout encoding for Windows console compatibility
23
+ if hasattr(sys.stdout, "reconfigure"):
24
+ sys.stdout.reconfigure(encoding="utf-8", errors="replace")
25
+ if hasattr(sys.stderr, "reconfigure"):
26
+ sys.stderr.reconfigure(encoding="utf-8", errors="replace")
27
+
28
+ ALLOWED_CATEGORIES = {
29
+ "test_automation_and_execution",
30
+ "architecture_and_analysis",
31
+ "verification_and_resilience",
32
+ "context_and_optimization",
33
+ }
34
+
35
+ ALLOWED_POLICIES = {
36
+ "network": {"none", "localhost-only", "sandbox-only"},
37
+ "shell": {"none", "read-only", "workspace-sandbox"},
38
+ "filesystem": {"read-only", "workspace-sandbox"},
39
+ }
40
+
41
+ SEMVER_REGEX = re.compile(r"^\d+\.\d+\.\d+$")
42
+ SKILL_NAME_REGEX = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
43
+ MD_LINK_REGEX = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
44
+ GITHUB_ACTION_REGEX = re.compile(r"uses:\s*actions/([a-zA-Z0-9_-]+)@([^\s#]+)")
45
+ COMMIT_SHA_40_REGEX = re.compile(r"^[0-9a-f]{40}$")
46
+
47
+ # Unproven quantitative / superlative claims patterns
48
+ UNPROVEN_CLAIMS_PATTERNS = [
49
+ re.compile(r"98%\s+of\s+all\s+risky\s+logic", re.IGNORECASE),
50
+ re.compile(r"80%\s+of\s+daily\s+test\s+automation\s+defects", re.IGNORECASE),
51
+ re.compile(r"100%\s+selector\s+hit\s+rate", re.IGNORECASE),
52
+ re.compile(r"100%\s+in\s+200ms", re.IGNORECASE),
53
+ re.compile(r"Infinite\s+CI/CD\s+replays\s+with\s+0\s+LLM\s+Tokens", re.IGNORECASE),
54
+ re.compile(r"100%\s+stable\s+tests\s*\(Zero\s+Flaky\s+Disruptions\)", re.IGNORECASE),
55
+ ]
56
+
57
+ REQUIRED_SECTION_PATTERNS = [
58
+ (1, re.compile(r"^##\s+1\.\s+Trigger\s*&\s*Activation", re.IGNORECASE | re.MULTILINE), "1. Trigger & Activation ('Use when...')"),
59
+ (2, re.compile(r"^##\s+2\.\s+Non-Goals?\s*&\s*Boundary\s*Constraints?", re.IGNORECASE | re.MULTILINE), "2. Non-Goals & Boundary Constraints"),
60
+ (3, re.compile(r"^##\s+3\.\s+Ordered\s+Execution\s+Workflow", re.IGNORECASE | re.MULTILINE), "3. Ordered Execution Workflow"),
61
+ (4, re.compile(r"^##\s+4\.\s+Verification\s+Points?\s*&\s*DoD", re.IGNORECASE | re.MULTILINE), "4. Verification Points & DoD"),
62
+ (5, re.compile(r"^##\s+5\.\s+Handoff\s+Protocol", re.IGNORECASE | re.MULTILINE), "5. Handoff Protocol"),
63
+ ]
64
+
65
+ # Backtick reference path pattern: matches backtick paths like `dir/file.ext` or `reports/file.json`
66
+ BACKTICK_PATH_REGEX = re.compile(r"`([a-zA-Z0-9_.-]+/[a-zA-Z0-9_./-]+\.[a-zA-Z0-9_-]+)`")
67
+
68
+
69
+ @dataclass
70
+ class CodeBlockInfo:
71
+ language: str
72
+ classification: str # "runnable" | "pseudocode" | "illustrative" | "unclassified"
73
+ code: str
74
+ start_line: int
75
+ has_prerequisites: bool = False
76
+ has_test_data: bool = False
77
+ has_expected_output: bool = False
78
+
79
+
80
+ def classify_code_blocks(file_content: str) -> List[CodeBlockInfo]:
81
+ """
82
+ Parses markdown content and extracts all fenced code blocks with language,
83
+ classification (runnable, pseudocode, illustrative), and metadata.
84
+ """
85
+ blocks: List[CodeBlockInfo] = []
86
+ lines = file_content.splitlines()
87
+ in_block = False
88
+ current_lang = ""
89
+ current_lines: List[str] = []
90
+ block_start_line = 0
91
+ preceding_comment_classification: Optional[str] = None
92
+ preceding_comment_line = -10
93
+
94
+ for idx, line in enumerate(lines, 1):
95
+ stripped = line.strip()
96
+
97
+ # Check for HTML comment classification tag immediately preceding code block
98
+ comment_match = re.search(
99
+ r"<!--\s*classification:\s*(runnable|pseudocode|illustrative)\s*-->",
100
+ stripped,
101
+ re.IGNORECASE,
102
+ )
103
+ if comment_match:
104
+ preceding_comment_classification = comment_match.group(1).lower()
105
+ preceding_comment_line = idx
106
+ continue
107
+
108
+ if stripped.startswith("```"):
109
+ if not in_block:
110
+ # Starting a code block
111
+ in_block = True
112
+ current_lang = stripped[3:].strip()
113
+ current_lines = []
114
+ block_start_line = idx
115
+ else:
116
+ # Ending a code block
117
+ in_block = False
118
+ code_text = "\n".join(current_lines)
119
+
120
+ # Determine classification
121
+ classification = "unclassified"
122
+ # 1. Check preceding HTML comment if it was within 2 lines
123
+ if preceding_comment_classification and (block_start_line - preceding_comment_line <= 2):
124
+ classification = preceding_comment_classification
125
+
126
+ # 2. Check if first few lines inside code block specify classification
127
+ if classification == "unclassified":
128
+ for c_line in current_lines[:3]:
129
+ inline_match = re.search(
130
+ r"(?:#|//|--|<!--)\s*classification:\s*(runnable|pseudocode|illustrative)",
131
+ c_line,
132
+ re.IGNORECASE,
133
+ )
134
+ if inline_match:
135
+ classification = inline_match.group(1).lower()
136
+ break
137
+
138
+ # 3. Check runnable metadata
139
+ has_prereq = bool(
140
+ re.search(r"(?i)(?:#|//|--)\s*(?:prerequisites?|requirements?):", code_text)
141
+ )
142
+ has_data = bool(
143
+ re.search(
144
+ r"(?i)(?:#|//|--)\s*(?:test\s*data|sample\s*payload|seed\s*data|sample\s*data):",
145
+ code_text,
146
+ )
147
+ )
148
+ has_output = bool(
149
+ re.search(
150
+ r"(?i)(?:#|//|--)\s*(?:expected\s*output|expected\s*result|expected\s*response):",
151
+ code_text,
152
+ )
153
+ )
154
+
155
+ blocks.append(
156
+ CodeBlockInfo(
157
+ language=current_lang,
158
+ classification=classification,
159
+ code=code_text,
160
+ start_line=block_start_line,
161
+ has_prerequisites=has_prereq,
162
+ has_test_data=has_data,
163
+ has_expected_output=has_output,
164
+ )
165
+ )
166
+
167
+ # Reset preceding comment tracking
168
+ preceding_comment_classification = None
169
+ preceding_comment_line = -10
170
+ elif in_block:
171
+ current_lines.append(line)
172
+ else:
173
+ # If line is non-empty and not a comment, invalidate distant preceding comment
174
+ if stripped and not comment_match:
175
+ if idx - preceding_comment_line > 2:
176
+ preceding_comment_classification = None
177
+
178
+ return blocks
179
+
180
+
181
+ def parse_yaml_frontmatter(content: str) -> Tuple[Optional[Dict[str, Any]], str, List[str]]:
182
+ """
183
+ Extracts and parses YAML frontmatter without external pyyaml dependency.
184
+ Falls back to yaml.safe_load if pyyaml is installed.
185
+ """
186
+ errors: List[str] = []
187
+ if not content.startswith("---"):
188
+ return None, "", ["File does not start with '---' delimiter on line 1"]
189
+
190
+ match = re.match(r"^---\s*\n(.*?)\n---\s*\n(.*)$", content, re.DOTALL)
191
+ if not match:
192
+ return None, "", ["Frontmatter missing closing '---' delimiter"]
193
+
194
+ fm_text = match.group(1)
195
+ body = match.group(2)
196
+
197
+ # If PyYAML is available, use it directly
198
+ if importlib.util.find_spec("yaml") is not None:
199
+ import yaml
200
+ try:
201
+ data = yaml.safe_load(fm_text)
202
+ if isinstance(data, dict):
203
+ return data, body, []
204
+ errors.append("PyYAML failed to parse frontmatter as a dictionary")
205
+ return None, "", errors
206
+ except yaml.YAMLError as y_err:
207
+ errors.append(f"PyYAML syntax error: {y_err}")
208
+ return None, "", errors
209
+
210
+ # Pure Python stdlib parser for frontmatter
211
+ data: Dict[str, Any] = {}
212
+ current_section: Optional[str] = None
213
+
214
+ for line_no, raw_line in enumerate(fm_text.splitlines(), 1):
215
+ line = raw_line.rstrip()
216
+ if not line or line.strip().startswith("#"):
217
+ continue
218
+
219
+ indent = len(line) - len(line.lstrip())
220
+ stripped = line.strip()
221
+
222
+ if indent == 0:
223
+ if ":" not in stripped:
224
+ errors.append(f"Line {line_no}: Invalid YAML key-value syntax: '{stripped}'")
225
+ continue
226
+ key, val = stripped.split(":", 1)
227
+ key, val = key.strip(), val.strip()
228
+ if not val:
229
+ current_section = key
230
+ data[current_section] = {}
231
+ else:
232
+ current_section = None
233
+ data[key] = val.strip("\"'")
234
+ elif indent >= 2 and current_section:
235
+ if ":" not in stripped:
236
+ errors.append(f"Line {line_no}: Invalid child YAML syntax in '{current_section}': '{stripped}'")
237
+ continue
238
+ ckey, cval = stripped.split(":", 1)
239
+ ckey, cval = ckey.strip(), cval.strip().strip("\"'")
240
+ if isinstance(data.get(current_section), dict):
241
+ data[current_section][ckey] = cval
242
+
243
+ return data, body, errors
244
+
245
+
246
+ def validate_upstream_schema(skill_data: Dict[str, Any], file_content: Optional[str] = None) -> Tuple[bool, List[str]]:
247
+ """
248
+ Layer 1: Upstream Schema Conformance (Agent Skills Specification v1.0).
249
+ Validates name, description, and markdown AST heading structure.
250
+ """
251
+ errors: List[str] = []
252
+
253
+ # 1. Name check
254
+ name = skill_data.get("name")
255
+ if not name or not str(name).strip():
256
+ errors.append("Missing required field: 'name'")
257
+ else:
258
+ name_str = str(name).strip()
259
+ if len(name_str) > 64:
260
+ errors.append(f"Field 'name' length ({len(name_str)}) exceeds 64 characters")
261
+ if not SKILL_NAME_REGEX.match(name_str):
262
+ errors.append(f"Invalid 'name' format: '{name_str}' (must be lowercase alphanumeric + hyphens)")
263
+
264
+ # 2. Description check
265
+ desc = skill_data.get("description")
266
+ if not desc or not str(desc).strip():
267
+ errors.append("Missing required field: 'description'")
268
+ else:
269
+ desc_str = str(desc).strip()
270
+ if len(desc_str) > 1024:
271
+ errors.append(f"Description length ({len(desc_str)}) exceeds 1024 characters")
272
+ if "use when" not in desc_str.lower():
273
+ errors.append("Description missing mandatory activation trigger clause ('Use when...')")
274
+
275
+ # 3. Heading check if content provided
276
+ if file_content is not None:
277
+ if not re.search(r"^##?\s+", file_content, re.MULTILINE):
278
+ errors.append("Body missing standard markdown section headings ('## ...')")
279
+
280
+ return (len(errors) == 0, errors)
281
+
282
+
283
+ def find_repo_root(start_path: Path) -> Path:
284
+ """Finds repository root by searching for .git, pyproject.toml, or tools directory."""
285
+ current = start_path.resolve()
286
+ for parent in [current] + list(current.parents):
287
+ if (parent / ".git").exists() or (parent / "pyproject.toml").exists() or (parent / "tools").exists():
288
+ return parent
289
+ return current.parents[3] if len(current.parents) >= 4 else current
290
+
291
+
292
+ def validate_synapse_policy_extensions(
293
+ skill_data: Dict[str, Any],
294
+ file_content: str,
295
+ file_path: str,
296
+ check_links: bool = True,
297
+ ) -> Tuple[bool, List[str]]:
298
+ """
299
+ Layer 2: Synapse Policy Extensions.
300
+ Validates category, version, policies, examples/ directory, 5 required sections,
301
+ code block classification, GitHub Actions SHA pinning, unproven claims heuristic,
302
+ and link & backtick reference resolution.
303
+ """
304
+ errors: List[str] = []
305
+ skill_file = Path(file_path).resolve()
306
+ skill_dir = skill_file.parent
307
+ repo_root = find_repo_root(skill_dir)
308
+
309
+ # 1. Category check
310
+ category = skill_data.get("category")
311
+ if not category:
312
+ errors.append("Missing required field: 'category'")
313
+ elif category not in ALLOWED_CATEGORIES:
314
+ errors.append(f"Invalid category '{category}'. Must be one of: {sorted(ALLOWED_CATEGORIES)}")
315
+
316
+ # 2. Version check
317
+ version = skill_data.get("version")
318
+ if not version:
319
+ errors.append("Missing required field: 'version'")
320
+ elif not SEMVER_REGEX.match(str(version).strip("\"'")):
321
+ errors.append(f"Invalid version format '{version}'. Must conform to SemVer (e.g. '1.0.0')")
322
+
323
+ # 3. Policies check
324
+ policies = skill_data.get("policies")
325
+ if policies is None:
326
+ errors.append("Missing required field: 'policies'")
327
+ elif not isinstance(policies, dict):
328
+ errors.append(f"'policies' must be a dictionary object, got {type(policies).__name__}")
329
+ else:
330
+ for pol_key, allowed_vals in ALLOWED_POLICIES.items():
331
+ val = policies.get(pol_key)
332
+ if not val:
333
+ errors.append(f"Missing required policy: 'policies.{pol_key}'")
334
+ elif val not in allowed_vals:
335
+ errors.append(f"Invalid value '{val}' for 'policies.{pol_key}'. Must be one of: {sorted(allowed_vals)}")
336
+
337
+ # 4. Mandatory examples/ directory check
338
+ examples_dir = skill_dir / "examples"
339
+ if not examples_dir.is_dir():
340
+ errors.append("Missing mandatory 'examples/' directory (Progressive Disclosure L3)")
341
+ elif not list(examples_dir.iterdir()):
342
+ errors.append("'examples/' directory is empty")
343
+
344
+ for l2_name in ("references", "resources"):
345
+ l2_dir = skill_dir / l2_name
346
+ if l2_dir.is_dir() and not list(l2_dir.iterdir()):
347
+ errors.append(f"Progressive disclosure directory '{l2_name}/' exists but is empty")
348
+
349
+ # 5. Standard 5 Required Sections Check
350
+ for sec_num, pattern, sec_title in REQUIRED_SECTION_PATTERNS:
351
+ if not pattern.search(file_content):
352
+ errors.append(f"Missing required section: '## {sec_title}'")
353
+
354
+ # 6. Code Block Classification and Language Tag Audit
355
+ blocks = classify_code_blocks(file_content)
356
+ for b in blocks:
357
+ # Ignore mermaid diagrams for code language tag enforcement
358
+ if not b.language.strip():
359
+ errors.append(f"Line {b.start_line}: Code block missing language identifier tag (bare ```)")
360
+ elif b.language.lower() != "mermaid":
361
+ if b.classification not in ("runnable", "pseudocode", "illustrative"):
362
+ errors.append(
363
+ f"Line {b.start_line}: Code block not classified. Must be tagged with "
364
+ "<!-- classification: runnable -->, <!-- classification: pseudocode -->, "
365
+ "or <!-- classification: illustrative -->"
366
+ )
367
+ elif b.classification == "runnable":
368
+ missing_meta = []
369
+ if not b.has_prerequisites:
370
+ missing_meta.append("# Prerequisites:")
371
+ if not b.has_test_data:
372
+ missing_meta.append("# Test Data:")
373
+ if not b.has_expected_output:
374
+ missing_meta.append("# Expected Output:")
375
+ if missing_meta:
376
+ errors.append(
377
+ f"Line {b.start_line}: Runnable code block missing required execution metadata: "
378
+ + ", ".join(missing_meta)
379
+ )
380
+
381
+ # 7. GitHub Actions Commit SHA Pinning Check
382
+ for match in GITHUB_ACTION_REGEX.finditer(file_content):
383
+ action_name = match.group(1)
384
+ ref = match.group(2)
385
+ if not COMMIT_SHA_40_REGEX.match(ref):
386
+ errors.append(
387
+ f"Unpinned GitHub Action detected: 'actions/{action_name}@{ref}'. "
388
+ "Must be pinned to immutable 40-character commit SHA with version tag comment"
389
+ )
390
+
391
+ # 8. Unproven Quantitative Claims Check
392
+ for pat in UNPROVEN_CLAIMS_PATTERNS:
393
+ claim_match = pat.search(file_content)
394
+ if claim_match:
395
+ errors.append(
396
+ f"Unproven quantitative/superlative claim detected: '{claim_match.group(0)}'. "
397
+ "Must be replaced with contextual engineering heuristic"
398
+ )
399
+
400
+ # 9. Link and Backtick Reference Resolution
401
+ if check_links:
402
+ # Markdown links
403
+ for match in MD_LINK_REGEX.finditer(file_content):
404
+ target = match.group(2).strip()
405
+ if target.startswith(("http://", "https://", "mailto:", "#")):
406
+ continue
407
+ # Check depth-4 excessive parent traversal link
408
+ if "../../../../" in target:
409
+ errors.append(
410
+ f"Excessive root-escaping parent traversal in relative link: '{target}'. "
411
+ "Use direct or intra-skill relative references"
412
+ )
413
+ continue
414
+ clean_target = target.split("#")[0].split("?")[0].strip()
415
+ if not clean_target:
416
+ continue
417
+ resolved = (skill_dir / clean_target).resolve()
418
+ if not resolved.exists():
419
+ errors.append(f"Broken relative link: '{target}' (resolved to non-existent path: {resolved})")
420
+
421
+ # Backtick references: check paths matching repository or skill files
422
+ for match in BACKTICK_PATH_REGEX.finditer(file_content):
423
+ ref_path = match.group(1).strip()
424
+ # Skip generated output directories and target project artifacts
425
+ if any(ref_path.startswith(prefix) for prefix in ("graphify-out/", "reports/", "Reports/", "Keywords/", "build/", "dist/", "Screenshots/", ".sandbox")):
426
+ continue
427
+ # Only validate references that target files in known source/config directories
428
+ if any(ref_path.startswith(prefix) for prefix in (".github/", "templates/")):
429
+ # Check against repo root
430
+ resolved_repo_file = (repo_root / ref_path).resolve()
431
+ if not resolved_repo_file.exists():
432
+ errors.append(
433
+ f"Broken internal file reference in backticks: '`{ref_path}`' "
434
+ f"(resolved to non-existent path: {resolved_repo_file})"
435
+ )
436
+
437
+ return (len(errors) == 0, errors)
438
+
439
+
440
+ def validate_skill(
441
+ skill_md_path: Path,
442
+ check_links: bool = True,
443
+ layer: str = "all",
444
+ ) -> List[str]:
445
+ """Validates a single SKILL.md file against the specification and selected layer."""
446
+ errors: List[str] = []
447
+ try:
448
+ content = skill_md_path.read_text(encoding="utf-8")
449
+ except Exception as e:
450
+ return [f"Cannot read file: {e}"]
451
+
452
+ fm, body, parse_errors = parse_yaml_frontmatter(content)
453
+ if parse_errors:
454
+ return parse_errors
455
+ if fm is None:
456
+ return ["Failed to parse frontmatter"]
457
+
458
+ expected_name = skill_md_path.parent.name
459
+ actual_name = fm.get("name")
460
+
461
+ # Layer 1: Upstream Schema Conformance
462
+ if layer in ("upstream", "all"):
463
+ if actual_name and actual_name != expected_name:
464
+ errors.append(f"Field 'name' ('{actual_name}') does not match directory name ('{expected_name}')")
465
+ ok_up, up_errs = validate_upstream_schema(fm, file_content=body)
466
+ errors.extend(up_errs)
467
+
468
+ # Layer 2: Synapse Policy Extensions
469
+ if layer in ("policy", "all"):
470
+ ok_pol, pol_errs = validate_synapse_policy_extensions(
471
+ skill_data=fm,
472
+ file_content=content,
473
+ file_path=str(skill_md_path),
474
+ check_links=check_links,
475
+ )
476
+ errors.extend(pol_errs)
477
+
478
+ return errors
479
+
480
+
481
+ def run_validation(
482
+ skills_dir: Path,
483
+ check_links: bool = True,
484
+ layer: str = "all",
485
+ ) -> Tuple[int, Dict[str, List[str]]]:
486
+ """Scans all skills under skills_dir and validates each SKILL.md for the given layer."""
487
+ results: Dict[str, List[str]] = {}
488
+ skill_files = sorted(skills_dir.glob("*/*/SKILL.md"))
489
+ for sf in skill_files:
490
+ rel_path = sf.as_posix()
491
+ errs = validate_skill(sf, check_links=check_links, layer=layer)
492
+ if errs:
493
+ results[rel_path] = errs
494
+ return len(skill_files), results
495
+
496
+
497
+ def main() -> int:
498
+ parser = argparse.ArgumentParser(
499
+ description="Validate Agent Skills frontmatter schema and Synapse policies across layers."
500
+ )
501
+ parser.add_argument(
502
+ "--skills-dir",
503
+ type=str,
504
+ default=".agents/skills",
505
+ help="Path to the .agents/skills directory (default: .agents/skills)",
506
+ )
507
+ parser.add_argument(
508
+ "--layer",
509
+ choices=["upstream", "policy", "all"],
510
+ default="all",
511
+ help="Validation layer to execute: 'upstream' (Agent Skills v1.0 schema), 'policy' (Synapse extensions), or 'all' (default: all)",
512
+ )
513
+ parser.add_argument(
514
+ "--check-links",
515
+ action="store_true",
516
+ default=True,
517
+ help="Verify existence of relative markdown resource links and backtick paths (default: True)",
518
+ )
519
+ parser.add_argument(
520
+ "--no-check-links",
521
+ action="store_false",
522
+ dest="check_links",
523
+ help="Disable relative markdown resource link checking",
524
+ )
525
+ parser.add_argument(
526
+ "--json",
527
+ action="store_true",
528
+ default=False,
529
+ help="Output results in JSON format",
530
+ )
531
+
532
+ args = parser.parse_args()
533
+ skills_path = Path(args.skills_dir).resolve()
534
+
535
+ if not skills_path.exists():
536
+ print(f"Error: Skills directory not found at {skills_path}", file=sys.stderr)
537
+ return 1
538
+
539
+ total_scanned, failures = run_validation(
540
+ skills_path,
541
+ check_links=args.check_links,
542
+ layer=args.layer,
543
+ )
544
+
545
+ if args.json:
546
+ output_payload = {
547
+ "total_skills": total_scanned,
548
+ "layer": args.layer,
549
+ "valid_skills": total_scanned - len(failures),
550
+ "failed_skills": len(failures),
551
+ "passed": len(failures) == 0,
552
+ "failures": failures,
553
+ }
554
+ print(json.dumps(output_payload, indent=2))
555
+ return 0 if len(failures) == 0 else 1
556
+
557
+ print(f"\nšŸ” Validating {total_scanned} skills in {skills_path} [Layer: {args.layer}]...")
558
+ if args.check_links and args.layer in ("policy", "all"):
559
+ print("šŸ”— Checking relative markdown links and backtick references...")
560
+
561
+ if not failures:
562
+ print(f"āœ… 100% Verified: All {total_scanned} skills conform to layer '{args.layer}'.")
563
+ return 0
564
+
565
+ print(f"āŒ Validation failed: {len(failures)}/{total_scanned} skills have errors in layer '{args.layer}':\n")
566
+ for file_path, err_list in failures.items():
567
+ print(f" • {file_path}:")
568
+ for err in err_list:
569
+ print(f" - {err}")
570
+ print()
571
+ return 1
572
+
573
+
574
+ if __name__ == "__main__":
575
+ sys.exit(main())