Organic Honey Forest Beekeeping Agent Skill

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).

1. 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).

1. Plan: router resolves the ordered sub-skill list.
2. Step 3 — core analysis: enrich with real tool computations

(compute_carrying_capacity, honey_quality_score) and the LLM (schema assets/schemas/analysis.schema.json).

1. Step 4 — knowledge: surface 1–5 citations with Tier labels + gaps.
2. Step 5 — advisor: synthesize a typed Verdict from exactly the declared

category set (schema assets/schemas/verdict.schema.json).

1. 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).

1. Tool validation — ToolRegistry validates each tool call against its

declared input/output JSON schema before/after execution (src/organic_honey/tools.py).

1. 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

# 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
• Source: dungnotnull/organic-honey-forest-beekeeping-agent-skill
• License: MIT

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