# Organic Honey Forest Beekeeping Agent Skill

> A Claude skill from dungnotnull/organic-honey-forest-beekeeping-agent-skill.

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-organic-honey-forest-beekeeping-agent-skill-organic-honey-forest-beekeeping-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/organic-honey-forest-beekeeping-agent-skill

## Install

```sh
agentstack add skill-dungnotnull-organic-honey-forest-beekeeping-agent-skill-organic-honey-forest-beekeeping-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 Documentation

`organic-honey-forest-beekeeping` ships a **modular skill-registry architecture**.
This document is the single source of truth for how skills are *registered*,
*resolved*, *executed*, and *validated*, including input/output JSON schemas.

> Companion to `PROJECT-detail.md` (domain spec) and `assets/skill-manifest.json`
> (machine-readable manifest). Runtime package: `src/organic_honey/`.

---

## 1. Registration

A **skill** is a markdown file in `skills/` whose YAML frontmatter declares:

| Field         | Required | Type   | Meaning |
|---------------|----------|--------|---------|
| `name`        | yes      | string | Skill identifier (kebab-case). `organic-honey-forest-beekeeping` is the main/orchestrator; `sub-*` are sub-skills. |
| `description` | yes      | string | One-line summary used by the registry and router. |
| `step`        | no       | int    | Explicit execution order. If omitted, the registry assigns the canonical order from `DEFAULT_ORDER`. |

`SkillRegistry` (`src/organic_honey/registry.py`) discovers every `skills/*.md`
at load time, parses frontmatter, and builds `SkillSpec` objects. The main
skill (`name: organic-honey-forest-beekeeping`) is the orchestrator; the
remaining `sub-*` skills form the execution pipeline.

Canonical default order (also the `DEFAULT_ORDER` in `registry.py`):

1. `sub-gather-requirements`
2. `sub-evidence-collector`
3. `sub-core-analysis`
4. `sub-knowledge-updater`
5. `sub-advisor`

(Step 6 — the quality-gate review — is performed by the `HarnessRunner`, not a
sub-skill.)

---

## 2. Resolution

The **chain-of-thought router** (`src/organic_honey/router.py`) produces the
ordered execution plan:

- **Default (no branching):** the canonical 5-step order.
- **Branching enabled** (`feature_flags.router_branching`, default on):
  - **Trivial/explain queries** (`analysis_type == explain` or "what is / define"
    phrasing) → trimmed plan: `requirements → knowledge-updater → advisor`.
  - **Weak evidence** (zero academic sources or degradation level ≥ 2) → an
    extra `sub-knowledge-updater` pass is appended.
- The router records its reasoning as an explicit chain-of-thought
  (`router.explain()`) that the runner attaches to every report for audit.

---

## 3. Execution

`HarnessRunner` (`src/organic_honey/runner.py`) drives execution:

1. **Step 1 — requirements:** parse the user query into a typed `Requirements`
   (schema `assets/schemas/requirements.schema.json`).
2. **Step 2 — evidence:** ground via the `query_knowledge` tool; degrade to
   knowledge-only with an explicit LIMITATION flag when live sources are
   unavailable (schema `assets/schemas/evidence.schema.json`).
3. **Plan:** router resolves the ordered sub-skill list.
4. **Step 3 — core analysis:** enrich with real tool computations
   (`compute_carrying_capacity`, `honey_quality_score`) and the LLM
   (schema `assets/schemas/analysis.schema.json`).
5. **Step 4 — knowledge:** surface 1–5 citations with Tier labels + gaps.
6. **Step 5 — advisor:** synthesize a typed `Verdict` from exactly the declared
   category set (schema `assets/schemas/verdict.schema.json`).
7. **Step 6 — quality gate:** run U1–U6 + G1–G4 with auto-fix and a 2-retry
   policy; emit a `GateResult` per gate.

Each sub-skill's prompt is assembled from its markdown body (persona + workflow +
output format) plus the working context, then sent to the `LLMClient`.

### LLM & graceful fallback

`LLMClient` (`src/organic_honey/llm.py`):
- If a key is configured (`OHFB_LLM_API_KEY`/`OPENAI_API_KEY`) it calls an
  OpenAI-compatible `/chat/completions` endpoint with retry + exponential
  backoff (configurable retries/delay/timeout).
- On any failure — or when no key is configured, or `OHFB_FORCE_OFFLINE=1`
  (air-gap mode) — it uses a **deterministic, rule-based offline fallback** that
  emits structured JSON for each skill. It never fabricates citations; in
  offline mode the verdict resolves to `Inconclusive` with explicit limitations.

---

## 4. Validation

Validation runs at three layers:

1. **Schema validation** — JSON Schemas under `assets/schemas/` describe the
   I/O contract of each typed artifact (`requirements`, `evidence`, `analysis`,
   `verdict`). The runner constructs typed dataclasses that enforce these
   contracts in-process (`src/organic_honey/models.py`).
2. **Tool validation** — `ToolRegistry` validates each tool call against its
   declared input/output JSON schema before/after execution
   (`src/organic_honey/tools.py`).
3. **Quality gates** — U1–U6 (universal) + G1–G4 (domain) enforced by the runner
   with auto-fix and 2-retry; a gate that cannot pass becomes an explicit
   limitation in the report (never silently dropped).

Project-level contract validation:
- `python tools/run_test_scenarios.py` — structural + content + gate coverage.
- `python tools/test_knowledge_updater.py` — knowledge pipeline unit tests.
- `python D:\972026\tools\validate_project.py .` — 8-File Contract.

---

## 5. Input / Output JSON Schemas

| Artifact     | Schema file | Required fields |
|--------------|-------------|-----------------|
| Requirements | `assets/schemas/requirements.schema.json` | `object`, `language` |
| Evidence     | `assets/schemas/evidence.schema.json` | `current_data`, `authoritative_docs`, `degradation_level` |
| Analysis     | `assets/schemas/analysis.schema.json` | `forage`, `hive_placement`, `gates` |
| Verdict      | `assets/schemas/verdict.schema.json` | `category` (enum of 4), `disclosure` |

The four valid verdict categories (enforced by `Verdict.__post_init__`):

1. `Sustainable Model`
2. `Conditional (density)`
3. `Ecological/Cert Risk`
4. `Inconclusive`

---

## 6. Tools (schema-bearing)

| Tool | Purpose | Key inputs |
|------|---------|------------|
| `compute_carrying_capacity` | Estimate hives from forage area + floral density | `forage_area_ha`, `floral_density`, `species_factor` |
| `honey_quality_score` | Score honey vs Codex STAN 12 targets (0–100) | `moisture_pct`, `hmf_mgkg`, `diastase_number`, `residue_free` |
| `read_knowledge` | Read a knowledge-brain section by heading keyword | `keyword` |
| `query_knowledge` | Keyword search of the knowledge brain | `keywords[]` |
| `dedup_hash` | SHA256 dedup hash for a DOI/URL | `identifier` |
| `web_search` | Offline-safe placeholder search (degrades gracefully) | `query` |

Each tool declares `input_schema` + `output_schema` (JSON Schema) and a
deterministic handler. See `src/organic_honey/tools.py`.

---

## 7. Hooks (lifecycle)

`Hooks` (`src/organic_honey/hooks.py`) emits events to registered handlers:

`before_run`, `after_run`, `before_skill`, `after_skill`, `before_gate`,
`after_gate`, `on_error`, `on_degradation`.

Handlers receive `(event_name, payload)`; the runner passes a mutable state dict
so hooks can synchronize state or emit metrics. A built-in
`default_degradation_hook` logs degradation-level changes.

---

## 8. Quick start

```bash
# Air-gap / offline run (no API key needed):
OHFB_FORCE_OFFLINE=1 python scripts/run_agent.py "Plan an organic forest apiary for Apis cerana" --pretty

# Self-check:
OHFB_FORCE_OFFLINE=1 python scripts/run_agent.py --selfcheck

# Live LLM:
export OHFB_LLM_API_KEY=sk-...
python scripts/run_agent.py "your query"
```

## 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/organic-honey-forest-beekeeping-agent-skill](https://github.com/dungnotnull/organic-honey-forest-beekeeping-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-organic-honey-forest-beekeeping-agent-skill-organic-honey-forest-beekeeping-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%.