feat: structured skill packages with config overrides, chaining, and TUI integration
Add a skill package system where each skill is a directory with a skill.yaml manifest and prompt markdown files. Skills support /command triggers, scoped config overrides (temperature, max_tokens, tool filtering), chain dependencies with cycle-safe resolution, and a finish_skill completion signal. Includes four built-in skills: explore, brainstorm, write-document, and plan. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
234
app/services/skill_runner.py
Normal file
234
app/services/skill_runner.py
Normal file
@@ -0,0 +1,234 @@
|
||||
"""SkillRunner — orchestrates skill activation, chaining, config scoping, and deactivation."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from dataclasses import dataclass, field
|
||||
|
||||
from app.agent.context import SessionContext
|
||||
from app.models.config import AppConfig
|
||||
from app.models.skill import SkillManifest
|
||||
from app.services.skills import Skill, SkillsManager
|
||||
from app.tools.registry import ToolRegistry
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class SkillChainError(Exception):
|
||||
"""Raised when skill chain resolution fails (e.g., cycle detected)."""
|
||||
|
||||
|
||||
@dataclass
|
||||
class _SkillSnapshot:
|
||||
"""Captured state before skill activation, for restoration on deactivate."""
|
||||
|
||||
temperature: float
|
||||
max_tokens: int
|
||||
disabled_tools: set[str] = field(default_factory=set)
|
||||
|
||||
|
||||
class SkillRunner:
|
||||
"""Manages skill lifecycle: activation, chaining, config overrides, deactivation.
|
||||
|
||||
Only one skill can be active at a time. Activating a new skill while one
|
||||
is active will first deactivate the current skill.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
skills_manager: SkillsManager,
|
||||
config: AppConfig,
|
||||
ctx: SessionContext,
|
||||
registry: ToolRegistry,
|
||||
) -> None:
|
||||
self._skills = skills_manager
|
||||
self._config = config
|
||||
self._ctx = ctx
|
||||
self._registry = registry
|
||||
self._active_skill: Skill | None = None
|
||||
self._snapshot: _SkillSnapshot | None = None
|
||||
|
||||
@property
|
||||
def is_active(self) -> bool:
|
||||
"""Whether a skill is currently active."""
|
||||
return self._active_skill is not None
|
||||
|
||||
@property
|
||||
def active_skill_name(self) -> str | None:
|
||||
"""Name of the currently active skill, or None."""
|
||||
return self._active_skill.name if self._active_skill else None
|
||||
|
||||
@property
|
||||
def active_skill(self) -> Skill | None:
|
||||
"""The currently active skill, or None."""
|
||||
return self._active_skill
|
||||
|
||||
def activate(self, skill_name: str) -> str | None:
|
||||
"""Activate a skill by name.
|
||||
|
||||
Resolves chain dependencies (depth-first), applies config overrides,
|
||||
injects prompt content into conversation context.
|
||||
|
||||
Args:
|
||||
skill_name: Name of the skill to activate.
|
||||
|
||||
Returns:
|
||||
The concatenated prompt content injected, or None on failure.
|
||||
|
||||
Raises:
|
||||
SkillChainError: If chain resolution detects a cycle.
|
||||
"""
|
||||
skill = self._skills.get_skill(skill_name)
|
||||
if skill is None:
|
||||
logger.warning("Cannot activate unknown skill: %s", skill_name)
|
||||
return None
|
||||
|
||||
# Deactivate current skill if one is active
|
||||
if self._active_skill is not None:
|
||||
self.deactivate()
|
||||
|
||||
# Resolve chain dependencies
|
||||
chain = self._resolve_chain(skill, set())
|
||||
|
||||
# Snapshot current config for restoration
|
||||
self._snapshot = _SkillSnapshot(
|
||||
temperature=self._config.llm.temperature,
|
||||
max_tokens=self._config.llm.max_tokens,
|
||||
)
|
||||
|
||||
# Collect and inject chain skill prompts first
|
||||
all_prompts: list[str] = []
|
||||
for chained_skill in chain:
|
||||
content = self._skills.load_skill(chained_skill.name)
|
||||
if content:
|
||||
all_prompts.append(f"[Chained skill: {chained_skill.name}]\n{content}")
|
||||
|
||||
# Load the target skill's prompts
|
||||
content = self._skills.load_skill(skill.name)
|
||||
if content:
|
||||
all_prompts.append(content)
|
||||
|
||||
# Apply config overrides from the target skill
|
||||
if skill.manifest:
|
||||
self._apply_overrides(skill.manifest)
|
||||
|
||||
# Inject prompts into context
|
||||
full_prompt = "\n\n".join(all_prompts) if all_prompts else None
|
||||
if full_prompt:
|
||||
self._ctx.add_message(
|
||||
"system",
|
||||
f"[Skill activated: {skill.name}]\n{full_prompt}",
|
||||
)
|
||||
|
||||
self._active_skill = skill
|
||||
logger.info("Skill activated: %s", skill.name)
|
||||
return full_prompt
|
||||
|
||||
def activate_by_trigger(self, trigger: str) -> str | None:
|
||||
"""Activate a skill by its /command trigger.
|
||||
|
||||
Args:
|
||||
trigger: The trigger string (with or without leading /).
|
||||
|
||||
Returns:
|
||||
The concatenated prompt content, or None if no skill matches.
|
||||
"""
|
||||
skill = self._skills.get_skill_by_trigger(trigger)
|
||||
if skill is None:
|
||||
return None
|
||||
return self.activate(skill.name)
|
||||
|
||||
def deactivate(self, summary: str | None = None) -> None:
|
||||
"""Deactivate the current skill, restoring config and tool state.
|
||||
|
||||
Args:
|
||||
summary: Optional summary message to inject into context.
|
||||
"""
|
||||
if self._active_skill is None:
|
||||
return
|
||||
|
||||
skill_name = self._active_skill.name
|
||||
|
||||
# Restore config
|
||||
if self._snapshot is not None:
|
||||
self._config.llm.temperature = self._snapshot.temperature
|
||||
self._config.llm.max_tokens = self._snapshot.max_tokens
|
||||
self._registry.restore_filter(self._snapshot.disabled_tools)
|
||||
self._snapshot = None
|
||||
|
||||
if summary:
|
||||
self._ctx.add_message(
|
||||
"system",
|
||||
f"[Skill completed: {skill_name}] {summary}",
|
||||
)
|
||||
|
||||
self._active_skill = None
|
||||
logger.info("Skill deactivated: %s", skill_name)
|
||||
|
||||
def _resolve_chain(
|
||||
self, skill: Skill, in_progress: set[str], completed: set[str] | None = None,
|
||||
) -> list[Skill]:
|
||||
"""Depth-first resolution of skill chain dependencies.
|
||||
|
||||
Uses separate in_progress (current path) and completed sets to correctly
|
||||
handle diamond dependencies without false cycle detection.
|
||||
|
||||
Args:
|
||||
skill: The skill whose chain to resolve.
|
||||
in_progress: Skills on the current recursion path (for cycle detection).
|
||||
completed: Skills already fully resolved (skip duplicates).
|
||||
|
||||
Returns:
|
||||
Ordered list of chained skills to activate before the target.
|
||||
|
||||
Raises:
|
||||
SkillChainError: If a cycle is detected.
|
||||
"""
|
||||
if completed is None:
|
||||
completed = set()
|
||||
|
||||
if skill.manifest is None or not skill.manifest.chain:
|
||||
return []
|
||||
|
||||
result: list[Skill] = []
|
||||
for dep_name in skill.manifest.chain:
|
||||
if dep_name in completed:
|
||||
continue # Already resolved via another branch (diamond dep)
|
||||
|
||||
if dep_name in in_progress:
|
||||
raise SkillChainError(
|
||||
f"Cycle detected in skill chain: {dep_name} already in progress "
|
||||
f"(path: {' -> '.join(in_progress)} -> {dep_name})"
|
||||
)
|
||||
|
||||
dep_skill = self._skills.get_skill(dep_name)
|
||||
if dep_skill is None:
|
||||
logger.warning("Chained skill not found: %s (required by %s)", dep_name, skill.name)
|
||||
continue
|
||||
|
||||
in_progress.add(dep_name)
|
||||
result.extend(self._resolve_chain(dep_skill, in_progress, completed))
|
||||
in_progress.discard(dep_name)
|
||||
completed.add(dep_name)
|
||||
result.append(dep_skill)
|
||||
|
||||
return result
|
||||
|
||||
def _apply_overrides(self, manifest: SkillManifest) -> None:
|
||||
"""Apply config overrides from a skill manifest."""
|
||||
overrides = manifest.config_overrides
|
||||
|
||||
if overrides.temperature is not None:
|
||||
self._config.llm.temperature = overrides.temperature
|
||||
|
||||
if overrides.max_tokens is not None:
|
||||
self._config.llm.max_tokens = overrides.max_tokens
|
||||
|
||||
if overrides.tools_enable is not None or overrides.tools_disable is not None:
|
||||
previous = self._registry.apply_filter(
|
||||
enable=overrides.tools_enable,
|
||||
disable=overrides.tools_disable,
|
||||
)
|
||||
# Store for restoration
|
||||
if self._snapshot:
|
||||
self._snapshot.disabled_tools = previous
|
||||
@@ -1,46 +1,92 @@
|
||||
"""Skills manager — scans for and loads skill markdown files."""
|
||||
"""Skills manager — scans for and loads skill packages and legacy markdown files."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from pathlib import Path
|
||||
|
||||
from pydantic import BaseModel
|
||||
import yaml
|
||||
from pydantic import BaseModel, ValidationError
|
||||
|
||||
from app.models.config import SkillsConfig
|
||||
from app.models.skill import SkillManifest
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class Skill(BaseModel):
|
||||
"""Metadata for a discovered skill file."""
|
||||
"""Metadata for a discovered skill (package or legacy flat file)."""
|
||||
|
||||
name: str
|
||||
description: str
|
||||
path: Path
|
||||
manifest: SkillManifest | None = None
|
||||
|
||||
|
||||
class SkillsManager:
|
||||
"""Discovers, indexes, and loads skill files from configured directories."""
|
||||
"""Discovers, indexes, and loads skill files from configured directories.
|
||||
|
||||
Supports both:
|
||||
- Directory-based packages (contain skill.yaml + prompt .md files)
|
||||
- Legacy flat .md files (backwards compatible)
|
||||
"""
|
||||
|
||||
def __init__(self, config: SkillsConfig, workspace_root: Path) -> None:
|
||||
self._config = config
|
||||
self._workspace = workspace_root
|
||||
self._skills: dict[str, Skill] = {}
|
||||
self._trigger_map: dict[str, str] = {} # trigger -> skill name
|
||||
self._scan()
|
||||
|
||||
def _scan(self) -> None:
|
||||
"""Scan configured directories for .md skill files."""
|
||||
"""Scan configured directories for skill packages and legacy .md files."""
|
||||
for skill_dir in self._config.directories:
|
||||
resolved = (self._workspace / skill_dir) if not skill_dir.is_absolute() else skill_dir
|
||||
if not resolved.is_dir():
|
||||
logger.debug("Skills directory does not exist: %s", resolved)
|
||||
continue
|
||||
for md in sorted(resolved.glob("*.md")):
|
||||
name = md.stem
|
||||
desc = self._extract_description(md)
|
||||
self._skills[name] = Skill(name=name, description=desc, path=md)
|
||||
logger.debug("Discovered skill: %s (%s)", name, desc)
|
||||
|
||||
for entry in sorted(resolved.iterdir()):
|
||||
if entry.is_dir():
|
||||
self._scan_package(entry)
|
||||
elif entry.suffix == ".md":
|
||||
self._scan_legacy(entry)
|
||||
|
||||
def _scan_package(self, pkg_dir: Path) -> None:
|
||||
"""Scan a directory-based skill package containing skill.yaml."""
|
||||
manifest_path = pkg_dir / "skill.yaml"
|
||||
if not manifest_path.exists():
|
||||
logger.debug("Skipping directory without skill.yaml: %s", pkg_dir)
|
||||
return
|
||||
|
||||
try:
|
||||
raw = yaml.safe_load(manifest_path.read_text())
|
||||
manifest = SkillManifest(**raw)
|
||||
except (yaml.YAMLError, ValidationError, TypeError) as e:
|
||||
logger.warning("Failed to parse skill manifest %s: %s", manifest_path, e)
|
||||
return
|
||||
|
||||
skill = Skill(
|
||||
name=manifest.name,
|
||||
description=manifest.description,
|
||||
path=pkg_dir,
|
||||
manifest=manifest,
|
||||
)
|
||||
self._skills[manifest.name] = skill
|
||||
|
||||
# Register triggers
|
||||
for trigger in manifest.triggers:
|
||||
normalized = trigger.lstrip("/").lower()
|
||||
self._trigger_map[normalized] = manifest.name
|
||||
|
||||
logger.debug("Discovered skill package: %s (%s)", manifest.name, manifest.description)
|
||||
|
||||
def _scan_legacy(self, md_path: Path) -> None:
|
||||
"""Scan a legacy flat .md skill file."""
|
||||
name = md_path.stem
|
||||
desc = self._extract_description(md_path)
|
||||
self._skills[name] = Skill(name=name, description=desc, path=md_path)
|
||||
logger.debug("Discovered legacy skill: %s (%s)", name, desc)
|
||||
|
||||
@staticmethod
|
||||
def _extract_description(path: Path) -> str:
|
||||
@@ -55,10 +101,51 @@ class SkillsManager:
|
||||
"""Return all discovered skills."""
|
||||
return list(self._skills.values())
|
||||
|
||||
def get_skill(self, name: str) -> Skill | None:
|
||||
"""Look up a skill by name."""
|
||||
return self._skills.get(name)
|
||||
|
||||
def get_skill_by_trigger(self, trigger: str) -> Skill | None:
|
||||
"""Look up a skill by /command trigger.
|
||||
|
||||
Args:
|
||||
trigger: The trigger string (with or without leading /).
|
||||
|
||||
Returns:
|
||||
The matching Skill, or None.
|
||||
"""
|
||||
normalized = trigger.lstrip("/").lower()
|
||||
skill_name = self._trigger_map.get(normalized)
|
||||
if skill_name:
|
||||
return self._skills.get(skill_name)
|
||||
return None
|
||||
|
||||
def load_skill(self, name: str) -> str | None:
|
||||
"""Load the full content of a skill by name. Returns None if not found."""
|
||||
"""Load the full content of a skill by name.
|
||||
|
||||
For package skills, concatenates all prompt .md files.
|
||||
For legacy skills, returns the .md file content.
|
||||
|
||||
Returns:
|
||||
Concatenated prompt content, or None if not found.
|
||||
"""
|
||||
skill = self._skills.get(name)
|
||||
return skill.path.read_text() if skill else None
|
||||
if skill is None:
|
||||
return None
|
||||
|
||||
if skill.manifest is not None:
|
||||
# Package skill: load prompt files
|
||||
parts: list[str] = []
|
||||
for prompt_file in skill.manifest.prompts:
|
||||
prompt_path = skill.path / prompt_file
|
||||
if prompt_path.exists():
|
||||
parts.append(prompt_path.read_text())
|
||||
else:
|
||||
logger.warning("Prompt file not found: %s", prompt_path)
|
||||
return "\n\n".join(parts) if parts else None
|
||||
else:
|
||||
# Legacy flat file
|
||||
return skill.path.read_text()
|
||||
|
||||
def get_system_prompt_snippet(self) -> str:
|
||||
"""Generate a snippet for the system prompt listing available skills."""
|
||||
@@ -66,6 +153,10 @@ class SkillsManager:
|
||||
return ""
|
||||
lines = ["\nAvailable skills (invoke with /skill-name):"]
|
||||
for s in self._skills.values():
|
||||
lines.append(f" - /{s.name}: {s.description}")
|
||||
if s.manifest and s.manifest.triggers:
|
||||
trigger_str = ", ".join(s.manifest.triggers)
|
||||
lines.append(f" - {trigger_str}: {s.description}")
|
||||
else:
|
||||
lines.append(f" - /{s.name}: {s.description}")
|
||||
lines.append("To use a skill's full instructions, call the load_skill tool.")
|
||||
return "\n".join(lines)
|
||||
|
||||
Reference in New Issue
Block a user