Layout Options in `install_skills.py`: How `flat`, `by-phase`, and `skills` Work

The install_skills.py script from the rohitg00/ai-engineering-from-scratch repository offers three --layout strategies—flat, by-phase, and skills—that determine whether course artifacts are placed in a single directory, grouped by curriculum phase, or wrapped in individual per-skill folders.

The install_skills.py utility is the main driver for installing course artifacts such as skills, prompts, and agents from the rohitg00/ai-engineering-from-scratch curriculum. By passing the --layout flag, users control the exact directory structure used in the target path. The default layout is skills, which recreates the original course output format.

How Destination Paths Are Computed in install_skills.py

Inside scripts/install_skills.py, the target_path function (lines 57–65) implements the mapping logic that translates a chosen layout into a concrete file system path. This function inspects the artifact’s metadata—parsed with helpers from scripts/_lib.py—and the user-supplied --layout argument to decide whether to flatten the output, create phase directories, or build per-skill folders. Understanding this function is key to predicting exactly where each markdown file will land after installation.

The Three Layout Options

flat – Single Directory Output

In the flat layout, every artifact is copied directly into the target directory with no sub-folders created. The destination file is named <target>/<name>.md, where <name> is drawn from the artifact’s name frontmatter field or the filename stem. This option is ideal when you want a simple, side-by-side view of all prompts, skills, and agents.

by-phase – Curriculum Phase Grouping

The by-phase layout organizes artifacts under phase-specific subdirectories following the pattern <target>/phase-NN/<name>.md. Each artifact is routed to a folder such as phase-01 or phase-02 based on the curriculum phase extracted from its source path. If the phase number cannot be determined, the script falls back to a phase-unknown folder, ensuring no file is dropped unpredictably.

skills – Per-Artifact Folders (Default)

The default skills layout mirrors the original curriculum structure by giving every artifact its own folder. The resulting path follows <target>/<name>/SKILL.md, meaning the directory name reflects the artifact’s name and the file inside is always called SKILL.md. This is the layout used when the --layout flag is omitted.

Command-Line Usage Examples

You can select any layout by appending --layout <option> when running the script.

Install everything side-by-side with the flat layout:

python3 scripts/install_skills.py <target_dir> --layout flat

Group artifacts by curriculum phase using by-phase:

python3 scripts/install_skills.py <target_dir> --layout by-phase

Use the default skills layout, either implicitly or explicitly:

python3 scripts/install_skills.py <target_dir>

python3 scripts/install_skills.py <target_dir> --layout skills

Combining Layouts with Filters

Layout options can be mixed with the script’s other flags, such as --type and --phase, to install only a subset of artifacts. For example, to install only prompts from phase 3 using the flat layout:

python3 scripts/install_skills.py <target_dir> \
    --type prompt --phase 3 --layout flat

This flexibility allows you to maintain a clean organization scheme even when extracting targeted content from the full curriculum tree stored under phases/*/*/outputs/.

Summary

• install_skills.py supports three --layout options: flat, by-phase, and skills.
• The target_path function in scripts/install_skills.py (lines 57–65) computes the final destination path based on the chosen layout and artifact metadata.
• flat places all files directly in <target>/<name>.md with no subdirectories.
• by-phase groups files into <target>/phase-NN/<name>.md, falling back to phase-unknown when necessary.
• skills is the default, creating <target>/<name>/SKILL.md folders that match the original curriculum format.

Frequently Asked Questions

What is the default layout if I omit the --layout flag?

The default layout is skills. If you run install_skills.py without specifying --layout, each artifact is placed into its own folder as <target>/<name>/SKILL.md, preserving the original course output structure.

How does the by-phase layout handle artifacts without a known phase number?

When the curriculum phase cannot be determined for an artifact, the target_path function routes it to a fallback folder named phase-unknown inside the target directory. This ensures every file is organized even when phase metadata is missing.

Can I use layout options together with filters like --type or --phase?

Yes. The --layout flag operates independently of filters. You can combine it with flags such as --type prompt or --phase 3 to control both which artifacts are installed and how they are arranged on disk.

Where is the layout logic implemented in the source code?

The mapping logic lives in the target_path function inside scripts/install_skills.py at lines 57–65. This function reads the selected layout and the artifact’s properties to produce the correct destination path string.

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