feat(skills): Improve structure of any SKILL.md with a defined Workflow (#684)

* feat(skills): Improve structure of any SKILL.md with a defined Workflow

* feat(skills): Simplify Skill generator

Author: jabrena

CONTRIBUTING.md

@@ -12,7 +12,7 @@ Read [AGENTS.md](./AGENTS.md) for the full contributor guide (tech stack, bounda
 The unified `skills-generator` module holds all XML sources and Java code used to build **agent skills** under `skills/`.
 
 - [System prompt XML files](./skills-generator/src/main/resources/skill-references/) use the PML Schema ([pml.xsd](https://jabrena.github.io/pml/schemas/0.5.0/pml.xsd)). They are transformed with [SkillReferenceGenerator.java](./skills-generator/src/main/java/info/jab/pml/SkillReferenceGenerator.java) and [skill-reference-to-markdown.xsl](./skills-generator/src/main/resources/skill-reference-to-markdown.xsl) when producing reference content for skills.
-- [Skill summaries and inventory](./skills-generator/src/main/resources/) (`skill-indexes/`, `skill-indexes.xml`) drive `SKILL.md` generation.
+- [Skill summaries and inventory](./skills-generator/src/main/resources/) (`skill-indexes/`, `skills.xml`) drive `SKILL.md` generation.
 
 If you have the idea to contribute, review the whole process in detail:
 
@@ -22,7 +22,7 @@ If you have the idea to contribute, review the whole process in detail:
 npx skill-check skills                     # Validate generated skills
 ```
 
-Keep `skill-indexes.xml` aligned with `skill-indexes/` and `skill-references/` when adding or changing skills.
+Keep `skills.xml` aligned with `skill-indexes/` and `skill-references/` when adding or changing skills.
 
 When you feel confident with the process, fork the repository and try to create new XML documents. Models will help you because an XML file is more rigid than natural language and it has `a common vocabulary` to create prompts.
 

documentation/MAINTENANCE.md

@@ -53,6 +53,7 @@ Can you update the current changelog for 0.15.0 comparing git commits in relatio
 # Review Skill registries
 https://github.com/jabrena/cursor-rules-java
 https://tessl.io/registry/skills/submit
+npx tessl skill review ./skills/xxx
 cd target && npx skills add jabrena/cursor-rules-java --all --agent cursor && cd ..
 ```
 
@@ -86,5 +87,5 @@ git push --tags
 ## Add a new Skills
 
 ```bash
-review if exist a new id in @skills-generator/src/main/resources/skill-indexes.xml to review compare with the content of @skills-generator/src/main/resources/skill-indexes and if exist add a new skill summary in @skills-generator/src/main/resources/skill-indexes . to elaborate the skill review the content of the id with @skills-generator/src/main/resources/skill-references when finish, validate generation with ./mvnw clean install -pl skills-generator and validate the skill with npx skill-check skills
+review if exist a new id in @skills-generator/src/main/resources/skills.xml to review compare with the content of @skills-generator/src/main/resources/skill-indexes and if exist add a new skill summary in @skills-generator/src/main/resources/skill-indexes. to elaborate the skill, review the `reference-list/reference` relation declared for that id in @skills-generator/src/main/resources/skills.xml. when finish, validate generation with ./mvnw clean install -pl skills-generator and validate the skill with npx skill-check skills
 ```

skills-generator/pom.xml

@@ -71,11 +71,10 @@
                                 <resource>
                                     <directory>${project.basedir}/src/main/resources</directory>
                                     <includes>
-                                        <include>skill-indexes.xml</include>
+                                        <include>skills.xml</include>
                                         <include>skill-indexes/**</include>
                                         <include>skill-references/**</include>
                                         <include>skill-reference-to-markdown.xsl</include>
-                                        <include>skill-references.xml</include>
                                     </includes>
                                 </resource>
                             </resources>

skills-generator/src/main/java/info/jab/pml/SkillIndexes.java

@@ -1,36 +1,26 @@
 package info.jab.pml;
 
-import java.io.IOException;
 import java.io.InputStream;
-import java.net.JarURLConnection;
-import java.net.URISyntaxException;
-import java.net.URL;
-import java.nio.file.Files;
-import java.nio.file.Path;
-import java.nio.file.Paths;
 import java.util.ArrayList;
 import java.util.List;
-import java.util.jar.JarEntry;
-import java.util.jar.JarFile;
 import java.util.stream.Stream;
 import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 import org.w3c.dom.NodeList;
 
 /**
- * Inventory of skills to generate, loaded from {@code skill-indexes.xml}.
+ * Inventory of skills to generate, loaded from {@code skills.xml}.
  * <p>
  * Each entry has an {@code id} (numeric or string like "010"). When {@code requiresSystemPrompt}
- * is true (default), the skillId is derived by matching skill-references with prefix {@code {id}-}.
- * When false, the entry must specify {@code skillId} and no skill-reference is required.
+ * is true (default), the skillId is derived from the first item in {@code references/reference-list/reference}
+ * unless {@code skillId} is explicitly set. When false, the entry must specify {@code skillId}
+ * and no reference is required.
  * Each skill must have a summary in {@code skill-indexes/{id}-skill.md} or {@code skill-indexes/{id}-skill.xml}
  * when {@code xml="true"} on the entry.
  */
 public final class SkillIndexes {
 
-    private static final String INVENTORY_RESOURCE = "skill-indexes.xml";
-    private static final String SYSTEM_PROMPTS_PREFIX = "skill-references/";
-
+    private static final String INVENTORY_RESOURCE = "skills.xml";
     private SkillIndexes() {}
 
     /**
@@ -49,7 +39,7 @@ public static Stream<String> skillIds() {
             String numericId = entry.numericId();
             validateSkillSummaryExists(numericId, entry.useXml());
             String skillId = entry.requiresSystemPrompt()
-                ? resolveSkillIdFromPrefix(numericId)
+                ? resolveSkillId(entry)
                 : entry.skillId();
             skillIds.add(skillId);
         }
@@ -67,91 +57,38 @@ public static Stream<SkillDescriptor> skillDescriptors() {
             String numericId = entry.numericId();
             validateSkillSummaryExists(numericId, entry.useXml());
             String skillId = entry.requiresSystemPrompt()
-                ? resolveSkillIdFromPrefix(numericId)
+                ? resolveSkillId(entry)
                 : entry.skillId();
-            descriptors.add(new SkillDescriptor(skillId, entry.requiresSystemPrompt(), entry.useXml()));
+            descriptors.add(new SkillDescriptor(skillId, entry.requiresSystemPrompt(), entry.useXml(), entry.references()));
         }
         return descriptors.stream();
     }
 
     /**
      * Skill ID, whether it requires a system prompt for reference generation, and whether to use XML source.
      */
-    public record SkillDescriptor(String skillId, boolean requiresSystemPrompt, boolean useXml) {}
+    public record SkillDescriptor(String skillId, boolean requiresSystemPrompt, boolean useXml, List<String> references) {}
 
     /**
-     * Resolves skillId by finding the skill-reference XML that starts with {@code {numericId}-}.
+     * Resolves skillId from inventory entry.
      *
-     * @param numericId numeric id from inventory (e.g. "111" or "014")
+     * @param entry inventory entry
      * @return full skillId (e.g. 110-java-maven-best-practices)
-     * @throws RuntimeException if none or multiple skill-references match
+     * @throws RuntimeException if required references are missing
      */
-    public static String resolveSkillIdFromPrefix(String numericId) {
-        String prefix = numericId + "-";
-        List<String> matches = listSystemPromptBaseNames().stream()
-            .filter(name -> name.startsWith(prefix) && name.endsWith(".xml"))
-            .map(name -> name.substring(0, name.length() - 4))
-            .toList();
-
-        if (matches.isEmpty()) {
-            throw new RuntimeException("No skill-reference found for id " + numericId
-                + ". Add a skill-references/" + prefix + "*.xml file under skills-generator/src/main/resources/skill-references.");
-        }
-        if (matches.size() > 1) {
-            throw new RuntimeException("Multiple skill-references match id " + numericId + ": " + matches);
-        }
-        return matches.getFirst();
-    }
-
-    private static List<String> listSystemPromptBaseNames() {
-        try {
-            // Anchor on skill-reference-to-markdown.xsl to locate the JAR or exploded classes directory
-            URL anchor = getResourceUrl("skill-reference-to-markdown.xsl");
-            if (anchor == null) {
-                throw new RuntimeException("skill-reference-to-markdown.xsl not found on classpath");
-            }
-            if ("jar".equals(anchor.getProtocol())) {
-                JarURLConnection conn = (JarURLConnection) anchor.openConnection();
-                try (JarFile jar = conn.getJarFile()) {
-                    return jar.stream()
-                        .map(JarEntry::getName)
-                        .filter(name -> name.startsWith(SYSTEM_PROMPTS_PREFIX) && name.endsWith(".xml"))
-                        .filter(name -> !name.contains("/assets/"))
-                        .map(name -> name.substring(SYSTEM_PROMPTS_PREFIX.length()))
-                        .toList();
-                }
-            }
-            if ("file".equals(anchor.getProtocol())) {
-                Path base = Paths.get(anchor.toURI()).getParent();
-                Path systemPromptsDir = base.resolve("skill-references");
-                if (!Files.isDirectory(systemPromptsDir)) {
-                    return List.of();
-                }
-                try (Stream<Path> files = Files.list(systemPromptsDir)) {
-                    return files
-                        .filter(p -> p.toString().endsWith(".xml"))
-                        .filter(p -> !p.toString().contains("assets"))
-                        .map(p -> p.getFileName().toString())
-                        .toList();
-                }
-            }
-            return List.of();
-        } catch (IOException | URISyntaxException e) {
-            throw new RuntimeException("Failed to list skill-references", e);
+    public static String resolveSkillId(InventoryEntry entry) {
+        if (entry.skillId() != null && !entry.skillId().isBlank()) {
+            return entry.skillId();
         }
-    }
-
-    private static URL getResourceUrl(String name) {
-        ClassLoader cl = SkillIndexes.class.getClassLoader();
-        URL url = cl.getResource(name);
-        if (url == null) {
-            url = Thread.currentThread().getContextClassLoader().getResource(name);
+        if (entry.references().isEmpty()) {
+            throw new RuntimeException("No skill-reference found for id " + entry.numericId()
+                + ". Add at least one reference-list/reference entry in skills.xml.");
         }
-        return url;
+        return entry.references().getFirst();
     }
 
     /**
-     * Loads and parses skill-indexes.xml.
+     * Loads and parses skills.xml.
      */
     public static List<InventoryEntry> loadInventory() {
         try (InputStream stream = getResource(INVENTORY_RESOURCE)) {
@@ -197,7 +134,12 @@ private static List<InventoryEntry> parseInventory(InputStream in) {
                         + " has requiresSystemPrompt=false but no skillId specified.");
                 }
                 boolean useXml = parseXmlAttribute(skillEl);
-                entries.add(new InventoryEntry(numericId, requiresSystemPrompt, skillId, useXml));
+                List<String> references = parseReferences(skillEl);
+                if (requiresSystemPrompt && references.isEmpty() && (skillId == null || skillId.isBlank())) {
+                    throw new RuntimeException("Entry with id " + numericId
+                        + " requires a system prompt but has no reference-list/reference and no skillId.");
+                }
+                entries.add(new InventoryEntry(numericId, requiresSystemPrompt, skillId, useXml, references));
             }
             if (entries.isEmpty()) {
                 throw new RuntimeException("Skill inventory must contain at least one <skill> entry");
@@ -226,6 +168,25 @@ private static boolean parseXmlAttribute(Element skillEl) {
         return "true".equals(s) || "yes".equals(s) || "1".equals(s);
     }
 
+    private static List<String> parseReferences(Element skillEl) {
+        // Canonical format: <skill><reference-list><reference>...</reference></reference-list></skill>
+        NodeList referenceLists = skillEl.getElementsByTagName("reference-list");
+        NodeList refs = referenceLists.getLength() > 0
+            ? ((Element) referenceLists.item(0)).getElementsByTagName("reference")
+            : skillEl.getElementsByTagName("reference"); // backward compatibility
+        List<String> values = new ArrayList<>();
+        for (int i = 0; i < refs.getLength(); i++) {
+            if (!(refs.item(i) instanceof Element refEl)) {
+                continue;
+            }
+            String value = refEl.getTextContent();
+            if (value != null && !value.trim().isEmpty()) {
+                values.add(value.trim());
+            }
+        }
+        return values;
+    }
+
     private static void validateSkillSummaryExists(String numericId, boolean useXml) {
         String resourceName = useXml
             ? "skill-indexes/" + numericId + "-skill.xml"
@@ -257,11 +218,17 @@ private static InputStream getResource(String name) {
     }
 
     /**
-     * Single entry from skill-indexes.xml. When requiresSystemPrompt is true,
-     * skillId is derived by matching skill-references with prefix {@code {numericId}-}.
+     * Single entry from skills.xml. When requiresSystemPrompt is true,
+     * skillId is derived from the first reference entry when not explicitly provided.
      * When false, skillId must be provided and no skill-reference is required.
      * When useXml is true, skill summary is loaded from skill-indexes/{numericId}-skill.xml
      * and transformed via schema validation and XSLT; otherwise from skill-indexes/{numericId}-skill.md.
      */
-    public record InventoryEntry(String numericId, boolean requiresSystemPrompt, String skillId, boolean useXml) {}
+    public record InventoryEntry(
+        String numericId,
+        boolean requiresSystemPrompt,
+        String skillId,
+        boolean useXml,
+        List<String> references
+    ) {}
 }

skills-generator/src/main/java/info/jab/pml/SkillReferences.java

@@ -1,72 +1,24 @@
 package info.jab.pml;
 
-import java.io.InputStream;
-import java.util.ArrayList;
-import java.util.List;
 import java.util.stream.Stream;
-import org.w3c.dom.Document;
-import org.w3c.dom.Element;
-import org.w3c.dom.NodeList;
 
 /**
- * Inventory of system prompts to generate, loaded from {@code skill-references.xml}.
+ * Inventory of system prompts to generate, loaded from {@code skills.xml}.
  * <p>
- * Each entry has a {@code name} attribute corresponding to the base name of the XML source file
- * (e.g. {@code 110-java-maven-best-practices} maps to {@code skill-references/110-java-maven-best-practices.xml}).
+ * References are declared per skill under {@code reference-list/reference}.
  */
 public final class SkillReferences {
 
-    private static final String INVENTORY_RESOURCE = "skill-references.xml";
-
     private SkillReferences() {
     }
 
     public static Stream<String> baseNames() {
-        return loadInventory().stream();
+        return SkillIndexes.loadInventory().stream()
+            .flatMap(entry -> entry.references().stream())
+            .distinct();
     }
 
     public static Stream<String> xmlFilenames() {
         return baseNames().map(name -> "skill-references/" + name + ".xml");
     }
-
-    private static List<String> loadInventory() {
-        ClassLoader cl = SkillReferences.class.getClassLoader();
-        try (InputStream stream = cl.getResourceAsStream(INVENTORY_RESOURCE)) {
-            if (stream == null) {
-                throw new RuntimeException("System prompt inventory not found: " + INVENTORY_RESOURCE);
-            }
-            return parseInventory(stream);
-        } catch (RuntimeException e) {
-            throw e;
-        } catch (Exception e) {
-            throw new RuntimeException("Failed to load system prompt inventory", e);
-        }
-    }
-
-    private static List<String> parseInventory(InputStream in) throws Exception {
-        Document doc = InventoryXmlLoader.parse(in);
-        Element root = doc.getDocumentElement();
-        if (!"system-prompt-inventory".equals(root.getNodeName())) {
-            throw new RuntimeException("System prompt inventory root must be <system-prompt-inventory>");
-        }
-        NodeList nodes = root.getElementsByTagName("prompt");
-        List<String> names = new ArrayList<>();
-        for (int i = 0; i < nodes.getLength(); i++) {
-            if (!(nodes.item(i) instanceof Element el)) {
-                continue;
-            }
-            if (el.getParentNode() != root) {
-                continue;
-            }
-            String name = el.getAttribute("name");
-            if (name == null || name.isBlank()) {
-                throw new RuntimeException("system-prompt-inventory entry missing name attribute");
-            }
-            names.add(name.trim());
-        }
-        if (names.isEmpty()) {
-            throw new RuntimeException("System prompt inventory must contain at least one <prompt> entry");
-        }
-        return names;
-    }
 }