Define skill model and add discovery from .agentd/skills/

[geoffjay]

Context

Part of #1208 (custom agent skills). Agents running in agentd currently have no way to receive project-level or agent-specific skills. Claude Code discovers skills from .claude/skills/ in the working directory, but there is no agentd-managed skill layer.

This is the foundation issue: define what an agentd skill looks like and implement discovery from a .agentd/skills/ directory.

Background

The project already has 16 skills in .claude/skills/ (agent-ops, git-spice, service-ops, etc.). These are Claude Code skills - markdown files with YAML frontmatter containing name, description, and optional trigger metadata. Example structure:

.claude/skills/agent-ops/SKILL.md
.claude/skills/git-spice/SKILL.md
.claude/skills/service-ops/SKILL.md

Each file has frontmatter like:

---
name: agent-ops
description: Create, monitor, message, and debug agents via the CLI.
---

# Agent Operations
...markdown content...

What to Build

1. Skill Model

Add a Skill struct (likely in crates/orchestrator/src/types.rs or a new crates/orchestrator/src/skills.rs module):

/// A discoverable skill that can be assigned to agents.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Skill {
    /// Skill name (directory name or filename stem).
    pub name: String,
    /// Human-readable description from frontmatter.
    pub description: Option<String>,
    /// Full markdown content (including frontmatter).
    pub content: String,
    /// Filesystem path where the skill was discovered.
    pub source_path: PathBuf,
}

2. Skill Discovery

Implement a function that scans a directory for skills:

/// Discover skills from a directory.
///
/// Supports two layouts (matching Claude Code conventions):
/// - `skills_dir/<name>/SKILL.md`
/// - `skills_dir/<name>.md`
pub fn discover_skills(skills_dir: &Path) -> Result<Vec<Skill>>

3. Discovery Paths

Skills should be discoverable from multiple locations with precedence:

1. .agentd/skills/ (project-level, primary)
2. ~/.config/agentd/skills/ (user-level, fallback)

4. API Endpoint

Add a GET /skills endpoint to the orchestrator that returns discovered skills:

[
  {
    "name": "git-spice",
    "description": "Branch stacking and PR management...",
    "source_path": ".agentd/skills/git-spice/SKILL.md"
  }
]

Acceptance Criteria

• Skill struct defined with name, description, content, source_path
• discover_skills() function scans a directory for SKILL.md files
• Supports both <name>/SKILL.md and <name>.md layouts
• Parses YAML frontmatter to extract name and description
• GET /skills endpoint on orchestrator returns discovered skills
• Unit tests for discovery (empty dir, single skill, multiple skills, malformed files)

Relevant Files

• crates/orchestrator/src/skills.rs - new module (primary deliverable)
• crates/orchestrator/src/types.rs - Skill struct (or in skills.rs)
• crates/orchestrator/src/api.rs - add GET /skills route
• crates/orchestrator/src/lib.rs - add pub mod skills;
• .agentd/skills/ - new directory (created in a later issue)

Stack Base

Stack on: feature/autonomous-pipeline
Parallel: no ordering constraint (this is the foundation issue)

References

• Parent plan: Plan: support custom agent skills #1208
• Existing skills in .claude/skills/ for format reference

[geoffjay]

✅ Triage Complete

Field	Value
Type	enhancement
Complexity	large
Milestone	v0.6.1 (already set)
Labels	enhancement, architecture, needs-tests, complexity:large, triaged

Foundation issue for the #1208 skills epic — architecture label correctly pre-applied. New crates/orchestrator/src/skills.rs module: Skill struct + discover_skills() with two-layout support (<name>/SKILL.md and <name>.md), YAML frontmatter parsing, and multi-path precedence (project-level → user-level). ACs require inline unit tests (empty dir, single skill, multiple skills, malformed files). Plus GET /skills route in api.rs (~25-35 lines) and lib.rs wiring. Implementation ~95-135 lines + tests ~50-80 lines = ~145-215 lines across 3-4 files. Multiple files exceed the medium ceiling; test-inclusive count crosses 200 lines. No ordering constraint — this is the unblocked foundation that #1210, #1211, and #1213 all stack on.