diff --git a/README.md b/README.md
index 2cceafd..30e5437 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,8 @@ restart Prime, or run `/reload` in a running session.
 
 ## use
 
+### for users (slash commands)
+
 ```text
 /threads                     list open and closed threads
 /threads done <id>           explicit user acceptance -> done
@@ -63,6 +65,17 @@ restart Prime, or run `/reload` in a running session.
 /threads reconcile           run the observer now
 ```
 
+### for agents (python skill)
+
+agents can inspect and control threads programmatically from the python REPL using the bundled `threads` skill:
+
+```python
+await threads.list()                                # list open and closed threads
+await threads.complete("t1", reason="done in test") # mark thread complete
+await threads.dismiss("t2", reason="obsolete")     # dismiss unwanted thread
+await threads.reopen("t3")                          # reopen a closed thread
+```
+
 nothing is hidden: every thread the model tracks is visible and correctable here.
 
 ### environment variables