Integrate Agent Skills support into jido_ai (port useful pieces from jido_skill)

[mikehostetler]

Summary

jido_ai should become the canonical home for Agent Skills support in the Jido ecosystem.

We already have the beginnings of this in Jido.AI.Skill, Loader, Registry, Prompt, and mix jido_ai.skill, but the separate jido_skill package explored a broader runtime and some of that work is worth pulling back into jido_ai.

After reviewing the Agent Skills spec and client implementation guidance, we should not port jido_skill wholesale. Instead, we should integrate the parts that improve standards compliance, interoperability, and runtime UX for skills, and explicitly defer the Jido-specific standalone signal runtime unless we later decide that executable skills are a core jido_ai concern.

Relevant references:

• Spec: https://agentskills.io/specification
• Client implementation guide: https://agentskills.io/client-implementation/adding-skills-support
• Source package to mine: https://github.com/agentjido/jido_skill

Why

The Agent Skills spec is centered on:

• progressive disclosure
• standard skill directory conventions
• discovery + disclosure + activation lifecycle
• relative resource loading from the skill root
• lenient parsing and good diagnostics
• preserving activated skill context over time

The spec does not require:

• compiling SKILL.md into executable Elixir modules
• jido.actions / jido.router
• a Jido.Signal.Bus dispatcher
• hook emission / lifecycle subscribers
• a standalone skill escript runtime

So the right goal is:

make jido_ai a strong Agent Skills implementation first, and only port Jido-specific runtime features when they provide clear value beyond the spec.

Goals

• Make jido_ai the canonical implementation for skills in the Jido ecosystem.
• Port the useful parts of jido_skill into jido_ai.
• Improve Agent Skills compatibility and cross-client interoperability.
• Keep the base implementation spec-aligned and decoupled from the jido_skill standalone runtime model.

Non-goals for the first pass

• Porting jido_skill as-is.
• Requiring Jido-specific frontmatter like jido.actions, jido.router, or jido.hooks.
• Compiling SKILL.md files into executable modules.
• Recreating the Jido.Signal.Bus dispatcher / signal runtime.
• Recreating mix skill.run, mix skill.routes, mix skill.watch, mix skill.signal, or the skill escript.
• Adding a global/local JSON settings system for hook defaults and runtime permissions.

What Looks Useful From The Spec

These are the pieces from jido_skill that still look useful after reviewing the Agent Skills docs:

1. Discovery across standard paths and scopes.
2. Deterministic precedence rules when names collide.
3. Better parsing compatibility and diagnostics.
4. A proper activation API/tool surface.
5. Progressive disclosure of bundled resources.
6. Session-level handling for activated skills (dedupe / protect from compaction).
7. Optional permission allowlisting around skill directories where a host runtime has gated file access.

These do not currently look necessary for jido_ai core Agent Skills support:

1. Signal-driven route dispatch.
2. Hook emitters / lifecycle subscribers.
3. Executable skill compilation.
4. allowed-tools enforcement as a hard runtime gate. The field is experimental in the spec and may remain advisory metadata unless a host runtime has a real permission system.
5. Standalone skill runtime CLIs.

Prioritized Implementation Plan

Priority 1: Discovery and Interop

• Add standard discovery support for:
  • project-level .agents/skills/
  • user-level ~/.agents/skills/
• Decide whether to also support Jido-native paths alongside the cross-client .agents/skills/ convention.
• Add deterministic precedence rules:
  • project-level overrides user-level
  • collisions within the same scope should be deterministic and logged
• Track enough metadata in runtime records to support activation cleanly:
  • name
  • description
  • absolute location of SKILL.md
  • skill root directory
  • scope / source metadata

Priority 2: Parser Compatibility and Diagnostics

• Extend Jido.AI.Skill.Loader to better match client-implementation guidance:
  • lenient handling where possible
  • diagnostics for malformed-but-recoverable skills
  • skip only when the skill is genuinely unusable
• Add non-fatal warnings for:
  • parent directory name mismatch
  • cosmetic naming violations we decide to tolerate for compatibility
• Preserve and expose diagnostics so they can be surfaced in tooling / logs.

Priority 3: Activation Surface

• Add a first-class activation API in jido_ai.
• Activation should return enough context for a host/client to inject skill content cleanly:
  • skill body (or optionally full file)
  • skill root directory
  • optionally a bounded listing of bundled resources
• Keep activation model-driven by default:
  • catalog disclosure at startup
  • load full skill content only on activation
• Support user-explicit activation in higher-level integrations, but keep syntax concerns outside the core library unless there is already a natural home for it.

Priority 4: Progressive Disclosure of Resources

• Add APIs/helpers to enumerate resources under a skill root without eagerly loading them.
• Standardize relative path resolution for skill-referenced files.
• Make it easy for callers to load scripts/, references/, and assets/ lazily.

Priority 5: Session / Context Management

• Track activated skills in-session so repeated activations can be deduplicated.
• Provide a way for higher-level runtimes to mark activated skill content as durable / protected from compaction or pruning.
• Ensure prompt assembly and runtime context handling preserve activated skill instructions across long sessions.

Priority 6: Optional Follow-ons

• Treat allowed-tools as advisory metadata first.
• If a host runtime has gated file access or tool permissions, add optional hooks for allowlisting skill directories/resources.
• Consider reload APIs/tooling if they help local development, but keep them secondary to the core discovery/activation model.

Concrete Port Candidates From jido_skill

The most promising things to port or adapt are:

• discovery path scanning
• scope/precedence handling
• richer runtime records (location, scope, loaded_at, skill root)
• reload support where useful
• structured activation output
• bundled resource enumeration
• permission allowlisting hooks for hosts that support gated access

The things to avoid porting into core jido_ai for now are:

• skill module compilation from markdown
• signal dispatcher
• hook emitter + lifecycle subscriber
• JSON runtime settings layer designed around the standalone runtime
• skill escript / operational CLIs

Open Questions

• Should discovery live inside Jido.AI.Skill.Registry, or should we introduce a separate Discovery module and keep the registry focused on storage?
• Should Jido also scan client-specific skill paths in addition to .agents/skills/?
• Where should user-explicit activation syntax live: jido_ai itself, or the client/harness embedding it?
• Do we want hot reload in the library, or only via optional tooling?
• How much leniency do we want in parsing before we risk masking genuinely broken skills?

Acceptance Criteria

• jido_ai can discover skills from standard directories and expose a compact catalog suitable for model disclosure.
• Activated skills can resolve bundled resources relative to the skill root.
• Discovery and parsing diagnostics are user-visible and lenient where practical.
• Repeated activation does not spam the conversation context.
• Base Agent Skills support in jido_ai does not depend on the jido_skill standalone signal runtime.