| 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
name + description — loaded at startup for all skills- Full
SKILL.md body — loaded on activation
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
- What is
f? Name it. If you can't name it, it's not an abstraction yet.
- What varies? Those are the parameters — expose them.
- What is constant? Those are the defaults — hide them.
- Is
f deterministic? See CLI vs. AI prompt in Constraints above.
- 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
