@teevee98/synapse-hub 4.1.3 → 4.2.0

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 (206) 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 +6 -1
  3. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +6 -1
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +8 -3
  5. package/.agents/skills/01-web-automation/clean-pom-crafter/examples/standard_test_case.groovy +3 -0
  6. package/.agents/skills/01-web-automation/clean-pom-crafter/references/pom_patterns.groovy +3 -0
  7. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +6 -1
  8. package/.agents/skills/01-web-automation/e2e-testing-patterns/examples/playwright_sharded_config.ts +3 -0
  9. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +6 -1
  10. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +6 -1
  11. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +6 -1
  12. package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
  13. package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
  14. package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
  15. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +7 -2
  16. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +6 -1
  17. package/.agents/skills/01-web-automation/playwright-webapp-testing/examples/server_lifecycle_playwright.py +3 -0
  18. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +6 -1
  19. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +6 -1
  20. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +6 -1
  21. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +6 -1
  22. package/.agents/skills/02-test-design/review-spec/SKILL.md +4 -1
  23. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +6 -1
  24. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +6 -1
  25. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +6 -1
  26. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +7 -2
  27. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +7 -2
  28. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +4 -1
  29. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +6 -1
  30. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +3 -0
  31. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +6 -1
  32. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/references/dast_recipes.ts +3 -0
  33. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +6 -1
  34. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +6 -1
  35. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +6 -1
  36. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +6 -1
  37. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +7 -2
  38. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +6 -1
  39. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +6 -1
  40. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +6 -1
  41. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +6 -1
  42. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +6 -1
  43. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +6 -1
  44. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +6 -1
  45. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +6 -1
  46. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +6 -1
  47. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +6 -1
  48. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +3 -0
  49. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +3 -0
  50. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +6 -1
  51. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +6 -1
  52. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +4 -1
  53. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +4 -1
  54. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +6 -1
  55. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +4 -1
  56. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +6 -1
  57. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +6 -1
  58. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +6 -1
  59. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +6 -1
  60. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +6 -1
  61. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +6 -1
  62. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +6 -1
  63. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +6 -1
  64. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +6 -1
  65. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/examples/surgical_code_window_walkthrough.md +1 -1
  66. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +6 -1
  67. package/AGENTS.md +7 -1
  68. package/LICENSE +5 -5
  69. package/NOTICE +1 -1
  70. package/README.en.md +4 -4
  71. package/README.md +4 -4
  72. package/agentskills.json +1 -1
  73. package/docs/ARCHITECTURE.en.md +2 -2
  74. package/docs/ARCHITECTURE.md +11 -2
  75. package/docs/CLI_REFERENCE.en.md +6 -4
  76. package/docs/CLI_REFERENCE.md +1 -1
  77. package/docs/CONTRIBUTING.en.md +1 -1
  78. package/docs/CONTRIBUTING.md +2 -2
  79. package/docs/PERFORMANCE_AUDIT_REPORT.md +2 -2
  80. package/docs/TOOL_CATALOG.md +6 -2
  81. package/docs/research/agent_skill_training_analysis.md +1 -1
  82. package/package.json +1 -1
  83. package/plugin.json +1 -1
  84. package/scripts/generate_skill_examples.py +3 -0
  85. package/scripts/package_dist.py +3 -0
  86. package/skills_manifest.json +320 -55
  87. package/synapse.config.json +1 -1
  88. package/templates/ui/index.html +2 -2
  89. package/tools/.infer_baseline.json +3 -796
  90. package/tools/TOOL_CATALOG.json +63 -3
  91. package/tools/__init__.py +4 -1
  92. package/tools/agent_canary.py +3 -0
  93. package/tools/analyze_project.py +3 -0
  94. package/tools/api_drift_sentinel.py +3 -0
  95. package/tools/api_fuzzer.py +182 -118
  96. package/tools/ast_cache.py +4 -2
  97. package/tools/author_integrity.py +174 -12
  98. package/tools/auto_heal.py +7 -2
  99. package/tools/autogen_qa_broker.py +14 -15
  100. package/tools/benchmark_swarm_context.py +119 -18
  101. package/tools/break_ui_generator.py +233 -0
  102. package/tools/browser_helpers.js +2 -2
  103. package/tools/bug_reporter.py +3 -0
  104. package/tools/build_consolidated_report.py +3 -0
  105. package/tools/bump_version.py +4 -1
  106. package/tools/cache_resolver.py +7 -3
  107. package/tools/check_env.py +3 -0
  108. package/tools/check_version_sync.py +21 -50
  109. package/tools/ci_healing_hook.py +3 -0
  110. package/tools/cli.py +116 -22
  111. package/tools/config_decoupler.py +3 -0
  112. package/tools/core/__init__.py +3 -0
  113. package/tools/core/bm25_retriever.py +218 -0
  114. package/tools/core/file_lock.py +23 -14
  115. package/tools/core/i18n.py +13 -11
  116. package/tools/core/memory_bus.py +6 -3
  117. package/tools/core/process_supervisor.py +28 -18
  118. package/tools/core/provider_usage_adapter.py +317 -0
  119. package/tools/core/token_estimator.py +83 -18
  120. package/tools/count_tokens.py +16 -7
  121. package/tools/coverage_reporter.py +245 -0
  122. package/tools/create_mock_docx.py +3 -0
  123. package/tools/dashboard_generator.py +17 -15
  124. package/tools/db_sandbox.py +150 -5
  125. package/tools/debt_harvester.py +2 -2
  126. package/tools/diagram_architect.py +3 -0
  127. package/tools/distill_log.py +22 -2
  128. package/tools/distill_skill.py +191 -0
  129. package/tools/e2e_flow_prober.py +3 -0
  130. package/tools/export_postman_collection.py +3 -0
  131. package/tools/flaky_detector.py +3 -0
  132. package/tools/fsm_enforcer.py +2 -2
  133. package/tools/fuzz_payloads.py +3 -0
  134. package/tools/generate_allure_report.py +3 -0
  135. package/tools/generate_api_matrix.py +3 -0
  136. package/tools/generate_jmx_plan.py +3 -0
  137. package/tools/generate_tc_from_story.py +3 -0
  138. package/tools/generate_test_reports.py +3 -0
  139. package/tools/git_pre_commit_guard.py +25 -3
  140. package/tools/git_worktree_manager.py +3 -0
  141. package/tools/heal/__init__.py +3 -0
  142. package/tools/heal_pr_automator.py +3 -0
  143. package/tools/heuristic_locator_matcher.py +3 -0
  144. package/tools/hub_publisher.py +3 -3
  145. package/tools/humanize_linter.py +3 -0
  146. package/tools/infer_linter.py +19 -9
  147. package/tools/init_config.py +6 -9
  148. package/tools/jtl_analyzer.py +3 -0
  149. package/tools/lint/__init__.py +3 -0
  150. package/tools/lint_ai_docs.py +3 -0
  151. package/tools/lookup_tc.py +3 -0
  152. package/tools/lookup_xpath.py +3 -0
  153. package/tools/matrix_sharder.py +3 -0
  154. package/tools/mcp/__init__.py +3 -0
  155. package/tools/mcp_docx_server.py +1 -1
  156. package/tools/mcp_excel_server.py +4 -1
  157. package/tools/mcp_server.py +78 -15
  158. package/tools/md_to_xlsx.py +3 -0
  159. package/tools/mechanical_ui_gate.py +3 -0
  160. package/tools/micro_mutator.py +93 -19
  161. package/tools/network_mock_shield.py +3 -0
  162. package/tools/newman_analyzer.py +3 -0
  163. package/tools/omni_emitter.py +3 -0
  164. package/tools/omni_parser.py +3 -0
  165. package/tools/omni_transpiler.py +3 -0
  166. package/tools/output_formatter.py +3 -0
  167. package/tools/package_release.py +6 -6
  168. package/tools/pairwise_generator.py +3 -0
  169. package/tools/pentest_scope_guard.py +401 -58
  170. package/tools/perf/__init__.py +3 -0
  171. package/tools/perf/benchmark_perf_runner.py +42 -0
  172. package/tools/pinpoint_failure.py +3 -0
  173. package/tools/project_state.py +3 -0
  174. package/tools/repo_map.py +3 -0
  175. package/tools/report/__init__.py +3 -0
  176. package/tools/rules_router.py +426 -34
  177. package/tools/runaway_stopper.py +3 -0
  178. package/tools/safety_firewall.py +3 -0
  179. package/tools/security_scanner.py +80 -0
  180. package/tools/senior_code_review.py +14 -0
  181. package/tools/setup_project.py +9 -4
  182. package/tools/skill_canonical_digest.py +244 -0
  183. package/tools/skill_collision_guard.py +2 -2
  184. package/tools/skill_profiles.py +77 -7
  185. package/tools/skillspector.py +2 -1
  186. package/tools/slide_deck_exporter.py +477 -0
  187. package/tools/smart_visual_masker.py +3 -0
  188. package/tools/sync_skills_manifest.py +166 -0
  189. package/tools/task_memory_manager.py +260 -0
  190. package/tools/telemetry_correlator.py +3 -0
  191. package/tools/template_excel_exporter.py +2 -2
  192. package/tools/test_impact.py +3 -0
  193. package/tools/trace_data_flow.py +3 -0
  194. package/tools/traffic_session_converter.py +3 -0
  195. package/tools/ui_server.py +2 -2
  196. package/tools/universal_ir.py +3 -0
  197. package/tools/update_sentinel.py +15 -9
  198. package/tools/validate_groovy_scripts.py +3 -0
  199. package/tools/validate_host_interop.py +485 -0
  200. package/tools/validate_skills_schema.py +282 -0
  201. package/tools/verify_all.py +600 -63
  202. package/tools/visual_diff_canvas.py +3 -0
  203. package/tools/visual_som_helper.py +3 -0
  204. package/tools/watch_mode.py +4 -4
  205. package/tools/wcag_audit.py +3 -0
  206. package/tools/welcome_page.py +2 -2
@@ -0,0 +1,282 @@
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 the Agent Skills Frontmatter & Policies Specification.
9
+ """
10
+
11
+ import sys
12
+ import re
13
+ import json
14
+ import argparse
15
+ import importlib.util
16
+ from pathlib import Path
17
+ from typing import Dict, Any, List, Tuple, Optional
18
+
19
+ # Enforce UTF-8 stdout encoding for Windows console compatibility
20
+ if hasattr(sys.stdout, "reconfigure"):
21
+ sys.stdout.reconfigure(encoding="utf-8", errors="replace")
22
+ if hasattr(sys.stderr, "reconfigure"):
23
+ sys.stderr.reconfigure(encoding="utf-8", errors="replace")
24
+
25
+ ALLOWED_CATEGORIES = {
26
+ "test_automation_and_execution",
27
+ "architecture_and_analysis",
28
+ "verification_and_resilience",
29
+ "context_and_optimization",
30
+ }
31
+
32
+ ALLOWED_POLICIES = {
33
+ "network": {"none", "localhost-only", "sandbox-only"},
34
+ "shell": {"none", "read-only", "workspace-sandbox"},
35
+ "filesystem": {"read-only", "workspace-sandbox"},
36
+ }
37
+
38
+ SEMVER_REGEX = re.compile(r"^\d+\.\d+\.\d+$")
39
+ SKILL_NAME_REGEX = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
40
+ MD_LINK_REGEX = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
41
+
42
+
43
+ def parse_yaml_frontmatter(content: str) -> Tuple[Optional[Dict[str, Any]], str, List[str]]:
44
+ """
45
+ Extracts and parses YAML frontmatter without external pyyaml dependency.
46
+ Falls back to yaml.safe_load if pyyaml is installed.
47
+ """
48
+ errors: List[str] = []
49
+ if not content.startswith("---"):
50
+ return None, "", ["File does not start with '---' delimiter on line 1"]
51
+
52
+ match = re.match(r"^---\s*\n(.*?)\n---\s*\n(.*)$", content, re.DOTALL)
53
+ if not match:
54
+ return None, "", ["Frontmatter missing closing '---' delimiter"]
55
+
56
+ fm_text = match.group(1)
57
+ body = match.group(2)
58
+
59
+ # If PyYAML is available, use it directly
60
+ if importlib.util.find_spec("yaml") is not None:
61
+ import yaml
62
+ try:
63
+ data = yaml.safe_load(fm_text)
64
+ if isinstance(data, dict):
65
+ return data, body, []
66
+ errors.append("PyYAML failed to parse frontmatter as a dictionary")
67
+ return None, "", errors
68
+ except yaml.YAMLError as y_err:
69
+ errors.append(f"PyYAML syntax error: {y_err}")
70
+ return None, "", errors
71
+
72
+ # Pure Python stdlib parser for frontmatter
73
+ data: Dict[str, Any] = {}
74
+ current_section: Optional[str] = None
75
+
76
+ for line_no, raw_line in enumerate(fm_text.splitlines(), 1):
77
+ line = raw_line.rstrip()
78
+ if not line or line.strip().startswith("#"):
79
+ continue
80
+
81
+ indent = len(line) - len(line.lstrip())
82
+ stripped = line.strip()
83
+
84
+ if indent == 0:
85
+ if ":" not in stripped:
86
+ errors.append(f"Line {line_no}: Invalid YAML key-value syntax: '{stripped}'")
87
+ continue
88
+ key, val = stripped.split(":", 1)
89
+ key, val = key.strip(), val.strip()
90
+ if not val:
91
+ current_section = key
92
+ data[current_section] = {}
93
+ else:
94
+ current_section = None
95
+ data[key] = val.strip("\"'")
96
+ elif indent >= 2 and current_section:
97
+ if ":" not in stripped:
98
+ errors.append(f"Line {line_no}: Invalid child YAML syntax in '{current_section}': '{stripped}'")
99
+ continue
100
+ ckey, cval = stripped.split(":", 1)
101
+ ckey, cval = ckey.strip(), cval.strip().strip("\"'")
102
+ if isinstance(data.get(current_section), dict):
103
+ data[current_section][ckey] = cval
104
+
105
+ return data, body, errors
106
+
107
+
108
+ def validate_skill(skill_md_path: Path, check_links: bool = True) -> List[str]:
109
+ """Validates a single SKILL.md file against the specification."""
110
+ errors: List[str] = []
111
+ try:
112
+ content = skill_md_path.read_text(encoding="utf-8")
113
+ except Exception as e:
114
+ return [f"Cannot read file: {e}"]
115
+
116
+ fm, body, parse_errors = parse_yaml_frontmatter(content)
117
+ if parse_errors:
118
+ return parse_errors
119
+ if fm is None:
120
+ return ["Failed to parse frontmatter"]
121
+
122
+ expected_name = skill_md_path.parent.name
123
+ actual_name = fm.get("name")
124
+
125
+ # 1. Name check
126
+ if not actual_name:
127
+ errors.append("Missing required field: 'name'")
128
+ elif actual_name != expected_name:
129
+ errors.append(f"Field 'name' ('{actual_name}') does not match directory name ('{expected_name}')")
130
+ elif len(actual_name) > 64 or not SKILL_NAME_REGEX.match(actual_name):
131
+ errors.append(f"Invalid 'name' format: '{actual_name}' (must be lowercase alphanumeric + hyphens, <= 64 chars)")
132
+
133
+ # 2. Description check
134
+ desc = fm.get("description")
135
+ if not desc or not str(desc).strip():
136
+ errors.append("Missing required field: 'description'")
137
+ else:
138
+ desc_str = str(desc).strip()
139
+ if len(desc_str) > 1024:
140
+ errors.append(f"Description length ({len(desc_str)}) exceeds 1024 characters")
141
+ if "use when" not in desc_str.lower():
142
+ errors.append("Description missing mandatory activation trigger clause ('Use when...')")
143
+
144
+ # 3. Category check
145
+ category = fm.get("category")
146
+ if not category:
147
+ errors.append("Missing required field: 'category'")
148
+ elif category not in ALLOWED_CATEGORIES:
149
+ errors.append(f"Invalid category '{category}'. Must be one of: {sorted(ALLOWED_CATEGORIES)}")
150
+
151
+ # 4. Version check
152
+ version = fm.get("version")
153
+ if not version:
154
+ errors.append("Missing required field: 'version'")
155
+ elif not SEMVER_REGEX.match(str(version).strip("\"'")):
156
+ errors.append(f"Invalid version format '{version}'. Must conform to SemVer (e.g. '1.0.0')")
157
+
158
+ # 5. Policies check
159
+ policies = fm.get("policies")
160
+ if policies is None:
161
+ errors.append("Missing required field: 'policies'")
162
+ elif not isinstance(policies, dict):
163
+ errors.append(f"'policies' must be a dictionary object, got {type(policies).__name__}")
164
+ else:
165
+ for pol_key, allowed_vals in ALLOWED_POLICIES.items():
166
+ val = policies.get(pol_key)
167
+ if not val:
168
+ errors.append(f"Missing required policy: 'policies.{pol_key}'")
169
+ elif val not in allowed_vals:
170
+ errors.append(f"Invalid value '{val}' for 'policies.{pol_key}'. Must be one of: {sorted(allowed_vals)}")
171
+
172
+ # 6. Relative links check
173
+ if check_links:
174
+ for match in MD_LINK_REGEX.finditer(body):
175
+ target = match.group(2).strip()
176
+ if target.startswith(("http://", "https://", "mailto:", "#")):
177
+ continue
178
+ clean_target = target.split("#")[0].split("?")[0].strip()
179
+ if not clean_target:
180
+ continue
181
+ resolved = (skill_md_path.parent / clean_target).resolve()
182
+ if not resolved.exists():
183
+ errors.append(f"Broken relative link: '{target}' (resolved to non-existent path: {resolved})")
184
+
185
+ # 7. Progressive disclosure directories check
186
+ examples_dir = skill_md_path.parent / "examples"
187
+ if not examples_dir.is_dir():
188
+ errors.append("Missing mandatory 'examples/' directory (Progressive Disclosure L3)")
189
+ elif not list(examples_dir.iterdir()):
190
+ errors.append("'examples/' directory is empty")
191
+
192
+ # If L2 references/ or resources/ exist, ensure they contain valid files
193
+ for l2_dir_name in ("references", "resources"):
194
+ l2_dir = skill_md_path.parent / l2_dir_name
195
+ if l2_dir.is_dir() and not list(l2_dir.iterdir()):
196
+ errors.append(f"Progressive disclosure directory '{l2_dir_name}/' exists but is empty")
197
+
198
+ # 8. Progressive disclosure structure check in SKILL.md body
199
+ if not re.search(r"^##?\s+", body, re.MULTILINE):
200
+ errors.append("SKILL.md body missing standard markdown section headings ('## ...') for progressive disclosure")
201
+
202
+ return errors
203
+
204
+
205
+ def run_validation(skills_dir: Path, check_links: bool = True) -> Tuple[int, Dict[str, List[str]]]:
206
+ """Scans all skills under skills_dir and validates each SKILL.md."""
207
+ results: Dict[str, List[str]] = {}
208
+ skill_files = sorted(skills_dir.glob("*/*/SKILL.md"))
209
+ for sf in skill_files:
210
+ rel_path = sf.as_posix()
211
+ errs = validate_skill(sf, check_links=check_links)
212
+ if errs:
213
+ results[rel_path] = errs
214
+ return len(skill_files), results
215
+
216
+
217
+ def main() -> int:
218
+ parser = argparse.ArgumentParser(description="Validate Agent Skills frontmatter schema and policies.")
219
+ parser.add_argument(
220
+ "--skills-dir",
221
+ type=str,
222
+ default=".agents/skills",
223
+ help="Path to the .agents/skills directory (default: .agents/skills)",
224
+ )
225
+ parser.add_argument(
226
+ "--check-links",
227
+ action="store_true",
228
+ default=True,
229
+ help="Verify existence of relative markdown resource links (default: True)",
230
+ )
231
+ parser.add_argument(
232
+ "--no-check-links",
233
+ action="store_false",
234
+ dest="check_links",
235
+ help="Disable relative markdown resource link checking",
236
+ )
237
+ parser.add_argument(
238
+ "--json",
239
+ action="store_true",
240
+ default=False,
241
+ help="Output results in JSON format",
242
+ )
243
+
244
+ args = parser.parse_args()
245
+ skills_path = Path(args.skills_dir).resolve()
246
+
247
+ if not skills_path.exists():
248
+ print(f"Error: Skills directory not found at {skills_path}", file=sys.stderr)
249
+ return 1
250
+
251
+ total_scanned, failures = run_validation(skills_path, check_links=args.check_links)
252
+
253
+ if args.json:
254
+ output_payload = {
255
+ "total_skills": total_scanned,
256
+ "valid_skills": total_scanned - len(failures),
257
+ "failed_skills": len(failures),
258
+ "passed": len(failures) == 0,
259
+ "failures": failures,
260
+ }
261
+ print(json.dumps(output_payload, indent=2))
262
+ return 0 if len(failures) == 0 else 1
263
+
264
+ print(f"\nšŸ” Validating {total_scanned} skills in {skills_path}...")
265
+ if args.check_links:
266
+ print("šŸ”— Checking relative markdown links...")
267
+
268
+ if not failures:
269
+ print(f"āœ… 100% Verified: All {total_scanned} skills conform to Frontmatter Schema & Policies.")
270
+ return 0
271
+
272
+ print(f"āŒ Validation failed: {len(failures)}/{total_scanned} skills have schema or link errors:\n")
273
+ for file_path, err_list in failures.items():
274
+ print(f" • {file_path}:")
275
+ for err in err_list:
276
+ print(f" - {err}")
277
+ print()
278
+ return 1
279
+
280
+
281
+ if __name__ == "__main__":
282
+ sys.exit(main())