Kernel Subsystems — Core Engines
Docs » Kernel Subsystems — Core Engines » ZQK Agent Skills Architecture: Evolutionary Breeding & Generative Mutation
Raw .md

ZQK Agent Skills Architecture: Evolutionary Breeding & Generative Mutation

This package tree (pkg/skills) implements autonomous agent skill maintenance, fitness-driven evolution, and generative synthesis within the ZQK Knowledge Kernel.

1. Architectural Overview

Agent skills in ZQK are first-class kernel objects (kind: agent_skill) backed by executable or procedural Markdown instructions (SKILL.md) or Go code. Over the lifecycle of swarm operations, skills are evaluated by automated execution monitors (maturation_report, metrics_feedback, and VDS validation passes).

   ┌─────────────────────────────────────────────────────────────────────────────┐
   │                            Kernel Event Mesh                                │
   └──────────────────────────────────────┬──────────────────────────────────────┘
                                          │ EventTypeObjectMutated (maturation_report)
                                          ▼
                         ┌─────────────────────────────────┐
                         │   breeding.Listener (Ambient)   │
                         └────────────────┬────────────────┘
                                          │ Triggers on mutation
                                          ▼
                         ┌─────────────────────────────────┐
                         │         breeding.Engine         │
                         │  - Scans agent_skill objects    │
                         │  - Evaluates fitness_score      │
                         │  - Identifies fitness < T       │
                         └────────────────┬────────────────┘
                                          │ Passes originalFilePath + feedback
                                          ▼
                         ┌─────────────────────────────────┐
                         │     breeding.MutationProvider   │
                         │     (breeding.LLMSkillMutator)  │
                         │  - Synthesizes improved skill   │
                         │  - Fallback: deterministic tag  │
                         └────────────────┬────────────────┘
                                          │ Creates new fork
                                          ▼
                         ┌─────────────────────────────────┐
                         │  New agent_skill Object Minted  │
                         └─────────────────────────────────┘

2. Package Decomposition

pkg/skills/breeding

  • Engine: Scans all registered agent_skill objects and inspects their linked maturation_report objects. If any skill exhibits a fitness_score strictly lower than the configured threshold (fitnessThreshold, e.g. 0.70), it accumulates feedback from both maturation_report and metrics_feedback and invokes the MutationProvider.
  • MutationProvider: Interface defining MutateSkill(ctx context.Context, originalFilePath string, feedback []string) (string, error).
  • LLMSkillMutator: Production implementation of MutationProvider. Employs ZQK's core llm.Client to optimize skill instructions and code. In airgapped or offline mode, falls back to a deterministic, timestamped fork preserving audit feedback.
  • Listener: Event-driven subscriber to the ZQK kernel event router. Intercepts EventTypeObjectMutated events for maturation_report kinds, allowing the breeding loop to operate autonomously in the background without polling.

pkg/skills/mutation

  • Engine: Generative multi-parent skill synthesis. Merges multiple parent skill implementations into a unified child skill, performs semantic validation via SemanticEngine, and generates technical documentation.
  • SkillSynthesisClient (llm_client.go): Concrete adapter connecting ZQK's unified LLM client (pkg/llm.Client) to generative skill synthesis. Provides customizable system prompts (DefaultSystemPromptCode, DefaultSystemPromptDocs) and sanitizes markdown fence wrappers from language model completions to return pristine, compilable Go source.

3. Operational Invocations

  • Manual Optimization: zqk ops level-up <agent_skill_id> evaluates and reports optimization targets for a given skill.
  • Autonomous Evolution: zqk system evolve triggers autonomous skill recombination and evolutionary convergence across active swarm seats.
  • Cryptographic Sealing: zqk system seal-skill <skill_name> signs and validates skill immutability via cryptographic digest headers in SKILL.md.