Summary

Decouple Skill capabilities from AgentEngine so they can be consumed by HTTP handlers, workflows, and any future module via a stable interface. The current design tightly couples *skills.Manager to the agent engine and rebuilds it on every agent request, blocking reuse and making the layer hard to evolve (no DB persistence, no RBAC decoration, no mocking, etc.).

This PR introduces a clean three-layer architecture without changing any external contract (HTTP response shape, env vars, AgentConfig fields are all preserved).

Architecture

Agent / Handler / Workflow  →  SkillRuntime (interface, DI singleton)
                                       │
                                       ▼
                              fileSystemRuntime (default impl)
                                       │
                                       ▼
                              SkillRepository (interface)
                                       │
                                       ▼
                              fsRepository (filesystem)

Key changes

• New abstractions

  • internal/agent/skills/runtime.go — SkillRuntime interface + ExecuteRequest / SkillInfo
  • internal/agent/skills/repository.go — SkillRepository interface + fsRepository (path-traversal protection preserved)
  • internal/agent/skills/runtime_fs.go — fileSystemRuntime consolidating the previous Manager and Loader, with explicit concurrency safety and idempotent Initialize
  • internal/agent/skills/factory.go — centralised sandbox construction and env-var parsing (NewRuntime / NewRuntimeFromEnv / FilterMetadata)

• Consumers switched to the interface

  • tools/skill_read.go, tools/skill_execute.go depend on SkillRuntime (mockable)
  • agent/engine.go field renamed skillsManager → skillRuntime; per-request AllowedSkills filtering applied via FilterMetadata since the runtime is a global singleton
  • handler/skill_handler.go no longer reads env vars; skills_available comes from runtime.SandboxAvailable()

• DI

  • container.go registers skills.NewRuntimeFromEnv as a singleton (single filesystem scan shared across requests, vs. per-request reconstruction before)
  • agent_service.NewAgentService now takes skills.SkillRuntime as a dependency; the 68-line initializeSkillsManager helper is removed

• Deleted

  • internal/agent/skills/manager.go
  • internal/agent/skills/loader.go
  • internal/application/service/skill_service.go
  • internal/types/interfaces/skill.go

Backwards compatibility

• GET /api/v1/skills response format unchanged (including skills_available)
• AgentConfig.{SkillsEnabled, SkillDirs, AllowedSkills} JSON fields unchanged
• Environment variables WEKNORA_SKILLS_DIR, WEKNORA_SANDBOX_* unchanged
• Filesystem layout (skills/preloaded/<name>/SKILL.md) unchanged

Behaviour difference (intended improvement)

• Skill discovery is now performed once at startup (DI singleton) instead of on every agent request. This is a performance win but means reload requires either restarting the process or calling runtime.Reload() (no HTTP endpoint added in this PR — can come later).

Future extension points unlocked

With this refactor, the following can each land as a small isolated PR:

• DB / OSS / marketplace SkillRepository implementation
• Retrieval-based Skill prompt injection (avoid token bloat with many skills)
• RBAC / audit-logging via Runtime decorator
• Parallel script execution (ExecuteBatch)
• fsnotify hot-reload

Test plan

• go build ./... passes
• go vet ./... passes
• go test ./internal/agent/... passes (including new tests covering Repository.Discover, GetByName, ReadFile path-traversal rejection, Runtime.Initialize, allow-list filtering, disabled state, FilterMetadata)
• grep -r "skills.Manager\|NewSkillService\|interfaces.SkillService" internal/ returns empty
• Manual smoke: start server with WEKNORA_SANDBOX_MODE=docker + skills enabled in agent config; verify read_skill and execute_skill_script tools work end-to-end against a preloaded skill
• Manual smoke: GET /api/v1/skills returns the same JSON shape (data + skills_available) as before