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

> Explore the flat, by-phase, and skills layout options in install_skills.py to organize course artifacts effectively in your AI engineering projects.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-06-09

---

**The [`install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/install_skills.py)

Inside [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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:

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

```

Group artifacts by curriculum phase using `by-phase`:

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

```

Use the default `skills` layout, either implicitly or explicitly:

```bash
python3 scripts/install_skills.py <target_dir>

```

```bash
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:

```bash
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/install_skills.py) supports three `--layout` options: `flat`, `by-phase`, and `skills`.
- The `target_path` function in [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.