# Home Composting Carbon Nitrogen Agent Skill

> A Claude skill from dungnotnull/home-composting-carbon-nitrogen-agent-skill.

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-home-composting-carbon-nitrogen-agent-skill-home-composting-carbon-nitrogen-agent-skill`
- **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/home-composting-carbon-nitrogen-agent-skill

## Install

```sh
agentstack add skill-dungnotnull-home-composting-carbon-nitrogen-agent-skill-home-composting-carbon-nitrogen-agent-skill
```

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

## About

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

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

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

```json
{
  "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:

```json
{
  "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

```json
{
  "$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

```json
{
  "$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:**
```json
{
  "user_query": "string",
  "context": {}
}
```

**Output Schema:**
```json
{
  "requirements": {
    "object": "string",
    "scope": "string",
    "timeframe": "string",
    "available_inputs": {},
    "target_audience": "string",
    "language": "string",
    "analysis_type": "string"
  }
}
```

#### sub-evidence-collector

**Input Schema:**
```json
{
  "requirements": {
    "object": "string"
  }
}
```

**Output Schema:**
```json
{
  "evidence_bundle": {
    "current_data": {},
    "authoritative_docs": [],
    "recent_news": [],
    "reference_benchmarks": {}
  }
}
```

#### sub-core-analysis

**Input Schema:**
```json
{
  "feedstocks": [
    {"name": "string", "mass_kg": "number"}
  ],
  "space": "string",
  "climate": "string",
  "target_use": "string"
}
```

**Output Schema:**
```json
{
  "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

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

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

```python
# 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](https://github.com/dungnotnull)
- **Source:** [dungnotnull/home-composting-carbon-nitrogen-agent-skill](https://github.com/dungnotnull/home-composting-carbon-nitrogen-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-home-composting-carbon-nitrogen-agent-skill-home-composting-carbon-nitrogen-agent-skill
- 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%.