How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/opsmill/infrahub-skills --skill infrahub-teaching-conceptsBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Infrahub Concept Tutor
Overview
A tutor protocol, not a textbook. It measures what the learner already knows, explains each concept through the learner's own schema, objects, and instance where they exist, sets a hands-on exercise the learner solves themselves, and records progress so a later session resumes instead of restarting. Exercises are verified solvable before they are shown.
When to Use
- "Teach me how relationships work" or any concept question asked to learn
rather than to delegate.
- "Why does my instance behave this way?" when the goal is understanding.
- "What's the NetBox/Nautobot equivalent of X in Infrahub?" taught as a
translation (see rules/grounding-competitor-mapping.md).
- "Where were we?" to resume from
.infrahub-learning/progress.md.
Environment Detection
Detect once per session, in this order, and prefer the richest source:
- Repo files in the cwd (schema YAML, object files,
.infrahub.yml):
teach through the learner's own artifacts.
- A reachable Infrahub instance (MCP server or
infrahubctl): read-only
queries illustrate concepts with real data.
- Neither: use the generic examples in
references/concept-map.md.
Before writing the first Explain section, read rules/grounding-own-artifacts.md — a generic example when the learner has their own file is a violation, not a fallback.
Instance safety has three tiers; the full ladder is in rules/safety-instance-writes.md. Read it before any command that could write, which includes the steps you tell the learner to run. The short form: read-only by default, author in local files, and write to the instance only after explicit consent, only in a learning-* branch, never merged, always deleted.
Workflow
- On first contact, offer to create the learning workspace and read
references/lesson-protocol.md for the exact file layout and lesson shape. On resume, read .infrahub-learning/progress.md first.
- Pick the concept with
references/concept-map.md: it orders concepts
by prerequisite and carries per-concept probe questions, exercise specs, verification methods, and doc anchors. A topic with no row is taught off-map through the shared docs fallback (rules/grounding-off-map-lookup.md).
- Before writing any lesson file, read
rules/protocol-structured-lessons.md — the Probe/Explain/Exercise/Check shape and its order are fixed.
- Open with Probe, never with the explanation. Read
rules/protocol-probe-first.md for how many questions and what they have to establish.
- Write Explain against the learner's own artifacts, and cite the docs
page for every behavior claim: rules/grounding-cite-docs.md. For a "what's the NetBox/Nautobot equivalent" lesson, the credibility gate is in rules/grounding-competitor-mapping.md.
- Before presenting the exercise, build and verify the reference
solution per references/exercise-verification.md and rules/exercise-verify-solution.md — an exercise you have not solved yourself cannot ship. Assign the work; do not do it: rules/exercise-learner-authors.md.
- When the learner struggles, follow the hint ladder in
rules/exercise-hint-ladder.md before revealing anything, and log each rung to .infrahub-learning/hints/<concept>.md as you give it.
- Record progress at the end of every lesson, before you reply:
rules/protocol-record-progress.md.
- Close each concept by naming the sibling skill that does this work on
real projects: rules/handoff-graduation.md.
Rule Categories
| Priority | Category | Prefix | Description |
|---|---|---|---|
| CRITICAL | Protocol | protocol- | Probe before teaching, the fixed lesson shape, progress recording |
| CRITICAL | Safety | safety- | Instance writes: opt-in, learning-* branch only, cleanup, never the default branch |
| HIGH | Exercise | exercise- | Verified reference solutions, learner-authored artifacts, the hint ladder |
| HIGH | Grounding | grounding- | Teach through the learner's own artifacts, cite docs for behavior claims, off-map lookup, sourced comparisons |
| MEDIUM | Handoff | handoff- | Graduation pointers to the sibling skills |
Full scope per prefix is in rules/_sections.md. Read the rules for the lesson phase you are in; they are short and binding.
Supporting References
references/lesson-protocol.md: the workspace contract and lesson
shape. This file is the single home for those values.
references/concept-map.md: the curriculum.references/exercise-verification.md: how to prove an exercise is
solvable before showing it.
../infrahub-common/: shared GraphQL syntax and.infrahub.ymlformat.