docs: add skills architecture reference and OpenCode resource comparison#19
Conversation
Capture key arguments from Anthropic's "Don't Build Agents, Build Skills Instead" talk (Barry Zhang & Mahesh Murag) that validate DocsClaw's general-purpose agent + skills architecture. Add OpenCode resource comparison showing 23x memory overhead (487Mi vs 9Mi) that justifies building a Go-based agent for multi-instance OpenShift deployments. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Pavel Anni <panni@redhat.com>
📝 WalkthroughWalkthroughTwo new documentation files are added to record empirical resource comparisons between OpenCode and DocsClaw agents on OpenShift, and to establish an architectural reference for a skills-based agent design pattern using reusable domain-specific components and external connectivity. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/dev/2026-04-11-opencode-resource-comparison.md`:
- Around line 34-38: The takeaway mixes baselines: it compares OpenCode (487Mi)
to "both DocsClaw instances combined" (21Mi) then projects 50 agents at ~10Mi
each (500Mi) which is inconsistent; pick one normalization (per-runtime,
per-skill-service pair, or shared-service topology), update the math
consistently, and recompute the 50-agent estimate using the chosen baseline
(adjust the 487Mi vs 21Mi comparison accordingly), then revise the sentence(s)
mentioning OpenCode, DocsClaw, and the 50-agent total so the numbers and
baseline are internally consistent.
- Around line 58-59: The line "Full evaluation report: external experiment at
`~/work/experiments/opencode/REPORT.md`" uses a local filesystem path that
reviewers can't access; replace that literal local path with a repo-relative
path or a permanent URL (e.g., a link to the REPORT.md checked into the
repository or an external permalink) so the report is accessible to others, and
update the Markdown link text accordingly to point to the new location.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 28e5d76c-0ec7-4926-ae18-0f3e90cf95ae
📒 Files selected for processing (2)
docs/dev/2026-04-11-opencode-resource-comparison.mddocs/dev/2026-04-11-skills-architecture-reference.md
| OpenCode uses **~23x more memory** than both DocsClaw instances | ||
| combined (487Mi vs 21Mi). For deploying multiple specialized agents | ||
| for business users on OpenShift, the Go-based approach is significantly | ||
| more efficient. A cluster running 50 specialized DocsClaw agents would | ||
| use roughly 500Mi total — about the same as a single OpenCode instance. |
There was a problem hiding this comment.
Inconsistent capacity math in the takeaway section
Lines 34-38 mix two different baselines: you compare OpenCode to both DocsClaw components combined (21Mi), but then project 50 agents using ~10Mi each (500Mi). This can materially skew deployment planning. Please normalize the model (either per-runtime, per-skill-service pair, or shared-service topology) and recompute the 50-agent estimate accordingly.
As per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/dev/2026-04-11-opencode-resource-comparison.md` around lines 34 - 38,
The takeaway mixes baselines: it compares OpenCode (487Mi) to "both DocsClaw
instances combined" (21Mi) then projects 50 agents at ~10Mi each (500Mi) which
is inconsistent; pick one normalization (per-runtime, per-skill-service pair, or
shared-service topology), update the math consistently, and recompute the
50-agent estimate using the chosen baseline (adjust the 487Mi vs 21Mi comparison
accordingly), then revise the sentence(s) mentioning OpenCode, DocsClaw, and the
50-agent total so the numbers and baseline are internally consistent.
| Full evaluation report: external experiment at | ||
| `~/work/experiments/opencode/REPORT.md` |
There was a problem hiding this comment.
Replace local filesystem source path with a repo/URL-accessible reference
Line 59 points to ~/work/experiments/opencode/REPORT.md, which is not accessible to reviewers or future maintainers. Use a repository-relative path or a permanent URL so readers can validate the measurements.
As per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/dev/2026-04-11-opencode-resource-comparison.md` around lines 58 - 59,
The line "Full evaluation report: external experiment at
`~/work/experiments/opencode/REPORT.md`" uses a local filesystem path that
reviewers can't access; replace that literal local path with a repo-relative
path or a permanent URL (e.g., a link to the REPORT.md checked into the
repository or an external permalink) so the report is accessible to others, and
update the Markdown link text accordingly to point to the new location.
1 participant
Summary
Context
These docs support the OCI-based skill distribution work planned in #4 by documenting the architectural rationale for the skills approach.
🤖 Generated with Claude Code
Summary by CodeRabbit