aidd-upskill

# 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: ```shell riteway ai path/to/my-skill-test.sudo ```