feat(linguistics): add korean_slang offline Gen-Z pack (#34)

.github/ISSUE_TEMPLATE/01_skill_proposal.yml

@@ -36,6 +36,7 @@ body:
         - defi
         - dev_tools
         - finance
+        - linguistics
         - monitoring
         - office
         - optimization

.github/labels.json

@@ -114,6 +114,11 @@
         "color": "E6D9F5",
         "description": "Registry skill category — finance (`skills/finance/`)."
     },
+    {
+        "name": "cat: linguistics",
+        "color": "E6D9F5",
+        "description": "Registry skill category — linguistics (`skills/linguistics/`)."
+    },
     {
         "name": "cat: monitoring",
         "color": "E6D9F5",

CHANGELOG.md

@@ -10,6 +10,10 @@ Contributors add user-facing entries under `[Unreleased]` in the same PR. Mainta
 
 ### Added
 
+- **Skill (`linguistics/korean_slang` v0.1.0):** New `linguistics/` category and offline Korean Gen-Z slang pack — interpret / suggest / lookup over a September 2026 curated KB, honorific audience gates, and constitution filters for slurs (#34).
+- **GitHub:** `cat: linguistics` in [`.github/labels.json`](.github/labels.json) and the New Skill Proposal category dropdown; GitHub UI labels sync on merge to `main` (#34).
+- **Examples:** [`korean_slang_demo.py`](examples/korean_slang_demo.py) — offline interpret, suggest, lookup, unmatched, and blocked-term paths (#34).
+- **Scripts:** [`korean_slang_stress_sim.py`](scripts/korean_slang_stress_sim.py) — offline interpret/suggest stress harness (#34).
 - **Docs:** [Glossary](docs/glossary.md) and [inclusive language](docs/contributing/inclusive-language.md) — operator / contributor / host agent / end user; skill bundle vs PyPI package; anatomy roles (#252).
 - **Core:** Pluggable secret providers — `SecretProvider`, `EnvSecretProvider`, `MappingSecretProvider`, `CallableSecretProvider`, and `SkillLoader.resolve_env_vars()` inject manifest `env_vars` into `BaseSkill(config=...)` without requiring global `os.environ` mutation (#39).
 - **Core:** `BaseSkill.credential()` — config-first credential lookup with `os.environ` fallback for local `.env` workflows (#39).

CONTRIBUTING.md

@@ -399,6 +399,7 @@ Place each skill under one top-level directory under `skills/`. Use an existing
 | `defi` | On-chain trading and agent wallet execution | `evm_tx_handler` |
 | `dev_tools` | Developer workflows, issue resolution, repo tooling | `issue_resolver` |
 | `finance` | Blockchain, risk, financial analysis | `wallet_screening`, `uk_companies_house_handler` |
+| `linguistics` | Language adapters and internet-register lexicons | `korean_slang` |
 | `office` | Documents, productivity, email | `pdf_form_filler`, `gmail_handler` |
 | `optimization` | Middleware, compression, efficiency | `prompt_rewriter` |
 | `monitoring` | Agent loop observability, budget gates, task control | `token_limiter` |

docs/contributing/ai_native_workflow.md

@@ -245,7 +245,7 @@ These align with [CONTRIBUTING.md](../../CONTRIBUTING.md). Violations block merg
 - Output-card `ui_schema.fields[].key` values must resolve in `execute()` JSON; keep `tests/fixtures/card_ui_schema/<category>__<skill_name>.json` in sync (#199)
 - Update `docs/skills/<skill_name>.md` and `docs/skills/README.md` (**Version**, **Skill history**, and index columns per [CONTRIBUTING.md § catalog page](../../CONTRIBUTING.md#6-docsskillsskill_namemd-catalog-page))
 - On each catalog page, add a **Usage Examples** section (Gemini, Claude, OpenAI, DeepSeek, Ollama prompt mode) per [skill usage template](../usage/skill_usage_template.md). Keep provider mechanics in `docs/usage/`; put skill-specific paths, sample user messages, and `execute` payloads on the skill page.
-- Categories: `compliance`, `creative`, `data_engineering`, `defi`, `dev_tools`, `finance`, `monitoring`, `office`, `optimization`, `security`, `wellness` — see [Skill library](../skills/README.md) for the live registry; [Choosing a category](../../CONTRIBUTING.md#choosing-a-category) in CONTRIBUTING.md (issue first for new top-level folders)
+- Categories: `compliance`, `creative`, `data_engineering`, `defi`, `dev_tools`, `finance`, `linguistics`, `monitoring`, `office`, `optimization`, `security`, `wellness` — see [Skill library](../skills/README.md) for the live registry; [Choosing a category](../../CONTRIBUTING.md#choosing-a-category) in CONTRIBUTING.md (issue first for new top-level folders)
 - Do not bump `pyproject.toml` version in skill-only PRs unless requested
 - **Effect** in `skill.py`; **Directive** (skill context, not host persona) in `instructions.md`; **Contract** in `manifest.yaml`
 - Never commit secrets; document `env_vars` in the manifest

docs/skills/README.md

@@ -91,6 +91,13 @@ Supportive coaching guardrails, crisis triage, and grounded psychoeducation for
 | :--- | :--- | :--- | :--- | :--- |
 | **[Mental Coach](mental_coach.md)** | `wellness/mental_coach` | `0.1.1` (9 Sep 2026) | [@mrmasa88](https://github.com/mrmasa88) ([AO](https://github.com/0x-AO-Protocol)) | Deterministic wellness coaching firewall with crisis triage, scope limits, and cited KB retrieval. |
 
+## Linguistics
+Language adapters: curated lexicons so host agents can interpret and produce informal, internet-native language that foundation models routinely miss.
+
+| Skill | ID | Version | Issuer | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| **[Korean Slang](korean_slang.md)** | `linguistics/korean_slang` | `0.1.0` (19 Sep 2026) | [@bd-c3](https://github.com/bd-c3) | Offline Korean Gen-Z slang interpreter and peer-register generator (September 2026 pack). |
+
 ---
 
 ## Installing Skills

docs/skills/korean_slang.md

@@ -0,0 +1,287 @@
+# Korean Slang
+
+**Domain:** `linguistics`
+**Skill ID:** `linguistics/korean_slang`
+**Issuer:** [@bd-c3](https://github.com/bd-c3)
+<!-- skill-doc-meta:begin -->
+**Version**: `0.1.0` — 19 Sep 2026
+<!-- skill-doc-meta:end -->
+**Recommended install:** `pip install "skillware[linguistics_korean_slang]"`. See [Install extras](../usage/install_extras.md).
+
+[Skill Library](README.md) · [Testing](../TESTING.md)
+
+Deterministic **Korean Gen-Z slang lexicon** for host agents that need to understand or speak modern internet Korean. `execute()` is a pure function: longest-first matching over a curated September 2026 pack, template-based `suggest()`, and constitution filters for slurs and appearance-policing slang. No network. No model calls.
+
+This is the v1 answer to [issue #34](https://github.com/ARPAHLS/skillware/issues/34) (preferred id `linguistics/korean_slang`, not `korean_pack_26_S`). The pack is small and honest: unmatched 줄임말 stay unmatched.
+
+> **Skill chains:** Often after `security/prompt_injection_firewall` when the Korean text arrived from an untrusted comment field — see [Skill chaining](../usage/skill_chaining.md).
+
+> **Language disclaimer:** This skill is a curated snapshot, not a native speaker and not a living social network. Slang dating, regional use, and irony can still be wrong. A Korean-native review of the data pack is expected at PR time.
+
+## Capabilities
+
+- **interpret** (default): gloss incoming Korean / Konglish / jamo chat. Returns the issue contract fields `translation`, `slang_breakdown`, `nuance`, `formality`.
+- **suggest**: peer-register lines from templates, gated by `audience` (`peers`, `mixed`, `work`, `elders`). Elders get polite Korean, not 반말 slang.
+- **lookup**: exact surface, alias, or romanization.
+- **Constitution**: blocked substrings are omitted from glosses and never generated. Vulgar items (`존나`, `존맛탱`) are interpreted but not suggested unless `vulgar_ok` is true.
+
+## Bundle layout
+
+The skill lives in `skills/linguistics/korean_slang/`. Roles: [Skill anatomy](../introduction.md#skill-anatomy) and the [glossary](../glossary.md). **Contract** — see Manifest Details below. **Assurance** — `test_skill.py` in the bundle.
+
+### Effect (`skill.py` + `lexicon.py`)
+
+Pure Python. Loads `kb/` once per process, matches compact Hangul (spaces ignored), applies jamo/latin boundaries, and fills templates. Identical input returns identical JSON.
+
+### Directive (`instructions.md`)
+
+When to call interpret vs suggest, honorific gates, and how to talk about unmatched or caution terms.
+
+### Corpus (`kb/`)
+
+| File | Role |
+| :--- | :--- |
+| `entries.json` | Curated slang entries (surfaces, aliases, romanization, intents, safety flags) |
+| `generation.json` | Intent aliases and audience-scoped templates |
+| `constitution.json` | Blocked substrings the skill will not gloss or generate |
+| `pack_meta.json` | Snapshot id `2026-09` and public sources used to seed the pack |
+
+## Manifest Details
+
+**Parameters Schema:**
+* `text` (string): Korean, Konglish, or English. Required for `interpret` and `lookup`.
+* `context` (string, optional): Situational note appended to `nuance`.
+* `action` (string, optional): `interpret` (default), `suggest`, or `lookup`.
+* `intent` (string, optional): Generation bucket for `suggest` (`praise`, `food`, `work`, `tired`, `annoyed`, `agree`, `greeting`, `bye`, `thanks`, `workout`, `weekend`, `dating`, `fandom`, `competence`).
+* `audience` (string, optional): `peers` (default), `mixed`, `work`, or `elders`.
+* `include_romanization` (boolean, optional): Attach romanization on hits.
+* `max_hits` (integer, optional): 1–50, default 12.
+* `vulgar_ok` (boolean, optional): Allow vulgar-marked items in `suggest()`. Default false.
+
+**Outputs Schema:**
+* `status` (string): `ok` or `error`.
+* `action` (string): Echoed action.
+* `translation` (string or null): English gloss, or generated Korean for `suggest`.
+* `slang_breakdown` (object): Surface → short explanation.
+* `nuance` (string): Socio-linguistic note.
+* `formality` (string): `Informal / Slang`, `Informal / Vulgar`, `Informal / Caution`, `Polite`, `Work-safe`, `unknown`, or `blocked`.
+* `hit_count` (integer): Hits or suggestion count.
+
+Contract violations return `{"status": "error", "error": {"code", "detail"}}`. Closed codes: `EMPTY_TEXT`, `UNKNOWN_ACTION`, `UNKNOWN_AUDIENCE`, `INVALID_MAX_HITS`, `NEED_TEXT_OR_INTENT`, `NO_SUGGESTIONS`, `PACK_FAILURE`.
+
+## Environment
+
+| Variable | Required | Purpose |
+| :--- | :--- | :--- |
+| *(none)* | — | Offline pack; `execute()` does not read secrets |
+
+Configure agent keys per [API keys for skills](../usage/api_keys.md) only when running provider loop examples.
+
+## Example Usage (Direct)
+
+```python
+from skillware.core.loader import SkillLoader
+
+bundle = SkillLoader.load_skill("linguistics/korean_slang")
+skill = bundle["class"]()
+result = skill.execute(
+    {
+        "text": "요즘 완전 폼 미쳤다",
+        "context": "A comment on a YouTube video about a popular singer.",
+    }
+)
+print(result["translation"], result["formality"])
+print(result["slang_breakdown"])
+```
+
+## Usage Examples
+
+Guides: [Usage index](../usage/README.md) · [Agent loops](../usage/agent_loops.md) · [Skill chaining](../usage/skill_chaining.md). No skill-specific API keys. See [Install extras](../usage/install_extras.md).
+
+Use `bundle["class"]()` in the snippets below; explicit `bundle["module"].KoreanSlangSkill()` also works.
+
+Sample user message: *What does 요즘 완전 폼 미쳤다 mean on a YouTube comment about a singer?*
+
+### Runnable examples
+
+| Script | Provider | Env vars |
+| :--- | :--- | :--- |
+| [`korean_slang_demo.py`](../../examples/korean_slang_demo.py) | Local execute | None |
+| [`korean_slang_stress_sim.py`](../../scripts/korean_slang_stress_sim.py) | Local execute (maintainer harness) | None |
+
+### Gemini
+
+```python
+import google.genai as genai
+from google.genai import types
+from skillware.core.env import load_env_file
+from skillware.core.loader import SkillLoader
+
+load_env_file()
+bundle = SkillLoader.load_skill("linguistics/korean_slang")
+skill = bundle["class"]()
+tool = SkillLoader.to_gemini_tool(bundle)
+client = genai.Client()
+response = client.models.generate_content(
+    model="gemini-3.5-flash-lite",
+    contents=(
+        "What does 요즘 완전 폼 미쳤다 mean on a YouTube comment about a singer?"
+    ),
+    config=types.GenerateContentConfig(
+        tools=[tool],
+        system_instruction=bundle["instructions"],
+    ),
+)
+for part in response.candidates[0].content.parts:
+    if part.function_call:
+        result = skill.execute(dict(part.function_call.args))
+        print(result["translation"], result["formality"])
+```
+
+### Claude
+
+```python
+import os
+import anthropic
+from skillware.core.env import load_env_file
+from skillware.core.loader import SkillLoader
+
+load_env_file()
+bundle = SkillLoader.load_skill("linguistics/korean_slang")
+skill = bundle["class"]()
+client = anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))
+tools = [SkillLoader.to_claude_tool(bundle)]
+response = client.messages.create(
+    model="claude-haiku-4-5-20251001",
+    max_tokens=1024,
+    system=bundle["instructions"],
+    tools=tools,
+    messages=[{
+        "role": "user",
+        "content": (
+            "What does 요즘 완전 폼 미쳤다 mean on a YouTube comment about a singer?"
+        ),
+    }],
+)
+for block in response.content:
+    if block.type == "tool_use":
+        result = skill.execute(dict(block.input))
+        print(result["translation"], result["formality"])
+```
+
+### OpenAI
+
+```python
+import os
+from openai import OpenAI
+from skillware.core.env import load_env_file
+from skillware.core.loader import SkillLoader
+
+load_env_file()
+bundle = SkillLoader.load_skill("linguistics/korean_slang")
+skill = bundle["class"]()
+client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
+tool = SkillLoader.to_openai_tool(bundle)
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[
+        {"role": "system", "content": bundle["instructions"]},
+        {
+            "role": "user",
+            "content": (
+                "What does 요즘 완전 폼 미쳤다 mean on a YouTube comment about a singer?"
+            ),
+        },
+    ],
+    tools=[tool],
+)
+message = response.choices[0].message
+if message.tool_calls:
+    import json
+    args = json.loads(message.tool_calls[0].function.arguments)
+    result = skill.execute(args)
+    print(result["translation"], result["formality"])
+```
+
+### DeepSeek
+
+```python
+import os
+from openai import OpenAI
+from skillware.core.env import load_env_file
+from skillware.core.loader import SkillLoader
+
+load_env_file()
+bundle = SkillLoader.load_skill("linguistics/korean_slang")
+skill = bundle["class"]()
+client = OpenAI(
+    api_key=os.environ.get("DEEPSEEK_API_KEY"),
+    base_url="https://api.deepseek.com",
+)
+tool = SkillLoader.to_deepseek_tool(bundle)
+response = client.chat.completions.create(
+    model="deepseek-chat",
+    messages=[
+        {"role": "system", "content": bundle["instructions"]},
+        {
+            "role": "user",
+            "content": (
+                "What does 요즘 완전 폼 미쳤다 mean on a YouTube comment about a singer?"
+            ),
+        },
+    ],
+    tools=[tool],
+)
+message = response.choices[0].message
+if message.tool_calls:
+    import json
+    args = json.loads(message.tool_calls[0].function.arguments)
+    result = skill.execute(args)
+    print(result["translation"], result["formality"])
+```
+
+### Ollama (prompt mode)
+
+```python
+import json
+from skillware.core.loader import SkillLoader
+
+bundle = SkillLoader.load_skill("linguistics/korean_slang")
+skill = bundle["class"]()
+prompt = (
+    "You may call tools as JSON blocks.\n"
+    f"Tool: {bundle['manifest']['name']}\n"
+    f"Instructions:\n{bundle['instructions']}\n"
+    "User: What does 요즘 완전 폼 미쳤다 mean on a YouTube comment about a singer?"
+)
+print(prompt)
+# When the model emits JSON tool args, pass them to execute:
+result = skill.execute({
+    "text": "요즘 완전 폼 미쳤다",
+    "context": "A comment on a YouTube video about a popular singer.",
+    "action": "interpret",
+})
+print(json.dumps(result, indent=2, ensure_ascii=False))
+```
+
+## Limitations
+
+- **Not an LLM translator.** Unseen slang returns `unmatched`. Do not invent 줄임말 expansions.
+- **Snapshot dated 2026-09.** Internet Korean moves faster than a registry pack.
+- **Register gates are coarse.** `elders` suppresses slang; it does not implement a full 존댓말 grammar engine.
+- **Blocked list is not exhaustive.** New slurs will appear; the constitution is a floor, not a hate-speech classifier.
+- **Romanization is a lookup aid**, not official Revised Romanization for every vowel nuance.
+
+<!-- skill-history:begin -->
+## Skill history
+
+Commits that touched this skill bundle or its catalog page ([`linguistics/korean_slang`](https://github.com/ARPAHLS/skillware/tree/main/skills/linguistics/korean_slang)).
+
+| Commit | Description | Date | Version | Contributors |
+| :--- | :--- | :--- | :--- | :--- |
+| *(this PR)* | feat(linguistics): add korean_slang offline Gen-Z pack (#34) | 19 Sep 2026 | `0.1.0` | [@bd-c3](https://github.com/bd-c3) |
+<!-- skill-history:end -->
+
+## Enterprise disclaimer
+
+This skill is provided for demonstration and integration purposes. It is intended as a starting point that you can adapt to your own data, schemas, and operational requirements. For an enterprise-grade version of this skill with dedicated support, SLAs, and customization, contact skills@arpacorp.net.

docs/usage/agent_loops.md

@@ -167,6 +167,7 @@ skills in one harness.
 | `data_engineering/semantic_web_proxy` | `semantic_web_proxy_demo.py` (local execute) | (catalog page) | (catalog page) | (catalog page) | (catalog page) | (catalog page) |
 | `dev_tools/issue_resolver` | - | `gemini_issue_resolver.py` | `claude_issue_resolver.py` | (catalog page) | (catalog page) | `ollama_issue_resolver.py` |
 | `wellness/mental_coach` | `mental_coach_demo.py` (local execute) | (catalog page) | (catalog page) | (catalog page) | (catalog page) | (catalog page) |
+| `linguistics/korean_slang` | `korean_slang_demo.py` (local execute) | (catalog page) | (catalog page) | (catalog page) | (catalog page) | (catalog page) |
 | `defi/evm_tx_handler` | - | `gemini_evm_tx_handler.py` | `claude_evm_tx_handler.py` | - | - | - |
 | `monitoring/token_limiter` | `token_limiter_loop.py` (local execute) | `gemini_token_limiter.py`, `skill_context_gemini_loop.py` (multi-skill) | `claude_token_limiter.py` | (catalog page) | (catalog page) | (catalog page) |
 | `monitoring/kpi_gate` | `kpi_gate_demo.py` (local execute) | (catalog page) | (catalog page) | (catalog page) | (catalog page) | (catalog page) |

docs/usage/install_extras.md

@@ -74,6 +74,7 @@ Union of non-core `requirements` from every skill in the category.
 | `defi` | `defi/evm_tx_handler` | `web3>=6.0.0` |
 | `dev_tools` | `dev_tools/issue_resolver` | *(none today)* |
 | `finance` | `finance/uk_companies_house_handler`, `finance/wallet_screening` | *(none today)* |
+| `linguistics` | `linguistics/korean_slang` | *(none today)* |
 | `monitoring` | `monitoring/token_limiter`, `monitoring/kpi_gate` | *(none today)* |
 | `office` | `office/gmail_handler`, `office/pdf_form_filler` | `anthropic`, `pymupdf` |
 | `optimization` | `optimization/context_optimizer`, `optimization/prompt_rewriter` | `fastembed`, `numpy` |
@@ -105,6 +106,7 @@ One extra per bundled registry skill. Naming: `{category}_{skill_name}` (registr
 | `dev_tools_issue_resolver` | `dev_tools/issue_resolver` | *(none today)* | Use this extra in docs and installs |
 | `finance_uk_companies_house_handler` | `finance/uk_companies_house_handler` | *(none today)* | Use this extra in docs and installs |
 | `finance_wallet_screening` | `finance/wallet_screening` | *(none today)* | Use this extra in docs and installs |
+| `linguistics_korean_slang` | `linguistics/korean_slang` | *(none today)* | Use this extra in docs and installs |
 | `monitoring_token_limiter` | `monitoring/token_limiter` | *(none today)* | Use this extra in docs and installs |
 | `monitoring_kpi_gate` | `monitoring/kpi_gate` | *(none today)* | Use this extra in docs and installs |
 | `office_gmail_handler` | `office/gmail_handler` | *(none today)* | Use this extra in docs and installs |