feat(skills): add arc skill for composable workflow orchestration 🤖🤖🤖

[pconnelly-nuance]

Add the arc skill — a declarative orchestration framework that chains existing Copilot skills into reproducible, reviewable development workflows via .arc.yml template files. Arcs can be shared and run by team members with simple prompts like run the bugfix arc on ticket 12345

Includes:

• SKILL.md with full execution lifecycle documentation
• 3 example arcs: feature-flow, bugfix-flow, quick-fix
• 3 reference docs: file-format, expression-syntax, acceptance-criteria

Pull Request Checklist

• I have read and followed the CONTRIBUTING.md guidelines.
• I have read and followed the Guidance for submissions involving paid services.
• My contribution adds a new instruction, prompt, agent, skill, or workflow file in the correct directory.
• The file follows the required naming convention.
• The content is clearly structured and follows the example format.
• I have tested my instructions, prompt, agent, skill, or workflow with GitHub Copilot.
• I have run npm start and verified that README.md is up to date.
• I am targeting the staged branch for this pull request.

---

Description

Arc is a composable orchestration skill that lets teams define multi-step development workflows as declarative .arc.yml templates. Instead of invoking skills one at a time or relying on unpredictable autopilot, you write the choreography once and the AI executes it — with a Terraform-style review gate before anything runs.

Key features:

• Declarative YAML templates with GitHub Actions-style ${{ }} expressions for parameter binding and context flow between steps
• Three execution modes: template (from .arc.yml), ad-hoc (from natural language), and inspect (preview without executing)
• Review gates — human-in-the-loop approval points before proceeding
• Graceful degradation — missing skills are detected at plan time and skipped with warnings, never hard failures at runtime
• Failure policies — per-step on_failure control: pause (default), skip, retry, or abort
• SQL state tracking — arc runs and step statuses tracked in the session database for progress queries

Bundled assets:

• examples/feature-flow.arc.yml — End-to-end feature implementation from issue to PR
• examples/bugfix-flow.arc.yml — Test-first bug fix with review and PR creation
• examples/tdd-cycle.arc.yml — Minimal implement → test → review → commit cycle
• references/file-format.md — Complete YAML schema reference
• references/expression-syntax.md — Expression resolution and namespace docs
• references/acceptance-criteria.md — 8 testable acceptance criteria with correct/incorrect examples

Example:
run tdd arc. add provider name to fields returned by GET /patients/{patient_id}

---

Type of Contribution

• New instruction file.
• New prompt file.
• New agent file.
• New plugin.
• New skill file.
• New agentic workflow.
• Update to existing instruction, prompt, agent, plugin, skill, or workflow.
• Other (please specify):

---

Additional Notes

This skill is language- and framework-agnostic. The example arcs use npm run lint, npm test, gh pr create, and community skills from this repo (git-commit, create-implementation-plan, breakdown-test, doublecheck) so they work across any project type. Teams customize by authoring their own .github/arcs/*.arc.yml files with whatever skills and commands fit their stack.

---

By submitting this pull request, I confirm that my contribution abides by the Code of Conduct and will be licensed under the MIT License.

[github-actions]

🔍 Skill Validator Results

⚠️ Warnings or advisories found

Scope	Checked
Skills	1
Agents	1
Total	2
Severity	Count
---	---:
❌ Errors	0
⚠️ Warnings	1
ℹ️ Advisories	0

Summary

Level	Finding
ℹ️	Found 1 skill(s)
ℹ️	[arc] 📊 arc: 3,007 BPE tokens [chars/4: 3,004] (standard ~), 23 sections, 11 code blocks
ℹ️	[arc] ⚠ Skill is 3,007 BPE tokens (chars/4 estimate: 3,004) — approaching "comprehensive" range where gains diminish.
ℹ️	✅ All checks passed (1 skill(s))

Full validator output

```text Found 1 skill(s) [arc] 📊 arc: 3,007 BPE tokens [chars/4: 3,004] (standard ~), 23 sections, 11 code blocks [arc] ⚠ Skill is 3,007 BPE tokens (chars/4 estimate: 3,004) — approaching "comprehensive" range where gains diminish. ✅ All checks passed (1 skill(s)) ```

[Copilot]

Pull request overview

Adds a new arc skill that documents a declarative “workflow orchestration” format (.arc.yml) for chaining existing Copilot skills/commands with review gates, conditional execution, and failure policies, plus bundled example arcs and reference docs.

Changes:

• Added skills/arc/SKILL.md defining the arc execution lifecycle, modes, trace review gate, and state tracking model.
• Added reference documentation for arc YAML schema, expression syntax, and acceptance criteria.
• Added example arc templates and registered the new skill in docs/README.skills.md.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
skills/arc/SKILL.md	Core skill documentation describing how arcs are discovered, planned (trace), reviewed, and executed
skills/arc/references/file-format.md	YAML schema + validation rules for .arc.yml templates
skills/arc/references/expression-syntax.md	${{ }} expression namespaces and resolution behavior
skills/arc/references/acceptance-criteria.md	Testable requirements and examples for expected skill behavior
skills/arc/examples/feature-flow.arc.yml	Example “feature” arc with params, gate, and multi-step flow
skills/arc/examples/bugfix-flow.arc.yml	Example “bugfix” arc with TDD-ish steps and PR creation
skills/arc/examples/tdd-cycle.arc.yml	Example arc file (currently contains a quick-fix arc)
docs/README.skills.md	Adds the arc entry to the skills index