Skill Registry Arid Irrigation

SKILL.md — Skill Registry for arid-region-water-saving-irrigation

Overview

This registry documents the complete skill architecture for the arid-region-water-saving-irrigation harness. It defines how skills are registered, resolved, executed, and validated with full JSON schemas for inputs/outputs.

Skill Architecture Pattern

┌─────────────────────────────────────────────────────────────────┐
│                     SKILL REGISTRY                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   Main       │  │   Sub-Skill   │  │    Utility    │          │
│  │   Harness    │─│   Registry    │─│    Skills     │          │
│  │              │  │              │  │              │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
         │                       │                    │
         ▼                       ▼                    ▼
    [Router]            [Resolver]          [Executor]
         │                       │                    │
    [Hooks]               [Validation]        [Logging]
         │                       │                    │
    [Config]              [Schemas]          [Metrics]

Registered Skills

Main Harness Skill

| Property | Value | |----------|-------| | Name | arid-region-water-saving-irrigation | | Path | skills/main.md | | Type | orchestrator | | Version | 1.0.0 | | Trigger | /arid-region-water-saving-irrigation [query] |

Input Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Natural language query about arid-region irrigation",
      "minLength": 1
    },
    "language": {
      "type": "string",
      "enum": ["en", "vi", "auto"],
      "default": "auto",
      "description": "Output language preference"
    },
    "context": {
      "type": "object",
      "properties": {
        "location": {"type": "string"},
        "crop": {"type": "string"},
        "climate": {"type": "string"},
        "soil": {"type": "string"},
        "water_quality": {"type": "string"}
      },
      "additionalProperties": true
    }
  },
  "required": ["query"]
}

Output Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "report": {
      "type": "object",
      "properties": {
        "executive_summary": {"type": "string"},
        "inputs_and_scope": {"type": "object"},
        "evidence_collected": {"type": "array"},
        "analysis": {"type": "object"},
        "action_plan": {"type": "array"},
        "academic_evidence": {"type": "array"},
        "disclosure": {"type": "string"},
        "recommendation": {"type": "object"}
      },
      "required": ["executive_summary", "disclosure", "recommendation"]
    },
    "metadata": {
      "type": "object",
      "properties": {
        "version": {"type": "string"},
        "timestamp": {"type": "string"},
        "language": {"type": "string"},
        "degradation_level": {"type": "integer", "minimum": 0, "maximum": 4},
        "gates_passed": {"type": "array", "items": {"type": "string"}},
        "execution_time_ms": {"type": "number"}
      }
    }
  }
}

Sub-Skills

| Name | Path | Type | Input Schema | Output Schema | |------|------|------|--------------|---------------| | sub-gather-requirements | skills/sub-gather-requirements.md | intake | RequirementsInput | RequirementsOutput | | sub-evidence-collector | skills/sub-evidence-collector.md | data | EvidenceInput | EvidenceOutput | | sub-core-analysis | skills/sub-core-analysis.md | analysis | AnalysisInput | AnalysisOutput | | sub-knowledge-updater | skills/sub-knowledge-updater.md | knowledge | KnowledgeInput | KnowledgeOutput | | sub-advisor | skills/sub-advisor.md | synthesis | SynthesisInput | SynthesisOutput |

Sub-Skill Input/Output Schemas

RequirementsInput:

{
  "raw_message": "string",
  "provided_materials": "array"
}

RequirementsOutput:

{
  "object": "string",
  "scope": "string",
  "timeframe": "string",
  "available_inputs": "object",
  "target_audience": "string",
  "language": "string",
  "analysis_type": "string"
}

EvidenceInput:

{
  "requirements": "RequirementsOutput",
  "sources": "array",
  "max_age_days": "integer"
}

EvidenceOutput:

{
  "current_data": "array",
  "authoritative_docs": "array",
  "recent_news": "array",
  "reference_benchmarks": "array",
  "access_timestamp": "string"
}

Skill Resolution Process

1. Registration

Skills are registered in config/skills_registry.json:

{
  "registry_version": "1.0.0",
  "skills": [
    {
      "name": "arid-region-water-saving-irrigation",
      "type": "orchestrator",
      "path": "skills/main.md",
      "version": "1.0.0",
      "enabled": true,
      "dependencies": [],
      "hooks": {
        "pre_execution": "hooks/pre_execution.py",
        "post_execution": "hooks/post_execution.py",
        "on_error": "hooks/on_error.py"
      },
      "metadata": {
        "domain": "Arid-Region Irrigation & Water-Efficiency Engineering",
        "quality_gates": ["U1", "U2", "U3", "U4", "U5", "U6", "G1", "G2", "G3", "G4"],
        "languages": ["en", "vi"]
      }
    }
  ],
  "sub_skills": [
    {
      "name": "sub-gather-requirements",
      "parent": "arid-region-water-saving-irrigation",
      "type": "intake",
      "path": "skills/sub-gather-requirements.md",
      "execution_order": 1
    },
    {
      "name": "sub-evidence-collector",
      "parent": "arid-region-water-saving-irrigation",
      "type": "data",
      "path": "skills/sub-evidence-collector.md",
      "execution_order": 2
    },
    {
      "name": "sub-core-analysis",
      "parent": "arid-region-water-saving-irrigation",
      "type": "analysis",
      "path": "skills/sub-core-analysis.md",
      "execution_order": 3
    },
    {
      "name": "sub-knowledge-updater",
      "parent": "arid-region-water-saving-irrigation",
      "type": "knowledge",
      "path": "skills/sub-knowledge-updater.md",
      "execution_order": 4
    },
    {
      "name": "sub-advisor",
      "parent": "arid-region-water-saving-irrigation",
      "type": "synthesis",
      "path": "skills/sub-advisor.md",
      "execution_order": 5
    }
  ]
}

2. Resolution

The skill resolver performs the following steps:

def resolve_skill(skill_name: str, registry: dict) -> SkillDefinition:
    """
    Resolve a skill from the registry.
    
    Steps:
    1. Look up skill_name in registry
    2. Validate skill is enabled
    3. Load skill file
    4. Parse frontmatter (name, description)
    5. Validate against schema
    6. Return SkillDefinition object
    """
    pass

3. Execution

The skill executor:

async def execute_skill(
    skill: SkillDefinition,
    input_data: dict,
    context: ExecutionContext
) -> dict:
    """
    Execute a skill with full lifecycle hooks.
    
    Steps:
    1. pre_execution hook
    2. Validate input against schema
    3. Execute skill logic
    4. Validate output against schema
    5. post_execution hook
    6. Log metrics
    7. Return output
    """
    pass

Lifecycle Hooks

Hook Types

| Hook Type | Timing | Purpose | Example | |------------|--------|---------|---------| | pre_execution | Before skill execution | Input validation, state initialization | Validate required inputs | | post_execution | After skill execution | Output validation, metrics collection | Log execution metrics | | on_error | On error during execution | Error recovery, graceful degradation | Fallback to knowledge base | | pre_validation | Before quality gate validation | Prepare validation context | Collect validation artifacts | | post_validation | After quality gate validation | Handle validation failures | Trigger auto-fix logic |

Hook Implementation Pattern

# hooks/pre_execution.py
async def pre_execution_hook(
    skill_name: str,
    input_data: dict,
    context: ExecutionContext
) -> HookResult:
    """
    Pre-execution hook for skill validation and setup.
    
    Returns:
        HookResult with modified_input_data and metadata
    """
    logger.info(f"Pre-execution hook for {skill_name}")
    
    # Validate language setting
    language = detect_language(input_data.get("query", ""))
    context.state["language"] = language
    
    # Initialize degradation level
    context.state["degradation_level"] = 0
    
    return HookResult(
        success=True,
        modified_input_data=input_data,
        metadata={"language": language}
    )

Quality Gate Validation

Gate Definitions

Quality gates are defined in config/quality_gates.json:

{
  "universal_gates": [
    {
      "id": "U1",
      "name": "Source Count",
      "check": "sources_count >= 3",
      "auto_fix": "fetch_from_knowledge_base",
      "max_retries": 2
    },
    {
      "id": "U2",
      "name": "Disclosure Present",
      "check": "disclosure_section_exists",
      "auto_fix": "prepend_disclosure",
      "max_retries": 1
    },
    {
      "id": "U3",
      "name": "Evidence Hierarchy",
      "check": "all_sources_have_tier_labels",
      "auto_fix": "annotate_source_tiers",
      "max_retries": 1
    },
    {
      "id": "U4",
      "name": "Language Match",
      "check": "output_language == input_language",
      "auto_fix": "translate_output",
      "max_retries": 1
    },
    {
      "id": "U5",
      "name": "Template Compliance",
      "check": "all_required_sections_present",
      "auto_fix": "reformat_to_template",
      "max_retries": 1
    },
    {
      "id": "U6",
      "name": "Claim Traceability",
      "check": "every_claim_has_source_or_judgment_flag",
      "auto_fix": "flag_unsupported_claims",
      "max_retries": 1
    }
  ],
  "domain_gates": [
    {
      "id": "G1",
      "name": "ETc Computed",
      "check": "etc_computed_via_penman_monteith",
      "auto_fix": "compute_etc",
      "max_retries": 1
    },
    {
      "id": "G2",
      "name": "Soil-Water Balance",
      "check": "irrigation_from_soil_balance",
      "auto_fix": "schedule_from_balance",
      "max_retries": 1
    },
    {
      "id": "G3",
      "name": "Salinity Managed",
      "check": "salinity_leaching_addressed",
      "auto_fix": "manage_salinity",
      "max_retries": 1
    },
    {
      "id": "G4",
      "name": "Automation Specified",
      "check": "automation_sensors_specified",
      "auto_fix": "specify_automation",
      "max_retries": 1
    }
  ]
}

Validation Process

async def validate_quality_gates(
    output: dict,
    gates: List[QualityGate],
    context: ExecutionContext
) -> ValidationResult:
    """
    Validate output against all quality gates.
    
    Process:
    1. For each gate in order:
       a. Evaluate check against output
       b. If failed, attempt auto_fix
       c. Retry up to max_retries
       d. If still failed, flag limitation
    2. Return ValidationResult with passed/failed gates
    """
    pass

Configuration Management

Configuration Schema

Configuration is managed through config/settings.json:

{
  "$schema": "config/schemas/settings.json",
  "version": "1.0.0",
  "skill": {
    "name": "arid-region-water-saving-irrigation",
    "version": "1.0.0",
    "environment": "production"
  },
  "execution": {
    "timeout_seconds": 300,
    "max_retries": 3,
    "retry_delay_ms": 1000,
    "enable_parallel_execution": true
  },
  "logging": {
    "level": "INFO",
    "format": "json",
    "outputs": ["console", "file"],
    "file_path": "logs/skill_execution.log"
  },
  "quality": {
    "strict_mode": false,
    "auto_fix_enabled": true,
    "max_degradation_level": 4
  },
  "knowledge": {
    "update_schedule": "weekly",
    "cache_duration_hours": 168
  },
  "features": {
    "enable_caching": true,
    "enable_metrics": true,
    "enable_tracing": false
  }
}

Error Handling & Graceful Degradation

Degradation Levels

| Level | Condition | Behavior | |-------|-----------|----------| | 0 | All primary sources reachable | Full evidenced analysis | | 1 | Some primary sources fail | Use secondary sources; flag substitutions | | 2 | Most live sources fail | Knowledge base only; flag historical context | | 3 | Required input missing | Proceed with available; mark unavailable | | 4 | All sources and KB fail | Emit DATA UNAVAILABLE; no fabrication |

Error Recovery

async def recover_from_error(
    error: Exception,
    context: ExecutionContext,
    degradation_level: int
) -> RecoveryResult:
    """
    Recover from errors with graceful degradation.
    
    Strategy:
    1. Identify error type
    2. Determine recovery action based on degradation level
    3. Execute recovery
    4. Update degradation level
    5. Log recovery action
    """
    pass

Metrics & Monitoring

Collected Metrics

| Metric | Type | Description | |--------|------|-------------| | execution_time_ms | histogram | Skill execution time | | gate_validation_count | counter | Number of gates validated | | gate_failure_count | counter | Number of gate failures | | degradation_level | gauge | Current degradation level | | source_fetch_count | counter | Number of sources fetched | | knowledge_base_hit_count | counter | Number of KB hits |

Extending the Registry

To add a new skill:

1. Create skill file in skills/
2. Add entry to config/skills_registry.json
3. Define input/output schemas
4. Implement lifecycle hooks
5. Add quality gates if applicable
6. Test with tools/test_skill_execution.py

---

Registry Version: 1.0.0 Last Updated: 2026-07-27 Maintained By: arid-region-water-saving-irrigation development team

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/arid-region-water-saving-irrigation-agent-skill
• License: MIT

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