Home Composting Carbon Nitrogen Agent Skill

SKILL.md — Skill Registry and Architecture Documentation

Overview

This document defines the comprehensive skill registry, resolution mechanism, execution protocol, and validation schemas for the home-composting-carbon-nitrogen harness skill.

Table of Contents

1. [Skill Architecture](#skill-architecture)
2. [Skill Registration](#skill-registration)
3. [Skill Resolution](#skill-resolution)
4. [Skill Execution](#skill-execution)
5. [Input/Output JSON Schemas](#inputoutput-json-schemas)
6. [Quality Gates](#quality-gates)
7. [Error Handling](#error-handling)
8. [Extension Points](#extension-points)

---

Skill Architecture

The skill uses a modular hierarchical architecture with specialized sub-skills orchestrated through a main harness:

home-composting-carbon-nitrogen (main harness)
    │
    ├─► sub-gather-requirements      (intake & clarification)
    ├─► sub-evidence-collector        (data aggregation)
    ├─► sub-core-analysis            (domain computation)
    ├─► sub-knowledge-updater         (research integration)
    └─► sub-advisor                   (synthesis & recommendation)

Design Principles

1. Single Responsibility: Each sub-skill handles one specific domain concern
2. Graceful Degradation: Each step can fail independently without compromising the entire pipeline
3. Evidence Discipline: All outputs must cite sources and disclose limitations
4. Type Safety: All inputs/outputs are validated against JSON schemas
5. Observable: All execution is logged through the hooks system

Flexibility Features

• Chain-of-Thought Routing: Sub-skills can delegate to specialized handlers based on input characteristics
• Modular Registry: New sub-skills can be registered without modifying the main harness
• Version Compatibility: Skills declare their API versions for compatibility checking
• Hot-Reloading: Skills can be reloaded at runtime without restart (in development mode)

---

Skill Registration

Skill Metadata Schema

Every skill must declare its metadata in YAML frontmatter:

---
name: skill-name
version: "1.0.0"
api_version: "1.0"
description: One-line summary of what this skill does
category: analysis|data|synthesis|utility
priority: critical|high|normal|low
dependencies:
  - skill-name:version (optional)
capabilities:
  - capability-name
tags:
  - tag-name
authoritative_sources:
  - source-name: tier (1-4)
---

Registration Protocol

Skills are registered through the main harness by:

1. File-based registration: Place .md file in skills/ directory with proper frontmatter
2. API-based registration: Call register_skill() from code (for dynamic skills)
3. Hook-based registration: Emit SKILL_REGISTER event with skill metadata

Registration Example

---
name: sub-core-analysis
version: "1.0.0"
api_version: "1.0"
description: Optimize home composting for an odorless, high-quality compost by calculating the C/N ratio from kitchen inputs and recommending the right process.
category: analysis
priority: critical
dependencies: []
capabilities:
  - cn_calculation
  - process_selection
  - odor_diagnosis
tags:
  - composting
  - carbon-nitrogen
  - soil-microbiology
authoritative_sources:
  - Cornell Composting: 3
  - US EPA: 3
  - USDA NRCS: 3
---

---

Skill Resolution

Resolution Algorithm

When the main harness receives a request, it resolves which sub-skills to invoke through:

1. Intent Analysis: Parse the user query to identify intent type
2. Capability Matching: Match required capabilities to available skills
3. Dependency Resolution: Ensure all dependency skills are available
4. Priority Ordering: Order skills by priority and dependencies
5. Compatibility Check: Verify API version compatibility

Intent Types

| Intent Type | Description | Default Skills | |-------------|-------------|----------------| | analysis | Domain-specific analysis | sub-core-analysis | | data_collection | Gathering real-time data | sub-evidence-collector | | research | Academic research integration | sub-knowledge-updater | | synthesis | Combining multiple analyses | sub-advisor | | clarification | Requirements gathering | sub-gather-requirements |

Capability Registry

The following capabilities are defined by the system:

{
  "cn_calculation": {
    "description": "Calculate carbon/nitrogen ratio from feedstock inputs",
    "skills": ["sub-core-analysis"],
    "version": "1.0"
  },
  "process_selection": {
    "description": "Select appropriate composting process",
    "skills": ["sub-core-analysis"],
    "version": "1.0"
  },
  "data_aggregation": {
    "description": "Fetch authoritative real-time data",
    "skills": ["sub-evidence-collector"],
    "version": "1.0"
  },
  "evidence_retrieval": {
    "description": "Query knowledge base for academic evidence",
    "skills": ["sub-knowledge-updater"],
    "version": "1.0"
  },
  "risk_disclosure": {
    "description": "Synthesize analysis with risk disclosure",
    "skills": ["sub-advisor"],
    "version": "1.0"
  }
}

---

Skill Execution

Execution Flow

USER INPUT
    │
    ▼
[Parse Intent & Resolve Skills]
    │
    ▼
[Execute in Dependency Order]
    │
    ├─► sub-gather-requirements
    ├─► sub-evidence-collector
    ├─► sub-core-analysis
    ├─► sub-knowledge-updater
    └─► sub-advisor
    │
    ▼
[Quality Gate Validation]
    │
    ├─► U1–U6 (Universal gates)
    └─► G1–G4 (Domain gates)
    │
    ▼
[Output Formatting & Delivery]

Execution Protocol

Each skill executes with:

1. Pre-execution hooks: SKILL_EXECUTION_START event emitted
2. Input validation: Input validated against JSON schema
3. State initialization: Execution context created in state manager
4. Skill execution: Main skill logic executed
5. Output validation: Output validated against JSON schema
6. Post-execution hooks: SKILL_EXECUTION_COMPLETE event emitted
7. State cleanup: Execution context marked complete

Context Protocol

Skills receive and return structured context:

{
  "execution_id": "uuid-v4",
  "skill_name": "skill-name",
  "timestamp": "ISO-8601",
  "inputs": {
    "user_query": "...",
    "parameters": {}
  },
  "outputs": {
    "result": {},
    "metadata": {}
  },
  "state": {
    "status": "running|completed|failed",
    "duration_ms": 1234,
    "error": null
  }
}

---

Input/Output JSON Schemas

Universal Input Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Skill Input Schema",
  "type": "object",
  "required": ["execution_id", "skill_name", "inputs"],
  "properties": {
    "execution_id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for this execution"
    },
    "skill_name": {
      "type": "string",
      "description": "Name of the skill to execute"
    },
    "inputs": {
      "type": "object",
      "description": "Skill-specific inputs"
    },
    "metadata": {
      "type": "object",
      "properties": {
        "language": {
          "type": "string",
          "enum": ["en", "vi"],
          "description": "Output language"
        },
        "priority": {
          "type": "string",
          "enum": ["critical", "high", "normal", "low"],
          "description": "Execution priority"
        }
      }
    }
  }
}

Universal Output Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Skill Output Schema",
  "type": "object",
  "required": ["execution_id", "skill_name", "outputs", "state"],
  "properties": {
    "execution_id": {
      "type": "string",
      "format": "uuid"
    },
    "skill_name": {
      "type": "string"
    },
    "outputs": {
      "type": "object",
      "description": "Skill-specific outputs"
    },
    "state": {
      "type": "object",
      "required": ["status", "duration_ms"],
      "properties": {
        "status": {
          "type": "string",
          "enum": ["completed", "failed", "degraded"]
        },
        "duration_ms": {
          "type": "number",
          "minimum": 0
        },
        "error": {
          "type": ["string", "null"],
          "description": "Error message if failed"
        },
        "quality_gates": {
          "type": "object",
          "description": "Quality gate results"
        }
      }
    }
  }
}

Sub-Skill Specific Schemas

sub-gather-requirements

Input Schema:

{
  "user_query": "string",
  "context": {}
}

Output Schema:

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

sub-evidence-collector

Input Schema:

{
  "requirements": {
    "object": "string"
  }
}

Output Schema:

{
  "evidence_bundle": {
    "current_data": {},
    "authoritative_docs": [],
    "recent_news": [],
    "reference_benchmarks": {}
  }
}

sub-core-analysis

Input Schema:

{
  "feedstocks": [
    {"name": "string", "mass_kg": "number"}
  ],
  "space": "string",
  "climate": "string",
  "target_use": "string"
}

Output Schema:

{
  "cn_calculation": {
    "blended_cn": "number",
    "cn_status": "low|in_target|high",
    "method": "harmonic|exact_pct"
  },
  "moisture_plan": {
    "target_moisture": "number",
    "status": "string"
  },
  "process_selection": {
    "process": "aerobic|bokashi|vermicomposting",
    "rationale": "string"
  },
  "troubleshooting": {
    "odor_diagnosis": "string",
    "fixes": []
  },
  "maturity_scenarios": {
    "best": {},
    "base": {},
    "worst": {}
  }
}

---

Quality Gates

Universal Gates (U1–U6)

| Gate | Description | Auto-Fix | |------|-------------|----------| | U1 | ≥3 sources cited, ≥1 academic/authoritative | Fetch from knowledge base | | U2 | Disclosure/limitations before recommendation | Prepend standard disclosure | | U3 | Evidence hierarchy stated per source (Tier 1–4) | Annotate source tiers | | U4 | Language matches user preference | Translate output | | U5 | Output uses declared template (all sections) | Reformat to template | | U6 | Every claim traceable to ≥1 source or flagged | Mark claims with sources |

Domain Gates (G1–G4)

| Gate | Description | Auto-Fix | |------|-------------|----------| | G1 | C/N computed from feedstock values and checked vs 25-30:1 target | Recompute C/N | | G2 | Moisture (50-60%) & aeration stated | Add moisture & aeration | | G3 | Process (aerobic/Bokashi/vermi) matched to feedstock & space | Match process | | G4 | Odor troubleshooting (anaerobic/ammonia) included | Add troubleshooting |

Gate Enforcement Logic

def enforce_quality_gates(output: dict, context: HookContext) -> dict:
    """Enforce all quality gates with auto-fix and retry logic."""
    gates = [U1, U2, U3, U4, U5, U6, G1, G2, G3, G4]

    for gate in gates:
        retries = 0
        while retries  None:
    """Custom post-processing logic."""
    # Your custom logic here
    pass

Custom Quality Gates

To add custom quality gates:

1. Define the gate check logic
2. Define the auto-fix logic
3. Add the gate to the enforcement sequence
4. Update the output schema if new fields are added

Custom Authoritative Sources

To add new authoritative sources:

1. Add source to SECOND-KNOWLEDGE-BRAIN.md Section 4
2. Declare source tier (1-4) in skill frontmatter
3. Update knowledge_updater.py with crawl targets
4. Add source-specific validation if needed

---

Version Compatibility

API Versioning

Skills declare their API version in frontmatter:

api_version: "1.0"

The harness supports skills with:

• Same major version (1.x) → Compatible
• Different major version → Compatibility check required

Compatibility Matrix

| Skill API Version | Harness Version | Compatible | |-------------------|-----------------|------------| | 1.0 | 1.0 | Yes | | 1.0 | 1.1 | Yes (backward compatible) | | 1.1 | 1.0 | No (forward incompatible) | | 2.0 | 1.0 | No (major version change) |

---

Performance Optimization

Context Window Management

• Compression Level: Configurable (0.0-1.0, default 0.3)
• Token Budgeting: Allocate tokens per sub-skill based on priority
• Cache Strategy: Enable caching for expensive operations

Parallel Processing

Independent sub-skills can execute in parallel when enable_parallel_processing feature flag is enabled:

# Skills without dependencies can run in parallel
parallel_skills = [
    "sub-evidence-collector",
    "sub-knowledge-updater",
]

Caching Strategy

• Knowledge Base Queries: Cache with 1-hour TTL
• External API Calls: Cache with 5-minute TTL
• C/N Calculations: No cache (must be fresh)

---

Security Considerations

Input Sanitization

• All user inputs are sanitized before processing
• File paths are validated to prevent directory traversal
• External URLs are validated against allowlist

Output Filtering

• Sensitive information is never included in outputs
• API keys and credentials are redacted
• User data is not logged

Rate Limiting

• External API calls are rate-limited per domain
• Concurrent skill executions are limited
• Knowledge base updates are throttled

---

Testing Strategy

Unit Tests

Each skill should have unit tests covering:

• Input validation
• Core logic
• Error handling
• Edge cases

Integration Tests

Test the full harness with:

• Standard scenarios
• Edge cases
• Error conditions
• Degraded modes

Quality Gate Tests

Verify all quality gates:

• Pass with valid output
• Fail with invalid output
• Auto-fix functionality
• Retry behavior

---

Maintenance Guidelines

Updating Skills

1. Increment version number for breaking changes
2. Update API version if interface changes
3. Add deprecation notice for 2 versions before removal
4. Update documentation and examples

Monitoring

Monitor:

• Skill execution success rate
• Average execution duration
• Error rates by category
• Quality gate pass rate

Logging

All skill execution is logged with:

• Execution ID
• Timestamp
• Inputs/outputs (sanitized)
• Quality gate results
• Errors and exceptions

---

Future Enhancements

Planned Features

• Machine Learning Maturity Prediction: ML models for compost maturity estimation
• IoT Integration: Support for IoT sensor data
• Multi-language Support: Full internationalization
• Webhook Notifications: Real-time event notifications
• API Export: REST API for programmatic access

API Stability

The following are considered stable:

• Skill registration protocol
• Input/output JSON schemas
• Quality gate definitions
• Error handling mechanism

The following may change:

• Internal execution flow
• Hook system internals
• State management 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/home-composting-carbon-nitrogen-agent-skill
• License: MIT

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