Add notes to docs from Discord and office hours discussions (#36)

* Add community insights from Discord threads and meeting notes

Distill Discord discussions (Feb 14-24) and Feb 26 office hours into
existing docs:

- New findings: NimbleBrain skill:// resource consolidation, skill
  reliability/adherence issues across implementations
- Expanded approaches with distribution/provenance considerations,
  resources adoption insight, and domain-level discovery (.well-known)
- Expanded open questions on dependencies and distribution trust
- Added Cloudflare Agent Skills Discovery RFC and NimbleBrain
  reference implementations to related work

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Remove trust note since its already mentioned in the doc separately

* Clarify attribution for community insights on skill dependencies in open questions

* Refine findings on model skill adherence and community workarounds

* Remove outdated comparison section and streamline evaluation insights in experimental findings

* Remove unnecessary blank line in experimental findings documentation

* Add SEP-2093 proposal to related work documentation

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Ola Hungerford 2026-03-03 13:12:01 -07:00 • committed by GitHub
commit e4de42cf8d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -18,7 +18,9 @@ Workflows that reference tools conditionally based on context, requiring rich st
## 3. Multi-Server Composition
Skills that leverage tools from multiple off-the-shelf servers where you can't (or don't want to) modify their individual instructions.
Skills that leverage tools from multiple off-the-shelf servers where you can't (or don't want to) modify their individual instructions. Skills can also make it more natural to translate ad-hoc tool-call-based workflows into scripted workflows, without fundamentally changing the content of the skill.
**Related:** [agentskills/agentskills#110](https://github.com/agentskills/agentskills/issues/110) — Skill dependency declaration
**Community input:**
@ -26,6 +28,8 @@ Skills that leverage tools from multiple off-the-shelf servers where you can't (
> "The ecosystem has been too focused on the server being the main deliverable in some ways, and actually there's a lot that can be done in terms of composition that we miss by people generally imagining their code as being the server boundary and not providing functionality more as a library." — [Sam Morrow](https://github.com/SamMorrowDrums)
Beyond multi-server tool orchestration, skills themselves may be composable — one skill depending on another skill's output or behavior. This extends the dependency model beyond tool availability to skill availability, and raises questions about declarative dependency metadata. See [Open Question 4](open-questions.md#4-how-should-skills-relate-to-multiple-servers) for the emerging proposal on host-mediated dependency resolution.
## 4. Progressive Disclosure
Skills broken into linked sets of files for effective context management, loaded progressively as the agent needs them rather than all at once.
@ -34,6 +38,12 @@ Skills broken into linked sets of files for effective context management, loaded
> "Especially mimicking progressive disclosure via resources and dynamically adding new ones as the agent reads pieces of the skill has been quite handy!" — [Ozz / Juan Antonio Osorio](https://github.com/JAORMX)
**Practical limitation:** In non-visual execution environments (CLI agents, headless), skills lack the "collapse" mechanism of UI-based progressive disclosure. Without a UI affordance to hide/show content, all disclosed context remains in the model's context window, contributing to the adherence decay problem (see [Skill Reliability and Adherence](experimental-findings.md#skill-reliability-and-adherence)). Tool-based expansion partially addresses this, since pruning a tool call also collapses the context, but this is not a general solution.
**At scale:** A server may expose hundreds or thousands of skills, but a client may only need a handful. This reinforces the need for selective loading via progressive disclosure rather than loading all skill content at once.
> "A server can contain 100s or 1000s of skills as an extreme but a client might only need handful of them." — [Kaxil Naik](https://github.com/kaxil) (Astronomer), via Discord
**Related:** [Anthropic's guidance on progressive disclosure](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
## 5. Server-Skill Pairing