aidd-upskill

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: Generated skills must use SudoLang syntax for constraints, commands, functions, composition pipelines, and any required typed interfaces, as needed.

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:

riteway ai path/to/my-skill-test.sudo