| name | meta-skill-improvement |
| description | Self-learning and skill-maintenance loop for the lab. Run at the end of every session that produces non-trivial work, and at the **start** of any session to check unanalyzed nightly failures. Enforces the write-back loop so the next agent starts smarter than this one did. Use when wrapping up any session, before creating a PR, at session start to check failures, or when a pattern was discovered through trial and error.
|
Skill Improvement — lab Self-Learning Loop
Every session produces exactly two outputs: the work and the learning.
Output 1 without Output 2 leaves the lab no smarter than before you arrived.
Canonical skill standard: /addyosmani/agent-skills
When to Use
- Start of session: check nightly failures from the past 7 days before doing new work
- End of any session that produced non-trivial code, config, or ops work
- Before creating a PR or marking work done
- When a pattern was discovered by trial and error
- When a tool, API, or cluster behaviour surprised you
When NOT to Use
- Read-only research sessions with no output
- Doc-only passes that update no skill file and create no new pattern
Core Process
Step 0 — Check for unanalyzed nightly failures (session start)
Nightly failures are retained for 7 days. Check before starting new work:
argo-mcp-list_workflows namespace=argo status=Failed
For each failed workflow:
argo-mcp-logs_workflow <name> — find the failing step and error message- Route to the relevant skill file (Step 1 routing table below)
- If pattern is already in the skill — the fix may be straightforward; do it now
- If pattern is new — fix it, then update the skill file before ending the session
- File a GitHub issue for infra work that goes beyond this session
Failures older than 7 days are gone. The self-improving loop only works if
someone runs Step 0 before Argo cleans them up.
Step 1 — Skill routing
Route by area changed:
| Area changed | Skill file to update |
|---|
argo/workflow-templates/ or argo/*.yaml | argo-workflows/SKILL.md |
provision-vm, KubeVirt, btrfs reflink | kubevirt-vms/SKILL.md |
ArgoCD Applications, argocd/, manifests/ | gitops-argocd/SKILL.md |
tests/, behave, dogtail, qecore | test-authoring/SKILL.md |
.github/workflows/ | ci-tooling/SKILL.md |
scripts/refresh_factory_stats.py or scripts/generate_page_datasets.py | ci-tooling/SKILL.md (+ astro-dashboard-pages/SKILL.md when page contracts/rendering changed) |
| Repo-wide agent behavior or session hygiene | AGENTS.md |
Bootstrap cluster setup, argo/bootstrap/ | docs/ops/bootstrap.md |
| Cluster topology, namespaces, RBAC | docs/ops/architecture.md |
| Agent operations, MCP tools | |
Ask: "If this finding had been in the skill file when I started, would I have avoided the trial-and-error?" If yes — update the skill file.
Step 2 — Context7 freshness
Whenever a skill file covers a named library or tool, verify its examples against current docs before updating:
DETECT → FETCH → EMBED → CITE
resolve-library-id("<library>") → get the Context7 library IDquery-docs("<id>", "<specific pattern>") → fetch current docs- Embed the verified pattern in the skill
- Note the library ID in frontmatter:
context7-sources: [/org/project]
Key library IDs for this repo:
- Argo Workflows:
/argoproj/argo-workflows
- Argo CD:
/argoproj/argo-cd
Step 3 — Canonical skill spec audit
Every skill file must meet the /addyosmani/agent-skills standard:
✓ Frontmatter: name + description with "Use when" trigger phrases
✓ ## When to Use
✓ ## When NOT to Use
✓ ## Core Process (numbered workflow)
✓ ## Common Rationalizations (excuses + rebuttals)
✓ ## Red Flags (anti-patterns)
✓ ## Verification (exit criteria checklist)
Step 4 — Documentation hygiene
Skill files are evergreen procedures. Remove from any skill file:
| ✗ Remove | ✓ Where it belongs |
|---|
Resolved items (✅ done, PR#123 merged) | Git history |
| Running gap tables with live issue numbers | GitHub issues |
Session-dated entries (2026-06-11: found X) | Extract the timeless pattern; drop the date |
| Current PR numbers as inline state | File a GitHub issue; link from there |
The model test: "Read this as a fresh agent with zero session context. Does it tell you how to operate — or does it make you dig through history?"
Step 5 — Live gaps → GitHub issues
Any gap, blocker, or open question you cannot fix this session:
gh issue create --repo projectbluefin/lab \
--title "infra: <what is broken>" \
--label "bug" \
--body "What: ...\nFix: ...\nAutomatable: yes/no"
Do not append gaps to skill files. Skill files are not backlogs.
Step 6 — Factory closure (required before handoff)
Before ending any non-trivial session:
- Write the durable pattern into the routed skill file.
- If the pattern changes how future agents should operate in this repo, update
.github/copilot-instructions.md too.
- If the session touched Pages or generated dashboard data, verify the live build/render still matches the published files.
- Do not hand off with only code changes; the skill/docs write-back is part of the deliverable.
Skill directory
All skill files live in docs/skills/:
docs/skills/
├── _template/SKILL.md Copy this to add a new skill
├── argo-workflows/ WorkflowTemplate authoring and patterns
├── ci-tooling/ GitHub Actions and CI reliability
├── cluster-tooling/ k3s, storage, BuildStream, node recovery
├── flatcar-node-onboarding/ Flatcar nodes, Nebraska, custom kernels
├── gitops-argocd/ ArgoCD sync, manifests, image policy
├── kubevirt-vms/ Ephemeral VM lifecycle and troubleshooting
├── meta-skill-improvement/ This file — the self-improvement loop
├── test-authoring/ behave/qecore/dogtail and bootc contract tests
└── README.md Skill index
Common Rationalizations
| Rationalization | Reality |
|---|
| "I'll update the skill next session." | You won't. The loop only compounds if agents write back immediately. |
| "I already know Argo Workflows — no need for Context7." | Training data is stale. Fetch and verify before embedding examples. |
| "The skill file is good enough." | Check for Red Flags and Verification sections — most common gaps. |
| "This pattern is obvious — no need to document it." | If you found it by trial and error, it isn't obvious. Write it. |
Red Flags
- Session ending with no skill update after discovering a non-obvious pattern
- A pattern being fixed a second time that wasn't written down after the first
- Session ending after Pages/dashboard work without a skill or instructions write-back
- Skill files with no
## Verification section
- Skill files covering Argo or ArgoCD with unverified code examples
- Any
docs/skills/*/SKILL.md file missing the canonical sections
Verification
Before marking any session done:
