Compound Workflows

Principle

The team improves by converting evidence from real executions into smaller future context, safer defaults, and executable instructions. Do not create a skill merely because a task had several steps.

Learning gate

At the natural end of substantial work, assess:

• Was a non-obvious knowledge gap closed, did at least two approaches fail, did the user establish a convention, or has this workflow recurred?
• Is the lesson likely to save another session meaningful exploration or prevent a consequential mistake?
• Does an existing skill or runbook already cover it?

If the first two answers are no, do not codify. If overlap exists, improve the existing artifact instead of creating a duplicate.

Capture ladder

Choose the lightest durable form that fits:

1. Update /agents/Administrator/memory/operating-context.md for a compact role-specific fact.
2. Update /SUBTERRANEAN.md for stable project-wide truth.
3. Write a runbook under /operations/runbooks/ when humans and agents both need narrative procedure.
4. Use the built-in skillify skill for a proven project workflow with recognizable future triggers.
5. Write /agents/_project/skills/<name>/SKILL.md only when the workflow is useful across roles; otherwise default to /agents/Administrator/skills/<name>/SKILL.md.

Agent-authored skill contract

Before writing:

• Search available skills and /agents//skills/ for overlap.
• Ground every instruction in a successful execution, observed failure, or explicit user convention.
• Put triggering symptoms in front matter, not a summary of the solution.
• Include prerequisites, exact paths or table IDs, ordered steps, verification, failure recovery, and stop conditions.
• Never embed secrets, transient IDs, or unverified guesses.

After writing:

• Re-read the skill as a cold agent and remove hidden session context.
• Run a cheap, non-destructive check when possible.
• Add or update the Workflow Registry skill path.
• Add uncertain or material changes to Improvement Backlog for review.
• Tell the user briefly when a new durable behavior was created.

The Background Maintainer may improve discovery, clarity, and duplication later, but Administrator owns the operational truth learned during execution.