Portable Agent Workflows via User-Installed Skills And Repo Seam

Date: 2026-06-18 Status: approved direction, updated 2026-06-21

Problem

The pr-batch family and related agent workflows are useful across ShakaCode repos, but repo-local copies can mix reusable process with repo-specific commands, labels, release policy, paths, and domain examples. We want agents to carry these workflows across repos without copying a stale .agents/ tree into every repository or making each repo responsible for shared workflow updates.

Goal

Make shared skills portable by installing them in the user or agent environment, then make each repo expose a small, validated AGENTS.md seam that supplies the repo-specific values the portable skills need.

Architecture

text

shakacode/agent-workflows
  skills/... and workflows/...        portable process, installed per user/agent
  bin/...                             install, status, upgrade, and validation helpers

consumer repo
  AGENTS.md                           canonical policy plus Agent Workflow Configuration seam
  .agents/bin/agent-workflow-seam-doctor
                                      optional local checker copy for the seam contract
  .agents/skills/...                  repo-specific skills or explicit overrides
  .agents/workflows/...               repo-local workflow files only when the repo needs them

The default distribution path is this repository plus the user's normal skill installation mechanism. For example, an agent may install the shared pr-batch, verify, address-review, and changelog skills once into Codex or Claude and use them in any repo. The skill then reads the target repo's AGENTS.md seam to resolve concrete commands and policy.

Repository-pinned shared skill copies remain an optional escape hatch for environments that need exact workflow text in the checkout, such as cloud agents that cannot use a user skill install. They are not the default design; in this repo, keeping shared copies would duplicate installed Codex picker entries and should be justified by a specific reproducibility or execution-environment need.

The Seam

Each adopting repo owns a section named ## Agent Workflow Configuration in AGENTS.md. Shared skills may refer to these values by name:

base branch
local validation command
CI change detector
hosted-CI trigger and labels
CI parity environment, runner image, reproduction guide, and secret redaction patterns
benchmark labels
follow-up issue prefix
changelog path, policy, and entry format
lint, format, build, type, docs, and test commands
merge ledger
review gate
optional default simplify model, when the repo wants /simplify to pin one
approval-exempt change categories
coordination backend

The seam is deliberately human-readable because AGENTS.md is already the repo's canonical agent policy. Add a structured config file only when a non-LLM script needs to consume the values mechanically.

Seam Doctor

agent-workflow-seam-doctor checks the boundary between portable skills and the repo:

verifies that AGENTS.md has the required seam keys
fails on unresolved template values in the seam
scans repo-local and explicitly supplied installed shared skill/workflow Markdown for executable snippets that still contain unresolved seam placeholders such as <follow-up prefix>

It does not reject ordinary command parameters such as <PR> or <sha>. Those are task inputs, not repo-seam values.

Why Not Subtree First

git subtree solves "every repo has a pinned copy of the shared files," but that is not the primary problem. The primary problem is whether a portable skill can safely resolve repo-specific behavior. A subtree also makes the .agents/ prefix all-or-nothing, which is awkward when a repo has real local skills such as destructive framework stress tests or product-specific release helpers.

Use a repository-pinned copy only when the execution environment cannot depend on user-installed shared skills or when the repo intentionally wants to review shared workflow updates like source code. Otherwise, install shakacode/agent-workflows once for the user/agent and validate each repo's seam.

Shared Vs Repo-Local

Shared skills should contain portable procedure and safety rules:

issue and PR batching
PR processing
review comment triage
verification
changelog updates
post-merge and adversarial audits
CI routing helpers

Shared skill installation must include each skill's bin/ helpers with its SKILL.md, and workflow text should call helpers relative to the installed skill directory or through a repo-local helper copy. A repo that can load installed skill Markdown but cannot execute installed helper scripts should pin the helper scripts locally without adding duplicate shared SKILL.md files.

Repo-local content should contain concrete policy and domain knowledge:

AGENTS.md
repo-specific destructive or domain-heavy skills
local scripts such as seam validators or pinned helper copies
compatibility copies only when a tool cannot load installed skills

Phasing

Consumer seam PRs: add the target repo seam, genericize local shared workflow copies to resolve values through that seam, add or reference agent-workflow-seam-doctor, and point adoption docs at this repository.
Shared pack: publish shakacode/agent-workflows, install it in the agent surfaces ShakaCode uses, and run bin/validate before updates. Use agent-workflows-status and upgrade-agent-workflows for ongoing installed pack maintenance.
Consumer repos: install or enable the shared skills for the user/agent, add the repo seam, run the seam doctor, and dry-run one workflow.
Optional pinning: revisit repository-pinned copies only for repos or agents that cannot rely on the user-installed skill pack.

Validation

Run from the shakacode/agent-workflows shared pack root:

bin/validate
ruby bin/agent-workflow-seam-doctor-test.rb
bash bin/install-agent-workflows-test.bash

Run from a consumer repository:

bin/agent-workflow-seam-doctor --root <consumer-repo> --shared <this-repo>
Markdown format and link checks for edited documentation
a dry run of one shared workflow against the repo seam