skill · phase: implementation

Operational Skill Authoring

Purpose

Turn a plain-language description of a repeatable operation into a working skill in the user's repo — one canonical body plus platform-native packaging, with verification steps already embedded.

Authoring a skill is not performing the operation. You are writing instructions for later, not running them now. Never execute the described operation while authoring it: do not publish the post, do not run the deployment, do not send the message. If the user wants the operation performed, that is a separate request made after the skill exists.

When to Use This

The user describes something they do repeatedly with the same steps — publishing a post, rotating credentials, regenerating a report, cutting a release note.

Before generating anything, apply the rule from aidlc-overview: lifecycle for changes to the system; skills for repeatable operations of the system.

Instructions

1. Check it is really an operation, not a system change

If the description is really a new capability — the system cannot do this yet, and doing it once requires building something — say so plainly and offer the alternative:

{{glossary:instance}}

"This sounds like a change to the system rather than a repeatable operation of it: . That usually belongs in the lifecycle. I can capture it as an idea (aidlc-idea) or start an instance instead. Or if you would rather have the skill anyway, say so and I will generate it."

If the user disagrees, generate the skill. A false positive must never be a dead end — the user knows their workflow better than this heuristic does.

Signals it is a system change: "add support for", "make it possible to", "we can't currently". Signals it is an operation: "every time I", "the steps are always", "I keep having to".

2. Elicit what the skill needs

Gather these before generating. Ask only for what is missing or genuinely ambiguous — do not interrogate the user for fields you can infer from what they already said.

Name — lowercase, hyphens, starts with a letter. The aidlc- prefix is reserved for framework skills and will be rejected. Suggest one derived from the description and confirm it.
Description — one line: what operation this performs.
Trigger — when this skill should be used, in the user's own words.
Steps — the concrete operation, as ordered markdown. This is the substance; get it specific. Vague steps produce a skill that cannot be followed.
Conventions it must honour — paths, naming schemes, frontmatter fields, index files to update, commands to run. These are what make the difference between a skill that works in this repo and generic advice.
Paths — repo-relative paths the operation touches. These are checked for existence by the skill's own smoke test, so list real ones.

3. Never put credential values in the skill

Environment variable names and secret-manager references are legitimate and should be kept: $GITHUB_TOKEN, op://vault/ci/token, arn:aws:secretsmanager:.... Actual token values must not appear. If the user pastes one, tell them, leave it out, and reference it by variable name instead.

Generation redacts detected credential values automatically before showing you a preview, but that detection is best-effort — do not rely on it in place of not asking for secrets.

4. Generate

Run the command. It renders a preview, asks for confirmation, and writes nothing until confirmed:

aidlc add skill <name> \
  --description "<one line>" \
  --steps "<the ordered steps, as markdown>" \
  --trigger "<when to use it>" \
  --paths <path> [<path>...]

Add --dry-run first if the user wants to see the output without a prompt.

The command owns the write path: it validates the name, redacts credentials before rendering the preview, asks for confirmation, writes all files or none, runs a smoke check, and registers the skill in the knowledge graph. Do not reimplement any of that by writing the files yourself — the confirmation is a security boundary, because a generated skill is instructions an agent will later execute.

5. Report what happened

Tell the user which files were written, whether the smoke check passed, and whether knowledge-graph registration succeeded. A registration warning is not a failure — the skill still works.

If the smoke check reports a missing declared path, that usually means a --paths entry was wrong, not that the skill is broken. Offer to re-run with corrected paths.

Other Modes

aidlc add skill --check [<name>] — verify existing skills parse, carry verification text, and that their declared paths exist. Run this if a skill has been hand-edited.
aidlc add skill --re-emit [<name>] — re-package for the currently configured platforms and refresh the verification text from the installed content package. Use it after adding a platform to .aidlc/config.yaml, after upgrading the content package, or to repair a skill whose knowledge-graph entry is missing. It never rewrites the user's own steps.
aidlc add skill <name> --overwrite — replace an existing skill. Generation refuses a name collision by default rather than silently overwriting.

What Not to Do

Do not create a lifecycle instance to run a generated skill. Running an operation is never an instance.
Do not author the skill by writing .aidlc/operational-skills/<name>.md directly. That bypasses name validation, redaction, atomic writes, and the confirmation gate.
Do not remove or edit the verification section in a generated skill. It is machine-managed, delimited by  / , and --re-emit refreshes it. Content outside those markers is yours to edit freely.
Do not use the aidlc- prefix. It is reserved and enforced.

Exit Criteria

The skill's canonical body and platform files are written (on confirmation), the smoke check has run, and its result was reported — or
The user declined, and the working tree is unchanged — or
The request was a system change and the user chose the lifecycle instead.