[codex] Clarify Python SDK skill invocation

examples/test_skill_tool.py

@@ -9,7 +9,6 @@
 4. Verifying permission isolation works
 """
 
-import asyncio
 import os
 import sys
 import tempfile
@@ -21,7 +20,7 @@
 
 from a3s_code import Agent
 
-async def main():
+def main():
     print("=" * 80)
     print("Skill Tool Test with Kimi Model")
     print("=" * 80)
@@ -90,7 +89,7 @@ async def main():
 
         try:
             print("\n💬 Prompt: Use the file-reader skill to read test.txt")
-            result = await session.send(
+            result = session.send(
                 "Use the file-reader skill to read test.txt and tell me what it contains"
             )
             print(f"\n✅ Response:\n{result.text}")
@@ -107,7 +106,7 @@ async def main():
 
         try:
             print("\n💬 Prompt: Use the file-reader skill to search for 'test' in all files")
-            result = await session.send(
+            result = session.send(
                 "Use the file-reader skill to search for the word 'test' in all files"
             )
             print(f"\n✅ Response:\n{result.text}")
@@ -124,7 +123,7 @@ async def main():
 
         try:
             print("\n💬 Prompt: Use the file-reader skill to write a summary to output.txt")
-            result = await session.send(
+            result = session.send(
                 "Use the file-reader skill to write a summary of test.txt to output.txt"
             )
             print(f"\n✅ Response:\n{result.text}")
@@ -146,4 +145,4 @@ async def main():
         print("=" * 80)
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    main()

sdk/python/README.md

@@ -280,6 +280,24 @@ session.tool("dynamic_workflow", {
 })
 session.unregister_dynamic_tool("dynamic_workflow")
 
+# Folder-style skills
+workspace = "/my-project"
+skill_dir = f"{workspace}/skills"
+session = agent.session(workspace, skill_dirs=[skill_dir])
+matches = session.tool("search_skills", {"query": "review database schema", "limit": 5})
+print(matches.output)
+
+skill_result = session.tool("Skill", {
+    "skill_name": "db-review",
+    "prompt": "Review the migrations and summarize correctness risks.",
+})
+print(skill_result.output)
+
+# Or configure skill directories through SessionOptions.
+opts = SessionOptions()
+opts.skill_dirs = [skill_dir]
+session = agent.session(workspace, opts)
+
 # S3-compatible workspace — point the same direct tools at object storage.
 # `bash`, `git`, `grep`, `glob` are automatically hidden because object
 # storage cannot service them. Works with AWS S3, MinIO, RustFS, R2, B2.

sdk/python/docs/QUICK_REFERENCE.md

@@ -1,4 +1,4 @@
-# A3S Code Python SDK 2.3 Quick Reference
+# A3S Code Python SDK Quick Reference
 
 This page is the short, current reference for the Python SDK.
 
@@ -74,6 +74,29 @@ session.unregister_dynamic_tool("dynamic_workflow")
 Direct tools bypass the LLM and are useful for deterministic checks,
 diagnostics, and tests.
 
+## Skills
+
+```python
+session = agent.session(".", skill_dirs=["./skills"])
+
+matches = session.tool("search_skills", {
+    "query": "review database schema",
+    "limit": 5,
+})
+print(matches.output)
+
+result = session.tool("Skill", {
+    "skill_name": "db-review",
+    "prompt": "Review the migrations and summarize correctness risks.",
+})
+print(result.output)
+```
+
+`search_skills` is a deterministic direct tool. `Skill` loads the selected
+folder-style skill and then runs the configured model with that skill's
+temporary allowed-tools grant, so the session still needs a working provider
+configuration.
+
 ## Evidence
 
 ```python

sdk/python/src/session.rs

@@ -846,7 +846,7 @@ impl PySession {
     ///         return f"pong! session={ctx['session_id']}"
     ///
     ///     session.register_command("ping", "Pong!", ping_handler)
-    ///     result = await session.send("/ping hello")
+    ///     result = session.send("/ping hello")
     #[pyo3(signature = (name, description, handler))]
     fn register_command(
         &self,