feat(skills): accept paths, validate SKILL.md, and bound eager injection (#350)

[jrob5756]

Closes #350.

What this does

#215 shipped the skills mechanism with a one-entry registry. skills: accepted exactly one hardcoded name and get_skill_directory raised for anything else, even though the underlying plumbing already took arbitrary paths. This generalizes it and fixes two silent-failure modes found along the way.

Four of the five deliverables in the issue. Discovery is deliberately deferred — see below.

1. skills: accepts filesystem paths

workflow:
  runtime:
    skills:
      - conductor                     # built-in, ships in the wheel
      - ./team-skills/acme-widgets    # versioned next to the workflow
      - ~/scratch/skills              # a skills root — expands to every child

• Classification is syntactic — path when it starts with ~/. or contains a separator, otherwise a built-in name. So a bare conductor can never be shadowed by a same-named local directory, and resolution never depends on what happens to exist locally.
• Either granularity — a skill directory (holds SKILL.md) or a root of them, expanding to every immediate child holding one (not recursive).
• Relative paths resolve against the workflow file's directory, the same rule working_dir uses, so a workflow behaves identically from any cwd. normpath, not resolve(), so symlink aliases stay distinct.
• Conductor expands roots itself rather than passing them through, because eager injection needs a name per skill and claude-agent-sdk needs a <plugin>:<skill> name. Doing it centrally keeps every provider seeing the same set.
• No extra trust gate. The same YAML can already declare type: script running arbitrary shell, so a skill path grants strictly less. Documented as trusted input.

AgentDef.validate_skills still checks bare names eagerly at load time (they need no base directory), so error timing for the common typo case does not regress. Only paths defer.

2. A malformed SKILL.md no longer fails silently

Both the Copilot CLI and Claude Code skip an unparseable skill without a word. The trap is ordinary and cost the issue author several debugging rounds:

description: Internal ACME conventions. Triggers: widget, acme widget.
#                                               ^ invalid YAML

New skills/frontmatter.py parses it with ruamel.yaml (the project's YAML library — PyYAML is not a dependency), requires a non-empty name and description, and reports the underlying error with the description: | fix spelled out.

Enforced inside resolve_skills, not only in the static validator, because conductor run never calls validate_workflow_config.

3. runtime.skill_injection bounds eager injection

Providers without a native skill surface have no progressive disclosure: AgentExecutor prepends each skill's SKILL.md plus its entire references/ tree on every call, every retry, and every validator: call — previously with no ceiling at all. The bundled conductor skill alone is 117,375 bytes (~29K tokens).

runtime:
  skill_injection:
    warn_bytes: 65536      # default 64KB; null disables
    max_bytes: 131072      # default 128KB; null disables

Enforced both at runtime and statically in conductor validate, measured against the exact string prepended, reported with a per-skill breakdown naming the offender. The defaults deliberately straddle the bundled skill so skills: [conductor] on claude — which works today — warns rather than breaking. A warn_bytes above max_bytes is rejected as unreachable. Native providers are exempt.

4. hermes declares skills=True

It omitted the field, defaulting to False, so the validator rejected skills: on it — while its own execute() docstring described eager injection working. Injection happens upstream in AgentExecutor, so the path was always reachable and the declaration was just inaccurate. Per AGENTS.md ("declare False only when neither path can work"), True is correct. Now bounded by the budget above.

Also: claude-agent-sdk refuses non-plugin skills at validate time

That SDK exposes no bare skill-directory option — only plugin roots plus skill names (verified against the installed package; the only relevant options are plugins, skills, setting_sources, add_dirs, agents). A path skill outside a Claude Code plugin is therefore unreachable there, though copilot loads the identical skill fine. It previously surfaced as a runtime ProviderError; it now fails before the run starts, naming the directory and both remedies.

Judgement call worth flagging: synthesizing a temporary plugin root would make the headline "team skill in the repo" use case work on that provider too. I chose not to — it stacks a second unverified CLI assumption on top of #352's unverified qualified-name assumption. Consequence: that use case is copilot-only for now (the default provider).

Not included: discovery

The issue's own "Update" section argues the discover_skills design does not generalize — Copilot discovers from ~/.copilot/…, Claude Code from ~/.claude/…, so one boolean would surface different skill sets to different agents inside the same run. Split out as #362, which carries the rationale, the measured 253KB/63K-token cost, and the enable_config_discovery warning.

Verification

• 4732 passed / 37 skipped in CI's exact environment (uv sync --group dev, no extras); 4897 / 24 with the claude-agent-sdk extra.
• make check clean, make validate-examples exit 0.
• Six mutation tests confirm the new tests fail when the feature is broken: engine drops workflow_dir; engine drops skill_injection; resolution skips frontmatter validation; executor skips the budget; hermes reverts to skills=False; validator skips the plugin check.
  • One initially escaped — the engine dropping workflow_dir — because tests that build an AgentExecutor directly hand it that argument themselves. That gap is why tests/test_skills/test_engine_integration.py exists.
• Reviewed by an independent code-review agent: no significant issues. Two things it surfaced and I fixed:
  • The bundled skill measures 117,375 bytes, not the 113,279 I had quoted throughout — it grew because this PR edits its own references/ docs. Prose corrected; the real invariant (warn < size < max) is now pinned by a test rather than by prose that rots.
  • Python 3.12 re-raises EACCES from Path.is_file(), so an unreadable skill directory leaked a bare PermissionError. _resolve_path_entry now catches OSError around the whole probe.

Docs

docs/workflow-syntax.md gains its first Skills section (it had zero mentions). Also updated: AGENTS.md, CHANGELOG.md, docs/providers/comparison.md, the example workflow, and the bundled skill's own authoring.md / yaml-schema.md — including a stale "mcp_servers ignored by claude-agent-sdk" line that #335 had already made false.