Banana Fiber Textile Production

SKILL.md — Skill Registry & Documentation

Overview

banana-fiber-textile-production is a production-grade harness for Claude Code targeting the Banana-Fiber (Bast) Textile Engineering & Green Textiles domain. It transforms Claude into a domain-expert that delivers structured, evidence-backed outputs by combining real-time data aggregation, recognized domain methods, and academic research into a single orchestrated workflow.

Skill Registration

Registration Protocol

Skills are registered through the harness's main orchestrator (skills/main.md) which maintains a catalog of available sub-skills. Each sub-skill must:

1. Declare identity via YAML frontmatter with name and description
2. Specify role in the ## Role & Persona section
3. Define workflow in the ## Workflow section
4. List tools in the ## Tools section
5. Specify output format in the ## Output Format section
6. Define quality gates in the ## Quality Gates section

Skill Resolution

When a skill is invoked via Skill("skill-name"):

1. The harness reads the skill file from skills/{skill-name}.md
2. Frontmatter is parsed for metadata validation
3. The skill's instructions are loaded into the context window
4. The skill executes according to its defined workflow
5. Output is validated against the skill's quality gates

Input/Output JSON Schemas

Standard Skill Input Schema

{
  "skill_name": "string (required)",
  "input_data": {
    "context": "object (optional)",
    "parameters": "object (optional)",
    "constraints": "object (optional)"
  },
  "metadata": {
    "invocation_id": "string (uuid)",
    "timestamp": "ISO8601 datetime",
    "language": "string (vi|en|default)"
  }
}

Standard Skill Output Schema

{
  "skill_name": "string (required)",
  "status": "success|partial|error",
  "output_data": {
    "result": "object",
    "artifacts": ["array of file references"],
    "metrics": "object (optional)"
  },
  "quality_gates": {
    "passed": ["array of gate IDs"],
    "failed": ["array of gate IDs"],
    "warnings": ["array of messages"]
  },
  "metadata": {
    "invocation_id": "string (uuid)",
    "duration_ms": "number",
    "timestamp": "ISO8601 datetime",
    "language": "string"
  }
}

Available Sub-Skills

| Skill Name | Description | Input Schema | Output Schema | |------------|-------------|--------------|---------------| | sub-gather-requirements | Clarify object of analysis, constraints, timeframe, inputs | {raw_message: string, provided_materials: []} | {requirements: {object, scope, timeframe, available_inputs, target_audience, language, analysis_type}} | | sub-evidence-collector | Fetch authoritative real-time and reference data | {requirements: {...}} | {evidence_bundle: {current_data, authoritative_docs, recent_news, reference_benchmarks}} | | sub-core-analysis | Optimize banana-fiber textile production | {banana_pseudostem, equipment, target_fabric, language} | {extraction, retting, fiber_properties, spinning_weaving, finishing, economics, scenarios} | | sub-knowledge-updater | Query knowledge base for academic evidence | {topic_keywords: []} | {citations: [{title, authors, year, venue, doi, tier}], coverage_rating, flagged_gaps: []} | | sub-advisor | Synthesize analysis into risk-disclosed conclusion | {core_analysis, evidence_bundle, knowledge_evidence} | {conclusion, scenarios, key_risks, evidence_chain, remediation, disclosure} |

Harness Execution Flow

USER INPUT (/banana-fiber-textile-production [query])
    │
    ▼
[Pre-Flight: Language Detection]
    │
    ├─► Detect Vietnamese/English from character set and domain words
    └─► Set LANG for all subsequent output
    │
    ▼
[Step 1: sub-gather-requirements]
    │
    ├─► Parse user message for required fields
    ├─► Ask clarifying questions if needed (max 2)
    └─► Emit structured requirements object
    │
    ▼
[Step 2: sub-evidence-collector]
    │
    ├─► WebSearch/WebFetch authoritative sources
    ├─► Read SECOND-KNOWLEDGE-BRAIN.md for cached benchmarks
    └─► Emit evidence bundle with source + date per item
    │
    ▼
[Step 3: sub-core-analysis]
    │
    ├─► Read domain references from SECOND-KNOWLEDGE-BRAIN.md
    ├─► Apply extraction + retting + properties + spinning + finishing
    └─► Emit analysis with scenarios
    │
    ▼
[Step 4: sub-knowledge-updater]
    │
    ├─► Query SECOND-KNOWLEDGE-BRAIN.md for academic citations
    ├─► Surface Tier 1–4 labels
    └─► Flag gaps for crawl pipeline
    │
    ▼
[Step 5: sub-advisor]
    │
    ├─► Synthesize all prior analysis
    ├─► Generate risk-disclosed conclusion
    └─► Emit final recommendation with evidence chain
    │
    ▼
[Quality Gate Review]
    │
    ├─► Verify U1–U6 universal gates
    ├─► Verify G1, G2, G3, G4 domain gates
    ├─► Auto-fix failures (max 2 retries per gate)
    └─► Deliver final report or limitation notice

Quality Gates

Universal Gates (U1–U6)

| Gate ID | Check | Auto-Fix Strategy | Enforcement | |---------|-------|-------------------|-------------| | U1 | ≥3 sources cited, ≥1 academic/authoritative | Fetch from knowledge base | Append missing sources | | U2 | Disclosure/limitations before recommendation | Prepend standard disclosure | Block until present | | U3 | Evidence hierarchy stated per source | Annotate source tiers | Tag each source with Tier 1–4 | | U4 | Language matches user preference | Translate output | Run pre-flight detection | | U5 | Output uses declared template | Reformat to template | Check mandatory sections | | U6 | Every claim traceable to source/judgment | Flag unsupported claims | Mark claims with source |

Domain Gates (G1–G4)

| Gate ID | Check | Auto-Fix Strategy | Enforcement | |---------|-------|-------------------|-------------| | G1 | Extraction & retting/softening chosen | Select extraction/retting method | Block until specified | | G2 | Fiber properties characterized (ASTM) | Characterize fiber properties | Block until complete | | G3 | Spinning/weaving & blend specified | Specify spinning/weaving method | Block until specified | | G4 | Durability improvement & sustainability | Add durability & sustainability | Block until specified |

Graceful Degradation

The harness implements 5 degradation levels (0–4):

| Level | Condition | Behavior | |-------|-----------|----------| | 0 | All primary sources reachable | Full evidenced analysis | | 1 | Some primary sources fail | Use secondary sources; flag substitutions | | 2 | Most live sources fail | Knowledge base only; flag "historical context" | | 3 | Required input missing/stale | Proceed with available; mark "DATA UNAVAILABLE" | | 4 | All sources + knowledge base fail | Emit "DATA UNAVAILABLE" notice |

Tool Definitions

Core Tools

| Tool | Purpose | Schema | Execution Handler | |------|---------|--------|-------------------| | WebSearch | Search live domain news and reports | {query: string, limit?: number} | MCP web-search-prime | | WebFetch | Scrape authoritative sources | {url: string} | MCP web-reader | | Read | Read knowledge base and project files | {file_path: string} | Native Read tool | | Write | Append knowledge entries | {file_path: string, content: string} | Native Write tool | | Bash | Run knowledge updater pipeline | {command: string} | Native Bash tool | | Skill | Invoke sub-skills sequentially | {skill: string, args?: object} | Native Skill tool |

Hook System

Hooks provide lifecycle management, state synchronization, and event emission:

| Hook | Trigger | Purpose | Schema | |------|---------|---------|--------| | pre-flight | Before Step 1 | Language detection, input validation | {input: string} | | pre-step | Before each step | State check, resource validation | {step: number, context: object} | | post-step | After each step | Output validation, metrics collection | {step: number, output: object} | | quality-gate | During gate review | Gate validation, auto-fix trigger | {gate: string, value: any} | | degradation | On source failure | Fallback chain execution | {level: number, failed_sources: []} | | completion | After final delivery | Metrics emission, cleanup | {result: object, duration_ms: number} |

Configuration Management

Configuration is centralized in /config:

• settings.py — Type-safe configuration classes (LLM, API, Knowledge, Features, Validation, Logging)
• .env — Environment variable overrides
• .env.example — Configuration template

Key Configuration Sections

from config import Settings, get_settings

settings = get_settings()

# LLM Configuration
settings.llm.provider  # LLMProvider
settings.llm.model  # str
settings.llm.temperature  # float

# Knowledge Configuration
settings.knowledge.keywords  # List[str]
settings.knowledge.scoring_weights  # Dict[str, float]

# Feature Flags
settings.features.enable_knowledge_updates  # bool
settings.features.strict_mode  # bool

# Validation Configuration
settings.validation.min_sources_required  # int
settings.validation.require_disclosure  # bool

Error Handling & Recovery

Error Types

| Error Type | Detection | Recovery | Retry Limit | |------------|-----------|----------|-------------| | Source timeout | No response in 30s | Retry alternate source | 3 | | Invalid input | Out-of-range/schema mismatch | Ask user to confirm | 2 | | Missing input | Field absent | Proceed with available + flag | N/A | | Stale reading | Timestamp old | Flag, request refresh | 1 | | Knowledge base miss | No matches | WebSearch gap-fill + queue crawl | 2 | | Conflicting actions | Mutually exclusive | Apply stated precedence | N/A | | Envelope unavailable | No setpoint for object | Use genus/category fallback | 1 | | Object/class ambiguous | Classification unclear | Ask user to confirm | 2 |

Error Recovery Flow

Error Detected
    │
    ├─► Log error with context
    ├─► Check retry limit
    ├─► Execute recovery strategy
    ├─► Update degradation level
    └─► Continue or Emit limitation notice

Logging System

Structured logging is configured in /config/settings.py:

• Levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
• Outputs: Console (stdout) and file (logs/)
• Format: %(asctime)s - %(name)s - %(levelname)s - %(message)s
• Rotation: 10MB max, 5 backup files

Log Categories

| Category | Purpose | Example | |----------|---------|---------| | skill.invocation | Skill lifecycle events | "Invoking sub-core-analysis" | | quality.gate | Gate validation events | "Gate U1 failed: only 2 sources" | | data.fetch | External API calls | "Fetching from Semantic Scholar" | | error.recovery | Error handling events | "Recovery strategy: fallback to knowledge base" | | degradation.level | Degradation state changes | "Degradation level 2: using historical data" |

Knowledge Pipeline

The knowledge base (SECOND-KNOWLEDGE-BRAIN.md) is auto-updated:

• Crawl tool: tools/knowledge_updater.py
• Schedule: Weekly academic (Mondays 08:00) + Daily news (Daily 07:00)
• Sources: ArXiv, Semantic Scholar, RSS feeds
• Deduplication: SHA256 of DOI/URL
• Scoring: Recency (0.4) + Keyword relevance (0.4) + Citation count (0.2)

Testing & Validation

Test Scenarios

See tests/test-scenarios.md for 5 concrete end-to-end scenarios:

1. Standard analysis — Full flow with complete inputs
2. Minimal-input analysis — Defaults with assumptions
3. Comparison scenario — Side-by-side analysis
4. Risk/feasibility scenario — Multi-scenario output
5. Degraded-mode scenario — Fallback chain test

Test Orchestrator

Run tools/run_test_scenarios.py for automated validation:

python tools/run_test_scenarios.py --all          # Run all scenarios
python tools/run_test_scenarios.py --scenario 1  # Run specific scenario
python tools/run_test_scenarios.py --verbose     # Detailed output

Version History

| Version | Date | Changes | |---------|------|---------| | 1.0.0 | 2026-07-10 | Initial production release | | 2.0.0 | 2026-07-16 | Production-grade hardening: encoding fix, validator accuracy, KB rewrite, sub-skill enrichment, mojibake tooling |

License

MIT License — See LICENSE file for 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/banana-fiber-textile-production-agent-skill
• License: MIT

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