Add foundry-hosted-agent-copilotkit skill + Forgewright App Builder agent

[lordlinus]

What this adds

A skill and a companion agent for building a complete agentic web app on the Azure AI Foundry hosted-agent + AG-UI + CopilotKit stack — a Next.js/CopilotKit v2 chat UI over a light FastAPI/AG-UI bridge that forwards every turn to ONE Microsoft Agent Framework agent hosted in Azure AI Foundry, with native human-in-the-loop (HITL) approval on consequential tools.

Type	Path
Skill	skills/foundry-hosted-agent-copilotkit/ (SKILL.md + 4 reference docs)
Agent	agents/foundry-hosted-agent-copilotkit.agent.md ("Forgewright App Builder")

Why it adds value (gap it fills)

This is a specialized, hard-to-discover workflow, not generic coding the model already handles. It encodes live-verified knowledge that frontier models get wrong by default:

• The hosted-agent-first topology (all tools + HITL + history server-side; a light bridge that is not the brain).
• Why the framework-native add_agent_framework_fastapi_endpoint(FoundryAgent) path cannot complete hosted HITL (no client-side mcp_approval_response), and the minimal hand-rolled forwarder that fixes exactly that gap — tracked upstream as microsoft/agent-framework#6652.
• The exact traps: HITL approve-resume 400 "No tool output found" (use FoundryChatClient, not the Responses OpenAIChatClient), the { accepted, steps } HITL contract, CopilotKit v2 catch-all [[...slug]] route + useSingleEndpoint={false}, AG-UI multi-tool snapshot split, and MCR base images to dodge Docker Hub ACR rate-limits.
• A strict Definition of Done (structural + smoke E2E against the real agent + a live browser E2E) so the agent never declares success on an unverified build.

The full runnable template and scaffolding scripts live in the companion repo lordlinus/forgewright; this skill is the focused build recipe + references.

Paid service disclosure

This stack targets Azure AI Foundry (paid). The prerequisite is stated up front in both SKILL.md and the agent. Per CONTRIBUTING, flagging for the paid-services guidance.

Validation

• npm run skill:validate → ✅ foundry-hosted-agent-copilotkit is valid
• npm run build → README tables regenerated (docs/README.skills.md, docs/README.agents.md)
• name matches folder, lowercase-hyphen; description within limits; references < 5 MB
• No secrets, endpoints, or app-specific hard-coding

Opened as draft for review.

[github-actions]

⚠️ This PR targets main, but PRs should target staged.

The main branch is auto-published from staged and should not receive direct PRs.
Please close this PR and re-open it against the staged branch.

You can change the base branch using the Edit button at the top of this PR,
or run: gh pr edit 2090 --base staged

[github-actions]

✅ Base branch is now set correctly.

Removing the prior block because this PR no longer targets main.

[github-actions]

✅ External plugin PR checks passed

• Changed entries detected: 0
• Workflow state label: ready-for-review

Per-plugin quality summary

Plugin	skill-validator	install smoke test	overall	source tree
none	not_run	not_run	not_run	n/a

No changed external plugin entries were detected in this PR.

[github-actions]

🔍 Skill Validator Results

⛔ Findings need attention

Scope	Checked
Skills	1
Agents	1
Total	2

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

Summary

Level	Finding
❌	[agent:Forgewright App Builder] Agent name 'Forgewright App Builder' does not match filename 'foundry-hosted-agent-copilotkit.agent.md' (expected 'Forgewright App Builder.agent.md').
❌	[agent:Forgewright App Builder] Agent name 'Forgewright App Builder' contains invalid characters — must be lowercase alphanumeric and hyphens only.

Full validator output

Found 1 skill(s)
[foundry-hosted-agent-copilotkit] 📊 foundry-hosted-agent-copilotkit: 3,187 BPE tokens [chars/4: 3,132] (standard ~), 15 sections, 3 code blocks
[foundry-hosted-agent-copilotkit]    ⚠  Skill is 3,187 BPE tokens (chars/4 estimate: 3,132) — approaching "comprehensive" range where gains diminish.
[foundry-hosted-agent-copilotkit]    ⚠  No numbered workflow steps — agents follow sequenced procedures more reliably.
Found 1 agent(s)
❌ [agent:Forgewright App Builder] Agent name 'Forgewright App Builder' does not match filename 'foundry-hosted-agent-copilotkit.agent.md' (expected 'Forgewright App Builder.agent.md').
❌ [agent:Forgewright App Builder] Agent name 'Forgewright App Builder' contains invalid characters — must be lowercase alphanumeric and hyphens only.
Validated 1 agent(s)
Agent spec conformance failures — fix the errors above.

Note: The validator returned a non-zero exit code. Please review the findings above before merge.

[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.

[lordlinus]

Re: PR Risk Scan — remaining 🟠 package-exec-command (docs/README.skills.md:31)

This finding is on a pre-existing, unrelated row — the acreadiness-assess skill, whose own description contains npx. It surfaces in this PR only because npm run build regenerated docs/README.skills.md (required by the validate-readme check, which runs git diff --exit-code on skills/** changes, so the generated tables must be committed).

My contributed files (skills/foundry-hosted-agent-copilotkit/**, agents/foundry-hosted-agent-copilotkit.agent.md) contain no npx/package-exec tokens. The two earlier unpinned-version-indicator findings in my reference docs were false positives on >1 tool_calls and have been reworded. Happy to adjust if maintainers prefer a different handling of the regenerated README.

[Copilot]

Pull request overview

Adds a new skill + companion agent to guide building agentic web apps using the Azure AI Foundry hosted-agent + AG-UI + CopilotKit stack, and updates the generated docs indexes to include them.

Changes:

• Introduces skills/foundry-hosted-agent-copilotkit/ with SKILL.md and four reference documents (architecture, patterns, troubleshooting, hosted deploy).
• Adds agents/foundry-hosted-agent-copilotkit.agent.md (“Forgewright” agent) that instructs users to drive work via the new skill.
• Updates docs/README.skills.md and docs/README.agents.md to list the new skill and agent.

Reviewed changes

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

Show a summary per file

File	Description
skills/foundry-hosted-agent-copilotkit/SKILL.md	Adds the new skill definition and its main workflow/DoD guidance.
skills/foundry-hosted-agent-copilotkit/references/architecture.md	Documents the hosted-agent-first architecture and why a HITL-forwarding bridge is required.
skills/foundry-hosted-agent-copilotkit/references/patterns-7.md	Summarizes AG-UI “dojo” patterns as applied to this stack.
skills/foundry-hosted-agent-copilotkit/references/troubleshooting.md	Captures known failure modes and fixes for HITL/AG-UI/CopilotKit/Foundry.
skills/foundry-hosted-agent-copilotkit/references/hosted-deploy.md	Documents azd-based hosted agent publishing and deployment gotchas.
agents/foundry-hosted-agent-copilotkit.agent.md	Adds the companion agent that directs usage through the skill and enforces the workflow.
docs/README.skills.md	Registers the new skill in the skills index table.
docs/README.agents.md	Registers the new agent in the agents index table.