# How the SKILL.md Template System Works in gstack

> Discover how the SKILL.md template system in gstack generates synchronized skill documentation from a single source ensuring AI commands stay documented. Learn more now.

- Repository: [Garry Tan/gstack](https://github.com/garrytan/gstack)
- Tags: internals
- Published: 2026-05-15

---

**The SKILL.md template system in garrytan/gstack generates synchronized skill documentation by rendering YAML-fronted template files (`SKILL.md.tmpl`) into final markdown ([`SKILL.md`](https://github.com/garrytan/gstack/blob/main/SKILL.md)) via the `bun run gen:skill-docs` build pipeline, ensuring every AI-driven command remains documented from a single source of truth.**

The garrytan/gstack repository orchestrates AI-driven development workflows through discrete, modular skills such as `/office-hours` and `/plan-eng-review`. Each skill requires consistent, versioned documentation that tracks with code changes. The SKILL.md template architecture solves this by treating documentation as a build artifact generated from declarative templates stored alongside source code.

## Core Architecture of the Template System

Every skill resides in its own directory (e.g., `unfreeze/`, `plan-eng-review/`) and contains a source template named `SKILL.md.tmpl`. This file acts as the **single source of truth** for that skill's documentation.

When the repository builds, a generation step—invoked via `bun run gen:skill-docs` or the equivalent npm script—scans the codebase for the glob pattern `**/SKILL.md.tmpl`. For each template found, the generator renders the markdown, substitutes dynamic variables, and writes the output to a plain [`SKILL.md`](https://github.com/garrytan/gstack/blob/main/SKILL.md) file in the same directory.

The resulting generated files serve multiple consumers: the **Skill Deep Dives** section in [`docs/skills.md`](https://github.com/garrytan/gstack/blob/main/docs/skills.md), the CLI help output, and the public-facing documentation site. Because the build process regenerates these files from templates, any modification to a `SKILL.md.tmpl` automatically propagates to all downstream documentation without manual synchronization.

## Template Structure and Front-Matter Schema

A `SKILL.md.tmpl` file consists of two distinct sections: a YAML front-matter metadata block followed by free-form markdown content.

The front-matter defines operational metadata consumed by the gstack engine:

- **name**: The skill identifier (e.g., `unfreeze`)
- **version**: Semantic version string (e.g., `0.1.0`)
- **description**: Human-readable summary of the skill's purpose
- **triggers**: Array of command triggers (e.g., `['/unfreeze']`)
- **allowed-tools**: List of permitted execution contexts (e.g., `Bash`, `Read`)
- **sensitive**: Boolean flag indicating if the skill handles privileged operations

The markdown body follows the front-matter and contains the actual documentation, including usage examples, argument descriptions, and operational notes. The generator performs minimal transformation on this body, primarily handling variable substitution for dynamic values like timestamps.

## The Build Pipeline: bun run gen:skill-docs

The generation logic is exposed through the npm script `gen:skill-docs` defined in the repository's [`package.json`](https://github.com/garrytan/gstack/blob/main/package.json). When executed with `bun run gen:skill-docs`, the script performs the following operations:

1. Recursively locates all `SKILL.md.tmpl` files across the repository
2. Parses the YAML front-matter to extract metadata
3. Processes the markdown body, evaluating shell placeholders such as `$(date -u +%Y-%m-%dT%H:%M:%SZ)` where they appear
4. Writes the rendered content to [`SKILL.md`](https://github.com/garrytan/gstack/blob/main/SKILL.md) in the same directory as the source template

This build-time approach ensures that [`SKILL.md`](https://github.com/garrytan/gstack/blob/main/SKILL.md) files are always deterministic outputs rather than manually maintained assets. Developers commit both the template and the generated file, allowing documentation to be readable in-source while remaining mechanically derived.

## Real-World Example: The unfreeze Skill

The `unfreeze` skill demonstrates the template system in practice. The source template at `unfreeze/SKILL.md.tmpl` defines the skill's metadata and usage instructions:

```markdown
---
name: unfreeze
version: 0.1.0
description: |
  Resumes work on a previously frozen task or branch.
triggers:
  - unfreeze
allowed-tools:
  - Bash
  - Read
sensitive: false
---

# /unfreeze — Resume Frozen Work

Run:

```bash
git stash pop
echo "Resumed work at $(date -u +%Y-%m-%dT%H:%M:%SZ)"

```

This skill restores the working state from the git stash.

```

After running `bun run gen:skill-docs`, the generator produces [`unfreeze/SKILL.md`](https://github.com/garrytan/gstack/blob/main/unfreeze/SKILL.md) containing the rendered markdown (minus the YAML delimiters, which are consumed as metadata). The [`docs/skills.md`](https://github.com/garrytan/gstack/blob/main/docs/skills.md) file then aggregates all such generated documents into a comprehensive registry.

## Integration with the Skill Registry

The generated [`SKILL.md`](https://github.com/garrytan/gstack/blob/main/SKILL.md) files feed directly into the project's documentation ecosystem. The [`docs/skills.md`](https://github.com/garrytan/gstack/blob/main/docs/skills.md) file contains a **Skill Deep Dives** section that references these generated files, creating a unified documentation surface without duplicating content. The CLI also parses these files to display help text when users invoke the `--help` flag on specific skills, ensuring command-line documentation matches the official docs exactly.

## Summary

- **SKILL.md.tmpl** files serve as the canonical source for skill documentation, living alongside code in skill-specific directories
- The `bun run gen:skill-docs` command renders templates into **SKILL.md** files, evaluating dynamic placeholders at build time
- **YAML front-matter** encodes machine-readable metadata including triggers, allowed tools, and sensitivity flags
- Generated documentation powers both the **docs/skills.md** registry and CLI help output, maintaining strict synchronization with source code

## Frequently Asked Questions

### What is the difference between SKILL.md.tmpl and SKILL.md?

`SKILL.md.tmpl` is the editable source template containing YAML front-matter and markdown body; [`SKILL.md`](https://github.com/garrytan/gstack/blob/main/SKILL.md) is the build artifact generated by `bun run gen:skill-docs`. You edit the template, while the generated file is consumed by documentation readers and the CLI.

### How do I create documentation for a new skill in gstack?

Create a new directory for your skill (e.g., `my-skill/`), add a `SKILL.md.tmpl` file with the required YAML front-matter (name, version, description, triggers, allowed-tools, sensitive) and markdown documentation, then run `bun run gen:skill-docs` to generate the [`SKILL.md`](https://github.com/garrytan/gstack/blob/main/SKILL.md) output.

### Can SKILL.md templates include dynamic content?

Yes. The generator evaluates shell command substitutions within the template body, allowing you to inject runtime values such as timestamps using standard Bash syntax like `$(date -u +%Y-%m-%dT%H:%M:%SZ)` during the build process.

### Where does gstack aggregate its skill documentation?

The [`docs/skills.md`](https://github.com/garrytan/gstack/blob/main/docs/skills.md) file automatically aggregates and displays content from all [`SKILL.md`](https://github.com/garrytan/gstack/blob/main/SKILL.md) files across the repository, specifically within the *Skill Deep Dives* section, creating a centralized reference without manual copying.