feat(skills): add /aidd-upskill by ericelliott · Pull Request #188 · paralleldrive/aidd

ericelliott · 2026-04-10T09:36:02Z

Split from PR #94. One skill per PR per project standards.

What

Adds the /aidd-upskill skill — a guide for creating and reviewing high-quality AIDD agent skills following the AgentSkills.io specification and SudoLang authoring patterns.

Changes

New files

ai/skills/aidd-upskill/ — Full skill directory with SKILL.md, README.md, references (process.md, types.md), and scripts (validate-skill.js + tests)
ai/commands/aidd-upskill.md — Command definition
ai-evals/aidd-upskill/ — AI eval tests (caveman, dedup, function tests) with fixtures
tasks/aidd-upskill-epic.md — Epic documentation

Modified files

ai/skills/aidd-agent-orchestrator/SKILL.md — Added upskill to agent routing
ai/skills/aidd-please/SKILL.md — Added /aidd-upskill command entry
ai/commands/index.md — Added upskill entry
ai/skills/index.md — Added upskill entry
.gitignore — Added compiled validate-skill binary
package.json — Added build:validate-skill and test:ai-eval:upskill scripts

Not included (RTC-only changes from PR #94)

ai/skills/aidd-review/SKILL.md changes (RTC refactor only, no upskill content)
ai/skills/aidd-please/SKILL.md RTC refactor (only upskill command line included)

Review

Ran the full /aidd-upskill review pipeline against this skill:

Check	Result	Detail
runFunctionTest	✅	`createSkill` and `reviewSkill` clearly named; parameters/defaults well separated; judgment-based → AI prompt; deterministic validation → CLI tool
checkRequiredSections	✅	`# aidd-upskill` title and `## Process` section present
checkSizeMetrics	✅	42 frontmatter tokens, 129 body lines, 989 body tokens — all within thresholds
checkCommandSeparation	✅	Pipeline stages separate thinking from effects; review is pure thinking
checkReadme	✅	Contains what/why/commands; no implementation details or process narratives
deduplicate	✅	Types in types.md only, pipelines in process.md only, Function Test in SKILL.md only; command text overlap between SKILL.md and README.md is by design

Overall verdict: ✅ Pass

Testing

All 544 unit tests pass
All 49 e2e tests pass
Lint and typecheck clean
validate-skill passes on the skill itself

janhesters · 2026-04-13T14:25:27Z

+  try {
+    parsedFrontmatter = frontmatter ? yaml.load(frontmatter) : {};
+  } catch (e) {
+    errors.push(`Invalid YAML in frontmatter: ${e.message}`);


Should we use a safe YAML schema here? yaml.load uses the full schema by default, which can instantiate arbitrary JS types from YAML tags. Since this reads user-supplied SKILL.md files, yaml.load(frontmatter, { schema: yaml.DEFAULT_SAFE_SCHEMA }) would be safer. Low risk for a local CLI, but a quality-focused skill should model safe patterns.

janhesters · 2026-04-13T14:25:27Z

+      ? "\n⚠  Validation passed with warnings."
+      : "\n✔  Validation passed.",
+  );
+}


The validator checks frontmatter and size metrics but doesn't verify that the body contains the skill's own RequiredSections (# Title and ## Steps | ## Process). This means the validator can't enforce what the skill defines as required. Should we add a RequiredSections check to validateSkillContent?

janhesters · 2026-04-13T14:25:27Z

@@ -0,0 +1,15 @@
+# 🛠️ /aidd-upskill


This command file is missing the description frontmatter block that every other command file has:

--- description: Create and review AIDD skills following the AgentSkills.io specification and SudoLang authoring patterns. ---

This is why commands/index.md shows "No description available" for this entry.

Additionally, the validate-skill.js tool should be recursively used here, then this error wouldn't have slipped through.

janhesters · 2026-04-13T14:25:27Z

+- Write frontmatter: `name` + `description` required; add `metadata.alwaysApply` if needed
+- Write body with all `RequiredSections`
+- If body will exceed the line threshold (run `validate-skill` to check), extract content to `references/` and use `import $referenceFile`


"Do not await user approval" + run /aidd-review then /aidd-fix until clean could loop indefinitely if review and fix keep introducing new issues. Should we add a max iteration count or circuit breaker here?

janhesters · 2026-04-13T14:25:28Z

+  bodyTokens: Math.ceil(body.length / 4),
+  frontmatterTokens: Math.ceil(frontmatter.length / 4),
+});


The chars / 4 token estimation can be off by 30-50% depending on content (code-heavy, non-ASCII, etc.). Should we at least document that this is a rough heuristic, not a real tokenizer, so users aren't misled by the metric output?

janhesters · 2026-04-13T14:25:28Z

+    assert({
+      given: "a valid aidd-prefixed lowercase hyphenated name",
+      should: "return no errors",
+      actual: validateName("aidd-format-code", "aidd-format-code"),
+      expected: [],
+    });
+  });
+
+  test("missing aidd- prefix", () => {
+    const errors = validateName("format-code", "format-code");
+


The validateName tests assert on error array indices (errors[0], errors[1]), which couples the tests to the internal push order. If the order of validation checks changes, these tests break even though the function still produces the same set of errors. Should we use errors.some(e => e.includes(...)) instead (like the validateSkillContent tests already do)?

janhesters · 2026-04-13T14:25:28Z

+## Role
+
+Expert skill author. Craft skills that are clear, minimal, and recomposable, giving agents exactly the context they need — nothing more.
+


Two things about the skill components reference:

Duplicate thinking pipeline — The caveman() / RTC thinking process (restate → ideate → reflect → expand → score → respond) tested in caveman-test.sudo is being extracted into its own standalone skill in feat(skills): add /aidd-rtc #193 (/aidd-rtc). Should we reference /aidd-rtc rather than re-testing the thinking pipeline here?

Missing SudoLang spec reference — A skill-authoring guide should probably reference and enforce the SudoLang spec (https://github.com/paralleldrive/sudolang/blob/main/sudolang.sudo.md). Should we include it as a reference file and add a constraint that generated skills must follow SudoLang syntax? Currently the skill mentions aidd-sudolang-syntax in passing but doesn't import or enforce it.

Split from PR #94. One skill per PR per project standards. Adds the /aidd-upskill skill for creating and reviewing AIDD agent skills, including: - Skill creation and review pipelines (SKILL.md, references, scripts) - Command definition (ai/commands/aidd-upskill.md) - AI eval tests (caveman, dedup, function tests) - validate-skill CLI and its unit tests - Epic documentation (tasks/aidd-upskill-epic.md) - Upskill entries in aidd-agent-orchestrator, aidd-please, index files - .gitignore and package.json entries for the validator binary and eval script

…om aidd-please - SKILL.md: update skill components to reference aidd-please (provides RTC think()) instead of non-existent aidd-rtc skill - references/process.md: replace /aidd-rtc --compact with think() --compact in both createSkill and reviewSkill pipelines and step descriptions - ai/commands/aidd-upskill.md: align format with other command files (# heading, /aidd-please reference, load-and-execute pattern)

- Use safe YAML schema in validate-skill.js to prevent arbitrary type instantiation - Add RequiredSections validation (# Title and ## Steps/Process) - Add description frontmatter to command file - Document token estimation as a rough heuristic (chars / 4) - Decouple validateName test assertions from push order (errors.some) - Add SudoLang spec reference to SKILL.md

janhesters requested changes Apr 13, 2026

View reviewed changes

cursoragent and others added 4 commits April 15, 2026 15:31

Fix lint

22174a6

janhesters force-pushed the cursor/aidd-upskill-skill-858e branch from c263b0f to 22174a6 Compare April 15, 2026 13:32

janhesters marked this pull request as ready for review April 15, 2026 13:33

janhesters merged commit dc13ee4 into main Apr 15, 2026
3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(skills): add /aidd-upskill#188

feat(skills): add /aidd-upskill#188
janhesters merged 4 commits intomainfrom
cursor/aidd-upskill-skill-858e

ericelliott commented Apr 10, 2026

Uh oh!

janhesters Apr 13, 2026

Uh oh!

janhesters Apr 13, 2026

Uh oh!

janhesters Apr 13, 2026 •

edited

Loading

Uh oh!

janhesters Apr 13, 2026

Uh oh!

janhesters Apr 13, 2026

Uh oh!

janhesters Apr 13, 2026

Uh oh!

janhesters Apr 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		## Role

		Expert skill author. Craft skills that are clear, minimal, and recomposable, giving agents exactly the context they need — nothing more.

Conversation

ericelliott commented Apr 10, 2026

What

Changes

New files

Modified files

Not included (RTC-only changes from PR #94)

Review

Testing

Uh oh!

janhesters Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

janhesters Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

janhesters Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janhesters Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

janhesters Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

janhesters Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

janhesters Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

janhesters Apr 13, 2026 •

edited

Loading