persona-kit: add local skill source provider

[khaliqgant]

Summary

• Adds a local skill source provider that accepts repo-relative or absolute paths to a .md SKILL file (e.g. .agentworkforce/workforce/skills/essay-authoring.md), alongside the existing prpm and skill.sh sources.
• Threads a repoRoot option through materializeSkills, buildInstallArtifacts, useSelection, and the CLI so relative local sources can be absoluteified before the install command runs — keeps cd <installRoot> && cp <source> … working in session mode.
• Registers the local provider first in the resolver chain. Its narrow .md-suffix test claims path-shaped sources before prpm's bare <scope>/<name> regex sees them; a coreyhaines31/marketingskills-style ref still routes to prpm, a ./skills/foo.md ref routes to local.

Motivation

Personas hosted in the same repo as their authoring patterns currently have no way to reference a sibling skill.md without first publishing it to GitHub or prpm. agentworkforce agent <persona> fails with Unsupported skill source: .agentworkforce/workforce/skills/<name>.md. Adds the missing source form so workforce-local skills don't require an extra remote-publish step.

Test plan

• pnpm --filter @agentworkforce/persona-kit run test — 127/127 pass (8 new local-source tests).
• pnpm --filter @agentworkforce/workload-router run test — 15/15 pass.
• pnpm --filter @agentworkforce/cli run test — 147/147 pass.
• pnpm -r typecheck on persona-kit + workload-router + cli — clean.
• Manual: run agentworkforce agent <persona> against a persona declaring a local/<name> skill with a .agentworkforce/...md source and confirm the SKILL.md is installed at <installRoot>/.claude/skills/<name>/SKILL.md.

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d5c6308-fb2c-46fb-80df-c9969a0f5fe6

📥 Commits

Reviewing files that changed from the base of the PR and between a5e8df9 and 10d6780.

📒 Files selected for processing (6)

• packages/cli/src/cli.ts
• packages/persona-kit/src/constants.ts
• packages/persona-kit/src/index.test.ts
• packages/persona-kit/src/skills.ts
• packages/persona-kit/src/types.ts
• packages/workload-router/src/index.ts

---

📝 Walkthrough

Walkthrough

This PR extends the skill materialization system to support repository-local .md file sources by threading a new repoRoot parameter through the persona-kit, workload-router, and CLI layers, enabling local relative paths to be resolved into absolute filesystem paths within install commands.

Changes

Local Skill Source Support

Layer / File(s)	Summary
Type Contracts packages/persona-kit/src/types.ts	SkillMaterializationOptions and SkillMaterializationPlan each gain an optional repoRoot?: string field to carry the repo filesystem root for resolving local skill sources.
Source Kind Registration packages/persona-kit/src/constants.ts	SKILL_SOURCE_KINDS now includes 'local' as a recognized skill source type.
Provider Interface packages/persona-kit/src/skills.ts	SkillProvider.buildInstallCommand now accepts an optional BuildInstallContext parameter, allowing providers to access repoRoot and other resolution context.
Local Provider Implementation packages/persona-kit/src/skills.ts	New local provider parses .md file paths, derives installed skill names (with special handling for SKILL.md), resolves relative paths against repoRoot, generates sh -c 'mkdir && cp' shell commands, and is prepended to the provider list to take precedence.
Skill Materialization Core packages/persona-kit/src/skills.ts	materializeSkills extracts repoRoot from options, builds a provider context, passes it into each provider's command builder, and includes repoRoot in the returned SkillMaterializationPlan; buildInstallArtifacts session mode also forwards repoRoot during artifact generation.
Router Integration packages/workload-router/src/index.ts	usePersona and useSelection option types gain optional repoRoot?: string fields; usePersona forwards repoRoot to useSelection, which conditionally includes it in SkillMaterializationOptions.
CLI Integration packages/cli/src/cli.ts	buildInstallContext, dry-run flow, and interactive run flow now explicitly supply repoRoot: process.cwd() to anchor local skill source resolution to the real repository.
Tests and Validation packages/persona-kit/src/index.test.ts	Comprehensive test suite covering local skill installation, path normalization (relative/absolute), SKILL.md directory naming, repoRoot-based path absolutization, session mode behavior, regression test for prpm non-shadowing, and .md suffix validation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• AgentWorkforce/relay#824: Aligns with extending materializeSkills and its CLI/router callers to support local skill source parsing and install-plan building.

Possibly related PRs

• AgentWorkforce/workforce#78: Modifies CLI's use of materializeSkills and buildInstallContext plumbing, directly related to the repoRoot threading in this PR.
• AgentWorkforce/workforce#74: Modifies persona-kit skill materialization surface and plan-builder/execute code paths that call materializeSkills.
• AgentWorkforce/workforce#73: Changes persona-kit skill materialization (constants, types, skills) and router/CLI wiring, extended by this PR's local source and repoRoot work.

Poem

🐰 A local skill in every .md,
Paths resolved with perfect care,
Through repo root we safely thread,
Install commands prepared with flair!
The rabbit's feast of fixtures bright,
Makes skill materialization just right. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'persona-kit: add local skill source provider' directly and clearly summarizes the main change: adding support for local skill sources in the persona-kit package.
Description check	✅ Passed	The description is well-structured and directly related to the changeset, covering the new local skill source provider feature, implementation details, motivation, and test results.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/local-skill-source

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.

[willwashburn]

Nice, good call!