How Code Is Organized in Leonxlnx/taste-skill: A Documentation-First Skill Library

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 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 descriptor.
• assets/: Stores static visual assets including logos and banners used by the 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: A minimal Bash registry mapping install names to markdown descriptor paths.

Additional standard files include README.md (the public entry point), LICENSE, CHANGELOG.md, and .github/ configuration for funding and Copilot instructions.

Skill Folder Structure

Each skill follows a minimal, consistent pattern:

skills/<skill-folder>/
├─ SKILL.md          # Front-matter + full skill specification

└─ (optional) other resources (e.g., DESIGN.md)

The front-matter in 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 declares an associative Bash array that maps install names to their corresponding markdown paths:

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 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 file and updating the 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:

# 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 front-matter to resolve design-taste-frontend to skills/taste-skill/SKILL.md.

Loading a skill descriptor directly in 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:

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 file with YAML front-matter and detailed specifications.
• The 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 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 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 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 descriptors.

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