Survival Open World Resource Strategy Agent Skill

SKILL.md Registry Documentation

Comprehensive documentation of skill registration, resolution, execution, and validation patterns

What is the SKILL.md Registry?

The SKILL.md Registry is a comprehensive catalog of all skills in the survival-open-world-resource-strategy project. It provides:

• Skill Registration: How each skill is defined and registered
• Skill Resolution: How Claude determines which skill to invoke
• Skill Execution: The orchestration pattern for skill execution
• Skill Validation: Quality gates and validation mechanisms
• Input/Output Schemas: JSON schemas for all skill interfaces

---

Skill Registration

Main Skill: survival-open-world-resource-strategy

name: survival-open-world-resource-strategy
description: Resource-Management Strategy for Survival Open-World Games — Survival-Game Resource Optimization & Decision Support evidence-backed analysis harness.
version: 2.0.0
status: production
type: main_harness

Registration Point: skills/main.md

Triggering Pattern:

• User invokes via /survival-open-world-resource-strategy [query]
• Skill description matches intent analysis
• Domain keywords detected: ["survival", "game", "resource", "strategy", "optimization"]

Dependencies:

• Sub-skills: 5 registered sub-skills
• Tools: WebSearch, WebFetch, Read, Write, Bash, Skill
• External: SECOND-KNOWLEDGE-BRAIN.md, knowledge_updater.py

---

Sub-Skills Registry

| Skill Name | File | Purpose | Trigger Condition | |------------|------|---------|-------------------| | sub-gather-requirements | skills/sub-gather-requirements.md | Clarify analysis scope | Step 1 of harness | | sub-evidence-collector | skills/sub-evidence-collector.md | Fetch authoritative data | Step 2 of harness | | sub-core-analysis | skills/sub-core-analysis.md | Analyze resource strategy | Step 3 of harness | | sub-knowledge-updater | skills/sub-knowledge-updater.md | Query knowledge base | Step 4 of harness | | sub-advisor | skills/sub-advisor.md | Synthesize recommendation | Step 5 of harness |

Sub-Skill Registration Pattern:

name: sub-{purpose}
description: {One-line summary of purpose}
version: 1.0.0
status: production
type: sub_skill
parent: survival-open-world-resource-strategy
execution_step: {1-5}

Sub-Skill Resolution:

• Main harness invokes sequentially (Steps 1-5)
• Each sub-skill completes before next begins
• Quality gates enforce step completion

---

Skill Resolution Mechanism

Intent Analysis

When user input is received, the skill resolution engine:

1. Parse Input: Extract keywords, context, and intent
2. Match Pattern: Compare against skill descriptions
3. Score Candidates: Rank by relevance (0.0-10.0)
4. Select Winner: Choose highest-scoring skill
5. Invoke: Execute selected skill with parameters

Scoring Algorithm

def score_skill_match(user_input: str, skill_description: str) -> float:
    """Calculate relevance score (0.0-10.0) for skill invocation."""

    # Extract keywords from input
    input_keywords = extract_keywords(user_input)

    # Domain keyword matching (40% weight)
    domain_hits = sum(1 for kw in DOMAIN_KEYWORDS if kw in user_input.lower())
    domain_score = (domain_hits / len(DOMAIN_KEYWORDS)) * 4.0

    # Description similarity (30% weight)
    desc_similarity = semantic_similarity(user_input, skill_description) * 3.0

    # Context clues (20% weight)
    context_score = detect_context_clues(user_input) * 2.0

    # Explicit invocation (10% weight)
    explicit_score = 1.0 if "/survival" in user_input else 0.0

    return min(domain_score + desc_similarity + context_score + explicit_score, 10.0)

Domain Keywords:

DOMAIN_KEYWORDS = [
    "survival", "game", "resource", "strategy", "optimization",
    "minecraft", "rust", "valheim", "don't starve",
    "gathering", "inventory", "base", "economy",
    "pvp", "pve", "raid", "defense", "efficiency"
]

Resolution Flow

USER INPUT → Intent Analysis → Skill Scoring → Threshold Check (≥5.0) → Skill Invocation
                                   ↓
                              No Match?
                                   ↓
                            Ask for clarification

---

Skill Execution Protocol

Main Harness Execution

The main harness executes in strict sequential order:

Step 1: sub-gather-requirements
    ↓ (gate: object confirmed)
Step 2: sub-evidence-collector
    ↓ (gate: data retrieved)
Step 3: sub-core-analysis
    ↓ (gate: efficiency quantified)
Step 4: sub-knowledge-updater
    ↓ (gate: citations surfaced)
Step 5: sub-advisor
    ↓ (gate: verdict assigned)
Step 6: Quality Gate Review
    ↓ (all gates pass)
Final Output

Sub-Skill Execution Pattern

Each sub-skill follows this pattern:

1. Receive Input: Get structured input from previous step
2. Execute Workflow: Follow skill-specific workflow
3. Validate Output: Check against quality gate
4. Return Result: Pass to next step

Input Passing:

• Step 1 → Step 2: Requirements object
• Step 2 → Step 3: Evidence bundle
• Step 3 → Step 4: Analysis keywords
• Step 4 → Step 5: Core analysis + citations
• Step 5 → Final: Verdict + recommendation

Error Handling During Execution

| Error Type | Detection | Recovery | Continue? | |------------|-----------|----------|-----------| | Sub-skill timeout | No response 60s | Retry 2x, then fallback | Yes (with flag) | | Invalid input | Schema validation fails | Ask user | No | | Missing input | Required field absent | Use default + flag | Yes | | Gate failure | Quality gate not met | Auto-fix 2x | Yes (with flag) |

---

Skill Validation

Quality Gate System

Universal Gates (U1-U6):

• U1: ≥3 sources cited, ≥1 academic/authoritative
• U2: Disclosure before recommendation
• U3: Evidence hierarchy per source
• U4: Language match user preference
• U5: Use declared template
• U6: Claims traceable or flagged

Domain Gates (G1-G4):

• G1: Gathering quantified (yield/time)
• G2: Inventory & base specified
• G3: Risk-reward addressed
• G4: Economy covered

Gate Enforcement

def enforce_quality_gates(output: dict) -> tuple[bool, list[str]]:
    """Enforce all quality gates.

    Returns:
        (all_passed, limitation_flags)
    """
    gates = load_gates()  # U1-U6, G1-G4

    all_passed = True
    limitation_flags = []

    for gate_name, gate_check in gates.items():
        passed, details = gate_check(output)

        if not passed:
            # Attempt auto-fix
            fixed = attempt_auto_fix(gate_name, output)

            if not fixed:
                all_passed = False
                limitation_flags.append(f"{gate_name}: {details}")

    return all_passed, limitation_flags

Validation Results

Pass: All gates clear → Deliver output Pass with Limitations: Some gates failed after auto-fix → Deliver with limitation notice Fail: Critical gates failed → Emit error notice, do not deliver

---

Input/Output Schemas

Schema Registry

All schemas are defined in assets/schemas.md and available as JSON Schema:

| Schema Name | Purpose | File | |-------------|---------|------| | SkillInput | Main skill input | assets/schemas.md (Schema 1) | | RequirementsOutput | Step 1 output | assets/schemas.md (Schema 2) | | EvidenceBundle | Step 2 output | assets/schemas.md (Schema 3) | | CoreAnalysisOutput | Step 3 output | assets/schemas.md (Schema 4) | | KnowledgeCitation | Step 4 output | assets/schemas.md (Schema 5) | | AdvisorVerdict | Step 5 output | assets/schemas.md (Schema 6) | | QualityGateResult | Gate verification | assets/schemas.md (Schema 7) | | FinalReport | Complete output | assets/schemas.md (Schema 8) |

Schema Validation

Input Validation (Step 1):

def validate_skill_input(user_input: dict) -> bool:
    """Validate user input against SkillInput schema."""
    schema = load_schema("SkillInput")
    return validate(instance=user_input, schema=schema)

Output Validation (Final):

def validate_final_output(output: dict) -> bool:
    """Validate final output against FinalReport schema."""
    schema = load_schema("FinalReport")
    return validate(instance=output, schema=schema)

Schema Evolution

Version Policy:

• Schemas version with the skill (e.g., 2.0.0)
• Breaking changes: Increment major version
• Additions only: Increment minor version
• Backward compatible: Increment patch version

---

Skill Lifecycle

Skill States

DRAFT → TESTING → VALIDATION → PRODUCTION → DEPRECATED
        ↓                                      ↓
     FAILED                                ARCHIVED

State Definitions:

• DRAFT: Initial skill development
• TESTING: Internal testing and validation
• VALIDATION: External validation and feedback
• PRODUCTION: Live deployment
• DEPRECATED: Scheduled for removal
• FAILED: Abandoned development
• ARCHIVED: Historical reference

Lifecycle Events

| Event | Trigger | Action | |-------|---------|--------| | Skill Created | New skill file written | Register in SKILL.md | | Skill Updated | Skill file modified | Update version, trigger tests | | Skill Validated | All tests pass | Move to PRODUCTION state | | Skill Deprecated | Decision to remove | Add notice, schedule removal |

---

Hooks System

Hook Points

The skill system provides hooks at key execution points:

| Hook Name | Trigger | Parameters | Return | |------------|---------|-------------|--------| | before_execute | Before skill invocation | skillname, input | Modified input or None | | after_execute | After skill completion | skillname, output | Modified output or None | | on_error | On skill execution error | skillname, error | Recovery action or None | | before_gate_check | Before quality gate verification | gatename, output | Modified output or None | | after_gate_check | After quality gate verification | gate_result | None |

Hook Implementation

Hook Definition:

def before_execute_hook(skill_name: str, input: dict) -> dict | None:
    """Hook called before skill execution.

    Args:
        skill_name: Name of skill being invoked
        input: Input parameters for the skill

    Returns:
        Modified input, or None to proceed unchanged
    """
    # Example: Log skill invocation
    logger.info("Invoking skill: %s with input: %s", skill_name, input)
    return None  # Proceed unchanged

Hook Registration:

# Register hooks in config/hooks.yaml
hooks:
  before_execute:
    - logger.log_invocation
    - validator.check_input
  after_execute:
    - logger.log_completion
  on_error:
    - recovery.retry_fallback

---

Dynamic Tool Invocation

Tool Registration

Tools are registered in the main skill definition:

tools:
  - name: WebSearch
    purpose: Fetch real-time domain data
    required: true
  - name: WebFetch
    purpose: Retrieve specific documents
    required: true
  - name: Read
    purpose: Access knowledge base
    required: true
  - name: Write
    purpose: Append knowledge entries
    required: false
  - name: Bash
    purpose: Run knowledge updater
    required: false
  - name: Skill
    purpose: Invoke sub-skills
    required: true

Tool Invocation Pattern

def invoke_tool(tool_name: str, parameters: dict) -> any:
    """Dynamically invoke a registered tool.

    Args:
        tool_name: Name of tool to invoke
        parameters: Tool-specific parameters

    Returns:
        Tool result or error

    Raises:
        ToolNotFoundError: If tool not registered
        ToolInvocationError: If invocation fails
    """
    tool = get_tool(tool_name)

    if tool is None:
        raise ToolNotFoundError(f"Tool not found: {tool_name}")

    try:
        return tool.execute(**parameters)
    except Exception as e:
        raise ToolInvocationError(f"Tool {tool_name} failed: {e}")

Tool Fallback Chain

If primary tool fails, system attempts fallback:

Primary Tool (WebSearch) → Fails
    ↓
Secondary Tool (Cached Search) → Fails
    ↓
Knowledge Base Query → Success

---

Skill Performance Metrics

Execution Metrics

Tracked for each skill invocation:

| Metric | Description | Unit | |--------|-------------|------| | invocationcount | Number of times skill invoked | count | | executiontime | Time from start to finish | milliseconds | | tokenusage | Total tokens consumed | tokens | | gatepassrate | Quality gates passed / total | percentage | | usersatisfaction | User feedback score | 1-5 |

Metric Collection

def collect_metrics(skill_name: str, execution_data: dict):
    """Collect and store skill execution metrics."""
    metrics = {
        "skill_name": skill_name,
        "timestamp": datetime.now().isoformat(),
        "execution_time_ms": execution_data["duration"],
        "tokens_used": execution_data["tokens"],
        "gates_passed": execution_data["gates_passed"],
        "gates_total": execution_data["gates_total"],
        "gate_pass_rate": execution_data["gates_passed"] / execution_data["gates_total"],
        "user_satisfaction": execution_data.get("user_rating", None)
    }

    store_metrics(metrics)

---

Troubleshooting

Common Issues

Issue: Skill not triggering

• Cause: Score below threshold (5.0)
• Fix: Improve skill description or add more domain keywords

Issue: Quality gates failing

• Cause: Missing citations or disclosure
• Fix: Ensure U1-U6 gates are satisfied before final output

Issue: Sub-skill timeout

• Cause: External API not responding
• Fix: Check network connectivity, increase timeout

Issue: Language detection wrong

• Cause: Ambiguous input
• Fix: Explicitly specify language in input

Debug Mode

Enable debug logging:

# In config/debug.yaml
debug:
  enabled: true
  log_level: DEBUG
  trace_execution: true
  log_all_tool_calls: true

---

API Reference

Skill Registration Function

def register_skill(
    name: str,
    description: str,
    version: str,
    skill_file: str,
    dependencies: list[str] = None
) -> bool:
    """Register a new skill in the registry.

    Args:
        name: Unique skill identifier
        description: One-line summary for triggering
        version: Semantic version (e.g., "2.0.0")
        skill_file: Path to skill .md file
        dependencies: List of required sub-skills/tools

    Returns:
        True if registration successful, False otherwise
    """

Skill Resolution Function

def resolve_skill(user_input: str) -> str | None:
    """Resolve user input to skill name.

    Args:
        user_input: Raw user query

    Returns:
        Skill name if match found, None otherwise
    """

Skill Execution Function

def execute_skill(
    skill_name: str,
    parameters: dict
) -> dict:
    """Execute a registered skill.

    Args:
        skill_name: Name of skill to execute
        parameters: Input parameters for the skill

    Returns:
        Skill output dictionary

    Raises:
        SkillNotFoundError: If skill not registered
        SkillExecutionError: If execution fails
    """

---

This SKILL.md Registry provides complete documentation of the skill system. Update when adding new skills, modifying execution patterns, or changing validation rules.

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/survival-open-world-resource-strategy-agent-skill
• License: MIT

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