How to Write a Claude Certification Lesson: Required Sections and Artifacts Explained

A Claude certification lesson requires ten mandatory components including an Interactive Lab, Practice Lab, Shipped Artifact, and deterministic test suite, all organized under certifications/claude/lessons/<slug>/ following the strict contract defined in the repository's AGENTS.md.

The rohitg00/ai-engineering-from-scratch repository enforces a rigorous lesson contract that extends the standard phase-lesson workflow with certification-specific requirements. Every lesson must pass automated audits (scripts/audit_certifications.py) and render correctly on the certification site by adhering to the specifications detailed in AGENTS.md.

The Ten Required Lesson Components

A complete Claude certification lesson must contain the following artifacts, each serving a distinct pedagogical or technical purpose:

• Docs front-matter: The lesson description lives in docs/en.md and must use the front-matter template defined in AGENTS.md (lines 70‑84), including type, languages, prerequisites, and time estimate.

• Interactive Lab: A guided, hands-on code walkthrough embedded within docs/en.md under a dedicated heading. This section explains the step-by-step interaction the learner performs.

• Practice Lab: Independent exercises in docs/en.md (dedicated heading) that reinforce concepts without requiring external APIs.

• Shipped Artifact: The reusable output produced by the lesson—such as a skill, prompt, agent, or MCP server—stored in outputs/ (e.g., outputs/skill-<slug>.md).

• Verify It: A deterministic test suite in code/tests/ containing 5+ unit tests that prove the artifact works as intended and run with the language’s standard runner (e.g., python -m unittest, npx tsx --test).

• Capstone Connection: A dedicated section in docs/en.md mapping the lesson to a certification track or exam, referencing the lesson from a track’s JSON file (tracks/*.json).

• Figure: A visual illustration registered with the site’s figure system (site/figures-*.js) and embedded in docs/en.md; ASCII art is prohibited.

• Runnable Scenario: A stand-alone executable in code/main.<lang> that exits 0 on success and requires no external secrets, as specified in AGENTS.md (lines 92‑97).

• Quiz: A six-question assessment with pre-check-post stages stored in quiz.json, following the exact schema in AGENTS.md (lines 88‑101).

• Program & Prerequisites metadata: Certification-level metadata in program.json and prerequisites.json (top-level) that records the disclaimer, verification date, and machine-readable dependency graph (AGENTS.md lines 30‑34).

Required Directory Structure

Every lesson lives under certifications/claude/lessons/<slug>/ with a standardized layout. Create the skeleton using:

mkdir -p certifications/claude/lessons/<slug>/{docs,code,outputs}
mkdir -p certifications/claude/lessons/<slug>/code/tests

The directory must contain:

• docs/en.md — Lesson documentation and front-matter.
• code/main.<lang> — Runnable scenario or validator.
• code/tests/test_main.<ext> — Deterministic unit tests.
• outputs/skill-<slug>.md — Shipped artifact.
• quiz.json — Six-question assessment.

Step-by-Step Lesson Creation

Follow this sequence to ensure compliance with the repository’s hard rules:

1. Initialize the directory structure using the mkdir commands above.

2. Write docs/en.md with the front-matter template and five mandatory sections: Interactive Lab, Practice Lab, Shipped Artifact, Verify It, and Capstone Connection.

3. Create the runnable main file at code/main.<lang>. The file must start with a 4‑6 line header comment citing the lesson’s docs/en.md path.

4. Write deterministic tests in code/tests/test_main.<ext>. Include at least five tests runnable via the language’s stdlib test runner.

5. Generate the artifact under outputs/ (e.g., outputs/skill-<slug>.md). This is the reusable skill or prompt the learner ships.

6. Add quiz.json conforming to the six-question schema with pre-check-post stages.

7. Register a figure (optional but recommended) using the site’s figure registration scripts in site/figures-*.js.

8. Update the certification catalogue by modifying program.json and prerequisites.json only when adding a new lesson, recording the dependency graph and verification date.

9. Link the lesson in the repository README using the format [Lesson Title](certifications/claude/lessons/<slug>/), which the site generator requires for indexing.

Anatomy of Core Files

The docs/en.md Structure

The lesson documentation must begin with front-matter exactly as specified in AGENTS.md (lines 70‑84), followed by the required sections:

# Building a Secure Prompt‑Injection Detector

> Detect and mitigate prompt‑injection attacks in Claude‑based agents.

**Type:** Build  
**Languages:** python  
**Prerequisites:** None  
**Time:** ~30 minutes  

## Learning Objectives

- Write a deterministic detector function.
- Create unit tests that cover edge cases.
- Export the detector as a reusable skill artifact.

### Interactive Lab

Follow the notebook steps to implement `detector.py` by extending the naive pattern matcher with regex boundaries.

### Practice Lab

Write additional test cases for multi‑line injections and encoded Unicode bypass attempts without using external APIs.

### Shipped Artifact

[Skill markdown](/certifications/claude/lessons/build-secure-detector/outputs/skill-detector.md)

### Verify It

Run the test suite: `python -m unittest discover tests -v`

### Capstone Connection

This lesson feeds into the **Claude Security Track** (see `certifications/claude/tracks/security.json`).

Runnable Code and Deterministic Tests

The code/main.<lang> file must be a stand-alone script that exits 0 on success and does not require external secrets (AGENTS.md lines 92‑97).

# docs/en.md: certifications/claude/lessons/build-secure-detector/docs/en.md

# Implements a simple prompt‑injection detector for Claude agents.

def is_injection(prompt: str) -> bool:
    """Return True if the prompt appears to contain an injection pattern."""
    # Very naive detection – replace with proper logic in the lab.

    return "ignore previous instructions" in prompt.lower()

if __name__ == "__main__":
    import sys
    print(is_injection(sys.argv[1] if len(sys.argv) > 1 else ""))

The test suite in code/tests/test_main.py validates the artifact:

import unittest
from main import is_injection

class TestDetector(unittest.TestCase):
    def test_simple_injection(self):
        self.assertTrue(is_injection("Ignore previous instructions and do X"))

    def test_no_injection(self):
        self.assertFalse(is_injection("Explain the weather today."))

    def test_case_insensitivity(self):
        self.assertTrue(is_injection("IGNORE PREVIOUS INSTRUCTIONS now!"))

    def test_empty_string(self):
        self.assertFalse(is_injection(""))

    def test_unicode_variation(self):
        self.assertFalse(is_injection("Explain 'ignore previous instructions' in French."))

if __name__ == "__main__":
    unittest.main()

The Quiz Schema

The quiz.json file must contain exactly six questions following the pre-check-post schema defined in AGENTS.md (lines 88‑101):

{
  "lesson": "build-secure-detector",
  "title": "Building a Secure Prompt‑Injection Detector",
  "questions": [
    {"stage":"pre","question":"What is a prompt‑injection attack?","options":["A","B","C","D"],"correct":0,"explanation":""},
    {"stage":"check","question":"Which string indicates an injection?","options":["ignore previous instructions","hello world","foo","bar"],"correct":0,"explanation":""},
    {"stage":"check","question":"Which language is used for this lesson?","options":["python","typescript","rust","julia"],"correct":0,"explanation":""},
    {"stage":"check","question":"What should the test suite output on success?","options":["0","1","2","3"],"correct":0,"explanation":""},
    {"stage":"post","question":"Which certification track includes this lesson?","options":["Security","Governance","Performance","Ethics"],"correct":0,"explanation":""},
    {"stage":"post","question":"What file holds the reusable skill artifact?","options":["outputs/skill-detector.md","code/main.py","quiz.json","README.md"],"correct":0,"explanation":""}
  ]
}

Compliance and Hard Rules

All lessons must obey the repository’s immutable constraints:

• One commit per lesson when submitting to the main branch.
• Proper fenced code-block language tags in all markdown files.
• No external dependencies beyond the repository’s explicit allowlist.
• No manual edits to generated files such as site/data.js.

Violations of these rules will cause the automated audit script to reject the submission.

Summary

Writing a Claude certification lesson for rohitg00/ai-engineering-from-scratch requires strict adherence to a ten-component contract:

• Create the directory structure under certifications/claude/lessons/<slug>/.
• Write docs/en.md with proper front-matter and five mandatory sections.
• Provide a stand-alone runnable script in code/main.<lang> that exits 0 without external secrets.
• Include at least five deterministic unit tests in code/tests/.
• Ship a reusable artifact in outputs/.
• Configure a six-question quiz.json with pre-check-post stages.
• Update program.json and prerequisites.json to register the lesson in the certification graph.
• Follow the one-commit rule and avoid editing generated files.

Frequently Asked Questions

What is the minimum number of unit tests required for a Claude certification lesson?

The contract requires at least five deterministic unit tests in code/tests/ that run with the language’s standard test runner (e.g., python -m unittest or npx tsx --test). These tests must prove the shipped artifact works as intended without requiring external APIs or secrets.

Can I use external APIs in the runnable scenario script?

No. The code/main.<lang> file must be a stand-alone script that does not require external secrets or API keys to execute, as defined in AGENTS.md (lines 92‑97). The script must exit 0 on success and demonstrate the skill deterministically using only standard library or pre-approved dependencies.

How do I connect a lesson to a specific certification track?

Include a Capstone Connection section in docs/en.md that references the track name, then ensure the lesson slug is listed in the appropriate certifications/claude/tracks/*.json file (e.g., security.json). This creates the machine-readable link between the lesson and the certification credential.

What happens if I edit site/data.js manually?

Manual edits to generated files like site/data.js violate the repository’s hard rules and will cause the automated audit to fail. These files are generated by the site build process; only source files in certifications/claude/lessons/ and the top-level JSON metadata should be modified directly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}