feat(plugins): add skills bundle plugin type

Add declarative skill and skill-bundle plugin support with local registry storage, manifest validation, and lifecycle handling.\n\nKeep skill plugins off the JVM loader path and advance core/dashboard defaults to 2.6.5-dev.

Author: FTMahringer

.github/release-notes/v2.6.5-dev.md

@@ -0,0 +1,16 @@
+# v2.6.5-dev
+
+Skills + Skill Bundle Plugin Type
+
+## Added
+- Declarative `type: skill` and `type: skill-bundle` manifest support for skills.sh entries.
+- `SkillsBundleRegistry` for local skill bundle registration and inspection.
+- Validation for skills manifests and `skills.sh` source constraints.
+- Declarative install/uninstall handling without the JVM loader path.
+
+## Changed
+- Core, dashboard, and plugin registry versions now advance to `2.6.5-dev`.
+- Skill plugins are treated as declarative external skill definitions.
+
+## Fixed
+- JVM plugin loading now rejects `skill` and `skill-bundle` manifests with a clear error.

CHANGELOG.md

@@ -9,6 +9,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [v2.6.5-dev] - 2026-05-19
+
+**Skills + Skill Bundle Plugin Type**
+
+### Added
+- Declarative `type: skill` and `type: skill-bundle` manifest support with `skills.sh` entries.
+- `SkillsBundleRegistry` to register, inspect, and persist skill bundle metadata locally.
+- Manifest validation for required `skills` entries and `skills.sh` source constraints.
+- Install-time handling for declarative skill plugins without the Java classloader path.
+- Skill bundle lifecycle tests covering registration and sandbox bypass behavior.
+
+### Changed
+- Core, dashboard, and plugin registry version defaults now advance to `2.6.5-dev`.
+- Declarative skill plugins are treated as external skill definitions instead of JVM-loaded plugins.
+
+### Fixed
+- Skill bundle installs now fail with a clear message if a JVM load path is attempted.
+
 ## [v2.6.4-dev] - 2026-05-19
 
 **MCP Server Plugin Type**

README.md

@@ -2,7 +2,7 @@
 
 > **Your AI. Your Rules. Your Stack.**
 
-**Current Release**: v2.6.4-dev (MCP Server Plugin Type)
+**Current Release**: v2.6.5-dev (Skills + Skill Bundle Plugin Type)
 
 SYNAPSE is a self-hosted, provider-agnostic AI orchestration platform. Run it on your own infrastructure, connect local or remote model providers, manage workflows and runtime services, and extend everything through plugins, registries, and integrations — without depending on a third-party cloud or a built-in model.
 

docs/roadmaps/SYNAPSE_V3_IMPLEMENTATION_ROADMAP.md

@@ -471,7 +471,7 @@ security controls. Completes the plugin platform story.
 - No ClassLoader / no bytecode scan path
 - **Exit**: `filesystem-mcp` installs and connects via stdio transport
 
-#### v2.6.5-dev: Skills + Skill Bundle Plugin Type
+#### v2.6.5-dev: Skills + Skill Bundle Plugin Type (completed)
 - skills.sh fetch + local skill storage
 - `SkillsBundleRegistry`
 - Atomic bundle install/uninstall (all-or-nothing)

packages/core/pom.xml

@@ -15,7 +15,7 @@
 
     <groupId>dev.synapse</groupId>
     <artifactId>synapse-core</artifactId>
-    <version>2.6.4-dev</version>
+    <version>2.6.5-dev</version>
     <name>synapse-core</name>
     <description>SYNAPSE Spring Boot backend</description>
 

packages/core/src/main/java/dev/synapse/core/common/domain/Plugin.java

@@ -89,6 +89,7 @@ public enum PluginType {
         model,
         skill,
         mcp,
+        skill_bundle,
     }
 
     public enum PluginStatus {

packages/core/src/main/java/dev/synapse/plugins/ManifestValidator.java

@@ -37,7 +37,7 @@ public ValidationResult validate(PluginManifest manifest) {
         }
 
         if (manifest.type() == null) {
-            errors.add("type is required and must be one of: channel, model, skill, mcp");
+            errors.add("type is required and must be one of: channel, model, skill, skill-bundle, mcp");
         }
 
         if (blank(manifest.version())) {
@@ -56,6 +56,11 @@ public ValidationResult validate(PluginManifest manifest) {
 
         if (manifest.type() == dev.synapse.core.common.domain.Plugin.PluginType.mcp) {
             validateMcp(manifest, errors);
+        } else if (
+            manifest.type() == dev.synapse.core.common.domain.Plugin.PluginType.skill ||
+            manifest.type() == dev.synapse.core.common.domain.Plugin.PluginType.skill_bundle
+        ) {
+            validateSkills(manifest, errors);
         }
 
         return errors.isEmpty() ? ValidationResult.ok() : ValidationResult.fail(errors);
@@ -103,6 +108,44 @@ private void validateMcp(PluginManifest manifest, List<String> errors) {
         }
     }
 
+    private void validateSkills(PluginManifest manifest, List<String> errors) {
+        if (manifest.skills() == null || manifest.skills().isEmpty()) {
+            errors.add("skills section is required for type skill and skill-bundle");
+            return;
+        }
+
+        Object skillsObj = manifest.skills().get("skills");
+        if (!(skillsObj instanceof List<?> skills) || skills.isEmpty()) {
+            errors.add("skills.skills must be a non-empty list");
+            return;
+        }
+
+        if (manifest.type() == dev.synapse.core.common.domain.Plugin.PluginType.skill && skills.size() != 1) {
+            errors.add("type skill requires exactly one skills entry");
+        }
+
+        for (Object item : skills) {
+            if (!(item instanceof Map<?, ?> skill)) {
+                errors.add("each skills entry must be a map");
+                continue;
+            }
+            String source = stringValue(skill.get("source"));
+            String id = stringValue(skill.get("id"));
+            String version = stringValue(skill.get("version"));
+            if (blank(source)) {
+                errors.add("skills source is required");
+            } else if (!"skills.sh".equalsIgnoreCase(source)) {
+                errors.add("skills source must be skills.sh");
+            }
+            if (blank(id)) {
+                errors.add("skills id is required");
+            }
+            if (blank(version)) {
+                errors.add("skills version is required");
+            }
+        }
+    }
+
     private String stringValue(Object value) {
         return value == null ? null : value.toString();
     }

packages/core/src/main/java/dev/synapse/plugins/PluginLifecycleService.java

@@ -39,6 +39,7 @@ public class PluginLifecycleService {
     private final PluginSandboxService sandboxService;
     private final PluginPerformanceMetrics performanceMetrics;
     private final McpServerRegistry mcpServerRegistry;
+    private final SkillsBundleRegistry skillsBundleRegistry;
 
     public PluginLifecycleService(
         PluginRepository pluginRepository,
@@ -50,7 +51,8 @@ public PluginLifecycleService(
         PluginDependencyResolver dependencyResolver,
         PluginSandboxService sandboxService,
         PluginPerformanceMetrics performanceMetrics,
-        McpServerRegistry mcpServerRegistry
+        McpServerRegistry mcpServerRegistry,
+        SkillsBundleRegistry skillsBundleRegistry
     ) {
         this.pluginRepository = pluginRepository;
         this.validator = validator;
@@ -62,6 +64,7 @@ public PluginLifecycleService(
         this.sandboxService = sandboxService;
         this.performanceMetrics = performanceMetrics;
         this.mcpServerRegistry = mcpServerRegistry;
+        this.skillsBundleRegistry = skillsBundleRegistry;
     }
 
     @Transactional
@@ -90,14 +93,14 @@ private Plugin doInstall(Map<String, Object> rawManifest) {
         plugin.setStatus(Plugin.PluginStatus.installed);
         plugin.setManifest(rawManifest);
         plugin.setStorageTier(
-            manifest.type() == Plugin.PluginType.mcp
+            isDeclarative(manifest.type())
                 ? Plugin.StorageTier.system
                 : Plugin.StorageTier.staging
         );
         plugin.setLoaderState(Plugin.LoaderState.UNLOADED);
         plugin.setTrustTier(detectTrustTier(rawManifest));
-        plugin.setSandboxEnabled(manifest.type() != Plugin.PluginType.mcp);
-        if (manifest.type() == Plugin.PluginType.mcp) {
+        plugin.setSandboxEnabled(!isDeclarative(manifest.type()));
+        if (isDeclarative(manifest.type())) {
             plugin.setScanClean(true);
         }
 
@@ -142,6 +145,11 @@ private Plugin doInstall(Map<String, Object> rawManifest) {
 
         if (manifest.type() == Plugin.PluginType.mcp) {
             mcpServerRegistry.register(manifest);
+        } else if (
+            manifest.type() == Plugin.PluginType.skill ||
+            manifest.type() == Plugin.PluginType.skill_bundle
+        ) {
+            skillsBundleRegistry.register(manifest);
         }
 
         logService.log(
@@ -233,6 +241,12 @@ public void uninstall(String id) {
             Plugin plugin = pluginRepository.findById(id).orElse(null);
             if (plugin != null && plugin.getType() == Plugin.PluginType.mcp) {
                 mcpServerRegistry.unregister(id);
+            } else if (
+                plugin != null &&
+                (plugin.getType() == Plugin.PluginType.skill ||
+                 plugin.getType() == Plugin.PluginType.skill_bundle)
+            ) {
+                skillsBundleRegistry.unregister(id);
             }
 
             storageService.deleteJar(id + ".jar");
@@ -264,6 +278,12 @@ private Plugin.TrustTier detectTrustTier(Map<String, Object> rawManifest) {
         return Plugin.TrustTier.COMMUNITY;
     }
 
+    private boolean isDeclarative(Plugin.PluginType type) {
+        return type == Plugin.PluginType.mcp ||
+            type == Plugin.PluginType.skill ||
+            type == Plugin.PluginType.skill_bundle;
+    }
+
     @Transactional(readOnly = true)
     @Cacheable(value = "plugin-metadata", key = "'installed-plugins'")
     public List<Plugin> findAll() {

packages/core/src/main/java/dev/synapse/plugins/PluginManifest.java

@@ -20,6 +20,7 @@ public record PluginManifest(
     List<String> tags,
     List<PluginDependency> dependencies,
     List<PluginDependency> softDependencies,
+    Map<String, Object> skills,
     Map<String, Object> mcp,
     Map<String, Object> configSchema,
     Map<String, Object> raw
@@ -29,7 +30,9 @@ public static PluginManifest fromMap(Map<String, Object> map) {
         Plugin.PluginType type = null;
         if (typeStr != null) {
             try {
-                type = Plugin.PluginType.valueOf(typeStr.toLowerCase());
+                type = Plugin.PluginType.valueOf(
+                    typeStr.toLowerCase().replace('-', '_')
+                );
             } catch (IllegalArgumentException ignored) {}
         }
 
@@ -61,6 +64,7 @@ public static PluginManifest fromMap(Map<String, Object> map) {
             tags,
             hardDeps,
             softDeps,
+            mapOf(map.get("skills")),
             mapOf(map.get("mcp")),
             mapOf(map.get("config_schema")),
             map

packages/core/src/main/java/dev/synapse/plugins/PluginRegistryService.java

@@ -48,7 +48,7 @@ public PluginRegistryService(
         RegistrySourceRepository registrySourceRepository,
         RegistryProperties registryProperties,
         RestClient restClient,
-        @Value("${synapse.version:${spring.application.version:v2.6.4-dev}}") String synapseVersion
+        @Value("${synapse.version:${spring.application.version:v2.6.5-dev}}") String synapseVersion
     ) {
         this.storeRegistryService = storeRegistryService;
         this.registrySourceRepository = registrySourceRepository;
@@ -444,12 +444,15 @@ private boolean matchesType(StoreEntry entry, String type) {
         if (!StringUtils.hasText(type)) {
             return true;
         }
-        String normalizedType = type.toLowerCase(Locale.ROOT);
+        String normalizedType = type.toLowerCase(Locale.ROOT).replace('-', '_');
         if (entry.getType().name().equalsIgnoreCase(normalizedType)) {
             return true;
         }
         Object manifestType = entry.getMeta().get("type");
-        return manifestType != null && normalizedType.equals(manifestType.toString().toLowerCase(Locale.ROOT));
+        return manifestType != null &&
+            normalizedType.equals(
+                manifestType.toString().toLowerCase(Locale.ROOT).replace('-', '_')
+            );
     }
 
     boolean isCompatible(StoreEntry entry) {