Sugar Detox Taste Restructuring Agent Skill

SKILL.md — Sugar Detox & Taste Restructuring Skill Registry

Overview

The sugar-detox-taste-restructuring skill system uses a flexible, production-grade architecture that supports dynamic skill registration, resolution, execution, and validation. This document serves as the authoritative reference for the skill registry system, including all schemas, workflows, and best practices.

---

Table of Contents

1. [Architecture Overview](#architecture-overview)
2. [Skill Registration](#skill-registration)
3. [Skill Resolution](#skill-resolution)
4. [Skill Execution](#skill-execution)
5. [Input/Output Schemas](#inputoutput-schemas)
6. [Validation & Quality Gates](#validation--quality-gates)
7. [Error Handling](#error-handling)
8. [Best Practices](#best-practices)

---

Architecture Overview

The skill system consists of the following components:

┌─────────────────────────────────────────────────────────────┐
│                    SKILL REGISTRY                           │
│  - Register/unregister skills                              │
│  - Skill discovery and metadata                           │
│  - Skill version management                                │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    SKILL RESOLVER                            │
│  - Intent analysis and matching                            │
│  - Skill selection algorithm                               │
│  - Chain-of-thought routing                                │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    SKILL EXECUTOR                            │
│  - Hook execution (before/after/error)                     │
│  - Context management                                       │
│  - Token tracking                                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    QUALITY GATES                             │
│  - Output validation                                       │
│  - Evidence hierarchy enforcement                          │
│  - Disclosure checking                                     │
└─────────────────────────────────────────────────────────────┘

Core Components

| Component | File | Purpose | |-----------|------|---------| | Skill Registry | skills/registry.py | Central registry for all skills | | Skill Resolver | skills/resolver.py | Intelligent skill selection | | Skill Executor | skills/executor.py | Execution with hooks and monitoring | | Skill Definitions | skills/*.md | Individual skill implementations | | Hooks System | hooks/*.py | Lifecycle management and events |

---

Skill Registration

Registration Process

Skills are registered through the SkillRegistry singleton:

from skills.registry import SkillRegistry, SkillMetadata

# Get the registry
registry = SkillRegistry.get_instance()

# Define skill metadata
metadata = SkillMetadata(
    name="sub-core-analysis",
    version="1.0.0",
    description="Design personalized sugar-detox journey...",
    capabilities=["detox_planning", "substitute_analysis", "behavior_design"],
    input_schema="core_analysis_input.json",
    output_schema="core_analysis_output.json",
    dependencies=[],
    author="system",
    tags=["nutrition", "endocrinology", "behavior"],
)

# Register the skill
registry.register(metadata, skill_file_path="skills/sub-core-analysis.md")

Skill Metadata Schema

interface SkillMetadata {
  // Identification
  name: string;                    // Unique skill identifier
  version: string;                 // Semantic version
  description: string;             // Human-readable description

  // Capabilities
  capabilities: string[];          // What the skill can do
  input_schema: string;            // Path to input JSON schema
  output_schema: string;           // Path to output JSON schema

  // Dependencies
  dependencies: string[];           // Other skills this depends on
  dependency_type?: "sequential" | "parallel" | "conditional";

  // Metadata
  author: string;
  tags: string[];
  created_at: string;
  updated_at: string;

  // Execution
  priority: number;                // For resolver ranking (0-100)
  timeout_ms: number;              // Maximum execution time
  max_retries: number;             // Retry attempts on failure

  // Quality
  quality_gates: string[];         // Quality gates to check
  requires_medical: boolean;       // Whether medical supervision required
}

Built-in Skills

| Skill Name | Purpose | Priority | |------------|---------|----------| | sub-gather-requirements | Clarify analysis parameters | 90 | | sub-evidence-collector | Fetch authoritative data | 85 | | sub-core-analysis | Design detox journey | 80 | | sub-knowledge-updater | Query knowledge base | 70 | | sub-advisor | Synthesize recommendations | 75 |

---

Skill Resolution

Resolution Algorithm

The skill resolver uses a multi-factor scoring algorithm:

def resolve_skill(user_query: str, context: Dict) -> List[SkillMetadata]:
    """
    Resolve and rank skills based on user query.

    Scoring factors:
    1. Keyword match (0-40 points)
    2. Capability match (0-30 points)
    3. Context fit (0-20 points)
    4. Dependencies satisfied (0-10 points)
    """

    scores = {}

    for skill in registry.get_all_skills():
        score = 0

        # Keyword matching
        query_lower = user_query.lower()
        for keyword in skill.keywords:
            if keyword in query_lower:
                score += min(10, 40 // len(skill.keywords))

        # Capability matching
        for capability in skill.capabilities:
            if capability in query_lower:
                score += 30 // len(skill.capabilities)

        # Context fit
        if has_required_context(context, skill):
            score += 20

        # Dependencies
        if dependencies_satisfied(skill, context):
            score += 10

        # Apply skill priority
        score *= (skill.priority / 100)

        scores[skill.name] = score

    # Return sorted skills
    return sorted(registry.get_all_skills(), key=lambda s: -scores.get(s.name, 0))

Chain-of-Thought Routing

For complex queries, the resolver uses chain-of-thought routing:

User Query: "Create a detox plan considering my diabetes"

Router Analysis:
1. Intent Detection: "detox plan" → sub-core-analysis
2. Context Analysis: "diabetes" → medical flag
3. Routing Decision:
   - Primary: sub-core-analysis (80 points)
   - Secondary: sub-advisor (70 points)
   - Medical check required → elevate priority
4. Execution Order:
   → sub-gather-requirements (diabetes note)
   → sub-evidence-collector (diabetes-friendly sources)
   → sub-core-analysis (diabetes-aware plan)
   → sub-knowledge-updater (diabetes research)
   → sub-advisor (medical supervision flag)

---

Skill Execution

Execution Flow

┌──────────────────┐
│  User Query     │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐      ┌──────────────────────┐
│  Skill Resolver  │─────│  Hook: BeforeExecution│
└────────┬─────────┘      └──────────────────────┘
         │
         ▼
┌──────────────────┐      ┌──────────────────────┐
│  Skill Executor  │─────│  Hook: TokenTracking  │
└────────┬─────────┘      └──────────────────────┘
         │
         ▼
┌──────────────────┐      ┌──────────────────────┐
│  Skill File      │─────│  Hook: StateUpdate    │
│  Execution       │      └──────────────────────┘
└────────┬─────────┘
         │
         ▼
┌──────────────────┐      ┌──────────────────────┐
│  Output Validator│─────│  Hook: AfterExecution │
└────────┬─────────┘      └──────────────────────┘
         │
         ▼
┌──────────────────┐
│  Quality Gates   │
│  (U1-U6, G1-G4) │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Final Output    │
└──────────────────┘

Hook Integration

Skills integrate with the hooks system for lifecycle management:

# Before execution
context.phase = "before"
await registry.execute_before(context)

# Execute skill
context.phase = "executing"
result = await execute_skill_file(skill_path, context)

# After execution
context.phase = "after"
context.output_data = result
await registry.execute_after(context)

# Quality gates
if registry.quality_gates_enabled:
    await execute_quality_gates(context)

---

Input/Output Schemas

Input Schema (Universal)

All skills accept a standardized input format:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "SkillInput",
  "type": "object",
  "required": ["query", "context"],
  "properties": {
    "query": {
      "type": "string",
      "description": "User's natural language query",
      "minLength": 1,
      "maxLength": 10000
    },
    "context": {
      "type": "object",
      "description": "Execution context",
      "properties": {
        "agent_id": {"type": "string"},
        "execution_id": {"type": "string"},
        "language": {"type": "string", "enum": ["en", "vi"]},
        "previous_outputs": {"type": "array"},
        "user_preferences": {"type": "object"}
      }
    },
    "parameters": {
      "type": "object",
      "description": "Skill-specific parameters",
      "additionalProperties": true
    },
    "constraints": {
      "type": "object",
      "properties": {
        "max_execution_time_ms": {"type": "integer"},
        "max_output_tokens": {"type": "integer"},
        "allowed_sources": {"type": "array"}
      }
    }
  }
}

Output Schema (Universal)

All skills produce a standardized output format:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "SkillOutput",
  "type": "object",
  "required": ["status", "data"],
  "properties": {
    "status": {
      "type": "string",
      "enum": ["success", "partial", "error"]
    },
    "data": {
      "type": "object",
      "description": "Primary output data",
      "properties": {
        "result": {"type": "object"},
        "sections": {
          "type": "object",
          "properties": {
            "executive_summary": {"type": "string"},
            "inputs_scope": {"type": "string"},
            "evidence_collected": {"type": "object"},
            "analysis": {"type": "object"},
            "conclusion": {"type": "string"},
            "risks": {"type": "array"},
            "disclosure": {"type": "string"}
          }
        }
      }
    },
    "metadata": {
      "type": "object",
      "properties": {
        "execution_time_ms": {"type": "number"},
        "tokens_used": {"type": "object"},
        "sources": {"type": "array"},
        "quality_gate_results": {"type": "array"},
        "degradation_level": {"type": "integer", "minimum": 0, "maximum": 4}
      }
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {"type": "string"},
          "message": {"type": "string"},
          "stack_trace": {"type": "string"}
        }
      }
    }
  }
}

Skill-Specific Schemas

Each skill has its own input/output schema extensions:

sub-core-analysis Input Schema

{
  "current_intake": {
    "type": "object",
    "properties": {
      "daily_sugar_grams": {"type": "number"},
      "primary_sources": {"type": "array", "items": {"type": "string"}},
      "timing_patterns": {"type": "array"}
    }
  },
  "cravings": {
    "type": "object",
    "properties": {
      "frequency": {"type": "string"},
      "triggers": {"type": "array"},
      "severity": {"type": "string", "enum": ["mild", "moderate", "severe"]}
    }
  },
  "health_profile": {
    "type": "object",
    "properties": {
      "comorbidities": {"type": "array"},
      "medications": {"type": "array"},
      "allergies": {"type": "array"}
    }
  }
}

sub-core-analysis Output Schema

{
  "intake_assessment": {
    "type": "object",
    "properties": {
      "current_daily_grams": {"type": "number"},
      "vs_limit_percentage": {"type": "number"},
      "primary_sources": {"type": "array"}
    }
  },
  "detox_plan": {
    "type": "object",
    "properties": {
      "target_daily_grams": {"type": "number"},
      "trajectory_weeks": {"type": "number"},
      "phase_breakdown": {"type": "array"}
    }
  },
  "substitutes": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "safety_evidence": {"type": "string"},
        "recommended_usage": {"type": "string"}
      }
    }
  },
  "conclusion": {
    "type": "string",
    "enum": [
      "Personalized Plan Ready",
      "Conditional (medical supervision)",
      "High Adherence Risk",
      "Inconclusive"
    ]
  }
}

---

Validation & Quality Gates

Quality Gate Schema

interface QualityGate {
  gate_id: string;
  name: string;
  description: string;

  // Check configuration
  check_function: string;              // Path to check function
  check_type: "automatic" | "manual";

  // Auto-fix configuration
  auto_fix_available: boolean;
  auto_fix_function?: string;

  // Enforcement
  enforcement: "soft" | "hard";        // Soft = warn, hard = block
  max_retries: number;

  // Dependencies
  depends_on_gates: string[];          // Gates that must pass first
}

Quality Gate Execution

async def execute_quality_gates(context: HookContext) -> QualityGateResult:
    """
    Execute all quality gates in dependency order.

    Returns:
        QualityGateResult with pass/fail status and details
    """
    gates = load_quality_gates()

    # Sort by dependency
    sorted_gates = topological_sort(gates)

    results = []
    for gate in sorted_gates:
        # Check dependencies
        if not all_dependencies_passed(gate, results):
            results.append(QualityGateResult(
                gate_id=gate.gate_id,
                passed=False,
                skipped=True,
                reason="Dependencies not met"
            ))
            continue

        # Execute gate
        result = await execute_gate(gate, context)

        # Auto-fix if failed
        if not result.passed and gate.auto_fix_available:
            result = await execute_auto_fix(gate, context)

        results.append(result)

        # Hard enforcement
        if not result.passed and gate.enforcement == "hard":
            raise QualityGateError(f"Gate {gate.gate_id} failed: {result.reason}")

    return aggregate_results(results)

Universal Quality Gates (U1-U6)

| Gate | Description | Enforcement | Auto-Fix | |------|-------------|-------------|----------| | U1 | ≥3 sources cited, ≥1 academic/authoritative | Hard | Append from knowledge base | | U2 | Disclosure/limitations before recommendation | Hard | Prepend standard disclosure | | U3 | Evidence hierarchy stated per source | Hard | Annotate source tiers | | U4 | Language matches user preference | Hard | Translate output | | U5 | Output uses declared template | Hard | Reformat to template | | U6 | Every claim traceable or flagged | Soft | Mark unsupported claims |

Domain-Specific Quality Gates (G1-G4)

| Gate | Description | Enforcement | Auto-Fix | |------|-------------|-------------|----------| | G1 | Target aligned with WHO/USDA/AHA free-sugar guidance | Hard | Align target to guidance | | G2 | Detox trajectory leverages taste-neuroplasticity | Soft | Add neuroplasticity rationale | | G3 | Substitutes cite safety evidence | Hard | Add safety evidence citations | |

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dungnotnull
• Source: dungnotnull/sugar-detox-taste-restructuring-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.