Agent skill

contribute

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.

View SKILL.md on GitHub Repository

Stars 5,124

Forks 287

Install this agent skill to your Project

npx add-skill https://github.com/mindfold-ai/Trellis/tree/main/.claude/skills/contribute

SKILL.md

Contributing to Trellis

Contributions are split across two repos:

What	Repo	Purpose
Documentation pages	mindfold-ai/docs	Mintlify doc site
Skills + Spec templates	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:

json

{
  "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:

json

{
  "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:

yaml

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

4. Update navigation in docs.json

Find the Spec Templates nested group and add your page:

json

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

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

json

{
  "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 for SKILL.md format.

2. Register in index.json

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

json

{
  "id": "your-skill-id",
  "type": "skill",
  "name": "Your Skill Name",
  "description": "Brief description",
  "path": "marketplace/skills/your-skill",
  "tags": ["relevant", "tags"]
}

3. Create documentation pages (in docs repo)

English: skills-market/your-skill.mdx Chinese: zh/skills-market/your-skill.mdx

4. Update navigation in docs.json

Find the Skills nested group and add your page to both languages.

5. Update the overview page

Add your skill to the table in:

skills-market/index.mdx
zh/skills-market/index.mdx

Installation

Users install skills via:

bash

npx skills add mindfold-ai/Trellis/marketplace -s your-skill

Contributing a Showcase Project

1. Copy the template

bash

cp showcase/template.mdx showcase/your-project.mdx
cp zh/showcase/template.mdx zh/showcase/your-project.mdx

2. Fill in project details

Update sidebarTitle with your project name
Add project description
Replace GitHub OG image URL with your repo
Describe how you used Trellis

3. Update navigation in docs.json

Find the Showcase / 项目展示 group and add your page:

json

{
  "group": "Showcase",
  "expanded": false,
  "pages": ["showcase/index", "showcase/open-typeless", "showcase/your-project"]
}

Do the same for Chinese.

4. Add Card to overview page

Add a Card component to display your project:

English (showcase/index.mdx):

mdx

<Card title="Project Name" icon="icon-name" href="/showcase/your-project">
  One-line description
</Card>

Chinese (zh/showcase/index.mdx):

mdx

<Card title="项目名" icon="icon-name" href="/zh/showcase/your-project">
  一句话描述
</Card>

Contributing Documentation

Adding a new guide

Create the page in guides/your-guide.mdx
Create Chinese version in zh/guides/your-guide.mdx
Update docs.json - add to Guides group in both languages

Adding a blog post

Create the page in blog/your-post.mdx
Create Chinese version in zh/blog/your-post.mdx
Update docs.json - add to Tech Blog group in both languages

Updating existing pages

Find the file in the appropriate directory
Make your changes
Ensure both language versions stay in sync

Bilingual Requirements

All user-facing content must have both English and Chinese versions.

Content Type	English Path	Chinese Path
Homepage	`index.mdx`	`zh/index.mdx`
Guides	`guides/*.mdx`	`zh/guides/*.mdx`
Templates	`templates/*.mdx`	`zh/templates/*.mdx`
Skills	`skills-market/*.mdx`	`zh/skills-market/*.mdx`
Showcase	`showcase/*.mdx`	`zh/showcase/*.mdx`
Blog	`blog/*.mdx`	`zh/blog/*.mdx`
Changelog	`changelog/*.mdx`	`zh/changelog/*.mdx`

Development Setup

bash

# Install dependencies
pnpm install

# Start local dev server
pnpm dev

# Check markdown lint
pnpm lint:md

# Verify docs structure
pnpm verify

# Format files
pnpm format

Pre-commit hooks: The project uses husky with lint-staged. On commit:

Markdown files are auto-linted and formatted
verify-docs.py checks docs.json and frontmatter

MDX Components

Mintlify supports MDX components. Common ones:

mdx

<Card title="Title" icon="download" href="/path">
  Card content here
</Card>

<CardGroup cols={2}>
  <Card>...</Card>
  <Card>...</Card>
</CardGroup>

<Accordion title="Click to expand">Hidden content</Accordion>

<AccordionGroup>
  <Accordion>...</Accordion>
</AccordionGroup>

Inline HTML is allowed (MDX). See Mintlify docs for all components.

Submitting a PR

For documentation changes (docs repo):

Fork: https://github.com/mindfold-ai/docs
Clone: git clone https://github.com/YOUR_USERNAME/docs.git
Install: pnpm install
Branch: git checkout -b feat/your-contribution
Make changes following this guide
Test: pnpm dev
Commit with conventional message (e.g., docs: add xxx template)
Push and create PR

For skills/spec templates (Trellis repo):

Fork: https://github.com/mindfold-ai/Trellis
Clone: git clone https://github.com/YOUR_USERNAME/Trellis.git
Add your skill/template under marketplace/
Update marketplace/index.json
Push and create PR

Checklist Before PR

Both EN and ZH versions created (for doc pages)
docs.json updated for both languages (for doc pages)
marketplace/index.json updated (for skills/templates)
Overview/index pages updated with new entries
Local preview tested (pnpm dev)
No broken links
Code blocks have correct language tags
Frontmatter includes title and description
Images placed in images/ directory (if any)

Maintainer

mindfold-ai Core maintainer

Source details

Full Name: mindfold-ai/Trellis
Branch: main
Path in repo: .claude/skills/contribute
License: GNU Affero General Public License v3.0
Topics: agentic-coding claudecode codex ai-workflow harness

Featured Tools

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

mindfold-ai/Trellis

create-command

Scaffolds a new skill file with proper naming conventions and structure. Analyzes requirements to determine skill type and generates appropriate content. Use when adding a new developer workflow skill, creating a custom skill, or extending the Trellis skill set.

5,124 287

Explore

mindfold-ai/Trellis

finish-work

Pre-commit quality checklist covering lint, typecheck, tests, code-spec sync, API changes, database migrations, cross-layer verification, and manual testing. Blocks commit if infra or cross-layer specs lack executable depth. Use when code is written and tested but not yet committed, before submitting changes, or as a final review before git commit.

5,124 287

Explore

mindfold-ai/Trellis

update-spec

Captures executable contracts and coding knowledge into .trellis/spec/ documents after implementation, debugging, or design decisions. Enforces code-spec depth for infra and cross-layer changes with mandatory sections for signatures, contracts, validation matrices, and test points. Use when a feature is implemented, a bug is fixed, a design decision is made, a new pattern is discovered, or cross-layer contracts change.

5,124 287

Explore

mindfold-ai/Trellis

check

Validates recently written code against project-specific development guidelines from .trellis/spec/. Identifies changed files via git diff, discovers applicable spec modules, runs lint and typecheck, and reports guideline violations. Use when code is written and needs quality verification, to catch context drift during long sessions, or before committing changes.

5,124 287

Explore

mindfold-ai/Trellis

check-cross-layer

Post-implementation verification across multiple code dimensions: cross-layer data flow, code reuse analysis, import path validation, and same-layer consistency checks. Identifies missed update sites, type mismatches, and duplicated constants. Use when changes span 3+ architectural layers, after modifying shared constants or configs, after batch file modifications, or when creating new utility functions.

5,124 287

Explore

mindfold-ai/Trellis

start

Initializes an AI development session by reading workflow guides, developer identity, git status, active tasks, and project guidelines from .trellis/. Classifies incoming tasks and routes to brainstorm, direct edit, or task workflow. Use when beginning a new coding session, resuming work, starting a new task, or re-establishing project context.

5,124 287

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

Contributing to Trellis

Docs Repo Structure

Trellis Main Repo Marketplace Structure

Understanding docs.json

Contributing a Spec Template

1. Create template directory

2. Register in index.json

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

4. Update navigation in docs.json

5. Update the overview page

Contributing a Skill

1. Create skill directory

2. Register in index.json

3. Create documentation pages (in docs repo)

4. Update navigation in docs.json

5. Update the overview page

Installation

Contributing a Showcase Project

1. Copy the template

2. Fill in project details

3. Update navigation in docs.json

4. Add Card to overview page

Contributing Documentation

Adding a new guide

Adding a blog post

Updating existing pages

Bilingual Requirements

Development Setup

MDX Components

Submitting a PR

Checklist Before PR

Recommended Agent Skills

create-command

finish-work

update-spec

check

check-cross-layer

start