feat(skills): add /aidd-upskill

.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-upskill.md

@@ -0,0 +1,19 @@
+---
+description: Create and review AIDD skills following the AgentSkills.io specification and SudoLang authoring patterns.
+---
+
+# 🛠️ /aidd-upskill
+
+Load and execute the skill at `ai/skills/aidd-upskill/SKILL.md`.
+
+Constraints {
+  Before beginning, read and respect the constraints in /aidd-please.
+}
+
+## Create
+
+Run: `/aidd-upskill create [name]`
+
+## Review
+
+Run: `/aidd-upskill review [path-to-skill]`

ai/commands/index.md

@@ -52,6 +52,12 @@ Write correct riteway ai prompt evals for multi-step tool-calling flows. Use whe
 
 *No description available*
 
+### 🛠️ /aidd-upskill
+
+**File:** `aidd-upskill.md`
+
+Create and review AIDD skills following the AgentSkills.io specification and SudoLang authoring patterns.
+
 ### 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

@@ -45,6 +45,7 @@ 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-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
   🧪 /aidd-riteway-ai - write correct riteway ai prompt evals for multi-step tool-calling flows
 }

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

ai/skills/aidd-upskill/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: aidd-upskill
+description: Guide for crafting high-quality AIDD skills. Use when creating, reviewing, or refactoring skills in ai/skills/ or aidd-custom/skills/.
+---
+
+# aidd-upskill
+
+## Role
+
+Expert skill author. Craft skills that are clear, minimal, and recomposable, giving agents exactly the context they need — nothing more.
+
+**Skill components:** `ai/skills/aidd-sudolang-syntax`, `ai/skills/aidd-please` (provides RTC think())
+
+**SudoLang spec:** https://github.com/paralleldrive/sudolang/blob/main/sudolang.sudo.md — generated skills must follow SudoLang syntax.
+
+Constraints {
+  Prefer natural language in markdown format
+  Use SudoLang interfaces, pattern matching, and /commands for formal specification
+  (logic is deterministic) => CLI tool or compiled Bun bundle
+  (logic requires judgment) => AI prompt
+  (a candidate abstraction cannot be named) => it is not an abstraction yet
+  (two or more skills share the same f) => extract a shared abstraction
+}
+
+Commands {
+  /aidd-upskill create [name] — scaffold a new skill at aidd-custom/skills/aidd-[name]/SKILL.md
+  /aidd-upskill review [target] — evaluate a skill against the criteria in this guide
+}
+
+> This skill is itself an example of the structure it prescribes.
+
+import references/types.md
+import references/process.md
+
+## Process
+
+The `createSkill` and `reviewSkill` pipelines — including all step definitions — are defined in
+`references/process.md` (imported above). Read that file for the full authoring and review
+workflows.
+
+---
+
+## Skill Structure
+
+```
+ai/skills/aidd-<verbOrRoleBasedNoun>/
+├── SKILL.md          # Required: frontmatter + instructions
+├── README.md         # Optional: what the skill is, why it's useful, command reference
+├── scripts/          # Optional: CLI tools
+├── references/       # Optional: detailed reference docs
+└── assets/           # Optional: templates, data files
+```
+
+## Progressive Disclosure
+
+1. `name` + `description` — loaded at startup for all skills
+2. Full `SKILL.md` body — loaded on activation
+3. `scripts/`, `references/`, `assets/` — loaded on demand
+
+Keep `SKILL.md` concise — run `validate-skill` to check thresholds. Move reference material to `references/`. Use `import $referenceFile` to link it.
+
+---
+
+## A Skill Is a Function
+
+```
+f: Input → Output
+```
+
+Every skill maps input context to output or action. Use this as the primary design lens.
+
+### Abstraction
+
+Two skills sharing the same `f` should share the same abstraction:
+
+- **Generalization:** extract the shared `f`, name it, hide it
+- **Specialization:** expose only what differs as parameters
+
+```
+f: A → B
+g: B → C
+h: A → C   ← h hides B. This is a good abstraction.
+```
+
+> "Simplicity is removing the obvious and adding the meaningful." — John Maeda
+
+### The Function Test
+
+1. What is `f`? Name it. If you can't name it, it's not an abstraction yet.
+2. What varies? Those are the parameters — expose them.
+3. What is constant? Those are the defaults — hide them.
+4. Is `f` deterministic? See CLI vs. AI prompt in Constraints above.
+5. Is the result independently useful and recomposable? If not, it's inlining, not abstraction.
+
+### Default Parameters
+
+Use defaults wherever the default is obvious. Callers supply only what is meaningfully different. If every caller passes the same value, it's a default waiting to be named.
+
+---
+
+## Eval Tests
+
+Use Riteway AI to write eval tests for skill commands. The Riteway AI skill may be available as `aidd-riteway-ai` in your project's `ai/skills/` directory.
+
+**Core principle:** never mix thinking and effects in a single `/command`. Break commands into sub-commands or separate skills so every thinking stage is independently testable.
+
+```
+(command involves thinking + side effects) => split into sub-commands
+(command is a pure thinking stage) => write an eval test
+(command is a side effect only) => skip the test
+```
+
+### Eval Test Structure
+
+Tests are `.sudo` files using SudoLang syntax:
+
+````
+# my-skill-test.sudo
+
+import 'path/to/skill.md'
+
+userPrompt = """
+<the prompt or command input being tested>
+"""
+
+- Given <context>, should <expected thinking output>
+- Given <context>, should <expected thinking output>
+````
+
+Run with:
+
+```shell
+riteway ai path/to/my-skill-test.sudo
+```
+
+Defaults: 4 passes, 75% pass rate threshold, claude agent.

ai/skills/aidd-upskill/index.md

@@ -0,0 +1,22 @@
+# aidd-upskill
+
+This index provides an overview of the contents in this directory.
+
+## Subdirectories
+
+### 📁 references/
+
+See [`references/index.md`](./references/index.md) for contents.
+
+### 📁 scripts/
+
+See [`scripts/index.md`](./scripts/index.md) for contents.
+
+## Files
+
+### aidd-upskill
+
+**File:** `SKILL.md`
+
+Guide for crafting high-quality AIDD skills. Use when creating, reviewing, or refactoring skills in ai/skills/ or aidd-custom/skills/.
+

ai/skills/aidd-upskill/references/index.md

@@ -0,0 +1,18 @@
+# references
+
+This index provides an overview of the contents in this directory.
+
+## Files
+
+### Skill Creation Process
+
+**File:** `process.md`
+
+*No description available*
+
+### Types & Interfaces
+
+**File:** `types.md`
+
+*No description available*
+