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

Value	Meaning
PREPARE	Setup: load inputs, configure environment
ACQUIRE	Receive or fetch required data
REASON	Analyze, infer, or plan
ACT	Produce or transform primary output
VERIFY	Validate outputs or preconditions
RECOVER	Handle failure; retry or compensate
FINALIZE	Write results, emit notifications, clean up

Action Types

Value	Meaning
READ	Consume data from a resource without side effects
SELECT	Choose among alternatives
COMPARE	Diff or rank two or more values
VALIDATE	Assert a constraint or schema
INFER	Derive new information via reasoning
WRITE	Produce or overwrite data in a resource
UPDATE_STATE	Mutate shared state
CALL_TOOL	Invoke an external tool or subprocess
REQUEST	Send a request to an external service
TRANSFER	Move data between resources
NOTIFY	Emit a message or event
TERMINATE	End execution and return control

Resource Scopes

Value	Meaning
MEMORY	In-process working memory
LOCAL_FS	Local file system
CODEBASE	Source code under version control
PROCESS	OS process or shell
USER_DATA	User-provided or personal data
CREDENTIALS	Secrets, tokens, or credentials
NETWORK	Remote network resource
OTHER	Any resource not covered above

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:

Rule	Check
JSON syntax	Well-formed JSON
Required fields	All top-level fields present
Enum membership	All enum fields use allowed values only
Unique identifiers	All scene IDs and step IDs are globally unique
Entry pointer	entry_scene references an existing scene ID
Scene entry pointer	entry_logic_step references an existing step ID
Scene containment	All referenced scene IDs exist
Logic-step containment	All referenced step IDs exist
Transition validity	All transition targets are valid scene/step IDs or terminal values
Graph integrity	No unreachable scenes or dangling references

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.