Splitting SKILL.md into three layers lifts retrieval 12%, risk detection 24%

Notes on From Skill Text to Skill Structure: The Scheduling-Structural-Logical Representation for Agent Skills (arXiv:2604.24026) — Qiliang Liang, Hansi Wang, Zhongzhi Liang, Yang Liu · April 2026

Note published July 25, 2026 · written by SkillFed’s research pipeline from the paper above · how these notes are made

AI-assisted notes · reviewed by SkillFed Skill retrieval Bridge: retrieval × security

LLM agent skills today live almost entirely as prose — SKILL.md-style files that bundle a skill's invocation rules, execution phases, and side effects into a single block of natural-language text. The Scheduling-Structural-Logical (SSL) representation pulls that block apart into three typed layers: a scheduling record for when and how a skill gets invoked, a structural graph of execution scenes (prepare, acquire, act, verify, and so on), and a logical graph of atomic actions with explicit resource boundaries. The three-way split borrows directly from Schank and Abelson's cognitive-linguistics work — Memory Organization Packets, Script Theory, Conceptual Dependency. An LLM normalizer (DeepSeek-V3.2) converts raw SKILL.md text into SSL's JSON schema; a 100-skill human audit found 83% of the normalized fields faithfully grounded in the source document.

Structure pays off on two concrete tasks, tested across a 6,184-skill corpus. On skill discovery, pairing a short description with rich SSL fields (skill identifier, scene types, dependencies, expected inputs/outputs) lifts retrieval MRR@50 from 0.649 — the best any text-only baseline reaches across 431 intent-level queries — to 0.729. That beats even embedding the complete SKILL.md verbatim (0.645), which means the gain comes from disentangling signal, not from adding more words. On risk assessment, across 252 skills labeled on six threat dimensions, giving an LLM judge both the full SKILL.md and its SSL representation raises macro F1 from 0.409 to 0.509 over source text alone. SSL by itself barely edges past the text-only baseline — it works as an evidence layer laid over the source document, not a replacement for it.

Key numbers

Skill Discovery MRR@50 (best SSL view vs. best text-only)	0.729 vs 0.649
Risk Assessment macro F1 (SKILL.md+SSL vs. SKILL.md alone)	0.509 vs 0.409
Covert-execution F1, best combined view	0.264
Normalizer fidelity (100-skill human audit)	83%
Benchmark scale	6,184 skills / 431 queries / 252 risk-labeled

What this means for skill authors

The retrieval result is the one worth sitting with if you write skills for other agents to install: a bloated, prose-heavy SKILL.md doesn't help at discovery time — the complete-document baseline actually retrieves worse than a short description paired with typed interface fields. If normalization like this becomes routine in skill registries, the practical lesson for authors is to front-load a skill's goal, inputs, outputs, and dependencies in a form a normalizer can extract cleanly, rather than trusting a wall of instructions to speak for itself.

The risk numbers are the more sobering half. Even the best-performing setup — full source text plus SSL — tops out at a macro F1 of 0.509, and the hardest category, covert execution, reaches only 0.264 F1 in that same configuration. That's worse than a coin flip on catching the risk type most associated with disguised or obfuscated behavior. It's also a static-analysis ceiling the authors are upfront about: SSL is extracted from the artifact as written, so it has nothing to say about payloads assembled at runtime or branches that only reveal their shape during execution. The practical argument is against letting any single structured-risk pass be the whole gate — pair multiple, differently-angled scans before a skill gets called safe, which is qualitatively the posture SkillFed's dual-tool scanning already takes toward vetting.

The framing that outlasts either benchmark number is the claim that skill registries need a shared, source-grounded manifest layer between raw documentation and every tool that has to reason about a skill — routers, reviewers, policy checkers — so each one stops re-deriving the same facts from the same prose. That's an infrastructure bet, not a finished standard, and the paper is explicit that SSL is meant to sit alongside the source skill, not replace the need to read it.

Skills related to this research

wiki-retrieve wiki-retrieve upgrades vault search from page-level to chunk-level granularity, combining contextual prefixes, BM25 sparse retrieval, and dense reranking to reduce retrieval failures. Setup is opt-in with built-in privacy gates: run fully on-machine with synthetic prefixes, or opt into Anthropic API or claude CLI tiers for better context generation.★ 10,007 axiom-resolve-spm This skill helps you troubleshoot Swift Package Manager problems by analyzing Package.swift and Package.resolved files to pinpoint version conflicts, duplicate symbol linker errors, transitive dependency issues, and platform compatibility gaps. It guides you through detection strategies and resolution patterns for common scenarios like version range conflicts, Swift language mode mismatches, and macro target build failures.★ 1,095 Tanstack Router Master TanStack Router with structured guidelines covering type safety, route organization, data loading, and search parameter handling. This skill provides critical and high-priority rules to optimize your React routing architecture and prevent runtime errors.★ 201 09 Product 360 Product 360 harnesses Seedance 2.0 on Higgsfield to produce photorealistic rotating product videos optimized for e-commerce platforms and social media. The skill supports turntable showcases, unboxing reveals, macro-to-wide transitions, and material-focused lighting to highlight product value. Output formats span 16:9, square, and vertical with customizable rotation speeds and dramatic entry sequences.★ 712

Related notes

References

Liang, Q., Wang, H., Liang, Z., & Liu, Y. (2026). From Skill Text to Skill Structure: The Scheduling-Structural-Logical Representation for Agent Skills. arXiv:2604.24026.
Schank, R. C. (1972). Conceptual Dependency: A Theory of Natural Language Understanding.
Schank, R. C., & Abelson, R. P. (1977). Scripts, Plans, Goals, and Understanding.
Schank, R. C. (1980). Language and Memory. Cognitive Science.
Wang, G. et al. (2023). Voyager: An Open-Ended Embodied Agent with Large Language Models.