mathias/hyperguild
1
0
Fork 0
Code Issues 7 Pull Requests Actions 1 Packages Projects Releases Wiki Activity

skills(platform): major overhaul — succinct + brain-backed + lazy + reconsider MCP-vs-CLI #25

New Issue
Open
opened 2026-05-21 19:39:57 +00:00 by mathias · 0 comments
mathias commented 2026-05-21 19:39:57 +00:00
Owner
Copy Link

Background

The agent platform ships a growing set of skills (general engineering: TDD, SOLID, refactoring, problem-analysis, grill-me, code-review, cognitive-load, etc.) plus harness-specific skills (caveman, gsd-*, etc.). They are loaded eagerly by harness invocation, consume meaningful input tokens at session start (especially in scaffolded projects that inherit all general skills), and have no built-in feedback loop from brain.

Scaffolded projects (template-go-agent, template-go-web, and per-repo .skills softlinks per wire-skills) carry the same general skill set regardless of whether the project actually exercises it. Token spend is paid every session.

The MCP layer (brain MCP, gitea MCP, infra MCP, routing MCP) duplicates capability that, in some cases, would be lighter as direct CLI tools or thin REST clients inside a skill — particularly for read-heavy paths (brain_query, repo browse, kubectl get).

Goals

  1. Sharper skills. Each skill is specific, succinct, focused on one decision or workflow. No catch-all skills. Triggers and use-when criteria explicit.
  2. Brain-backed learning. Skills cite + draw from brain entries; a skill that fails or surprises an operator writes a brain note that future invocations consult. Make the trainer skill or an analogue the closed loop.
  3. Lazy loading. Skills should be discoverable from a small index, loaded on demand (per harness capability — Skill tool already supports this), not eagerly injected.
  4. Reconsider MCP boundary. For each MCP server, evaluate whether the agent-facing surface should remain MCP, or move to a CLI binary + skill wrapper, or a thin REST client embedded in a skill. Decision per server, not blanket.

Scope

  • General skills in scaffolded projects (template-go-agent, template-go-web, per-repo .skills)
  • Harness-level skills under ~/.claude/skills and the GSD skill cluster
  • SKILLS_INDEX.md schema and lazy-loading conventions
  • MCP servers maintained by Mathias: brain-mcp, gitea-mcp, infra-mcp, routing-mcp
  • Brain feedback loop wiring (trainer / session-retrospective integration)

Out of scope (this issue)

  • Replacing existing agent harnesses (Claude Code, Crush, Pi, Antigravity)
  • Brain corpus content refactor
  • Specific business-app skill content (cobalt-dingo, agentsquad)

Acceptance criteria

  • Audit: list every active skill across ~/.claude/skills, ~/dev/.skills, scaffolded .skills softlinks, and harness-specific skills. Score each on (a) used-this-month, (b) token cost when loaded, (c) overlap with another skill, (d) brain-citation count.
  • Skill quality bar codified: one decision/workflow per skill, explicit triggers, max-token-budget per skill, brain-citation requirement on rules of thumb.
  • Lazy-loading scheme: every harness that supports it loads skills via Skill tool (or equivalent) from an index; only the index loads at session start.
  • Brain feedback loop: defined trigger (skill failure, operator correction, surprise) writes a brain entry; future skill load surfaces relevant brain hits as context.
  • MCP-vs-CLI-vs-REST decision matrix: per server, a written verdict with rationale. Action items derived per server (keep / convert / split).
  • Migration plan: ordered set of issues / commits to move from current state to target state. Each step ships independently.

Risks

  • Over-narrowing skills creates a proliferation of micro-skills that themselves become hard to discover.
  • Lazy loading shifts cost from session start to skill load; net token spend may not improve without measurement.
  • Moving MCP capability to CLI/REST changes auth surface — each path needs the same Bearer model or it regresses security.

Forward references

  • Touches the mathias/hyperguild agent platform repo, mathias/template-go-agent, mathias/template-go-web, the four MCP server repos, and possibly ~/.claude/skills globally.
  • Related: docs/superpowers/specs/2026-05-homelab-architecture-review.md in mathias/infra flagged MCP federation cognitive load (620/1000); this issue is the agent-side counterpart.

First step

Audit existing skills. Output a scored table (one row per skill) into docs/skills-audit-2026-05.md here. Block on that before any deletion / rewrite / migration.

## Background The agent platform ships a growing set of skills (general engineering: TDD, SOLID, refactoring, problem-analysis, grill-me, code-review, cognitive-load, etc.) plus harness-specific skills (caveman, gsd-*, etc.). They are loaded eagerly by harness invocation, consume meaningful input tokens at session start (especially in scaffolded projects that inherit all general skills), and have no built-in feedback loop from brain. Scaffolded projects (`template-go-agent`, `template-go-web`, and per-repo `.skills` softlinks per `wire-skills`) carry the same general skill set regardless of whether the project actually exercises it. Token spend is paid every session. The MCP layer (brain MCP, gitea MCP, infra MCP, routing MCP) duplicates capability that, in some cases, would be lighter as direct CLI tools or thin REST clients inside a skill — particularly for read-heavy paths (`brain_query`, repo browse, `kubectl get`). ## Goals 1. **Sharper skills.** Each skill is specific, succinct, focused on one decision or workflow. No catch-all skills. Triggers and use-when criteria explicit. 2. **Brain-backed learning.** Skills cite + draw from brain entries; a skill that fails or surprises an operator writes a brain note that future invocations consult. Make the trainer skill or an analogue the closed loop. 3. **Lazy loading.** Skills should be discoverable from a small index, loaded on demand (per harness capability — Skill tool already supports this), not eagerly injected. 4. **Reconsider MCP boundary.** For each MCP server, evaluate whether the agent-facing surface should remain MCP, or move to a CLI binary + skill wrapper, or a thin REST client embedded in a skill. Decision per server, not blanket. ## Scope - General skills in scaffolded projects (`template-go-agent`, `template-go-web`, per-repo `.skills`) - Harness-level skills under `~/.claude/skills` and the GSD skill cluster - `SKILLS_INDEX.md` schema and lazy-loading conventions - MCP servers maintained by Mathias: brain-mcp, gitea-mcp, infra-mcp, routing-mcp - Brain feedback loop wiring (trainer / session-retrospective integration) ## Out of scope (this issue) - Replacing existing agent harnesses (Claude Code, Crush, Pi, Antigravity) - Brain corpus content refactor - Specific business-app skill content (cobalt-dingo, agentsquad) ## Acceptance criteria - [ ] Audit: list every active skill across `~/.claude/skills`, `~/dev/.skills`, scaffolded `.skills` softlinks, and harness-specific skills. Score each on (a) used-this-month, (b) token cost when loaded, (c) overlap with another skill, (d) brain-citation count. - [ ] Skill quality bar codified: one decision/workflow per skill, explicit triggers, max-token-budget per skill, brain-citation requirement on rules of thumb. - [ ] Lazy-loading scheme: every harness that supports it loads skills via `Skill` tool (or equivalent) from an index; only the index loads at session start. - [ ] Brain feedback loop: defined trigger (skill failure, operator correction, surprise) writes a brain entry; future skill load surfaces relevant brain hits as context. - [ ] MCP-vs-CLI-vs-REST decision matrix: per server, a written verdict with rationale. Action items derived per server (keep / convert / split). - [ ] Migration plan: ordered set of issues / commits to move from current state to target state. Each step ships independently. ## Risks - Over-narrowing skills creates a proliferation of micro-skills that themselves become hard to discover. - Lazy loading shifts cost from session start to skill load; net token spend may not improve without measurement. - Moving MCP capability to CLI/REST changes auth surface — each path needs the same Bearer model or it regresses security. ## Forward references - Touches the `mathias/hyperguild` agent platform repo, `mathias/template-go-agent`, `mathias/template-go-web`, the four MCP server repos, and possibly `~/.claude/skills` globally. - Related: `docs/superpowers/specs/2026-05-homelab-architecture-review.md` in `mathias/infra` flagged MCP federation cognitive load (620/1000); this issue is the agent-side counterpart. ## First step Audit existing skills. Output a scored table (one row per skill) into `docs/skills-audit-2026-05.md` here. Block on that before any deletion / rewrite / migration.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
mathias
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mathias/hyperguild#25
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?