Skip to content

v1.9.0 ·

Skills the app owns: operational work as a lifecycle deliverable

The problem

Apps built with AIDLC need repeatable operational actions that are not features — a blog app needs "create a new MDX post about topic ABC" with correct frontmatter, slug/date conventions, image paths, and index updates. These belong in the app's repo as agent skills, but AIDLC today has no opinion on them. Users cannot tell whether authoring such a skill, or running it, should pass through the lifecycle. The result is either ceremony (a lifecycle instance per blog post) or paralysis (nobody writes the skill because its status is unclear).

Two distinct gaps sit behind the confusion:

  1. A conceptual gap — no stated rule separating lifecycle work from operational work.
  2. A tooling gap — no paved road for authoring an app skill, so each user reinvents the structure, and nothing guarantees the skill carries its own verification steps.

How it could be solved

Four product shapes came out of the source idea. All were weighed; the decision is a synthesis of shapes 1 and 4.

Option A — Guidance only (shape 1)

A docs section stating the build-vs-use rule. Pros: smallest possible change; resolves the stated confusion, which the source idea concedes may be sufficient. Zero maintenance surface. Cons: leaves every user to invent skill structure by hand; nothing enforces G4, so generated skills vary in quality. Does not address the tooling gap.

Option B — Tooling only (shape 4)

Build aidlc-add-skill and let the tool teach the distinction implicitly. Pros: paves the road; the tool's existence answers "am I allowed to do this?". Cons: the use half of the rule stays untaught — a user can still conclude that running the skill needs an instance. Discoverability depends on stumbling onto the command.

Option C — Skills as recognized implementation artifacts (shape 3)

A feature's Implementation phase may include authoring the operational skills that run it. Pros: strong conceptual fit — the blog-publishing feature ships the blog-post skill together. Cons: touches the template/artifact model, the largest blast radius of the four. Better folded in later as a documented practice than as a schema change now.

Option D (chosen) — Guidance + add-skill helper

Ship the rule and the paved road: docs state the litmus test; aidlc-add-skill scaffolds the skill through the existing adapter seam with a verify step injected from a new bundled guidance layer; generated skills are registered in the knowledge graph. Pros: closes both gaps; reuses three mechanisms already in the codebase (adapter seam, guidance placeholders, knowledge graph) rather than inventing any. Each half covers the other's weakness. Cons: largest of the three viable scopes; adds one guidance layer and one skill to maintain. Trade-off accepted: the maintenance cost is one markdown layer plus one skill file — both in existing, well-worn slots.

Rejected sub-option — a dedicated skill-authoring template

Considered and rejected (open question 2 below): authoring one app skill is implementation plus a smoke test, which micro-task already covers. A sixth template is not worth its upkeep for a case the smallest existing scope handles.

How AIDLC solves it

Two deliverables, as Ideation Option D specified.

1. The guidance rule. aidlc-overview gained a "Lifecycle or Skill?" section stating lifecycle for changes to the system; skills for repeatable operations of the system, with a worked example ("add a series feature" vs. "publish a post"), the escape hatch for when an operation reveals a missing capability, and the rule that verification belongs inside the skill rather than in phases wrapped around each invocation. aidlc-getting-started carries a Quick Answer pointing at it, so the rule is met during onboarding.

2. The aidlc-add-skill helper. A content skill (judgment: interpretation, elicitation, deflection) plus aidlc add skill (mechanics: validation, redaction, atomic write, smoke check, registration). One canonical body under the operational-skills directory — OPERATIONAL_DIR in packages/cli/src/operational/packagers.ts, created on the first aidlc add skill — plus platform-native pointers for all five platforms, and verification steps inlined as literal text from the content package.