Config

SKILL Registry — craft-village-heritage-tourism

Overview

The SKILL Registry is the central system for managing, resolving, and executing all skills in the craft-village-heritage-tourism project — a Claude Code harness for the Craft-Village Heritage Tourism & Living Culture domain. This document describes how skills are registered, how they are resolved during execution, their input/output JSON schemas, and how they are validated.

The registry sits on top of four reusable subsystems in config/:

• Configuration (config/__init__.py) — type-safe SystemConfig, feature flags, env overrides.
• Hooks (config/hooks.py) — HookRegistry emitting named lifecycle events.
• Logging (config/logging.py) — structured StructuredLogger with performance tracking.
• Tools (config/tools.py) — ToolRegistry with schema-validated execution handlers.

Skill Architecture

Hierarchical Structure with Chain-of-Thought Router

craft-village-heritage-tourism (Main Skill / Orchestrator)
├── Pre-Flight Router (language + intent detection)
├── Sub-skills (sequential pipeline with router dispatch)
│   ├── sub-gather-requirements     (Step 1 — intake)
│   ├── sub-evidence-collector      (Step 2 — real-time + authoritative data)
│   ├── sub-core-analysis           (Step 3 — experience/IP/capacity planning)
│   ├── sub-knowledge-updater       (Step 4 — academic grounding)
│   └── sub-advisor                 (Step 5 — risk-disclosed synthesis)
├── Tools (dynamic invocation via ToolRegistry)
│   ├── web_search
│   ├── knowledge_query
│   ├── carrying_capacity
│   ├── community_benefit
│   └── experience_design
└── Quality Gates (enforcement)
    ├── Universal Gates (U1-U6)
    └── Domain Gates (G1-G4)

The orchestrator is not a rigid pipeline: the main harness acts as a chain-of-thought router. Each step output is inspected; if a quality gate fails the router re-dispatches the responsible sub-skill (max 2 retries) before escalating to a degradation level. This combines the predictability of a fixed bookend flow (requirements → evidence → core → knowledge → synthesis → quality gate) with the adaptability of a router that can re-enter earlier stages to repair evidence gaps.

Skill Resolution Process

1. Discovery — Skills are discovered from the skills/ directory.
2. Registration — Each skill YAML frontmatter is parsed and registered.
3. Validation — Skill schemas are validated against the contract (name, description, required sections).
4. Execution — Skills are executed in order, emitting SUBSKILL_BEFORE_INVOKE / SUBSKILL_AFTER_INVOKE hooks.

Skill Registration

Frontmatter Schema

Every skill MUST include YAML frontmatter:

---
name: skill-name              # Unique identifier (kebab-case)
description: one-line summary # When to trigger, what it does
---

Registration Process

1. Scan skills/ directory for *.md files.
2. Parse YAML frontmatter from each file.
3. Validate required fields (name, description).
4. Extract skill metadata (sections, tools, gates, language support).
5. Register in the skill registry with metadata.

Skill Metadata Extraction

From each skill file, the system extracts:

• Sections — Role & Persona, Workflow, Tools, Output Format, Quality Gates.
• Tool Dependencies — tools the skill requires.
• Gate Dependencies — quality gates the skill participates in.
• Language Support — whether the skill supports multiple languages.
• Sub-skills — for main.md, the list of sub-skills it orchestrates.

Skill Execution Model

Main Harness Execution

USER INPUT → Pre-Flight (language + intent detection) → Step 1 → Step 2 → Step 3 → Step 4 → Step 5 → Quality Gates → OUTPUT

Sub-Skill Execution

1. Invoke — Skill("sub-skill-name") called.
2. Pre-hook — SUBSKILL_BEFORE_INVOKE emitted (router logs dispatch).
3. Execute — sub-skill runs with its context.
4. Post-hook — SUBSKILL_AFTER_INVOKE emitted.
5. Validate — quality gates checked; on failure the router re-dispatches.
6. Continue — next sub-skill or error handling.

Error Handling

If a sub-skill fails:

1. Hook — SUBSKILL_ON_FAILURE emitted (audit trail records it).
2. Retry — up to 3 attempts with exponential backoff.
3. Fallback — graceful degradation to a lower quality level.
4. Recovery — continue with the next sub-skill if non-critical.
5. Failure — if critical, halt and emit SKILL_ON_ERROR.

Input/Output Schemas

Generic Skill Input

interface SkillInput {
  skill_name: string;
  parameters: Record;
  context: {
    execution_id: string;
    language: string;            // "en" | "vi"
    degradation_level: number;   // 0-4
    metadata: Record;
  };
}

Generic Skill Output

interface SkillOutput {
  success: boolean;
  skill_name: string;
  result: {
    data: any;
    metadata: Record;
  };
  gates_passed: string[];
  gates_failed: string[];
  execution_time_ms: number;
  timestamp: string;            // ISO 8601
}

Skill-Specific Schemas

sub-gather-requirements

Input:

{
  raw_message: string;
  provided_materials: any[];
}

Output:

{
  object: string;              // e.g. "Bat Trang ceramics village tourism plan"
  scope: string;
  timeframe: string;
  available_inputs: any[];
  target_audience: string;
  language: string;            // "en" | "vi"
  analysis_type: string;       // default "combined"
}

sub-evidence-collector

Input:

{ requirements: object; }      // from sub-gather-requirements

Output:

{
  current_data: any[];
  authoritative_docs: any[];
  recent_news: any[];
  reference_benchmarks: any[];
  sources: Array;
}

sub-core-analysis

Input:

{
  village: string;
  craft: string;
  capacity: object;            // carrying-capacity inputs
  community: object;           // community-benefit inputs
  language: string;
}

Output:

{
  village_profile: object;
  authentic_experiences: object;   // from experience_design tool
  interpretation_storytelling: string[];
  community_benefit_ip: object;    // from community_benefit tool
  carrying_capacity: object;       // from carrying_capacity tool
  sustainability_marketing: object;
  scenarios: {best: object, base: object, worst: object};
}

sub-knowledge-updater

Input:

{ keywords: string[]; max_results?: number; }

Output:

{
  citations: Array;
  gaps: string[];
  coverage_rating: string;   // "Strong" | "Moderate" | "Weak"
}

sub-advisor

Input:

{
  core_analysis: object;
  evidence_bundle: object;
  knowledge_evidence: object;
}

Output:

{
  conclusion: string;  // "Sustainable Plan" | "Conditional (capacity)" | "Over-Commercialization Risk" | "Inconclusive"
  scenarios: {best: object, base: object, worst: object};
  key_risks: Array;
  evidence_chain: Array;
  remediation: string[];
  disclosure: string;
}

Quality Gate Validation

Gate Enforcement

1. Pre-hook — GATE_BEFORE_CHECK emitted.
2. Check — gate condition evaluated.
3. Decision — pass or fail.
4. Auto-fix — if enabled and failed, attempt auto-fix.
5. Retry — re-check after auto-fix (max 2 retries).
6. Post-hook — GATE_AFTER_CHECK emitted.
7. Failure — GATE_ON_FAILURE emitted; limitation notice added.

Universal Gates (U1-U6)

| Gate | Condition | Auto-Fix | |------|-----------|----------| | U1 | ≥3 sources cited, ≥1 academic/authoritative | Fetch from knowledge base | | U2 | Disclosure before recommendation | Prepend disclosure | | U3 | Evidence hierarchy per source | Annotate tiers | | U4 | Language matches user preference | Translate output | | U5 | Output uses template | Reformat | | U6 | Every claim traceable | Flag unsupported |

Domain Gates (G1-G4)

| Gate | Condition | Auto-Fix | |------|-----------|----------| | G1 | Authentic experiences designed | Invoke experience_design tool | | G2 | Community benefit & artisan IP | Invoke community_benefit tool | | G3 | Carrying capacity & infrastructure | Invoke carrying_capacity tool | | G4 | Sustainability & marketing | Add sustainability/marketing block |

Tool Integration

Tool Invocation

from config.tools import register_builtin_tools, get_tool_registry

register_builtin_tools()
registry = get_tool_registry()

result = registry.execute(
    "carrying_capacity",
    usable_area_m2=2000,
    ecological_weight=0.6,
)
if result.success:
    report = result.data
else:
    error = result.error

Available Tools

See config/tools.py for complete definitions:

| Tool | Category | Purpose | |------|----------|---------| | websearch | datafetch | Search web for current craft-village / ICH / artisan evidence | | knowledgequery | knowledgequery | In-process search over SECOND-KNOWLEDGE-BRAIN.md | | carryingcapacity | analysis | Physical/Real/Ecological carrying-capacity model | | communitybenefit | analysis | Community benefit & artisan IP scoring (0-10) | | experience_design | analysis | Authentic experience module plan + interpretation hooks |

Configuration Integration

from config import get_config, FeatureFlag

config = get_config()
model = config.llm.model_name
budget = config.available_context_budget()
if config.is_feature_enabled(FeatureFlag.ENABLE_CARRYING_CAPACITY_MODEL):
    pass  # use carrying_capacity tool

Feature Flags

| Flag | Effect | |------|--------| | ENABLEWEBSEARCH | Allow live web search | | ENABLESEMANTICSCHOLAR | Allow Semantic Scholar crawl | | ENABLEARXIVCRAWL | Allow ArXiv crawl | | ENABLERSSFEEDS | Allow RSS ingestion | | ENABLEAUTOUPDATE | Allow scheduled knowledge updates | | ENABLEGRACEFULDEGRADATION | Allow degradation fallbacks | | ENABLESTRICTMODE | Fail-fast on any gate failure | | ENABLECOMMUNITYBENEFITCHECK | Enforce G2 via community_benefit tool | | ENABLECARRYINGCAPACITYMODEL | Enforce G3 via carrying_capacity tool |

Performance Monitoring

from config.logging import get_logger

logger = get_logger("skill_execution")
with logger.performance_tracking("sub-core-analysis"):
    result = execute_skill("sub-core-analysis", **params)

Statistics:

from config.tools import get_tool_registry
stats = get_tool_registry().get_stats("carrying_capacity")
print(stats["execution_count"], stats["avg_execution_time_ms"])

Context-Window Management

The harness bounds token consumption by:

• Reserving reserved_output_tokens (default 4096) from the model context window.
• Sizing evidence/knowledge payloads against available_context_budget().
• Streaming sub-skill outputs as compact structured envelopes (see schemas) instead of full prose until the final synthesis step.
• Capping knowledge citations at 3-5 entries and news items at 2-3 per run.

Extension Points

Adding a New Skill

1. Create skills/new-skill.md with proper frontmatter.
2. Implement required sections (Role, Workflow, Tools, Output, Gates).
3. Add input/output schemas to this document.
4. Register in main.md if it is a sub-skill.
5. Add a test scenario to tests/test-scenarios.md.

Adding a New Tool

1. Define the ToolSchema in config/tools.py.
2. Implement a ToolHandler subclass with a real execute().
3. Register it in register_builtin_tools().
4. Document input/output in this SKILL.md.
5. Add usage examples.

Adding a New Hook

1. Add the event to HookEvent in config/hooks.py.
2. Register a handler at the appropriate lifecycle point.
3. Document the hook purpose and context.
4. Add test coverage for the hook behavior.

Validation

Skill Validation

1. Frontmatter — must include name and description.
2. Sections — must include required sections.
3. Schema — input/output must match defined schemas.
4. Gates — must specify quality gates.
5. Tools — must specify required tools.

Configuration Validation

from config import get_config, validate_config
errors = validate_config(get_config())
if errors:
    for e in errors:
        print("Validation error: " + e)

References

• Main Skill — skills/main.md
• Sub-Skills — skills/sub-*.md
• Tool Definitions — config/tools.py
• Hook System — config/hooks.py
• Logging — config/logging.py
• Configuration — config/__init__.py
• JSON Schemas — assets/schemas.json
• Domain Methods — references/domain-methods.md
• Prompt Templates — references/prompt-templates.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/craft-village-heritage-tourism-agent-skill
• License: MIT

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