skillware 0.3.3__tar.gz → 0.3.5__tar.gz

{skillware-0.3.3/skillware.egg-info → skillware-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillware
-Version: 0.3.3
+Version: 0.3.5
 Summary: A framework for modular, self-contained AI skills.
 Author-email: ARPA Hellenic Logical Systems <skillware-os@arpacorp.net>
 License: MIT License
@@ -255,7 +255,7 @@ Also read the [Agent Code of Conduct](CODE_OF_CONDUCT.md). Open PRs with the [pu
 
 ## Comparison
 
-Skillware differs from the Model Context Protocol (MCP), and Anthropic's Skills repository in several ways:
+Skillware differs from the Model Context Protocol (MCP), and Agent Skills (SKILL.md) in several ways:
 
 *   **Model Agnostic**: Native adapters for Gemini, Claude, Ollama, and OpenAI.
 *   **Code-First**: Skills are executable Python packages, not just server specs.

{skillware-0.3.3 → skillware-0.3.5}/README.md

@@ -192,7 +192,7 @@ Also read the [Agent Code of Conduct](CODE_OF_CONDUCT.md). Open PRs with the [pu
 
 ## Comparison
 
-Skillware differs from the Model Context Protocol (MCP), and Anthropic's Skills repository in several ways:
+Skillware differs from the Model Context Protocol (MCP), and Agent Skills (SKILL.md) in several ways:
 
 *   **Model Agnostic**: Native adapters for Gemini, Claude, Ollama, and OpenAI.
 *   **Code-First**: Skills are executable Python packages, not just server specs.

{skillware-0.3.3 → skillware-0.3.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillware"
-version = "0.3.3"
+version = "0.3.5"
 description = "A framework for modular, self-contained AI skills."
 readme = "README.md"
 authors = [
@@ -69,3 +69,7 @@ include = ["skillware*", "skills*"]
 # and this wildcard. No per-skill entries needed when adding registry skills.
 [tool.setuptools.package-data]
 skills = ["**/*"]
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]

{skillware-0.3.3 → skillware-0.3.5}/skills/compliance/pii_masker/skill.py

@@ -11,10 +11,7 @@ class PIIMaskerSkill(BaseSkill):
 
     @property
     def manifest(self) -> Dict[str, Any]:
-        return {
-            "name": "compliance/pii_masker",
-            "version": "0.1.0"
-        }
+        return {"name": "compliance/pii_masker", "version": "0.1.0"}
 
     def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
         text = params.get("text", "")
@@ -25,7 +22,7 @@ class PIIMaskerSkill(BaseSkill):
         sanitized_text = self._apply_mode(sanitized_text, mode)
 
         # Build unique entity types list
-        entities = list(set([re.sub(r'_[0-9]+$', '', e) for e in detected_entities]))
+        entities = list(set([re.sub(r"_[0-9]+$", "", e) for e in detected_entities]))
 
         return {
             "sanitized_text": sanitized_text,
@@ -33,17 +30,21 @@ class PIIMaskerSkill(BaseSkill):
                 "detected_entities": entities,
                 "entity_count": len(detected_entities),
                 "security_level": "local-only",
-                "model": "arpacorp/micro-f1-mask"
-            }
+                "model": "arpacorp/micro-f1-mask",
+            },
         }
 
     def _call_ollama(self, text: str, endpoint: str) -> Tuple[str, List[str]]:
         try:
-            response = requests.post(f"{endpoint}/api/generate", json={
-                "model": "arpacorp/micro-f1-mask",
-                "prompt": text,
-                "stream": False
-            }, timeout=30)
+            response = requests.post(
+                f"{endpoint}/api/generate",
+                json={
+                    "model": "arpacorp/micro-f1-mask",
+                    "prompt": text,
+                    "stream": False,
+                },
+                timeout=30,
+            )
             if response.status_code == 200:
                 result_text = response.json().get("response", text)
             else:
@@ -56,7 +57,7 @@ class PIIMaskerSkill(BaseSkill):
             result_text = text
 
         # Detect entities in the response
-        detected = re.findall(r'\[([A-Z_]+(?:_[0-9]+)?)\]', result_text)
+        detected = re.findall(r"\[([A-Z_]+(?:_[0-9]+)?)\]", result_text)
         return result_text, detected
 
     def _apply_mode(self, text: str, mode: str) -> str:
@@ -64,14 +65,14 @@ class PIIMaskerSkill(BaseSkill):
             return text
 
         # Pattern to catch [DOCUMENT], [PERSON_1], etc.
-        pattern = r'\[[A-Z_]+(?:_[0-9]+)?\]'
+        pattern = r"\[[A-Z_]+(?:_[0-9]+)?\]"
         if mode == "redact":
             return re.sub(pattern, "XXXX", text)
         elif mode == "remove":
             # Replace token and any immediate preceding/following spaces safely
             # A simple sub is sufficient. Cleaning up double spaces.
             text = re.sub(pattern, "", text)
-            text = re.sub(r'\s+', ' ', text).strip()
+            text = re.sub(r"\s+", " ", text).strip()
             return text
 
         return text

{skillware-0.3.3 → skillware-0.3.5}/skills/compliance/tos_evaluator/skill.py

@@ -213,7 +213,9 @@ class TOSEvaluatorSkill(BaseSkill):
         try:
             response = self.session.get(robots_url, timeout=10)
             if response.status_code >= 400:
-                assessment["reason"] = f"robots.txt returned HTTP {response.status_code}."
+                assessment["reason"] = (
+                    f"robots.txt returned HTTP {response.status_code}."
+                )
                 return assessment
 
             parser = RobotFileParser()
@@ -266,13 +268,20 @@ class TOSEvaluatorSkill(BaseSkill):
                 else:
                     candidates[item["url"]] = item
 
-        ordered = sorted(candidates.values(), key=lambda item: item["score"], reverse=True)
+        ordered = sorted(
+            candidates.values(), key=lambda item: item["score"], reverse=True
+        )
         return {"candidates": ordered[:max_terms_pages]}
 
-    def _extract_candidate_links(self, page_url: str, origin: str) -> List[Dict[str, Any]]:
+    def _extract_candidate_links(
+        self, page_url: str, origin: str
+    ) -> List[Dict[str, Any]]:
         links: List[Dict[str, Any]] = []
         response = self._safe_get(page_url, timeout=10)
-        if not response or "html" not in response.headers.get("Content-Type", "").lower():
+        if (
+            not response
+            or "html" not in response.headers.get("Content-Type", "").lower()
+        ):
             return links
 
         soup = BeautifulSoup(response.text[:300000], "html.parser")
@@ -449,7 +458,10 @@ class TOSEvaluatorSkill(BaseSkill):
             return False
         if robots_assessment.get("can_fetch") is False:
             return False
-        return bool(tos_assessment.get("matched_clauses") or tos_assessment["status"] == "caution")
+        return bool(
+            tos_assessment.get("matched_clauses")
+            or tos_assessment["status"] == "caution"
+        )
 
     def _run_llm_evaluator(
         self, normalized: Dict[str, Any], tos_assessment: Dict[str, Any]
@@ -512,26 +524,33 @@ class TOSEvaluatorSkill(BaseSkill):
         verdict = "INSUFFICIENT_EVIDENCE"
         confidence_score = 0.35
         reason = "Insufficient policy evidence to safely approve the requested action."
-        recommended_next_step = "Review the discovered policy pages manually before proceeding."
+        recommended_next_step = (
+            "Review the discovered policy pages manually before proceeding."
+        )
 
         if robots_assessment.get("can_fetch") is False:
             verdict = "UNSAFE"
             confidence_score = 0.98
             reason = robots_assessment["reason"]
-            recommended_next_step = (
-                "Do not automate access to this path unless you have explicit permission."
-            )
+            recommended_next_step = "Do not automate access to this path unless you have explicit permission."
         elif tos_assessment["status"] == "blocked":
             verdict = "UNSAFE"
             confidence_score = 0.9
             reason = tos_assessment["summary"]
-            recommended_next_step = "Avoid the requested action or obtain explicit written permission."
+            recommended_next_step = (
+                "Avoid the requested action or obtain explicit written permission."
+            )
         elif tos_assessment["status"] == "caution":
             verdict = "CAUTION"
             confidence_score = 0.65
             reason = tos_assessment["summary"]
-            recommended_next_step = "Prefer an official API or documented integration path if one exists."
-        elif tos_assessment["status"] == "allowed" and robots_assessment.get("can_fetch") is not False:
+            recommended_next_step = (
+                "Prefer an official API or documented integration path if one exists."
+            )
+        elif (
+            tos_assessment["status"] == "allowed"
+            and robots_assessment.get("can_fetch") is not False
+        ):
             verdict = "SAFE"
             confidence_score = 0.72
             reason = tos_assessment["summary"]
@@ -575,7 +594,9 @@ class TOSEvaluatorSkill(BaseSkill):
             "tos_assessment": tos_assessment,
             "llm_assessment": llm_assessment or {"status": "not_used"},
             "discovered_policy_urls": {
-                "candidates": [item["url"] for item in policy_candidates.get("candidates", [])]
+                "candidates": [
+                    item["url"] for item in policy_candidates.get("candidates", [])
+                ]
             },
             "evidence": evidence,
         }

{skillware-0.3.3 → skillware-0.3.5}/skills/data_engineering/synthetic_generator/skill.py

@@ -18,6 +18,7 @@ class SyntheticGeneratorSkill(BaseSkill):
         manifest_path = os.path.join(os.path.dirname(__file__), "manifest.yaml")
         if os.path.exists(manifest_path):
             import yaml
+
             with open(manifest_path, "r", encoding="utf-8") as f:
                 return yaml.safe_load(f)
         return {}
@@ -35,16 +36,11 @@ class SyntheticGeneratorSkill(BaseSkill):
         # Scaled for readability
         return round(min(ratio * 1.5, 1.0), 3)
 
-    def _call_gemini(
-        self, prompt: str, temperature: float, model_name: str
-    ) -> str:
+    def _call_gemini(self, prompt: str, temperature: float, model_name: str) -> str:
         import google.genai as genai
         from google.genai import types
 
-        api_key = (
-            self.config.get("GOOGLE_API_KEY")
-            or os.environ.get("GOOGLE_API_KEY")
-        )
+        api_key = self.config.get("GOOGLE_API_KEY") or os.environ.get("GOOGLE_API_KEY")
         client = genai.Client(api_key=api_key)
         response = client.models.generate_content(
             model=model_name,
@@ -53,31 +49,28 @@ class SyntheticGeneratorSkill(BaseSkill):
         )
         return response.text
 
-    def _call_anthropic(
-        self, prompt: str, temperature: float, model_name: str
-    ) -> str:
+    def _call_anthropic(self, prompt: str, temperature: float, model_name: str) -> str:
         import anthropic
-        api_key = (
-            self.config.get("ANTHROPIC_API_KEY")
-            or os.environ.get("ANTHROPIC_API_KEY")
+
+        api_key = self.config.get("ANTHROPIC_API_KEY") or os.environ.get(
+            "ANTHROPIC_API_KEY"
         )
         client = anthropic.Anthropic(api_key=api_key)
         message = client.messages.create(
             model=model_name,
             max_tokens=4096,
             temperature=temperature,
-            messages=[{"role": "user", "content": prompt}]
+            messages=[{"role": "user", "content": prompt}],
         )
         return message.content[0].text
 
-    def _call_ollama(
-        self, prompt: str, temperature: float, model_name: str
-    ) -> str:
+    def _call_ollama(self, prompt: str, temperature: float, model_name: str) -> str:
         import ollama
+
         response = ollama.chat(
             model=model_name,
             messages=[{"role": "user", "content": prompt}],
-            options={"temperature": temperature}
+            options={"temperature": temperature},
         )
         return response.get("message", {}).get("content", "")
 
@@ -107,21 +100,15 @@ class SyntheticGeneratorSkill(BaseSkill):
 
         try:
             if provider == "gemini":
-                raw_text = self._call_gemini(
-                    system_prompt, temperature, model_name
-                )
+                raw_text = self._call_gemini(system_prompt, temperature, model_name)
             elif provider == "anthropic":
-                raw_text = self._call_anthropic(
-                    system_prompt, temperature, model_name
-                )
+                raw_text = self._call_anthropic(system_prompt, temperature, model_name)
             else:
-                raw_text = self._call_ollama(
-                    system_prompt, temperature, model_name
-                )
+                raw_text = self._call_ollama(system_prompt, temperature, model_name)
         except Exception as e:
             return {
                 "status": "error",
-                "message": f"LLM Call Failed via {provider}: {str(e)}"
+                "message": f"LLM Call Failed via {provider}: {str(e)}",
             }
 
         samples = []
@@ -141,7 +128,7 @@ class SyntheticGeneratorSkill(BaseSkill):
             return {
                 "status": "error",
                 "message": f"Parsing failed: {e}",
-                "raw_output": raw_text
+                "raw_output": raw_text,
             }
 
         all_text = " ".join([str(s) for s in samples])
@@ -152,5 +139,5 @@ class SyntheticGeneratorSkill(BaseSkill):
             "entropy_score": score,
             "status": "success",
             "provider_used": provider,
-            "samples_generated": len(samples)
+            "samples_generated": len(samples),
         }

skillware-0.3.5/skills/defi/evm_tx_handler/abis.py

@@ -0,0 +1,136 @@
+"""Minimal contract ABIs for Uniswap V2 router and ERC20."""
+
+ROUTER_V2_ABI = [
+    {
+        "name": "getAmountsOut",
+        "type": "function",
+        "stateMutability": "view",
+        "inputs": [
+            {"name": "amountIn", "type": "uint256"},
+            {"name": "path", "type": "address[]"},
+        ],
+        "outputs": [{"name": "amounts", "type": "uint256[]"}],
+    },
+    {
+        "name": "getAmountsIn",
+        "type": "function",
+        "stateMutability": "view",
+        "inputs": [
+            {"name": "amountOut", "type": "uint256"},
+            {"name": "path", "type": "address[]"},
+        ],
+        "outputs": [{"name": "amounts", "type": "uint256[]"}],
+    },
+    {
+        "name": "swapExactTokensForTokens",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "amountIn", "type": "uint256"},
+            {"name": "amountOutMin", "type": "uint256"},
+            {"name": "path", "type": "address[]"},
+            {"name": "to", "type": "address"},
+            {"name": "deadline", "type": "uint256"},
+        ],
+        "outputs": [{"name": "amounts", "type": "uint256[]"}],
+    },
+    {
+        "name": "swapTokensForExactTokens",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "amountOut", "type": "uint256"},
+            {"name": "amountInMax", "type": "uint256"},
+            {"name": "path", "type": "address[]"},
+            {"name": "to", "type": "address"},
+            {"name": "deadline", "type": "uint256"},
+        ],
+        "outputs": [{"name": "amounts", "type": "uint256[]"}],
+    },
+    {
+        "name": "swapExactETHForTokens",
+        "type": "function",
+        "stateMutability": "payable",
+        "inputs": [
+            {"name": "amountOutMin", "type": "uint256"},
+            {"name": "path", "type": "address[]"},
+            {"name": "to", "type": "address"},
+            {"name": "deadline", "type": "uint256"},
+        ],
+        "outputs": [{"name": "amounts", "type": "uint256[]"}],
+    },
+    {
+        "name": "swapETHForExactTokens",
+        "type": "function",
+        "stateMutability": "payable",
+        "inputs": [
+            {"name": "amountOut", "type": "uint256"},
+            {"name": "path", "type": "address[]"},
+            {"name": "to", "type": "address"},
+            {"name": "deadline", "type": "uint256"},
+        ],
+        "outputs": [{"name": "amounts", "type": "uint256[]"}],
+    },
+    {
+        "name": "swapExactTokensForETH",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "amountIn", "type": "uint256"},
+            {"name": "amountOutMin", "type": "uint256"},
+            {"name": "path", "type": "address[]"},
+            {"name": "to", "type": "address"},
+            {"name": "deadline", "type": "uint256"},
+        ],
+        "outputs": [{"name": "amounts", "type": "uint256[]"}],
+    },
+]
+
+ERC20_ABI = [
+    {
+        "name": "balanceOf",
+        "type": "function",
+        "stateMutability": "view",
+        "inputs": [{"name": "account", "type": "address"}],
+        "outputs": [{"name": "", "type": "uint256"}],
+    },
+    {
+        "name": "decimals",
+        "type": "function",
+        "stateMutability": "view",
+        "inputs": [],
+        "outputs": [{"name": "", "type": "uint8"}],
+    },
+    {
+        "name": "allowance",
+        "type": "function",
+        "stateMutability": "view",
+        "inputs": [
+            {"name": "owner", "type": "address"},
+            {"name": "spender", "type": "address"},
+        ],
+        "outputs": [{"name": "", "type": "uint256"}],
+    },
+    {
+        "name": "approve",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "spender", "type": "address"},
+            {"name": "amount", "type": "uint256"},
+        ],
+        "outputs": [{"name": "", "type": "bool"}],
+    },
+    {
+        "name": "transfer",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "to", "type": "address"},
+            {"name": "amount", "type": "uint256"},
+        ],
+        "outputs": [{"name": "", "type": "bool"}],
+    },
+]
+
+MAX_UINT256 = 2**256 - 1

skillware-0.3.5/skills/defi/evm_tx_handler/card.json

@@ -0,0 +1,20 @@
+{
+  "name": "EVM Tx Handler",
+  "description": "Quote and transfer from a dedicated agent wallet on Ethereum and Base.",
+  "issuer": {
+    "name": "Hendobox",
+    "email": "henryonyebuchi53@gmail.com",
+    "github": "Hendobox",
+    "org": "ARPAHLS"
+  },
+  "icon": "wallet",
+  "color": "emerald",
+  "ui_schema": {
+    "type": "card",
+    "fields": [
+      {"key": "preview.you_pay", "label": "You pay"},
+      {"key": "preview.you_receive", "label": "You receive"},
+      {"key": "tx_hash", "label": "Transaction", "type": "link"}
+    ]
+  }
+}

skillware-0.3.5/skills/defi/evm_tx_handler/config.yaml.example

@@ -0,0 +1,11 @@
+# Long-term preferences (copy to config.yaml beside this file). No secrets.
+default_chain: ethereum
+default_spend_asset: usdc
+gas_policy: normal
+confirm_before_send: true
+slippage_bps: 50
+max_trade_usd: 500
+private_key_env: AGENT_WALLET_PRIVATE_KEY
+# Optional guardrails (omit to allow all configured chains/tokens)
+# allowed_chains: [ethereum, base]
+# allowed_tokens: [usdc, weth, eth]

skillware-0.3.5/skills/defi/evm_tx_handler/data/addressbook.yaml

@@ -0,0 +1,4 @@
+# Label (lowercase) -> checksummed address. Replace placeholders before mainnet use.
+# Example only — do not send real funds to these addresses.
+mom: "0x000000000000000000000000000000000000dEaD"
+george: "0x000000000000000000000000000000000000dEaD"

skillware-0.3.5/skills/defi/evm_tx_handler/data/chains.yaml

@@ -0,0 +1,18 @@
+# Verified Uniswap V2 Router02 deployments (re-check before mainnet use).
+ethereum:
+  chain_id: 1
+  rpc_env: ETHEREUM_RPC_URL
+  native_symbol: eth
+  native_decimals: 18
+  explorer_tx_url: "https://etherscan.io/tx/{tx_hash}"
+  router_v2: "0x7a250d5630B4cF539739dF2C5dA4bF9C15291ECE"
+  weth: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
+
+base:
+  chain_id: 8453
+  rpc_env: BASE_RPC_URL
+  native_symbol: eth
+  native_decimals: 18
+  explorer_tx_url: "https://basescan.org/tx/{tx_hash}"
+  router_v2: "0x4752ba5DBC23f44d87826276bf6fd6b1c372aD24"
+  weth: "0x4200000000000000000000000000000000000006"

skillware-0.3.5/skills/defi/evm_tx_handler/data/tokens.yaml

@@ -0,0 +1,25 @@
+# Friendly symbol (lowercase) -> contract per chain. Extend via PR; do not edit skill.py.
+ethereum:
+  eth:
+    native: true
+    decimals: 18
+  weth:
+    address: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
+    decimals: 18
+  usdc:
+    address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+    decimals: 6
+
+base:
+  eth:
+    native: true
+    decimals: 18
+  weth:
+    address: "0x4200000000000000000000000000000000000006"
+    decimals: 18
+  usdc:
+    address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+    decimals: 6
+  degen:
+    address: "0x4ed4e862860bed51a9570b96d89af5e1b0efefed"
+    decimals: 18

skillware-0.3.5/skills/defi/evm_tx_handler/instructions.md

@@ -0,0 +1,81 @@
+# EVM Transaction Handler
+
+You are equipped with **`evm_tx_handler`**: a deterministic EVM tool for a **dedicated agent wallet** on Ethereum and Base.
+
+## Your job vs the skill's job
+
+| You (agent) | Skill |
+|-------------|--------|
+| Parse natural language into partial `intent` JSON | Merge intent with `config.yaml` and YAML registries |
+| Ask for missing fields in plain language | Return `missing_fields` and `suggested_defaults` |
+| Show `preview` to the user and obtain approval | Build on-chain quotes; sign swaps and transfers when confirmed |
+| Pass `confirmed: true` after approval | Approve (if needed), swap, or transfer; return tx hash + receipt |
+
+**Do not** expect the skill to parse free text. **Do not** pass private keys in tool arguments.
+
+## Quote vs execute (important)
+
+- **`quote` / `preview`** use live router math at call time.
+- **`execute` re-quotes on-chain at broadcast time** using a fresh quote built from the same intent.
+- Preview amounts, rates, and USD hints **may drift** between preview and execute.
+- **Always call `quote` or `preview` immediately before** asking the user to confirm and before `execute`.
+
+## ERC20 swaps: approve then swap
+
+When the spend asset is an ERC20, the router may need allowance:
+
+1. Optional **`needs_confirmation`** when `confirm_before_send` is true (human-in-the-loop).
+2. On **`execute`**, the skill may broadcast an **`approve`** transaction first, wait for confirmation, then broadcast the **swap**.
+3. If the response includes `approve_tx_hash`, tell the user this was a **two-step** flow (approve, then swap).
+
+Native ETH spends skip ERC20 approve but still consume ETH for gas.
+
+## Actions
+
+| Action | Use when |
+|--------|----------|
+| `resolve` | Intent is incomplete — check `missing_fields` |
+| `quote` | Buy/sell intent is complete — get amounts, path, optional USD |
+| `preview` | Same as quote but preview-focused response |
+| `execute` | User confirmed — broadcast Uni V2 swap (fresh on-chain quote) |
+| `transfer` | Send native ETH or ERC20 to `0x…` or addressbook label |
+| `balances` | List wallet balances on a chain |
+| `wallet_info` | Agent address, chains, preferences (no secrets) |
+| `update_preferences` | User explicitly asks to change defaults in `config.yaml` |
+
+## Typical buy flow
+
+1. User: “Buy 10 Degen on Base with USDC.”
+2. `resolve` with `{ "side": "buy", "chain": "base", "target_asset": "degen", "amount": 10, "amount_kind": "target_out" }`.
+3. If `spend_asset` missing, ask user; suggest `suggested_defaults.spend_asset`.
+4. `quote` then show `preview` (you pay / you receive, rate, gas, warnings, optional `usd`).
+5. After explicit user approval, `execute` with the same intent and **`confirmed: true`** (run quote/preview again if more than a few seconds passed).
+
+## Transfer flow
+
+1. Build intent: `chain`, `target_asset`, `amount`, `recipient` (label or address).
+2. `transfer` without `confirmed` first if `confirm_before_send` — skill returns `needs_confirmation`.
+3. After user approves, `transfer` with `confirmed: true`.
+
+## Pre-flight balances
+
+Before swap or transfer broadcast, the skill checks wallet balance (and native ETH for gas on ERC20 operations). On failure you get `status: insufficient_balance` with `agent_hint` — surface this clearly and do not retry execute until funded.
+
+## Wallet key missing
+
+If you see `status: missing_config`, the dedicated agent wallet key is not in `.env`. Follow `setup` in the JSON (env var name, docs links). Never ask the user to paste a private key into chat or tool args.
+
+## Intent fields
+
+- `side`: `buy` | `sell` (transfers use action `transfer`)
+- `chain`: `ethereum` | `base` (default from config)
+- `target_asset` / `spend_asset`: symbols from `data/tokens.yaml`
+- `amount` + `amount_kind`: `target_out` for “buy 10 DEGEN”; `spend_in` for “sell 100 DEGEN”
+- `recipient`: addressbook label or `0x` address
+- `gas_policy`: `low` | `normal` | `high` | `aggressive` (per-tx only; does not persist)
+
+## Safety
+
+- Always preview before `execute` or `transfer`.
+- `max_trade_usd` in config blocks quotes/executes when USD price is unavailable (fail closed).
+- Recommend `finance/wallet_screening` for unknown recipient addresses before large sends.