feat(skills): repo-scoped procedural memory loaded into agent prompt

[corylanou]

Context

Today every Codex session that Symphony dispatches starts cold — no recall of how this repo solves common task patterns. Maintainers solve the same shape of problem repeatedly (add a migration, wire a new endpoint, fix a flaky test in package X) and that knowledge lives only in human memory or scattered docs.

This issue adds a skills system: repo-scoped reusable procedural recipes that get loaded into the agent's system prompt before each dispatch. Layout is intentionally compatible with the agentskills.io open standard so skills authored for one agent ecosystem work in another.

Scope: human-authored skills only in this issue. Agent-authored skills (the agent writes its own skill on successful completion) is a follow-up.

Design

File layout

Per-repo skills live under the repo's .symphony/skills/ directory:

.symphony/
  config.yaml                    # existing per-repo config (already shipped)
  skills/
    add-migration/
      SKILL.md                   # the recipe (markdown, front-matter optional)
    wire-graphql-field/
      SKILL.md
    fix-flake-pattern-x/
      SKILL.md

Skills are checked into git alongside code so they version with the repo and code review applies.

SKILL.md format (agentskills.io-compatible)

---
name: add-migration
description: Add an Ecto migration with the project's standard naming + safety checks.
when_to_use: Issue mentions schema change, new table, new column, or "migration".
---
# Add migration

Steps the agent should follow...

The front matter is small and stable: name, description, when_to_use (a one-liner that helps the agent decide if this skill applies). Body is free-form markdown.

Loading & prompt injection

• On agent dispatch, the loader walks .symphony/skills/*/SKILL.md in the workspace, validates front matter, and produces a [name, description, when_to_use, body_path] index.
• The index is summarized into a ## Available skills block in the system prompt envelope. Each skill is listed as name — when_to_use. The agent decides which to read and reads bodies on demand via the existing file-read tool — bodies are not preloaded (keeps the prompt small even with many skills).
• Validation errors on skills (missing front matter, duplicate name, unparseable YAML) post a tracker comment on the issue being worked on but do not block dispatch — the agent just gets a smaller skill set.

Config schema

Add to WORKFLOW.md:

agent:
  skills:
    enabled: true                        # default on once shipped
    path: ".symphony/skills"             # relative to workspace root
    max_skills_in_prompt: 50             # safety cap for very large repos

Files to touch

• lib/symphony_elixir/skills/loader.ex — new module. Walks the skills dir, parses front matter, returns {:ok, [%Skill{}]} or {:error, [%ValidationError{}]}.
• lib/symphony_elixir/agent_runner.ex — call the loader before dispatch; inject the ## Available skills block into the system prompt envelope.
• lib/symphony_elixir/config/schema.ex — add agent.skills block + validations.
• test/symphony_elixir/skills/loader_test.exs — new test module.
• test/symphony_elixir/agent_runner_skills_test.exs — integration: skills index appears in the assembled prompt; bad SKILL.md surfaces an error comment.
• README / docs — explain the layout, the agentskills.io compat, and authoring guidance.

Acceptance

• A repo with no .symphony/skills/ directory dispatches exactly like today (zero behavior change when skills enabled).
• A repo with three well-formed SKILL.md files surfaces all three in the agent prompt's ## Available skills block (name + when_to_use only).
• A repo with one malformed SKILL.md (e.g. missing name) still dispatches, the valid skills appear, and a comment is posted on the issue noting the malformed file by path.
• agent.skills.enabled: false skips the loader entirely (no walk, no prompt injection).
• max_skills_in_prompt: 2 with three skills caps to two and logs which was dropped.

Why agentskills.io shape, not invented-here

Hermes (Nous Research) and a handful of other agent projects are converging on the agentskills.io front-matter shape. Matching it means a skill written for Symphony can be tried in another agent and vice versa, and we don't need to teach users a Symphony-specific format.

Test plan

• make -C elixir all clean.
• Loader unit tests cover: empty dir, well-formed, missing front matter, duplicate name, oversized count.
• Agent-runner integration test asserts the assembled prompt contains the ## Available skills block when skills exist.
• Dogfood: author one real skill for this repo (e.g. "add a new tracker adapter"), confirm Codex picks it up on a relevant issue.

[corylanou]

Codex Workpad

Corys-Mac-Studio.local:/Users/corylanou/code/symphony-workspaces/digitaldrywood_symphony_87@a457c25

Plan

• Verify worktree isolation, branch, and project-specific instructions.
• Move project item from Todo to In Progress.
• Fetch latest origin/main and confirm branch base.
• Re-read issue/PR context, existing implementation, comments, and CI state.
• Rebase PR feat(skills): load repo scoped skills #90 onto current origin/main and resolve conflicts with new budget/lessons config.
• Complete implementation and verification work.
• Run focused tests.
• Run make all from elixir/.
• Commit, push, update PR feat(skills): load repo scoped skills #90, mark ready, and verify CI.
• Move issue to Human Review after the full pre-review gate passed.
• Merge gate: rebase PR feat(skills): load repo scoped skills #90 onto current origin/main from Merging.
• Merge gate: run make all from elixir/ after the final rebase.
• Merge gate: push the rebased branch and watch CI.
• Merge gate: confirm reviews/checks are merge-ready, squash merge, and move issue to Done.

Acceptance Criteria

• Missing .symphony/skills/ keeps dispatch behavior unchanged.
• Valid SKILL.md files surface in a ## Available skills prompt block with name and when_to_use only.
• Malformed SKILL.md files do not block dispatch and are reported on the issue by path.
• agent.skills.enabled: false skips skill discovery and prompt injection.
• max_skills_in_prompt caps prompt entries and logs dropped skills.
• SSH worker dispatches discover skills from the worker workspace path.

Validation

• Focused tests passed: mix test test/symphony_elixir/core_test.exs test/symphony_elixir/lessons_test.exs test/symphony_elixir/agent_runner_skills_test.exs test/symphony_elixir/skills/loader_test.exs with 86 tests, 0 failures.
• make -C elixir all passed after latest pre-review rebase: build, format check, lint, coverage with 666 tests, 0 failures, 2 skipped, 100% total coverage, and dialyzer with 0 errors.
• Merge gate make all passed after final rebase on 2026-05-22: build, format check, lint, coverage with 666 tests, 0 failures, 2 skipped, 100% total coverage, and dialyzer with 0 errors.
• PR body validated with mix pr_body.check --file /tmp/symphony_pr_90_body.md.
• PR feat(skills): load repo scoped skills #90 is open, not draft, references Fixes #87, and is mergeable/clean.
• Latest GitHub checks passed on a457c25: elixir-ci, make-all, and validate-pr-description.
• Merge gate CI watch passed on 2026-05-22: gh pr checks 90 --watch returned all checks passing.
• Review-thread sweep complete: thread PRRT_kwDOSQRuvs6EIHPh is resolved and outdated; no unresolved actionable review threads remain.
• Reviewer state check complete: no open CHANGES_REQUESTED; no pending bot review in flight; prior Codex review was comment-only on old commit 5f617f3 and its thread is resolved/outdated.

Notes

• Worktree isolation checked: current branch symphony/digitaldrywood_symphony_87; git common dir /Users/corylanou/projects/digitaldrywood/symphony/.git; elixir/_build, elixir/deps, and elixir/cover are ordinary directories inside this worktree.
• Rebase gate checked on 2026-05-22: branch is already based on current origin/main at 6dd15cf.
• Push gate checked on 2026-05-22: branch was already up to date on origin.
• PR feat(skills): load repo scoped skills #90: feat(skills): load repo scoped skills #90
• Merge flow started from project Status Merging on 2026-05-22.

Blockers

• None.