Skip to content

refactor(aidd-context): the skill template still teaches the format onboard abandoned #418

Description

@blafourcade

skill-generate holds the base every skill is built from: the rules (references/skill-authoring.md) and the templates a new skill is scaffolded from (assets/skill-template.md, assets/action-template.md). Both still teach the format onboard abandoned. Until they are fixed, nothing propagates: a skill generated today copies the old pattern, and every later cleanup has no rule to follow.

The base contradicts the shipped skill

onboard ships the new pattern on next. The template a new skill copies teaches the old one.

assets/skill-template.md onboard/SKILL.md on next
Action table # | Action | Role | Input — 4 columns # | Action | Does — 3 columns
Flow a prose sentence a mermaid diagram
References flat, "Plain paths, no @" nested: references/state/, order/, run/
Load cost nothing the entire point

And the rules say nothing either. Checked on next:

  • Zero occurrence of nested or a references/<group>/ path. R3 still reads "References one level deep", while onboard ships 11 nested references.
  • Zero occurrence of always-on, per path, conditional, or load cost. No rule constrains what one run reads.
  • The only size rule is R4: SKILL.md <= 500 lines — a file ceiling that aidd-orchestrator:00-async-dev clears with a 131-line router while being the heaviest skill in the repo at 1915 lines. It measures a file where the cost lives in a path.

Scope

The rules — references/skill-authoring.md

  • Sanction nested references. State when a group earns a directory: a load boundary, not a topic.
  • Name the always-on surface: the description is the only content loaded when a skill is not invoked. Everything else is on demand.
  • Replace the R4 file ceiling with a budget on what one run reads, and say how an author measures it.
  • State the split rule: split A from B only when a path needs A without B. Co-loaded content stays one file.

The templates — assets/skill-template.md, assets/action-template.md

  • Drop the Input column from the action table; an action's input lives in its own ## Input.
  • Show the flow as a schema, not prose.
  • Show a nested reference group, so the shape is copied rather than explained.

The skill itself

  • 378 lines, 10 files. skill-authoring.md (64 lines) is read by all five generators, so its weight is paid five times over. tool-paths.md (57 lines) is a lookup table an action reads whole to use one row.

Acceptance criteria

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Fields

    Priority

    High

    Projects

    Status
    Todo

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions