Ssl Skill Normalizer

SSL Skill Normalizer

Purpose

This skill converts markdown-based skill artifacts into a structured Scheduling-Structural-Logical (SSL) representation as introduced in:

Liang et al., "From Skill Text to Skill Structure: The Scheduling-Structural-Logical Representation for Agent Skills", arXiv:2604.24026 (2026).

SSL addresses the core limitation of free-form skill text: it is human-readable but hard for agents to reason over, discover, and audit. By mapping each skill into three complementary layers, SSL makes skills searchable (improved MRR 0.573 → 0.707 in the paper) and risk-assessable (improved macro F1 0.744 → 0.787).

The Three SSL Layers

The representation is grounded in Schank & Abelson's theories of Memory Organization Packets (MOPs), Script Theory, and Conceptual Dependency. Each layer captures a different dimension of skill knowledge:

Layer 1 — Scheduling (When / Who)

Answers: When should this skill be invoked? By whom, given which inputs and outputs?

Fields extracted:

• id — stable lowercase identifier
• name — human-readable skill name
• goal — one-sentence purpose
• intent_signature — typed function signature (fn($input) -> $output)
• inputs — $-prefixed named input bindings
• outputs — $-prefixed named output bindings
• dependencies — explicit runtime tool or library requirements
• control_flow_features — e.g. sequential, conditional, loop
• entry_scene — ID of the first scene to execute
• subscene_refs — IDs of any nested/delegated scenes

Layer 2 — Structural (How / Order)

Answers: What are the macro-level execution stages and how do they connect?

Each scene is a named execution stage with:

• id — unique within the skill
• type — one of the restricted scene-type enum (see below)
• goal — what the scene accomplishes
• entry_condition — precondition for entering the scene
• exit_condition — postcondition that must hold on exit
• next_scene_rules — conditional transitions to the next scene ID, END_SUCCESS, or END_FAIL
• inputs / outputs — $-prefixed bindings consumed and produced
• entry_logic_step — ID of the first logic step in this scene

Layer 3 — Logical (What / Actions)

Answers: What atomic operations are performed, on which resources?

Each logic step is an indivisible operation with:

• id — unique within the skill
• scene_id — owning scene
• action_type — one of the restricted action-type enum (see below)
• resource_scope — one of the restricted resource-scope enum (see below)
• description — one sentence describing the operation
• inputs / outputs — named $-variable bindings
• next — ID of the following step, YIELD_SUCCESS, or YIELD_FAIL

Restricted Enumerations

Scene Types

Action Types

Resource Scopes

Terminal Targets

• Scene transitions: END_SUCCESS | END_FAIL
• Logic-step transitions: YIELD_SUCCESS | YIELD_FAIL

Behavioral Requirements

General Rules

• Only extract information directly supported by the source artifact.
• Do not invent hidden behavior, tools, dependencies, or side effects.
• Use restricted enum vocabularies only; never free-form strings in typed fields.
• Reject malformed outputs instead of silently repairing them.
• Prefer null, empty arrays, or coarse-grained classifications when evidence is weak.

Execution Pipeline

Pass 1: Scheduling Extraction

Read the source SKILL.md, then extract the scheduling layer.

Produce scheduling with all fields in Layer 1. When evidence is absent for an optional field, emit an empty array or null.

Requirements

• Use only explicit evidence from the source document.
• Preserve semantic intent without paraphrasing behavior into unsupported claims.
• Normalize all identifiers to snake_case.

Pass 2: Scene Decomposition

Analyse the skill's execution flow and decompose it into macro-level scenes.

Requirements

• Prefer 2–5 scenes when supported by the source. Only add more if the source describes clearly distinct phases.
• Assign only allowed scene types from the enum table.
• For each scene define: goal, entry_condition, exit_condition, next_scene_rules, inputs, outputs, entry_logic_step.

Constraints

• Every next_scene_rules target must resolve to another scene ID, END_SUCCESS, or END_FAIL.
• Include a RECOVER scene when the source describes retry or error-recovery behaviour.

Pass 3: Logic-Step Expansion

Expand each scene into its sequence of atomic logic steps.

Split a step whenever any of the following changes:

• action type
• resource boundary
• execution effect
• control-flow behaviour

Requirements

• Assign only allowed action types and resource scopes.
• Use $-prefixed variable bindings for all named data ($user_request, $selected_file, $generated_output).
• Do not use unnamed or free-form intermediate variables.

Pass 4: Validation

Validate the draft SSL JSON against all of the following rules:

Failure Handling

• Retry malformed generations within a bounded retry budget (recommend ≤ 3 retries).
• Record each validation failure with the specific rule that was violated.
• Reject records that remain invalid after retries; do not silently emit invalid JSON.

Reporting

Generate a normalization report containing:

• processed artifact count
• valid SSL count
• rejected SSL count
• parse failures
• schema failures
• graph failures
• enum failures
• retry counts

Include per-artifact diagnostics with the specific Pass-4 rule that caused rejection.

Do not expose secrets or credentials in reports.

Success Criteria

The skill succeeds when:

• a valid SSL JSON artifact is produced
• all references resolve correctly
• all enum values are valid
• the output passes all Pass-4 validation rules
• the output remains grounded in the source artifact with no invented behaviour

The skill fails when:

• required graph structures are missing
• transitions are invalid
• unsupported inference is required to fill required fields
• validation errors remain unresolved after retries

Output Expectations

Primary Output

A schema-valid SSL JSON file named ssl.json placed alongside the source SKILL.md. Top-level keys: scheduling, scenes, logic_steps.

Secondary Output

A validation and normalization report summarizing accepted artifacts, rejected artifacts, per-artifact validation diagnostics, and retry behaviour.

Safety Constraints

• Never invent credentials or external systems.
• Never infer unstated side effects.
• Never fabricate execution logic not present in the source.
• Never silently repair invalid graph structures.
• Never emit malformed JSON intentionally.
• Keep normalization deterministic where possible.

Reuse Instructions

To apply this skill to a SKILL.md artifact:

1. Invoke this skill with skill_path pointing to the target SKILL.md.
2. The normalizer runs all four passes in sequence.
3. If Pass 4 fails, the RECOVER pass retries generation up to the retry budget.
4. The resulting ssl.json is written alongside the source file.
5. Review the validation_report output to confirm acceptance.

For batch normalization, invoke this skill once per artifact and aggregate the per-artifact reports.