Ai Coastal Erosion Monitoring

SKILL.md — Skill Registry Documentation

Skill Registration & Resolution

Registration Process

Skills in the ai-coastal-erosion-monitoring system are registered through a hierarchical registry pattern. Each skill has metadata that determines when and how it's invoked:

1. Frontmatter Registry (required): All skills MUST include YAML frontmatter with name

and description fields. The description is the PRIMARY triggering mechanism — it must clearly state both what the skill does AND the contexts in which it should be used.

1. Registry Hierarchy:

`` Main Skill (main.md) ├── Sub-Skills (sub-*.md) — invoked via Skill() tool └── Bundled Resources — loaded on-demand ``

1. Resolution Order:

• Frontmatter is loaded first (~100 words, always in context)
• SKILL.md body is loaded when skill triggers ( None:

"""Called before skill execution starts."""

def beforesubskill(ctx: SkillContext, sub_skill: str) -> None: """Called before each sub-skill invocation."""

def aftersubskill(ctx: SkillContext, sub_skill: str, result: Any) -> Any: """Called after each sub-skills completes."""

def on_degradation(ctx: SkillContext, level: int) -> None: """Called when degradation level changes."""

def beforequalitygate(ctx: SkillContext, gate: str) -> None: """Called before each quality gate check."""

def after_execution(ctx: SkillContext, result: Any) -> Any: """Called after skill execution completes."""

### State Synchronization

The skill maintains execution state across sub-skills:

```python
class SkillContext:
    query: str
    language: str
    requirements: Dict
    evidence_bundle: Dict
    analysis_scorecard: Dict
    knowledge_entries: List
    degradation_level: int
    gates_status: Dict[str, bool]

Configuration Management

Environment-Based Configuration

The system supports environment-specific configuration:

# Development
config/environment/development.json

# Staging
config/environment/staging.json

# Production
config/environment/production.json

Feature Flags

Optional functionality can be toggled via feature flags:

{
  "features": {
    "enable_experimental_ai": false,
    "enable_degraded_mode": true,
    "enable_multi_language": true,
    "enable_auto_crawl": true,
    "enable_caching": true
  }
}

Monitoring & Logging

Structured Logging

All operations emit structured logs:

{
  "timestamp": "2026-07-15T10:30:00Z",
  "level": "INFO",
  "component": "sub-core-analysis",
  "operation": "compute_shoreline_change",
  "correlation_id": "uuid",
  "duration_ms": 1250,
  "metadata": {
    "location": "Vietnam_Coast",
    "imagery_source": "Sentinel-2"
  }
}

Metrics Tracking

Key metrics tracked:

• Execution time per sub-skill
• Degradation level distribution
• Quality gate pass/fail rates
• Source availability
• Token usage

Extension Points

Adding New Sub-Skills

To add a new sub-skill:

1. Create skills/sub-new-skill.md with proper frontmatter
2. Define input/output JSON schemas in this SKILL.md
3. Update main.md to invoke the sub-skill
4. Add quality gates if applicable
5. Update test scenarios

Adding New Data Sources

To add a new data source:

1. Update config/default.config.json sources section
2. Update SECOND-KNOWLEDGE-BRAIN.md sources section
3. Update CLAUDE.md knowledge sources section
4. Test with degraded mode scenarios

Modifying Quality Gates

To modify quality gates:

1. Update config/default.config.json quality_gates section
2. Update skills/main.md quality gates table
3. Update PROJECT-detail.md gates definition
4. Test with gate failure scenarios

Testing Strategy

Test Scenarios

The system includes 5+ test scenarios in tests/test-scenarios.md:

1. Standard analysis (full data availability)
2. Minimal input (partial data)
3. Comparison (multiple locations)
4. Risk/conflict (conflicting data)
5. Degraded mode (source failures)

Validation Tools

# Validate project structure
python scripts/validate.py

# Run test scenarios
python tools/run_test_scenarios.py --all

# Test knowledge updater
python tools/test_knowledge_updater.py

Performance Optimization

Context Window Management

The skill implements progressive disclosure to manage context:

1. Frontmatter only (~100 words) — Always loaded
2. SKILL.md body (~500 lines) — Loaded on trigger
3. Sub-skill files — Loaded on invocation
4. Reference materials — Loaded on demand

Caching Strategy

• Knowledge base entries cached for 24 hours
• Source responses cached with TTL
• LLM responses cached when idempotent

Troubleshooting

Common Issues

Issue: Skill not triggering

• Cause: Description not matching user intent
• Fix: Optimize description with trigger eval queries

Issue: Quality gate failures

• Cause: Data unavailability or logic error
• Fix: Check degradation level, source availability

Issue: Sub-skill timeout

• Cause: External source slow or unavailable
• Fix: Check network, enable degraded mode

Debug Mode

Enable debug logging:

{
  "logging": {
    "level": "DEBUG",
    "format": "json"
  }
}

Version Compatibility

This skill is compatible with:

• Claude Code: All versions supporting Skill tool
• Claude.ai: With limitations (no subagent support)
• Python: 3.11+
• Claude Models: Opus 4.7, Sonnet 4.6, Haiku 4.5

License

MIT License — See LICENSE file for details.

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/ai-coastal-erosion-monitoring-agent-skill
• License: MIT

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