From 20f35ffabb0c02641dbfbae72837aa665af91fdf Mon Sep 17 00:00:00 2001
From: Shaw Innes <shaw@immortal.net.au>
Date: Fri, 6 Mar 2026 22:07:55 +1000
Subject: [PATCH 1/2] docs: add skills command and managing skills section to
 README

---
 README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 64 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index ad9b76b..d2c1437 100644
--- a/README.md
+++ b/README.md
@@ -105,20 +105,80 @@ Usage
   $ aitool [command]
 
 Commands
+  agent     Manage and check AI coding agents
+  skills    Manage agent skills
   update    Update to the latest version
   version   Print the current version
 
 Options
-  --name  Your name
+  --json    Output as JSON
+  --tui     Force TUI rendering
 
 Examples
-  $ aitool --name=Jane
-  Hello, Jane
-
+  $ aitool agent check
+  $ aitool skills install https://github.com/org/my-skills.git
+  $ aitool skills update
   $ aitool version
   $ aitool update
 ```
 
+## Managing Skills
+
+Skills are reusable instruction sets for AI coding agents. The `skills` command installs them from
+a Git repository and symlinks them into `~/.claude/skills/` and `~/.agents/skills/` so agents can
+discover and use them.
+
+### Install skills from a repo
+
+```bash
+aitool skills install https://github.com/org/my-skills.git
+# or via SSH
+aitool skills install git@github.com:org/my-skills.git
+```
+
+The repo is cloned into `~/.agent-skills/<repo-name>` and each skill is symlinked into the agent
+skill directories. Re-running install on an already-present skill is safe — existing links are
+skipped.
+
+### Update installed skills
+
+```bash
+aitool skills update
+```
+
+Pulls the latest changes for every installed skills repo and links any newly added skills.
+
+### Skills repo structure
+
+A skills repository only needs a top-level `skills/` folder. Each subdirectory inside it is one
+skill:
+
+```
+my-skills/
+└── skills/
+    ├── commit/
+    │   └── SKILL.md
+    ├── testing/
+    │   └── SKILL.md
+    └── code-review/
+        └── SKILL.md
+```
+
+Each `SKILL.md` has a short YAML front matter block followed by the skill's instructions:
+
+```markdown
+---
+name: commit
+description: Create a git commit with a conventional commit message
+---
+
+## Instructions
+
+...
+```
+
+That's the full required structure — no config files, manifests, or build steps needed.
+
 ## Releases
 
 Releases are automated via GitHub Actions. To publish a new version:

From 83886090f7b18d28938b76adb181ce55de7556e2 Mon Sep 17 00:00:00 2001
From: Shaw Innes <shaw@immortal.net.au>
Date: Fri, 6 Mar 2026 22:10:36 +1000
Subject: [PATCH 2/2] doc: Update README

---
 README.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/README.md b/README.md
index d2c1437..71c0a3c 100644
--- a/README.md
+++ b/README.md
@@ -209,7 +209,3 @@ bun run build:all
 ```
 
 
-### Experiment - BD/Beads for Issue Tracking
-
-sudo bash -c 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash'
-curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash