/contribute

name: contribute
description: "Guide for contributing to Trellis documentation and marketplace. Covers adding spec templates, marketplace skills, documentation pages, and submitting PRs across both the Trellis main repo and docs repo. Use when someone wants to add a new spec template, add a new skill to the marketplace, add or update documentation pages, or submit a PR to this project."

Contributing to Trellis

Contributions are split across two repos:

| What | Repo | Purpose | |------|------|---------| | Documentation pages | [mindfold-ai/docs](https://github.com/mindfold-ai/docs) | Mintlify doc site | | Skills + Spec templates | [mindfold-ai/Trellis](https://github.com/mindfold-ai/Trellis) | `marketplace/` directory |

Docs Repo Structure

docs/
├── docs.json              # Navigation config (MUST update for new pages)
│
├── index.mdx              # English homepage
├── quickstart.mdx         # English quickstart
├── zh/index.mdx           # Chinese homepage
├── zh/quickstart.mdx      # Chinese quickstart
│
├── guides/                # English guide pages
├── zh/guides/             # Chinese guide pages
│
├── templates/             # English template pages
├── zh/templates/          # Chinese template pages
│
├── skills-market/         # English skill marketplace pages
├── zh/skills-market/      # Chinese skill marketplace pages
│
├── blog/                  # English tech blog
├── zh/blog/               # Chinese tech blog
│
├── changelog/             # English changelog
├── zh/changelog/          # Chinese changelog
│
├── contribute/            # English contribution guide
├── zh/contribute/         # Chinese contribution guide
│
├── showcase/              # English showcase
└── zh/showcase/           # Chinese showcase

Trellis Main Repo Marketplace Structure

marketplace/
├── index.json             # Template registry (lists all available templates)
├── README.md              # Marketplace overview
├── specs/                 # Spec templates
│   └── electron-fullstack/
│       ├── README.md
│       ├── frontend/
│       ├── backend/
│       ├── guides/
│       └── shared/
└── skills/                # Skills
    └── trellis-meta/
        ├── SKILL.md
        └── references/

Understanding docs.json

The navigation uses a **language-based structure**:

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["index", "quickstart"]
          },
          {
            "group": "Guides",
            "pages": ["guides/specs", "guides/tasks", ...]
          },
          {
            "group": "Resource Marketplace",
            "pages": [
              {
                "group": "Skills",
                "expanded": false,
                "pages": ["skills-market/index", "skills-market/trellis-meta"]
              },
              {
                "group": "Spec Templates",
                "expanded": false,
                "pages": ["templates/specs-index", "templates/specs-electron"]
              }
            ]
          }
        ]
      },
      {
        "language": "zh",
        "groups": [
          // Same structure with zh/ prefix
        ]
      }
    ]
  }
}

**Key points**:

• English pages: no prefix (e.g., `guides/specs`)
• Chinese pages: `zh/` prefix (e.g., `zh/guides/specs`)
• Nested groups supported (e.g., Skills inside Resource Marketplace)
• `expanded: false` keeps groups collapsed by default

Contributing a Spec Template

Spec templates live in the **Trellis main repo** at `marketplace/specs/`.

1. Create template directory

marketplace/specs/your-template-name/
├── README.md              # Template overview (required)
├── frontend/              # Frontend guidelines
│   ├── index.md
│   └── ...
├── backend/               # Backend guidelines
│   ├── index.md
│   └── ...
├── guides/                # Thinking guides
│   └── ...
└── shared/                # Cross-cutting concerns (optional)
    └── ...

Structure varies by stack. Include directories relevant to your template.

2. Register in index.json

Add your template to `marketplace/index.json` in the Trellis repo:

{
  "id": "your-template-id",
  "type": "spec",
  "name": "Your Template Name",
  "description": "Brief description of the template",
  "path": "marketplace/specs/your-template-name",
  "tags": ["relevant", "tags"]
}

3. Create documentation pages (both languages, in docs repo)

**English**: `templates/specs-your-template.mdx` **Chinese**: `zh/templates/specs-your-template.mdx`

Use this frontmatter:

---
title: 'Your Template Name'
description: 'Brief description'
---

4. Update navigation in docs.json

Find the `Spec Templates` nested group and add your page:

{
  "group": "Spec Templates",
  "expanded": false,
  "pages": ["templates/specs-index", "templates/specs-electron", "templates/specs-your-template"]
}

Do the same for Chinese under `"language": "zh"`:

{
  "group": "Spec Templates",
  "expanded": false,
  "pages": [
    "zh/templates/specs-index",
    "zh/templates/specs-electron",
    "zh/templates/specs-your-template"
  ]
}

5. Update the overview page

Add your template to the table in:

• `templates/specs-index.mdx`
• `zh/templates/specs-index.mdx`

Contributing a Skill

Skills live in the **Trellis main repo** at `marketplace/skills/`.

1. Create skill directory

marketplace/skills/your-skill/
├── SKILL.md               # Skill definition (required)
└── references/            # Reference docs (optional)

See [Claude Code Skills documentation](https://code.claude.com/docs/en/skills) for SKILL.md format.

2. Register in index.json

Add your skill to `marketplace/index.json` in the Trellis repo:

{
  "id": "your-skill-id",
  "type": "skill",
  "name": "Your Skill Name",
  "description": "Brief description",
  "path": "marketplace/