Add create-skill command with validation and documentation

.gitignore

@@ -149,3 +149,6 @@ core.*
 # Local AIDD database
 .aidd/
 
+# Compiled validate-skill binary (built via npm run build:validate-skill)
+ai/skills/aidd-upskill/scripts/validate-skill
+

ai-evals/aidd-upskill/caveman-test.sudo

@@ -0,0 +1,18 @@
+# caveman-test.sudo
+
+import 'ai/skills/aidd-upskill/SKILL.md'
+
+userPrompt = """
+Use caveman() to evaluate this skill design decision:
+
+A skill is being designed to both fetch external API data AND format the response
+into a markdown report. Should these two responsibilities live in a single skill
+command, or be split into two separate commands?
+"""
+
+- Given the caveman() function is invoked, should produce a 🎯 restate stage that restates the problem in plain terms (e.g. one command vs two commands, fetch + format responsibilities)
+- Given the caveman() function is invoked, should produce a 💡 ideate stage that generates at least two distinct design options (e.g. single combined command, split into fetch and format commands)
+- Given the caveman() function is invoked, should produce a 🪞 reflect stage that critically identifies a flaw in the ideation — such as noting that mixing a side effect (fetch) with a thinking stage (format) violates the "never mix thinking and effects" constraint from the skill
+- Given the caveman() function is invoked, should produce a 🔭 expand stage that explores orthogonal considerations not yet covered (e.g. testability, composability, progressive disclosure)
+- Given the caveman() function is invoked, should produce a ⚖️ score stage that ranks or evaluates the options against explicit criteria
+- Given the caveman() function is invoked, should produce a 💬 respond stage with a concrete recommendation

ai-evals/aidd-upskill/dedup-test.sudo

@@ -0,0 +1,17 @@
+# dedup-test.sudo
+
+import 'ai/skills/aidd-upskill/SKILL.md'
+
+userPrompt = """
+Run deduplicateWithCaveman() on the following two files:
+
+SKILL.md body: ai-evals/aidd-upskill/fixtures/dedup-skill.md
+Reference file: ai-evals/aidd-upskill/fixtures/dedup-reference.md
+
+Identify every piece of information that appears in both files and determine
+where the single source of truth should live.
+"""
+
+- Given the SkillName constraints (lowercase alphanumeric, 1-64 chars, aidd- prefix, match parent dir) appear in both dedup-skill.md and dedup-reference.md, should identify the name constraint rules as duplicated information present in both files
+- Given the name constraints are duplicated, should identify the reference file (dedup-reference.md) as the canonical location because it is titled "Name Constraints" and explicitly notes it is the canonical definition
+- Given the name constraints are in the reference file, should recommend removing the duplicated name constraint prose from the SKILL.md body and relying solely on the import of the reference file

ai-evals/aidd-upskill/fixtures/dedup-reference.md

@@ -0,0 +1,10 @@
+# Name Constraints
+
+The `name` field in a SKILL.md frontmatter must be:
+
+- lowercase alphanumeric with hyphens
+- 1-64 characters
+- prefixed with `aidd-`
+- must match the parent directory name
+
+This is the canonical definition of `SkillName` constraints.

ai-evals/aidd-upskill/fixtures/dedup-skill.md

@@ -0,0 +1,24 @@
+---
+name: aidd-example-dedup
+description: Example skill used to test deduplication detection. Use when running dedup eval tests.
+---
+
+# aidd-example-dedup
+
+## Skill Structure
+
+Skills follow this directory layout:
+
+```
+ai/skills/aidd-<verbOrRoleBasedNoun>/
+├── SKILL.md          # Required: frontmatter + instructions
+├── scripts/          # Optional: CLI tools
+├── references/       # Optional: detailed reference docs
+└── assets/           # Optional: templates, data files
+```
+
+Frontmatter must include `name` and `description`. The `name` field must be
+lowercase alphanumeric with hyphens, 1-64 characters, prefixed with `aidd-`,
+and must match the parent directory name.
+
+import ai-evals/aidd-upskill/fixtures/dedup-reference.md

ai-evals/aidd-upskill/fixtures/sample-format-skill.md

@@ -0,0 +1,30 @@
+---
+name: aidd-format-changelog
+description: Format a list of git commits into a structured markdown changelog. Use when generating release notes or changelogs from commit history.
+---
+
+# aidd-format-changelog
+
+Given a list of raw git commit messages, produce a markdown changelog grouped
+by conventional commit type (feat, fix, chore, etc.) with each entry on its
+own line.
+
+## Steps
+
+1. Parse each commit message to extract type, scope, and description.
+2. Group entries by type.
+3. Render the grouped entries as a markdown changelog.
+
+## Example
+
+Input: `["feat(auth): add OAuth login", "fix(api): handle 429 rate limit"]`
+
+Output:
+
+```md
+## Features
+- **auth**: add OAuth login
+
+## Bug Fixes
+- **api**: handle 429 rate limit
+```

ai-evals/aidd-upskill/function-test.sudo

@@ -0,0 +1,21 @@
+# function-test.sudo
+
+import 'ai/skills/aidd-upskill/SKILL.md'
+
+userPrompt = """
+Run the Function Test on the skill described in
+ai-evals/aidd-upskill/fixtures/sample-format-skill.md.
+
+Answer all five Function Test questions:
+1. What is f? Name it.
+2. What varies? (parameters)
+3. What is constant? (defaults)
+4. Is f deterministic?
+5. Is the result independently useful and recomposable?
+"""
+
+- Given the skill description maps raw git commits to a structured markdown changelog, should name f as something like "formatChangelog" or "groupCommitsByType" — a clear verb-based name
+- Given the skill accepts a list of commit messages as input, should identify the commit list as the parameter (what varies per caller)
+- Given every caller uses the same grouping logic and markdown rendering, should identify the grouping strategy and output format as defaults (what is constant)
+- Given the formatting logic is rule-based and produces the same output for the same input, should conclude that f is deterministic and therefore better suited to a CLI tool than an AI prompt
+- Given a deterministic f verdict, should state the result in terms of the CLI vs AI prompt constraint from the skill (i.e. deterministic logic => CLI tool or compiled Bun bundle)

ai/commands/aidd-rtc.md

@@ -0,0 +1,13 @@
+## 🧠 Reflective Thought Composition
+
+Use `ai/skills/aidd-rtc/SKILL.md` to run a structured thinking pipeline that shows work at each stage.
+
+Run: `/aidd-rtc [--compact] [--depth N]`
+
+Options:
+- `--compact` — SPR dense/associative thinking with explicit causality in reflect/score. Every internal token earns its place. Use when thinking quality matters more than polish.
+- `--depth N` — Set response density (1–10). Default: 5.
+
+Constraints {
+  Before beginning, read and respect the constraints in ai/skills/aidd-please/SKILL.md.
+}

ai/commands/aidd-upskill.md

@@ -0,0 +1,13 @@
+## 🛠️ Upskill — Create or Review Skills
+
+Use `ai/skills/aidd-upskill/SKILL.md` to create a new agent skill following the AgentSkills.io specification.
+
+Constraints {
+  Before beginning, read and respect the constraints in ai/skills/aidd-please/SKILL.md.
+}
+
+## 🔍 Review Skill
+
+Use `ai/skills/aidd-upskill/SKILL.md` to review an existing skill against the quality criteria in this guide.
+
+Run: `/aidd-upskill review [path-to-skill]`

ai/commands/index.md

@@ -16,6 +16,18 @@ Rank files by hotspot score to identify prime candidates for refactoring before
 
 *No description available*
 
+### aidd-rtc
+
+**File:** `aidd-rtc.md`
+
+*No description available*
+
+### aidd-upskill
+
+**File:** `aidd-upskill.md`
+
+*No description available*
+
 ### Commit
 
 **File:** `commit.md`

ai/skills/aidd-agent-orchestrator/SKILL.md

@@ -24,6 +24,7 @@ Agents {
   javascript-io-effects: when you need to make network requests or invoke side-effects, use this guide for saga pattern implementation
   ui: when building user interfaces and user experiences, use this guide for beautiful and friendly UI/UX design
   requirements: when writing functional requirements for a user story, use this guide for functional requirement specification
+  aidd-upskill: when creating a new agent skill, use this guide for AgentSkills.io specification and SudoLang skill authoring
 }
 
 const taskPrompt = "# Guides\n\nRead each of the following guides for important context, and follow their instructions carefully: ${list guide file refs in markdown format}\n\n# User Prompt\n\n${prompt}"

ai/skills/aidd-please/SKILL.md

@@ -12,23 +12,11 @@ Act as a top-tier senior software engineer, product manager, project manager, an
 You are a SoTA AI agent system with access to advanced tools and computational resources. Gigs of memory, the best models and GPUs, and all the time you need to accomplish anything the user asks. You got this! 🦾
 
 
-Think() deeply when a complex task is presented.
+Think() deeply when a complex task is presented — use /aidd-rtc.
 Read the project README.md and /aidd-stack before responding.
 
 UnrecognizedCommand => check the agent orchestrator for relevant instructions.
 
-
-# Thinking: Reflective Thought Composition (RTC)
-
-fn think() {
-  show your work:
-  🎯 restate |>💡 ideate |> 🪞 reflectCritically |> 🔭 expandOrthogonally |> ⚖️ scoreRankEvaluate |> 💬 respond
-
-  Constraints {
-    Keep the thinking process concise, compact, and information-dense, ranging from a few words per step (d=1) to a few bullet points per step (d = 10).
-  }
-}
-
 Options {
   --depth | -d [1..10] - Set response depth. 1 = ELIF, 10 = prep for PhD
 }
@@ -45,6 +33,8 @@ Commands {
   📊 /aidd-churn - rank files by hotspot score (LoC × churn × complexity) to identify prime candidates for refactoring
   🧪 /user-test - use /aidd-user-testing to generate human and AI agent test scripts from user journeys
   🤖 /run-test - execute AI agent test script in real browser with screenshots
+  🧠 /aidd-rtc - Reflective Thought Composition — structured thinking pipeline; use --compact for dense internal reasoning
+  🛠️ /aidd-upskill - create a new agent skill using AgentSkills.io spec and SudoLang
   🐛 /aidd-fix - fix a bug or implement review feedback following the full AIDD fix process
 }
 

ai/skills/aidd-review/SKILL.md

@@ -35,8 +35,7 @@ Constraints {
   Avoid unfounded assumptions. If you're unsure, note and ask in the review response.
 }
 
-For each step, show your work:
-    🎯 restate |> 💡 ideate |> 🪞 reflectCritically |> 🔭 expandOrthogonally |> ⚖️ scoreRankEvaluate |> 💬 respond
+For each step: /aidd-rtc
 
 ReviewProcess {
   1. Use /aidd-churn to identify hotspot files in the diff

ai/skills/aidd-rtc/README.md

@@ -0,0 +1,56 @@
+# aidd-rtc
+
+Reflective Thought Composition (RTC) — a structured way for an agent to think
+through a problem before answering: clarify the ask, surface alternatives,
+stress-test assumptions, and compare trade-offs so the final reply is grounded.
+Use it when the quality of reasoning matters more than answering in one shot.
+
+## Why
+
+Fast answers can miss edge cases, weak assumptions, or better alternatives.
+RTC slows the loop on purpose so trade-offs and risks surface before a final
+reply — useful for design decisions, reviews, planning, and any task where
+getting the reasoning right reduces rework.
+
+## Commands
+
+```
+/aidd-rtc [prompt]
+```
+
+Run RTC on the given prompt (or the current task context). The agent works
+through the full reflective sequence and ends with a clear, user-facing
+response.
+
+```
+/aidd-rtc --compact [prompt]
+```
+
+Dense internal reasoning: minimal tokens per thinking step, with explicit
+causality where it helps, then a full natural-language answer at the end.
+Suited when RTC output feeds another step (e.g. review or planning) rather
+than being shown directly to the user.
+
+```
+/aidd-rtc --depth N [prompt]
+```
+
+Controls how much detail appears in each step (`N` from 1–10; higher = more
+bullets per stage). Use when you want the visible thinking to carry more
+explanation.
+
+```
+/aidd-rtc --compact --depth N [prompt]
+```
+
+Combines compact internal reasoning with a chosen response density for the
+stages that are surfaced.
+
+## When to use
+
+- Complex decisions where assumptions and alternatives need to be challenged
+- Design or architecture evaluation before committing to an approach
+- Deep analysis (risk, security, product trade-offs) where conclusions should
+  follow from explicit reasoning
+- Any workflow that benefits from a structured “think first, then answer”
+  pass

ai/skills/aidd-rtc/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: aidd-rtc
+description: Reflective Thought Composition. Structured thinking pipeline for complex decisions, design evaluation, and deep analysis. Use when quality of reasoning matters more than speed of response.
+---
+
+# aidd-rtc
+
+Reflective Thought Composition (RTC) — a structured thinking pipeline that shows work at each stage before responding.
+
+Commands {
+  /aidd-rtc [--compact] [--depth=] [prompt]  Reflective Thought Composition — think deeply and critically over multiple reasoning paths prior to responding.
+}
+
+Options {
+  🗜️🐘🤔💭 --compact  Compress thinking: SPR🧠 associative. Dense noun phrases, concept clusters, emojis as semantic shortcuts in restate/ideate/expand. Reflect and score: add explicit causality (∵/∴ or "because/therefore") to surface the reasoning chain, not just conclusions. Every internal stage: load-bearing tokens only, no filler. 💬Respond = full natural language, standalone, structured.
+  --depth -d [1..10] (default: 10)  Response density. 1 = a few words per step, 10 = several bullet points per step.
+}
+
+## Pipeline
+
+```
+fn think(input, options) {
+  show work:
+    🎯 restate |> 💡 ideate |> 🪞 ReflectCriticallyFindYourFlaws |>
+    🔭 expandOrthogonally |> ⚖️ scoreRankEvaluate |> 💬 respond
+}
+```
+
+## When to use each option
+
+```
+(thinking itself is the goal — improving reasoning quality) => /aidd-rtc --compact
+(communicating depth to the user is the goal)              => /aidd-rtc --depth N
+(both)                                                     => /aidd-rtc --compact --depth N
+```
+
+`--compact` is for internal reasoning passes where the output feeds another step, not directly to the user. Think deeply but compactly — every token earns its place. Switch to natural language at 💬 respond.
+
+**Pass:** remove any word → lose meaning. Reflect/score show explicit causal chain, not just conclusions.
+**Fail:** consultant prose. Hedging. Filler. Conclusions without reasoning. Polish before the respond stage.
+
+## Steps
+
+**🎯 restate** — Restate the problem in your own words. Surface any ambiguity.
+**💡 ideate** — Generate candidate approaches, options, or observations without filtering.
+**🪞 ReflectCriticallyFindYourFlaws** — Attack your own ideation. Find the weakest assumptions, the missing cases, the things that could go wrong.
+**🔭 expandOrthogonally** — Look sideways. What adjacent concerns, second-order effects, or non-obvious angles haven't been considered?
+**⚖️ scoreRankEvaluate** — Weigh options. Rank by quality, risk, or fit. Reach a conclusion.
+**💬 respond** — Deliver the output. `--compact` ends here: switch to natural language.

ai/skills/aidd-upskill/README.md

@@ -0,0 +1,34 @@
+# aidd-upskill
+
+Creates and reviews AIDD skills — the reusable instruction modules that guide
+agent behavior across a project.
+
+## Why
+
+Skills written without a clear structure accumulate bloat, mix concerns, and
+become hard to maintain. `aidd-upskill` applies a consistent authoring
+standard: each skill is a named function with defined inputs and outputs,
+sized to stay concise, and organized for progressive disclosure.
+
+## Commands
+
+```
+/aidd-upskill create [name]
+```
+
+Scaffolds a new skill at `aidd-custom/skills/aidd-[name]/SKILL.md` with the required
+frontmatter, sections, and directory layout.
+
+```
+/aidd-upskill review [target]
+```
+
+Evaluates an existing skill against authoring criteria: function test,
+required sections, size thresholds, command separation, and README quality.
+Reports issues and a pass/fail verdict.
+
+## When to use
+
+- Creating a new skill from scratch in `ai/skills/` or `aidd-custom/skills/`
+- Reviewing or refactoring an existing skill for quality and consistency
+- Checking whether a candidate abstraction is ready to become a named skill