Designer Toy Trend Analysis

SKILL.md — Designer Toy Trend Analysis Registry

> Version: 2.0.0 | Status: Production Ready | Last Updated: 2026-07-27

Overview

designer-toy-trend-analysis is a professional-grade agent system for Designer Toy Collectible Market & Trend Forecasting. It transforms Claude into a domain-expert that delivers structured, evidence-backed outputs by combining real-time data aggregation, recognized domain methods, and academic research into a single orchestrated workflow ending in a risk/limitation-disclosed recommendation.

Skill Registration & Resolution

Registration Protocol

Skills are registered in the agent-registry/ directory with the following structure:

agent-registry/
├── agents.json                    # Master agent registry
├── skills.json                    # Master skill registry
├── hooks.json                     # Hooks configuration
└── agents/
    ├── market-data-agent.md       # Real-time market data agent
    ├── research-agent.md          # Academic research agent
    ├── trend-analysis-agent.md    # Trend & forecasting agent
    └── risk-assessment-agent.md  # Risk & bubble detection agent

Resolution Process

When /designer-toy-trend-analysis is invoked:

1. Pre-Flight: Language detection (Vietnamese/English)
2. Agent Selection: Chain-of-thought router selects optimal agent path
3. Skill Resolution: Skills are resolved from skills.json with dependency injection
4. Execution: Agents execute with hooks and tool schemas
5. Quality Gate: All outputs pass through 10 quality gates (U1–U6 + G1–G4)

Agent Architecture

Agent Registry (agents.json)

{
  "agents": {
    "market-data": {
      "name": "market-data-agent",
      "type": "data-collector",
      "description": "Real-time market data from authoritative sources",
      "tools": ["WebSearch", "WebFetch", "Read"],
      "skills": ["sub-evidence-collector"],
      "hooks": {
        "before": ["log_start", "validate_input"],
        "after": ["validate_output", "log_complete"]
      },
      "retry_policy": {
        "max_retries": 3,
        "backoff": "exponential"
      },
      "fallback": "knowledge-base"
    },
    "research": {
      "name": "research-agent",
      "type": "knowledge-base",
      "description": "Academic research and authoritative evidence",
      "tools": ["Read", "WebSearch"],
      "skills": ["sub-knowledge-updater"],
      "hooks": {
        "before": ["log_start"],
        "after": ["log_complete", "cache_result"]
      },
      "fallback": "gap-fill"
    },
    "trend-analysis": {
      "name": "trend-analysis-agent",
      "type": "analyzer",
      "description": "Demand, resale, liquidity, and trend signal analysis",
      "tools": ["WebFetch", "Read"],
      "skills": ["sub-core-analysis"],
      "hooks": {
        "before": ["log_start", "load_cache"],
        "after": ["validate_scorecard", "log_complete"]
      },
      "fallback": "qualitative"
    },
    "risk-assessment": {
      "name": "risk-assessment-agent",
      "type": "evaluator",
      "description": "Risk, bubble, and solvency assessment",
      "tools": ["Read", "WebSearch"],
      "skills": ["sub-advisor"],
      "hooks": {
        "before": ["log_start"],
        "after": ["validate_verdict", "log_complete"]
      },
      "fallback": "conservative"
    }
  },
  "chains": {
    "full-analysis": ["market-data", "research", "trend-analysis", "risk-assessment"],
    "quick-trend": ["market-data", "trend-analysis"],
    "deep-research": ["research", "trend-analysis", "risk-assessment"]
  }
}

Chain-of-Thought Router

The router determines the optimal agent chain based on:

def route_analysis(query, requirements):
    """
    Select optimal agent chain based on query type and requirements.
    
    Args:
        query: User's input query
        requirements: Parsed requirements from sub-gather-requirements
    
    Returns:
        chain_key: Key to agent chain from chains.json
    """
    if requirements.get('analysis_type') == 'research':
        return 'deep-research'
    elif requirements.get('timeframe', {}).get('forecast_horizon_days', 0) <= 30:
        return 'quick-trend'
    else:
        return 'full-analysis'

Skill Registry (skills.json)

{
  "skills": {
    "sub-gather-requirements": {
      "file": "skills/sub-gather-requirements.md",
      "type": "intake",
      "inputs": {
        "required": ["user_message"],
        "optional": ["provided_materials"]
      },
      "outputs": {
        "schema": "references/schemas/requirements-schema.json"
      },
      "quality_gates": ["G0"]
    },
    "sub-evidence-collector": {
      "file": "skills/sub-evidence-collector.md",
      "type": "data-collection",
      "inputs": {
        "required": ["requirements"],
        "optional": []
      },
      "outputs": {
        "schema": "references/schemas/evidence-bundle-schema.json"
      },
      "quality_gates": ["U1", "U3", "U6"],
      "agent": "market-data"
    },
    "sub-core-analysis": {
      "file": "skills/sub-core-analysis.md",
      "type": "analysis",
      "inputs": {
        "required": ["evidence_bundle"],
        "optional": ["knowledge_base_entries"]
      },
      "outputs": {
        "schema": "references/schemas/scorecard-schema.json"
      },
      "quality_gates": ["G1", "G2", "G3"],
      "agent": "trend-analysis"
    },
    "sub-knowledge-updater": {
      "file": "skills/sub-knowledge-updater.md",
      "type": "knowledge",
      "inputs": {
        "required": ["topic_keywords"],
        "optional": []
      },
      "outputs": {
        "schema": "references/schemas/knowledge-citation-schema.json"
      },
      "quality_gates": ["U1"],
      "agent": "research"
    },
    "sub-advisor": {
      "file": "skills/sub-advisor.md",
      "type": "synthesis",
      "inputs": {
        "required": ["scorecard", "evidence_bundle", "knowledge_entries"],
        "optional": []
      },
      "outputs": {
        "schema": "references/schemas/conclusion-schema.json"
      },
      "quality_gates": ["U2", "U4", "U5", "G4"],
      "agent": "risk-assessment"
    }
  }
}

Hooks System

Hooks Configuration (hooks.json)

{
  "lifecycle_hooks": {
    "before_execution": [
      {
        "name": "log_start",
        "handler": "scripts/hooks/log_start.py",
        "async": false
      },
      {
        "name": "validate_input",
        "handler": "scripts/hooks/validate_input.py",
        "async": false
      },
      {
        "name": "check_rate_limit",
        "handler": "scripts/hooks/check_rate_limit.py",
        "async": false
      }
    ],
    "after_execution": [
      {
        "name": "validate_output",
        "handler": "scripts/hooks/validate_output.py",
        "async": false
      },
      {
        "name": "log_complete",
        "handler": "scripts/hooks/log_complete.py",
        "async": false
      },
      {
        "name": "emit_event",
        "handler": "scripts/hooks/emit_event.py",
        "async": true
      }
    ],
    "on_error": [
      {
        "name": "handle_error",
        "handler": "scripts/hooks/handle_error.py",
        "async": false
      },
      {
        "name": "log_error",
        "handler": "scripts/hooks/log_error.py",
        "async": false
      }
    ]
  },
  "state_sync_hooks": {
    "before_save": ["validate_state"],
    "after_save": ["emit_state_change"],
    "on_conflict": ["resolve_state_conflict"]
  },
  "event_emission": {
    "events": [
      "analysis.started",
      "analysis.completed",
      "analysis.failed",
      "agent.retry",
      "agent.fallback"
    ]
  }
}

Hook Handlers

Hook handlers are Python scripts in scripts/hooks/ that follow this interface:

def handle(context, config):
    """
    Hook handler interface.
    
    Args:
        context: Execution context (agent, skill, inputs, state)
        config: Hook configuration
    
    Returns:
        result: Hook result (may modify context)
    
    Raises:
        HookError: If hook fails critically
    """
    pass

Tool Schemas

All tools have JSON schemas for input validation and output structure.

WebSearch Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "WebSearch",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2,
      "description": "Search query for domain information"
    },
    "max_results": {
      "type": "integer",
      "default": 10,
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": ["query"]
}

WebFetch Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "WebFetch",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "URL to fetch"
    },
    "prompt": {
      "type": "string",
      "description": "Extraction prompt"
    }
  },
  "required": ["url", "prompt"]
}

Input/Output JSON Schemas

All skill inputs and outputs are validated against JSON schemas in references/schemas/.

Requirements Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Requirements",
  "type": "object",
  "properties": {
    "object_id": {
      "type": "string",
      "pattern": "^[a-z0-9:.-]+$"
    },
    "scope": {
      "type": "string",
      "enum": ["primary", "resale", "both"]
    },
    "timeframe": {
      "type": "object",
      "properties": {
        "analysis_window_days": {"type": "integer"},
        "forecast_horizon_days": {"type": "integer"}
      }
    },
    "available_inputs": {
      "type": "array",
      "items": {"type": "string"}
    },
    "target_audience": {
      "type": "string",
      "enum": ["practitioner", "investor", "researcher", "learner"]
    },
    "language": {
      "type": "string",
      "enum": ["vi", "en"]
    },
    "region": {
      "type": "string",
      "enum": ["PRC", "JP", "US", "EU", "global"]
    },
    "currency": {
      "type": "string",
      "default": "USD"
    },
    "analysis_type": {
      "type": "string",
      "enum": ["demand", "resale", "combined"],
      "default": "combined"
    }
  },
  "required": ["object_id", "scope", "timeframe", "language"]
}

Execution Protocol

Main Harness Flow

USER INPUT → /designer-toy-trend-analysis
    │
    ▼
[Pre-Flight: Language Detection]
    │
    ├─► [Chain-of-Thought Router] → Select agent chain
    │
    ├─► [Agent 1: sub-gather-requirements]
    │   └─► Hooks: before_execution → execute → after_execution
    │
    ├─► [Agent 2: market-data + sub-evidence-collector]
    │   └─► Hooks: before_execution → execute → after_execution
    │       └─► Fallback chain: primary → secondary → knowledge-base → LIMITATION
    │
    ├─► [Agent 3: trend-analysis + sub-core-analysis]
    │   └─► Hooks: before_execution → execute → after_execution
    │
    ├─► [Agent 4: research + sub-knowledge-updater]
    │   └─► Hooks: before_execution → execute → after_execution
    │
    ├─► [Agent 5: risk-assessment + sub-advisor]
    │   └─► Hooks: before_execution → execute → after_execution
    │
    └─► [Quality Gate: U1–U6 + G1–G4]
        ├─► Auto-fix attempts (max 2 per gate)
        ├─► Degradation level assignment (0-4)
        └─► Final output with disclosure

Error Handling

{
  "error_handling": {
    "retry_policy": {
      "max_retries": 3,
      "backoff_strategy": "exponential_with_jitter",
      "retry_on": ["timeout", "rate_limit", "transient_error"]
    },
    "fallback_chain": {
      "market-data": ["primary_source", "secondary_source", "knowledge_base", "limitation_flag"],
      "research": ["cached_result", "gap_fill_search", "limitation_flag"],
      "trend-analysis": ["quantitative", "qualitative", "limitation_flag"],
      "risk-assessment": ["full_analysis", "conservative", "limitation_flag"]
    },
    "graceful_degradation": {
      "levels": {
        "0": "All primary sources available",
        "1": "Some primary sources failed, using secondary",
        "2": "Most sources failed, using knowledge base",
        "3": "Required inputs missing, proceeding with available",
        "4": "All sources failed, data unavailable"
      }
    }
  }
}

Configuration Management

Configuration is centralized in config/ with environment-specific overrides.

config/
├── default.json           # Default configuration
├── development.json       # Development overrides
├── production.json        # Production overrides
└── test.json             # Test configuration

Configuration Schema

{
  "version": "2.0.0",
  "environment": "${NODE_ENV}",
  "logging": {
    "level": "info",
    "format": "json",
    "outputs": ["console", "file"]
  },
  "agents": {
    "timeout_ms": 30000,
    "max_concurrent": 4,
    "cache_ttl_seconds": 3600
  },
  "quality_gates": {
    "auto_fix_enabled": true,
    "max_retries": 2,
    "strict_mode": false
  },
  "knowledge_base": {
    "path": "SECOND-KNOWLEDGE-BRAIN.md",
    "update_schedule": "weekly",
    "min_relevance_score": 5.0
  },
  "api": {
    "rate_limit": {
      "requests_per_minute": 100,
      "burst_size": 10
    }
  }
}

Validation & Testing

Input Validation

All inputs are validated against their JSON schemas before agent execution. Invalid inputs trigger the validate_input hook and return a structured error.

Output Validation

All outputs are validated against their JSON schemas and quality gates. Validation failures trigger auto-fix attempts.

Quality Gates

Quality gates are defined in skills/main.md and enforced at the harness level. Each gate has an auto-fix procedure and retry limit.

Dependencies

Required Tools

• WebSearch: Domain information retrieval
• WebFetch: Authoritative source scraping
• Read: File and knowledge base reading
• Write: Knowledge base appending (via tools/knowledge_updater.py)
• Bash: Tool execution for knowledge pipeline
• Skill: Sub-skill invocation

Required Files

• SECOND-KNOWLEDGE-BRAIN.md: Living knowledge base
• skills/main.md: Main harness orchestrator
• skills/sub-*.md: Five domain sub-skills
• agent-registry/*.json: Agent and skill registries
• config/*.json: Configuration files
• references/schemas/*.json: JSON schemas for validation

Extension Points

Adding New Agents

1. Create agent file in agent-registry/agents/
2. Add entry to agent-registry/agents.json
3. Define hooks in agent-registry/hooks.json
4. Create associated skills if needed

Adding New Skills

1. Create skill file in skills/
2. Add entry to agent-registry/skills.json
3. Define input/output schemas in references/schemas/
4. Define quality gates

Adding New Hooks

1. Create hook handler in scripts/hooks/
2. Add entry to agent-registry/hooks.json
3. Define hook interface and error handling

Performance Optimization

Context Window Management

• Prioritize high-relevance knowledge base entries (score ≥ 7.0)
• Summarize long evidence bundles before passing to synthesis
• Use selective fetching for large source documents

Token Consumption

• Cache frequently accessed knowledge base entries
• Deduplicate evidence across agents
• Use structured templates to reduce formatting overhead

Structured Logging

Logs are written in JSON format with severity levels, timestamps, and correlation IDs.

{
  "timestamp": "2026-07-27T10:00:00Z",
  "level": "info",
  "correlation_id": "uuid",
  "agent": "market-data",
  "skill": "sub-evidence-collector",
  "event": "execution_started",
  "metadata": {}
}

License

MIT License — see LICENSE.

---

For detailed technical specifications, see PROJECT-detail.md

For build status and phase tracking, see PROJECT-DEVELOPMENT-PHASE-TRACKING.md

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/designer-toy-trend-analysis-agent-skill
• License: MIT

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