# Config

> A Claude skill from dungnotnull/craft-village-heritage-tourism-agent-skill.

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-craft-village-heritage-tourism-agent-skill-config`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dungnotnull](https://agentstack.voostack.com/s/dungnotnull)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** https://github.com/dungnotnull/craft-village-heritage-tourism-agent-skill/tree/main/config

## Install

```sh
agentstack add skill-dungnotnull-craft-village-heritage-tourism-agent-skill-config
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```yaml
---
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

```typescript
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

```typescript
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:**
```typescript
{
  raw_message: string;
  provided_materials: any[];
}
```

**Output:**
```typescript
{
  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:**
```typescript
{ requirements: object; }      // from sub-gather-requirements
```

**Output:**
```typescript
{
  current_data: any[];
  authoritative_docs: any[];
  recent_news: any[];
  reference_benchmarks: any[];
  sources: Array;
}
```

#### sub-core-analysis

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

**Output:**
```typescript
{
  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:**
```typescript
{ keywords: string[]; max_results?: number; }
```

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

#### sub-advisor

**Input:**
```typescript
{
  core_analysis: object;
  evidence_bundle: object;
  knowledge_evidence: object;
}
```

**Output:**
```typescript
{
  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

```python
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 |
|------|----------|---------|
| web_search | data_fetch | Search web for current craft-village / ICH / artisan evidence |
| knowledge_query | knowledge_query | In-process search over `SECOND-KNOWLEDGE-BRAIN.md` |
| carrying_capacity | analysis | Physical/Real/Ecological carrying-capacity model |
| community_benefit | analysis | Community benefit & artisan IP scoring (0-10) |
| experience_design | analysis | Authentic experience module plan + interpretation hooks |

## Configuration Integration

```python
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 |
|------|--------|
| ENABLE_WEB_SEARCH | Allow live web search |
| ENABLE_SEMANTIC_SCHOLAR | Allow Semantic Scholar crawl |
| ENABLE_ARXIV_CRAWL | Allow ArXiv crawl |
| ENABLE_RSS_FEEDS | Allow RSS ingestion |
| ENABLE_AUTO_UPDATE | Allow scheduled knowledge updates |
| ENABLE_GRACEFUL_DEGRADATION | Allow degradation fallbacks |
| ENABLE_STRICT_MODE | Fail-fast on any gate failure |
| ENABLE_COMMUNITY_BENEFIT_CHECK | Enforce G2 via `community_benefit` tool |
| ENABLE_CARRYING_CAPACITY_MODEL | Enforce G3 via `carrying_capacity` tool |

## Performance Monitoring

```python
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:

```python
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

```python
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](https://github.com/dungnotnull)
- **Source:** [dungnotnull/craft-village-heritage-tourism-agent-skill](https://github.com/dungnotnull/craft-village-heritage-tourism-agent-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dungnotnull-craft-village-heritage-tourism-agent-skill-config
- Seller: https://agentstack.voostack.com/s/dungnotnull
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.