# How to Contribute to the Leonxlnx/taste-skill Repository: A Complete Guide

> Learn how to contribute to Leonxlnx/taste-skill. Fork the repo, add your skill, update documentation, and submit a pull request with this complete guide.

- Repository: [Leon Lin/taste-skill](https://github.com/Leonxlnx/taste-skill)
- Tags: how-to-guide
- Published: 2026-05-26

---

**To contribute to Leonxlnx/taste-skill, fork the repository, create a new directory under `skills/`, add a [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) file with valid YAML front-matter, optionally register the mapping in [`skill.sh`](https://github.com/Leonxlnx/taste-skill/blob/main/skill.sh), update the [`README.md`](https://github.com/Leonxlnx/taste-skill/blob/main/README.md) table, verify with the Bash helper, and open a pull request against the `main` branch.**

The Leonxlnx/taste-skill repository distributes portable SKILL files that define agent capabilities for both code generation and image generation. Contributing to this project means creating self-contained skill definitions that the CLI (`npx skills add`) can automatically discover without additional configuration. This guide explains the exact repository structure, contribution workflow, and validation steps required to get your changes merged.

## Repository Architecture and Key Files

Understanding the file layout is essential before contributing. The repository is intentionally minimal, relying on convention over configuration to make skills portable.

| Component | Purpose | Location |
|---|---|---|
| **[`README.md`](https://github.com/Leonxlnx/taste-skill/blob/main/README.md)** | High-level overview, installation instructions, skill inventory table, and contribution guidelines (see lines 38-45 for maintainer contact details). | Repository root |
| **[`skill.sh`](https://github.com/Leonxlnx/taste-skill/blob/main/skill.sh)** | Bash associative array that maps skill identifiers to their canonical [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) file paths; sourced by the CLI during discovery. | Repository root |
| **`skills/*/SKILL.md`** | The complete definition of a skill, including metadata, design-system parameters, and anti-slop rules; the only file an agent needs to load. | `skills/<skill-name>/SKILL.md` |
| **`assets/`** | Visual resources (logos, banners, example renders) referenced by documentation. | `assets/` |
| **`research/``** | Academic papers and design research that motivate the dial settings and remediation strategies. | `research/` |

## Step-by-Step Guide to Contributing

Follow these eight steps to ensure your contribution aligns with the project's portable-skill philosophy.

1. **Fork and clone** the repository to your GitHub account, then create a feature branch:

   ```bash
   git clone https://github.com/<your-username>/taste-skill.git
   cd taste-skill
   git checkout -b my-new-skill
   ```

2. **Create a skill directory** under `skills/` using a lowercase, hyphenated name (e.g., `skills/my-new-skill/`).

3. **Add a [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md)** file inside your new directory. The file must include YAML front-matter with the following keys:

   ```yaml
   name: my-new-skill
   description: Concise description of what this skill generates
   ```

   You may optionally include design-dial parameters such as `DESIGN_VARIANCE`, `MOTION_INTENSITY`, or `VISUAL_DENSITY` to control generation behavior.

4. **Update [`skill.sh`](https://github.com/Leonxlnx/taste-skill/blob/main/skill.sh)** (optional but recommended). Add an entry to the associative array so the Bash helper can resolve your skill:

   ```bash
   [my-new-skill]="skills/my-new-skill/SKILL.md"
   ```

5. **Update [`README.md`](https://github.com/Leonxlnx/taste-skill/blob/main/README.md)** to include your skill in the inventory table. Follow the existing column layout: Skill (folder), Install name, and Description.

6. **Add assets** if your skill requires reference images. Place them in `assets/` and link using relative URLs from your [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md).

7. **Run validation** by sourcing the helper script to ensure the path resolves correctly:

   ```bash
   source ./skill.sh my-new-skill
   ```

   If the repository includes linting (e.g., `npm run lint`), execute it to verify that all links resolve and YAML front-matter is valid.

8. **Open a Pull Request** against the `main` branch. Include a summary of the contribution, links to the new [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md), and any relevant discussion from the issue tracker.

## Local Development Workflow

Use the following terminal commands to verify your skill is correctly registered and portable before submitting:

```bash

# Verify the skill registry resolves

source ./skill.sh my-new-skill

# Expected output: skills/my-new-skill/SKILL.md

# Stage all changes

git add .

# Commit with a descriptive message

git commit -m "Add my-new-skill with design-dial parameters"

# Push to your fork

git push origin my-new-skill

```

Once pushed, open the PR via the GitHub web interface. Ensure the GitHub Actions CI passes; the workflow typically validates YAML syntax and checks for broken links.

## Best Practices for SKILL.md Files

To ensure a smooth code review and maintain repository consistency:

- **Keep front-matter valid.** The YAML block must parse correctly; invalid syntax breaks the `npx skills add` CLI parser.
- **Use unique install names.** Verify that the `name:` key in your [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) does not duplicate an existing key in [`skill.sh`](https://github.com/Leonxlnx/taste-skill/blob/main/skill.sh).
- **Reference assets properly.** Store images in `assets/` rather than skill-specific folders to maintain the portable nature of `skills/`.
- **Follow existing conventions.** Examine [`skills/taste-skill/SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/skills/taste-skill/SKILL.md) (v2) or [`skills/gpt-tasteskill/SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/skills/gpt-tasteskill/SKILL.md) for examples of strict formatting and parameter usage.
- **Document design rationale.** If your skill introduces new dial settings, cite relevant papers from the `research/` directory in your PR description.

## Summary

- Fork the Leonxlnx/taste-skill repository and branch from `main`.
- Create a new directory under `skills/` containing a [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) with valid YAML front-matter.
- Optionally register the skill path in [`skill.sh`](https://github.com/Leonxlnx/taste-skill/blob/main/skill.sh) to enable Bash helper resolution.
- Update the [`README.md`](https://github.com/Leonxlnx/taste-skill/blob/main/README.md) skill table and place visual assets in `assets/`.
- Validate locally using `source ./skill.sh <skill-name>` and ensure CI passes.
- Submit a pull request with clear documentation and links to the new skill files.

## Frequently Asked Questions

### What format must the [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) file follow?

The [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) file must begin with YAML front-matter delimited by triple dashes. Required fields include `name:` (the install identifier used with `npx skills add`) and `description:` (a human-readable summary). Optional fields like `DESIGN_VARIANCE` or `MOTION_INTENSITY` control generation behavior according to the design-system research located in `research/`.

### Do I need to manually edit [`skill.sh`](https://github.com/Leonxlnx/taste-skill/blob/main/skill.sh) for my skill to work?

Editing [`skill.sh`](https://github.com/Leonxlnx/taste-skill/blob/main/skill.sh) is optional but recommended. The CLI (`npx skills add`) primarily scans the `skills/` folder for [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) files, making skills automatically discoverable. However, adding an entry to the [`skill.sh`](https://github.com/Leonxlnx/taste-skill/blob/main/skill.sh) associative array enables the Bash helper to resolve skill paths for local testing and legacy integrations.

### How does the CLI discover new skills?

The `npx skills add` command scans the `skills/` directory for any folder containing a [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) file. Because skills are self-contained and portable, no central registry update is required beyond placing the file in the correct directory structure. The [`skill.sh`](https://github.com/Leonxlnx/taste-skill/blob/main/skill.sh) script provides a secondary lookup mechanism for environments that source Bash utilities.

### What should I include in the pull request description?

Include a brief summary of the skill's purpose, links to the specific [`SKILL.md`](https://github.com/Leonxlnx/taste-skill/blob/main/SKILL.md) file and any assets in `assets/`, and references to related issue tracker discussions. If your skill introduces new design-dial parameters, explain their relationship to the research papers in `research/` and confirm that you have tested the installation via `source ./skill.sh <skill-name>`.