skills.rest
github
githubOFFICIAL
Explore all skills by this author →
WebsiteGitHub

ssl-skill-normalizer

Convert SKILL.md artifacts into validated Scheduling-Structural-Logical JSON representations.

5.1k|530|Updated Aug 12, 2025
Search Tags:#metadata extraction#schema validation#Agent Skills#markdown parsing#graph validation#skill normalization#ssl json
One-click install
npx skills add https://github.com/github/gh-aw --skill ssl-skill-normalizer
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: ssl-skill-normalizer
Source: https://github.com/github/gh-aw/tree/main/.github/skills/ssl
Command: npx skills add https://github.com/github/gh-aw --skill ssl-skill-normalizer

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Free-form SKILL.md files are human-readable but hard for agents to search, reason over, and audit. This Skill normalizes them into a structured Scheduling-Structural-Logical (SSL) JSON representation with typed layers, restricted enums, and graph validation.

Core Features & Use Cases

  • Four-pass extraction pipeline: Extracts scheduling metadata, decomposes execution flow into scenes, expands scenes into atomic logic steps, then validates the result.
  • Restricted vocabularies: Enforces fixed enums for scene types, action types, and resource scopes so outputs stay consistent and machine-comparable.
  • Validation with bounded retries: Checks JSON syntax, enum membership, unique identifiers, pointer integrity, and graph reachability, retrying failed generations up to a bounded budget.
  • Use Case: Given a repository of agent skill definitions, run the normalizer on each SKILL.md to produce searchable ssl.json files plus a per-artifact validation report for auditing.

Quick Start

Normalize the SKILL.md at .github/skills/ssl/SKILL.md into an SSL JSON representation and show me the validation report.

Frequently Asked Questions about ssl-skill-normalizer

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I convert a SKILL.md file into structured JSON?▼

Invoke the normalizer with skill_path pointing to the target SKILL.md. It runs four passes to extract scheduling metadata, decompose scenes, expand logic steps, and validate the result, then writes ssl.json alongside the source file.

What is the SSL representation for agent skills?▼

SSL is a Scheduling-Structural-Logical representation with three layers: scheduling captures when and by whom a skill runs, structural defines macro execution scenes, and logical lists atomic operations. It makes skills searchable and risk-assessable.

What validation rules does the SSL normalizer enforce?▼

Pass 4 checks JSON syntax, required fields, enum membership, unique scene and step identifiers, entry pointer validity, transition targets, and graph integrity with no unreachable scenes. Failures are recorded per rule and retried within a bounded budget.

Can I batch normalize multiple SKILL.md files?▼

Yes, invoke the skill once per artifact and aggregate the per-artifact validation reports. Each run produces an ssl.json next to its source file plus diagnostics covering accepted, rejected, and retried records.

What happens when SSL validation fails after retries?▼

Records that remain invalid after the retry budget are rejected rather than silently repaired. The report logs each failure with the specific Pass-4 rule violated, and no malformed JSON is emitted.

Related Skills

Explore More Software Engineering Skills→
skill-toolsskill-tools

skill-quality

Provides guidance for writing well-structured, effective skill definitions.

Official
Intermediate
cabeznocabezno

bmb-skills-hub

Generate index, embedding, skill-tree, and MCP manifest files from a skills directory.

Community
Intermediate
mattjeffersonmattjefferson

dev-review

Detect changed files, run parallel reviewers, and synthesize prioritized findings.

Community
Advanced
zenbase-aizenbase-ai
10

skill-retrieval

Index and retrieve skills via ColBERT semantic search.

Official
Advanced