paralleldrive · janhesters · Jan 20, 2026
diff --git a/.gitignore b/.gitignore
@@ -140,6 +140,7 @@ vite.config.ts.timestamp-*
 
 # AI agent tools
 .agent-tools/
+.claude/
 
 # Core dump files
 core

diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -1,3 +1,10 @@
+# Extract commands from skills/ and generate command files
+node bin/aidd.js --skills "$(git rev-parse --show-toplevel)"
+
+# Stage generated skills and command files
+git add 'skills/index.md' 2>/dev/null || true
+git add 'ai/commands/*.md' 2>/dev/null || true
+
 # Generate index.md files for ai/ folders
 node bin/aidd.js --index "$(git rev-parse --show-toplevel)"
 

diff --git a/AGENTS.md b/AGENTS.md
@@ -41,3 +41,54 @@ If any conflicts are detected between a requested task and the vision document,
 3. Ask the user to clarify how to resolve the conflict before proceeding
 
 Never proceed with a task that contradicts the vision without explicit user approval.
+
+## Agent Skills
+
+AIDD includes reusable skills in the `skills/` directory following the [agentskills.io](https://agentskills.io) specification. These skills work with any compatible agent (Claude Code, Cursor, etc.).
+
+### Available Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `aidd-discover` | Product discovery, user journeys, personas |
+| `aidd-task` | Plan and break down epics into tasks |
+| `aidd-execute` | Implement using TDD |
+| `aidd-review` | Code review with security focus |
+| `aidd-log` | Document changes to activity-log.md |
+| `aidd-commit` | Conventional commit formatting |
+| `aidd-user-test` | Generate human and AI test scripts |
+
+### Setup for Claude Code
+
+Claude Code doesn't natively support `AGENTS.md`. To enable AIDD:
+
+```bash
+# Copy or symlink AGENTS.md to CLAUDE.md
+cp AGENTS.md CLAUDE.md
+# or: ln -s AGENTS.md CLAUDE.md
+
+# Symlink skills directory
+mkdir -p .claude
+ln -s ../skills .claude/skills
+```
+
+### Setup for Cursor
+
+```bash
+# Symlink skills directory (Cursor also discovers .claude/skills)
+mkdir -p .cursor
+ln -s ../skills .cursor/skills
+```
+
+### Manual Invocation
+
+Primary commands invoke their corresponding skill:
+- `/task` - Plan a new epic
+- `/execute` - Implement with TDD
+- `/review` - Code review
+- `/discover` - Product discovery
+- `/commit` - Conventional commits
+- `/log` - Activity logging
+- `/user-test` - Generate test scripts
+
+For the complete command reference including sub-commands, see `skills/index.md`.
diff --git a/ai/commands/commit.md b/ai/commands/commit.md
@@ -1,15 +1,5 @@
-# Commit
+# /commit
 
-Act as a senior software engineer to commit changes to the repository in non-interactive modes ONLY, using the following template:
+create a conventional commit for staged changes
 
-"$type${[(scope)]}{[!]}: $description":where `[]` is optional and `!` is a breaking change
-
-Types: fix|feat|chore|docs|refactor|test|perf|build|ci|style|revert|$other
-
-Constraints {
-  When committing, don't log about logging in the commit message.
-  Use multiple -m flags, one for each log entry.
-  Limit the first commit message line length to 50 characters.
-  Use conventional commits with the supplied template.
-  Do NOT add new things to the CHANGELOG.md file.
-}
+Use the commit skill to create a conventional commit for staged changes.
diff --git a/ai/commands/discover.md b/ai/commands/discover.md
@@ -1,8 +1,5 @@
-## 🔍 Discover
+# /discover
 
-Use productmanager.mdc to discover a user journey, user story, or feature.
+Enter interactive product discovery planning mode
 
-Constraints {
-Begin by reading the file and asking the user relevant questions to spark the discovery process.
-Before beginning, read and respect the constraints in please.mdc.
-}
+Use the discover skill to enter interactive product discovery planning mode.
diff --git a/ai/commands/execute.md b/ai/commands/execute.md
@@ -1,8 +1,5 @@
-## ⚙️ Execute Task/Epic
+# /execute
 
-Use the task creator to execute a task epic.
+implement code using TDD (red-green-refactor cycle)
 
-Constraints {
-Before beginning, read and respect the constraints in please.mdc.
-Remember to use the TDD process if asked to implement code.
-}
+Use the execute skill to implement code using tdd (red-green-refactor cycle).
diff --git a/ai/commands/help.md b/ai/commands/help.md
@@ -1,8 +1,10 @@
-## ❓ Help
+# /help
 
-List commands from please.mdc and report them to the user.
+List available commands and their usage.
+
+Read [skills/index.md](../../skills/index.md) for complete command reference and build help text from it.
 
 Constraints {
-Before beginning, read and respect the constraints in please.mdc.
-Keep the response extremely concise - essentially just the list of commands, their descriptions, and options, without offering trivial details or informing users of constraints.
+  Before beginning, read and respect the constraints in @ai/rules/please.mdc.
+  Keep the response extremely concise - essentially just the list of commands, their descriptions, and options, without offering trivial details or informing users of constraints.
 }
diff --git a/ai/commands/index.md b/ai/commands/index.md
@@ -1,66 +1,50 @@
-# commands
+# AIDD Commands
 
-This index provides an overview of the contents in this directory.
+Primary workflow entry points. Each command activates its corresponding skill.
 
-## Files
+For complete command reference including sub-commands, see [skills/index.md](../../skills/index.md).
 
-### Commit
+## Commands
 
-**File:** `commit.md`
+### /commit
 
-*No description available*
+create a conventional commit for staged changes
 
-### discover
+**Skill:** [aidd-commit](../../skills/aidd-commit/SKILL.md)
 
-**File:** `discover.md`
+### /discover
 
-*No description available*
+Enter interactive product discovery planning mode
 
-### execute
+**Skill:** [aidd-discover](../../skills/aidd-discover/SKILL.md)
 
-**File:** `execute.md`
+### /execute
 
-*No description available*
+implement code using TDD (red-green-refactor cycle)
 
-### help
+**Skill:** [aidd-execute](../../skills/aidd-execute/SKILL.md)
 
-**File:** `help.md`
+### /log
 
-*No description available*
+log completed epics to activity-log.md
 
-### log
+**Skill:** [aidd-log](../../skills/aidd-log/SKILL.md)
 
-**File:** `log.md`
+### /review
 
-*No description available*
+conduct a thorough code review focusing on code quality, best practices, and adherence to project standards
 
-### plan
+**Skill:** [aidd-review](../../skills/aidd-review/SKILL.md)
 
-**File:** `plan.md`
+### /task
 
-*No description available*
+create a task/epic
 
-### 🔬 Code Review
+**Skill:** [aidd-task](../../skills/aidd-task/SKILL.md)
 
-**File:** `review.md`
+### /user-test
 
-*No description available*
+Generate human and agent scripts, save to $projectRoot/plan/
 
-### run-test
-
-**File:** `run-test.md`
-
-*No description available*
-
-### task
-
-**File:** `task.md`
-
-*No description available*
-
-### user-test
-
-**File:** `user-test.md`
-
-*No description available*
+**Skill:** [aidd-user-test](../../skills/aidd-user-test/SKILL.md)
 
diff --git a/ai/commands/log.md b/ai/commands/log.md
@@ -1,4 +1,5 @@
-## 📝 Log
+# /log
 
-Use log.mdc to collect salient changes, and log them to the activity-log.md.
-Before beginning, read and respect the constraints in please.mdc.
+log completed epics to activity-log.md
+
+Use the log skill to log completed epics to activity-log.md.
diff --git a/ai/commands/review.md b/ai/commands/review.md
@@ -1,7 +1,5 @@
-# 🔬 Code Review
+# /review
 
-use review.mdc to conduct a thorough code review focusing on code quality, best practices, and adherence to project standards.
+conduct a thorough code review focusing on code quality, best practices, and adherence to project standards
 
-Constraints {
-Before beginning, read and respect the constraints in please.mdc.
-}
+Use the review skill to conduct a thorough code review focusing on code quality, best practices, and adherence to project standards.
diff --git a/ai/commands/run-test.md b/ai/commands/run-test.md
diff --git a/ai/commands/task.md b/ai/commands/task.md
@@ -1,8 +1,5 @@
-## ✅ Task
+# /task
 
-Use the task creator to plan and execute a task epic.
+create a task/epic
 
-Constraints {
-Before beginning, read and respect the constraints in please.mdc.
-Remember to use the TDD process if asked to implement code.
-}
+Use the task skill to create a task/epic.
diff --git a/ai/commands/user-test.md b/ai/commands/user-test.md
@@ -1,7 +1,5 @@
-## 🧪 User Test
+# /user-test
 
-Use @user-testing.mdc to generate human and AI agent test scripts from user journeys.
+Generate human and agent scripts, save to $projectRoot/plan/
 
-Constraints {
-Before beginning, read and respect the constraints in please.mdc.
-}
+Use the user-test skill to generate human and agent scripts, save to $projectroot/plan/.
diff --git a/ai/rules/index.md b/ai/rules/index.md
@@ -16,6 +16,10 @@ See [`javascript/index.md`](./javascript/index.md) for contents.
 
 See [`security/index.md`](./security/index.md) for contents.
 
+### 📁 sudolang/
+
+See [`sudolang/index.md`](./sudolang/index.md) for contents.
+
 ## Files
 
 ### Aiden Agent Orchestrator

diff --git a/ai/rules/sudolang/index.md b/ai/rules/sudolang/index.md
@@ -0,0 +1,12 @@
+# sudolang
+
+This index provides an overview of the contents in this directory.
+
+## Files
+
+### SudoLang Syntax
+
+**File:** `sudolang-syntax.mdc`
+
+A quick cheat sheet for SudoLang syntax.
+
diff --git a/ai/rules/user-testing.test.js b/ai/rules/user-testing.test.js
@@ -71,44 +71,43 @@ describe("user-testing", () => {
       });
     });
 
-    test("references user-testing.mdc", async () => {
+    test("references user-test skill", async () => {
       const filePath = path.join(__dirname, "../commands/user-test.md");
       const content = await fs.readFile(filePath, "utf-8");
 
       assert({
         given: "user-test.md content",
-        should: "reference user-testing.mdc",
-        actual:
-          content.includes("@user-testing.mdc") ||
-          content.includes("user-testing.mdc"),
+        should: "reference user-test skill",
+        actual: content.includes("user-test skill"),
         expected: true,
       });
     });
   });
 
-  describe("run-test.md command", () => {
-    test("command file exists", async () => {
-      const filePath = path.join(__dirname, "../commands/run-test.md");
-      const exists = await fs.pathExists(filePath);
+  describe("/run-test sub-command", () => {
+    test("is documented in aidd-user-test skill", async () => {
+      const filePath = path.join(
+        __dirname,
+        "../../skills/aidd-user-test/SKILL.md",
+      );
+      const content = await fs.readFile(filePath, "utf-8");
 
       assert({
-        given: "run-test.md command file",
-        should: "exist in ai/commands directory",
-        actual: exists,
+        given: "aidd-user-test skill content",
+        should: "include /run-test sub-command in Commands block",
+        actual: content.includes("/run-test"),
         expected: true,
       });
     });
 
-    test("references user-testing.mdc", async () => {
-      const filePath = path.join(__dirname, "../commands/run-test.md");
+    test("is listed in skills index", async () => {
+      const filePath = path.join(__dirname, "../../skills/index.md");
       const content = await fs.readFile(filePath, "utf-8");
 
       assert({
-        given: "run-test.md content",
-        should: "reference user-testing.mdc",
-        actual:
-          content.includes("@user-testing.mdc") ||
-          content.includes("user-testing.mdc"),
+        given: "skills/index.md content",
+        should: "include /run-test command reference",
+        actual: content.includes("/run-test"),
         expected: true,
       });
     });