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

To contribute to Leonxlnx/taste-skill, fork the repository, create a new directory under skills/, add a SKILL.md file with valid YAML front-matter, optionally register the mapping in skill.sh, update the 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	High-level overview, installation instructions, skill inventory table, and contribution guidelines (see lines 38-45 for maintainer contact details).	Repository root
skill.sh	Bash associative array that maps skill identifiers to their canonical 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:

   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 file inside your new directory. The file must include YAML front-matter with the following keys:

   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 (optional but recommended). Add an entry to the associative array so the Bash helper can resolve your skill:

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

5. Update 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.

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

   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, 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:

# 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 does not duplicate an existing key in 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 (v2) or 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 with valid YAML front-matter.
• Optionally register the skill path in skill.sh to enable Bash helper resolution.
• Update the 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 file follow?

The 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 for my skill to work?

Editing skill.sh is optional but recommended. The CLI (npx skills add) primarily scans the skills/ folder for SKILL.md files, making skills automatically discoverable. However, adding an entry to the 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 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 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 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>.

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