Repository navigation
Research: External API documentation layer for agent spawns #355
Description
Problem
Squad agents rely on training data when writing code against external libraries and APIs. This can bring hallucinated API shapes, outdated SDK patterns, and incorrect usage. The skill system (.squad/skills/) handles internal project knowledge well, but there's no mechanism for agents to access current, versioned external documentation at work time.
Idea
Add an external documentation layer that complements Squad skills. Two options worth evaluating:
Option A — Integrate context-hub (chub): A community-curated, versioned doc CDN for AI agents. Provides curated API docs in markdown, language variants, incremental fetch, persistent local annotations (cross-session memory), and a feedback loop to maintainers. Already ships a SKILL.md that teaches agents to search/fetch/annotate.
Option B — Build a native Squad equivalent: A .squad/docs/ or skill extension that lets agents fetch, cache, and annotate external API docs. Could leverage the plugin marketplace for distribution and tie into the existing confidence lifecycle.
Why This Matters
| Layer | What it covers | Exists today? |
|---|---|---|
Skills (.squad/skills/) |
Internal project patterns & conventions | Yes |
History (history.md) |
Per-agent learnings (siloed) | Yes |
Decisions (decisions.md) |
Team-level architectural choices | Yes |
| External API docs | Current SDK/library documentation | No |
The gap is the last row. Agents working with any external library are guessing from training data instead of reading current docs.
Research Questions
- Delivery mechanism — Should the coordinator auto-detect dependencies (from
package.json,.csproj, etc.) and inject docs into spawn prompts, or should agents self-serve via a skill? - Context budget — Full API docs can be large. How does this interact with cheaper models that already receive charter + history + decisions?
- Annotation as shared memory — Persistent notes about external APIs (gotchas, workarounds) don't fit neatly into
history.md(per-agent) ordecisions.md(project decisions). Should this become a new knowledge tier? - Distribution — If built natively, the plugin marketplace is a natural fit. If wrapping context-hub, a bundled skill during
squad initwould be the lightest integration.
Minimal Version
Regardless of build-vs-integrate:
- A skill that teaches agents to fetch external docs before writing code against unfamiliar APIs
- A convention for persisting API-specific notes across sessions and agents
- Spawn template guidance: "If the task involves an external library, check for available docs before writing code"
References
- context-hub — existing community solution
- Content guide — how their docs/skills are structured
Activity
github-actions commentedon Mar 13, 2026
🏗️ Squad Triage — Flight (Lead)
Issue: #355 — Research: External API documentation layer for agent spawns
Assigned to: FIDO (Quality Owner)
Reason: Issue relates to testing/quality work
@copilot evaluation: 🔴 Not suitable — issue involves work outside the coding agent's capability profile.
Team roster:
squad:flightsquad:proceduressquad:eecomsquad:fidosquad:paosquad:capcomsquad:controlsquad:surgeonsquad:boostersquad:gncsquad:networksquad:retrosquad:incosquad:guidosquad:telemetrysquad:voxsquad:dskysquad:simssquad:handbooksquad:ralphsquad:copilotbradygaster commentedon Mar 13, 2026
📌 Brady requested this issue be assigned to @diberry (docs/UX triage). Pending collaborator invite to complete assignment.
github-actions commentedon Mar 13, 2026
📋 Assigned to Procedures (Prompt Engineer)
Issue: #355 — Research: External API documentation layer for agent spawns
Procedures will pick this up in the next Copilot session.
github-actions commentedon Mar 13, 2026
📋 Assigned to Flight (Lead)
Issue: #355 — Research: External API documentation layer for agent spawns
Flight will pick this up in the next Copilot session.
feat: ghost response detection and retry logic (github#355)
bradygaster commentedon Mar 22, 2026
Flagging this for follow-up. Brady wants to explore whether Carlos has input on the external API docs layer approach.
Key question: how should agents access external API documentation at spawn time? Current thinking:
.squad/apis/directory with curated doc snippetsIf we don't have enough signal yet, this stays as a research spike. Carlos — any thoughts on how you've handled this?
bradygaster commentedon Mar 24, 2026
Closing — this research spike hasn't had traction and the external API docs problem is better solved ad-hoc per agent skill than as a generic layer. Will revisit if a concrete use case surfaces.