Teaching Concepts Skill
Relevant source files
The following files were used as context for generating this wiki page:
- skills/infrahub-teaching-concepts/SKILL.md
- skills/infrahub-teaching-concepts/references/concept-map.md
- skills/infrahub-teaching-concepts/references/lesson-protocol.md
- skills/infrahub-teaching-concepts/rules/protocol-structured-lessons.md
- skills/infrahub-teaching-concepts/rules/_sections.md
- tests/graders/test_teaching_lib.py
- AGENTS.md
The Infrahub Concept Tutor teaches Infrahub concepts, including schemas, objects, and branches, by using the learner's own repository files and live instances as lesson material. It follows a tutor protocol rather than a textbook approach, measuring existing knowledge and providing hands-on exercises that are verified solvable before presentation.
Sources: skills/infrahub-teaching-concepts/SKILL.md:20-25
Core Workflow
The skill executes a structured sequence to ensure pedagogical consistency and progress tracking. It detects the environment to ground lessons in real data, creates a local workspace for durable records, and follows a probe-first teaching method.
Skill Execution Flow
This diagram illustrates the operational steps from initial trigger to graduation.
The diagram shows the logic for session resumption and the fixed lesson order.
Sources: skills/infrahub-teaching-concepts/SKILL.md:46-65
Workspace Architecture
All learning artifacts reside in a dedicated hidden directory named .infrahub-learning/ within the user's current working directory. The skill never creates this workspace without explicit consent.
Workspace File Structure
| Path | Description |
|---|---|
progress.md | Stores the state of the learning session, including concept statuses and dates. |
lessons/<slug>.md | Contains the durable lesson artifact for a specific concept. |
solutions/<slug>.md | Holds the reference solution and verification evidence; written before exercises are shown. |
hints/<slug>.md | Logs the escalation ladder for a concept to help the learner get unstuck. |
Sources: skills/infrahub-teaching-concepts/references/lesson-protocol.md:7-16
Curriculum and Concept Mapping
The skill uses a dependency-ordered curriculum defined in a concept map. Topics range from foundations to complex automation like generators.
Concept Hierarchy
| # | Concept Slug | Prerequisites | Graduation Skill |
|---|---|---|---|
| 1 | foundations | None | None |
| 2 | schema | foundations | infrahub-managing-schemas |
| 3 | objects | schema | infrahub-managing-objects |
| 4 | graphql | schema | infrahub-analyzing-data |
| 5 | branches | foundations | None |
| 8 | checks | proposed-changes | infrahub-managing-checks |
| 9 | transforms | repo-integration | infrahub-managing-transforms |
Sources: skills/infrahub-teaching-concepts/references/concept-map.md:10-21, skills/infrahub-teaching-concepts/references/lesson-protocol.md:18-19
Lesson Protocol
Every lesson file must adhere to a strict structure of four H2 headings to ensure consistency and facilitate automated evaluation.
Section Definitions
- Probe: Contains 2 to 3 questions to establish the learner's background. It must always precede the explanation.
- Explain: Provides the core teaching content. It anchors claims to the learner's own artifacts (e.g., specific schema nodes) and cites
docs.infrahub.app. - Exercise: Assigns a task starting with the marker
**Your task:**. It contains no solution content. - Check: Includes 1 to 2 recall or transfer questions to verify understanding.
Sources: skills/infrahub-teaching-concepts/rules/protocol-structured-lessons.md:19-25, skills/infrahub-teaching-concepts/references/lesson-protocol.md:21-30
Lesson Sequence Diagram
This diagram shows the interaction between the Tutor and the Learner during a typical concept lesson.
The sequence highlights the mandatory solution verification and progress recording steps.
Sources: skills/infrahub-teaching-concepts/SKILL.md:46-65, skills/infrahub-teaching-concepts/references/lesson-protocol.md:40-48
Hint Ladder and Escalation
When a learner fails an attempt or requests help, the skill follows a three-rung hint ladder to avoid immediate solution spoilers.
- Hint 1: A conceptual nudge with no code blocks longer than two lines.
- Hint 2: A concrete pointer to a specific file, field, or line number.
- Hint 3: The reference solution with a full walkthrough.
Every hint is appended to hints/<concept>.md before being presented in chat to ensure the escalation log survives the session.
Sources: skills/infrahub-teaching-concepts/references/lesson-protocol.md:40-48, tests/graders/test_teaching_lib.py:273-280
Safety and Branching
The tutor enforces strict safety rules for any exercise involving instance writes to prevent corruption of the default branch.
- Opt-in Consent: The tutor asks for explicit consent before any command that could write data.
- Sandbox Branches: All mutating steps must target a branch starting with
learning-. - No Merging: Learning branches are never merged into the default branch.
- Cleanup: The tutor includes a final step to delete the sandbox branch.
Sources: skills/infrahub-teaching-concepts/SKILL.md:38-44, skills/infrahub-teaching-concepts/references/lesson-protocol.md:50-54
Summary
The Teaching Concepts Skill transforms Infrahub documentation into an interactive, guided experience. By enforcing a structured lesson protocol, maintaining a durable local workspace, and implementing a safety-first branching model, the skill ensures that learners gain hands-on proficiency while grounding their knowledge in their own project's specific context.