# How Code Is Organized in Leonxlnx/taste-skill: A Documentation-First Skill Library > Discover how code is organized in Leonxlnx/taste-skill. Explore its flat, documentation-first structure with skills in separate folders and SKILL.md documentation. - Repository: [Leon Lin/taste-skill](https://github.com/Leonxlnx/taste-skill) - Tags: documentation - Published: 2026-05-26 --- **The Leonxlnx/taste-skill repository organizes code as a flat, documentation-first skill library where each self-contained agent skill lives in its own folder within `skills/` and is described by a [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) file consumed by the `npx skills` CLI.** The **taste-skill** repository is a skill-library that ships a collection of self-contained "agent skills" for code and image generation. Unlike traditional codebases with deep source trees, this project adopts a deliberately flat structure oriented around **skill discovery**. The primary artifacts are markdown specifications rather than executable source files, making the repository consumable by both humans and automated agents. ## Top-Level Directory Layout The repository root contains five functional directories and key metadata files: - **`skills/`**: Houses every skill (code-generation or image-generation). Each skill occupies its own subfolder containing a [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) descriptor. - **`assets/`**: Stores static visual assets including logos and banners used by the [`README.md`](https://github.com/Leonxlnx/taste-skill/blob/main/README.md) and individual skills. - **`examples/`**: Contains reference screenshots illustrating the output of design skills. - **`research/`**: Holds design-system research, bias-analysis, and remediation notes that inform the "anti-slop" guidelines. - **[`skill.sh`](https://github.com/Leonxlnx/taste-skill/blob/main/skill.sh)**: A minimal Bash registry mapping install names to markdown descriptor paths. Additional standard files include [`README.md`](https://github.com/Leonxlnx/taste-skill/blob/main/README.md) (the public entry point), `LICENSE`, [`CHANGELOG.md`](https://github.com/Leonxlnx/taste-skill/blob/main/CHANGELOG.md), and `.github/` configuration for funding and Copilot instructions. ## Skill Folder Structure Each skill follows a minimal, consistent pattern: ``` skills// ├─ SKILL.md # Front-matter + full skill specification └─ (optional) other resources (e.g., DESIGN.md) ``` The **front-matter** in [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) provides the `name:` (install name) and description fields that the `npx skills` CLI uses for discovery. The remainder of the file contains exhaustive, rule-heavy specifications governing how downstream LLMs should generate UI code or images according to the **anti-slop** design principles. ## The Skill Registry (skill.sh) Located at the repository root, [`skill.sh`](https://github.com/Leonxlnx/taste-skill/blob/main/skill.sh) declares an associative Bash array that maps install names to their corresponding markdown paths: ```bash declare -A SKILLS=( [taste-skill]="skills/taste-skill/SKILL.md" [taste-skill-v1]="skills/taste-skill-v1/SKILL.md" # … additional mappings … ) ``` When a user executes `npx skills add https://github.com/Leonxlnx/taste-skill --skill "design-taste-frontend"`, the CLI looks up the install name and uses this registry to fetch the correct descriptor file. ## Documentation-First Architecture Rather than traditional source files, the repository's **knowledge base** (the markdown skill specifications) serves as the primary artifact. This organization enables: - **Human consumption**: Developers can copy-paste specifications directly from [`skills/taste-skill/SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/skills/taste-skill/SKILL.md) into prompts. - **Automated consumption**: The `npx skills` tool parses front-matter and retrieves specifications programmatically. - **Rapid iteration**: Adding a new skill requires only creating a new folder with a [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) file and updating the [`skill.sh`](https://github.com/Leonxlnx/taste-skill/blob/main/skill.sh) registry. Supporting materials in `assets/`, `examples/`, and `research/` exist solely to augment these specifications. ## Working with the Repository Installing a skill via the CLI: ```bash # Install the default taste-skill (v2 experimental) npx skills add https://github.com/Leonxlnx/taste-skill # Install a specific skill by install name npx skills add https://github.com/Leonxlnx/taste-skill \ --skill "design-taste-frontend" ``` The CLI reads the [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) front-matter to resolve `design-taste-frontend` to [`skills/taste-skill/SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/skills/taste-skill/SKILL.md). Loading a skill descriptor directly in Bash: ```bash # Source the registry script source ./skill.sh # Retrieve path for "soft-skill" echo "${SKILLS[soft-skill]}" # Output: skills/soft-skill/SKILL.md ``` Using the specification in a prompt: ```text You are a design agent. Follow the skill described in https://github.com/Leonxlnx/taste-skill/blob/main/skills/taste-skill/SKILL.md to generate a landing-page UI for a minimalist SaaS product. ``` ## Summary - The repository uses a **flat directory structure** centered on the `skills/` folder. - Each skill is a self-contained folder containing a [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) file with YAML front-matter and detailed specifications. - The [`skill.sh`](https://github.com/Leonxlnx/taste-skill/blob/main/skill.sh) Bash registry maps install names (e.g., `design-taste-frontend`) to markdown paths via an associative array. - **Documentation is the primary artifact**, not executable code, enabling consumption by both humans and the `npx skills` CLI. - Supporting directories (`assets/`, `examples/`, `research/`) provide visual and research backing for the skill specifications. ## Frequently Asked Questions ### What is the purpose of the SKILL.md file in each skill folder? The [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) file serves as the complete specification for an agent skill. Its YAML front-matter contains metadata like the install name and description consumed by the `npx skills` CLI, while the body contains detailed rules, anti-slop guidelines, and generation parameters that LLMs follow when producing code or images. ### How does the skill.sh registry work? The [`skill.sh`](https://github.com/Leonxlnx/taste-skill/blob/main/skill.sh) file declares a Bash associative array named `SKILLS` that maps string install names (such as `taste-skill` or `taste-skill-v1`) to filesystem paths pointing to the corresponding [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) files. When the `npx skills` CLI installs a skill, it sources this script to resolve the install name to the correct markdown descriptor location in the `skills/` directory. ### Why is the repository organized around markdown files instead of source code? This documentation-first approach treats **knowledge specifications** as the primary deliverable. Since these skills instruct LLMs on how to generate code rather than containing executable logic themselves, markdown specifications are more portable and accessible than traditional source trees. Users can copy-paste specs directly into chat interfaces, while automated tools parse the structured front-matter programmatically. ### Where are the actual generated assets and research materials stored? Visual assets like logos and banners reside in `assets/`, example outputs and screenshots live in `examples/`, and design-system research including bias analysis is contained in `research/`. These directories support the skill specifications but remain separate from the `skills/` folder containing the core [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) descriptors.