Add foundry-hosted-agent-copilotkit skill

[lordlinus]

Summary

Adds skills/foundry-hosted-agent-copilotkit — a skill for ongoing development inside existing apps built on the CopilotKit + AG-UI + Microsoft Agent Framework + Azure AI Foundry hosted agents stack.

Where the model uplift is

This stack is genuinely under-represented in training data: every layer is pre-1.0/RC/preview (@ag-ui/* 0.0.x, agent-framework-ag-ui RC, Foundry hosting packages alpha, hosted agents in preview) and APIs have churned recently (useCopilotAction → useFrontendTool/useHumanInTheLoop, agent-framework-azure-ai → agent-framework-foundry). The content is built from live-verified failure modes, including:

• The architecture decision that drives everything: a deployed Foundry hosted agent endpoint speaks OpenAI Responses / invocations, not AG-UI — and the three viable wirings with their trade-offs.
• A safety-relevant HITL hazard: approval-gated tools silently re-executing on a later unrelated turn via previous_response_id chaining (Python: [Bug]: Approval-gated tool (confirm_changes flow) re-executes a second time on a later unrelated turn — duplicate side effect, not just a UI display issue microsoft/agent-framework#6851 / #6828, isolated by reproducing against the bare /responses endpoint), plus the mitigation and the regression test to keep.
• HITL approvals that resolve locally and never reach a remote agent (Python: [Feature]: AG-UI agent adapter should forward HITL approval to a hosted/remote FoundryAgent (mcp_approval_response) instead of executing locally microsoft/agent-framework#6652).
• Symptom → root-cause → fix tables with exact error strings (tenant-mismatch 403s that mimic missing RBAC, token audience 401s, orphaned-tool-call 400s, protocol-version fast-fails, the fetch Illegal invocation crash, frontend-tool forwarding regressions in CopilotKit 1.62.x).
• Upgrade discipline for a multi-package pre-1.0 matrix: version relationship rules and a workaround↔upstream-issue ledger so fixes get removed when upstream ships, not before.

Checklist

• npm run skill:validate passes (369 skills valid)
• npm start run; regenerated docs/README.skills.md committed
• bash eng/fix-line-endings.sh run
• SKILL.md 100 lines (~2.3k tokens), numbered workflow steps, all 6 reference files linked from SKILL.md (no orphans), description single-quoted
• Uses a paid service (Azure AI Foundry) — disclosed per the paid-services guidance; CopilotKit/AG-UI/Agent Framework layers are open source

[github-actions]

🔒 PR Risk Scan Results

Scanned 8 changed file(s).

Severity	Count
🔴 High	0
🟠 Medium	1
ℹ️ Info	0

Severity	Rule	File	Line	Match
🟠	package-exec-command	docs/README.skills.md	31	| [acreadiness-assess](../skills/acreadiness-assess/SKILL.md)<br />`gh skills install github/awesome-copilot acreadiness-assess` | Run the AgentRC readiness assessment on the curre

This is an automated soft-gate report. Findings indicate review targets and do not block merge by themselves.

[github-actions]

🔍 Vally Lint Results

✅ All checks passed

Scope	Checked
Skills	1
Agents	0
Total	1

Severity	Count
❌ Errors	0
⚠️ Warnings	0
ℹ️ Advisories	0

Summary

Level	Finding
ℹ️	npm warn EBADENGINE Unsupported engine {
ℹ️	npm warn EBADENGINE package: 'commander@15.0.0',
ℹ️	npm warn EBADENGINE required: { node: '>=22.12.0' },
ℹ️	npm warn EBADENGINE current: { node: 'v20.20.2', npm: '10.8.2' }
ℹ️	npm warn EBADENGINE }
ℹ️	npm warn deprecated prebuild-install@7.1.3: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.
ℹ️	✅ foundry-hosted-agent-copilotkit (2/2 checks passed)
ℹ️	✓ [spec-compliance] All 1 skill(s) are spec-compliant.
ℹ️	✓ spec-compliance: All spec checks passed.
ℹ️	✓ [valid-refs] All file references across 1 skill(s) are valid.

Full linter output

### Linting skills/foundry-hosted-agent-copilotkit
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: 'commander@15.0.0',
npm warn EBADENGINE   required: { node: '>=22.12.0' },
npm warn EBADENGINE   current: { node: 'v20.20.2', npm: '10.8.2' }
npm warn EBADENGINE }
npm warn deprecated prebuild-install@7.1.3: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.
✅ foundry-hosted-agent-copilotkit (2/2 checks passed)
    ✓ [spec-compliance] All 1 skill(s) are spec-compliant.
        ✓ spec-compliance: All spec checks passed.
    ✓ [valid-refs] All file references across 1 skill(s) are valid.
        ✓ valid-refs: All file references resolve to existing files within the skill directory.

1 skill(s) linted, 1 passed

[Copilot]

Pull request overview

Adds a new Agent Skill, foundry-hosted-agent-copilotkit, providing structured, reference-driven guidance for maintaining and evolving existing CopilotKit + AG-UI applications backed by Microsoft Agent Framework agents running on (or developed against) Azure AI Foundry hosted agents.

Changes:

• Introduces a new skill entrypoint (SKILL.md) with a workflow-oriented “mental model”, task playbooks, and completion criteria focused on correctness/safety (notably HITL).
• Adds six focused reference documents covering architecture options, HITL behavior/hazards, troubleshooting signatures, upgrade rules, interaction patterns, and the local→deploy iteration loop.
• Updates docs/README.skills.md to include the new skill and its reference files.

Reviewed changes

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

Show a summary per file

File	Description
skills/foundry-hosted-agent-copilotkit/SKILL.md	Defines the skill’s scope, workflow, and pointers into the reference set for ongoing app development.
skills/foundry-hosted-agent-copilotkit/references/architecture.md	Documents the three viable architectures and where AG-UI is produced, establishing the key integration decision.
skills/foundry-hosted-agent-copilotkit/references/deploy-loop.md	Captures the recommended inner/outer dev loop for hosted agents (azd ai agent run / deploy + verification).
skills/foundry-hosted-agent-copilotkit/references/hitl.md	Details HITL wiring and debugging, including the duplicate-execution hazard and mitigation/regression test guidance.
skills/foundry-hosted-agent-copilotkit/references/patterns.md	Maps the “7 AG-UI interaction patterns” to CopilotKit + MAF implementation points and caveats.
skills/foundry-hosted-agent-copilotkit/references/troubleshooting.md	Provides symptom→root-cause→fix tables across layers with concrete signatures and remediation.
skills/foundry-hosted-agent-copilotkit/references/upgrading.md	Defines upgrade constraints and a verification loop tailored to a rapidly-churning pre-1.0 dependency matrix.
docs/README.skills.md	Registers the new skill in the generated skills index, including its reference files list.