Contributing to SkillStore

Thank you for your interest in contributing to SkillStore. This guide covers everything you need to create, test, and submit new skills or improvements.

Creating a New Skill

1. Start from the Template

Copy shared/skill-template/ as your starting point. Every skill must include:

• SKILL.md — The main skill file with YAML frontmatter, triggers, process phases, and output requirements
• references/ — Detailed reference documents loaded by each process phase
• assets/ — Sample outputs demonstrating realistic results

2. Write SKILL.md

Follow the structure in the template:

---
name: your-skill-name
description: Use when [trigger condition]. Provides [specific value].
---

Then include these sections:

• When to Use — List 2-4 specific trigger conditions
• Process — Numbered phases, each referencing a file in references/
• Output Requirements — What deliverables the skill produces
• Quick Reference — Table mapping scenarios to actions

3. Add References (2-3 minimum)

Each reference file in references/ should be:

• Self-contained and practical (not theoretical)
• Include copy-paste ready templates
• Provide actionable checklists

4. Add Sample Output

Place at least one sample output in assets/ that:

• Demonstrates a realistic scenario (not generic placeholder content)
• Follows the skill's own templates and output format
• Contains industry-specific content

Skill Quality Checklist

Before submitting, verify your skill meets these requirements:

Structure

• [ ] SKILL.md exists with valid YAML frontmatter
• [ ] name in frontmatter matches directory name (kebab-case)
• [ ] description includes trigger conditions
• [ ] SKILL.md is under 100 lines
• [ ] references/ directory contains detailed knowledge files
• [ ] assets/ directory contains sample outputs

Content

• [ ] Clear "When to Use" section with specific triggers
• [ ] Process section with numbered phases
• [ ] Each phase references an appropriate reference document
• [ ] Skip conditions defined where applicable
• [ ] Output requirements specified
• [ ] Quick reference table for common scenarios

Progressive Disclosure

• [ ] Level 1 (SKILL.md): Overview and navigation — enough to start
• [ ] Level 2 (references/): Detailed frameworks and checklists
• [ ] Level 3 (assets/): Examples and sample deliverables

Code Quality Standards

All contributions must follow shared/framework/rules/development-rules.md. Key rules:

Critical Rules (no exceptions)

1. No completion claims without verification evidence. Before saying "done", there must be actual output: build pass, test pass, or user confirmation.
2. No fixes without root cause investigation. Before fixing, you must understand WHY the error occurred. "Try replacing X and see" is not acceptable.

Standards

• File size: Keep files under 200 lines of content
• Naming: Use kebab-case for all directories and files
• Single responsibility: Each file should have one clear purpose
• No secrets: Never commit credentials, API keys, or .env files
• Clean code: Self-explanatory code; comments only for complex logic

Testing Your Skill

Before submitting a pull request, verify the following:

1. SKILL.md loads correctly — Ensure YAML frontmatter parses without errors and all sections are present
2. References are linked — Every Load: references/... directive in the process section points to an existing file
3. Sample output is realistic — The content in assets/ reflects a real-world scenario, not lorem ipsum
4. Progressive disclosure works — A user can start with just SKILL.md and go deeper into references as needed
5. Build passes — Run the project build and confirm no errors are introduced

Pull Request Guidelines

When submitting a PR:

• Descriptive title — Summarize the change in under 70 characters (e.g., "Add database-migration skill to framework")
• List files changed — Include a summary of all new and modified files
• How to test — Provide clear steps for reviewers to verify your changes
• Screenshots if applicable — For UI-related skills (e.g., ui-generation), include visual examples

Naming Conventions

Where to Put Things

Review Process

1. Automated quality checks — Your skill is validated against the checklist in shared/quality-checks/skill-checklist.md
2. Manual content review — A maintainer reviews for content quality, accuracy, and practical value
3. Structure review — Verify progressive disclosure (SKILL.md -> references -> assets) is well-organized
4. Merge — Once approved, the skill is merged and included in the next release