contributor

name	contributor
description	Contributing to skillet itself. Covers architecture, development setup, testing, and PR workflow.
version	2026.02.27
trigger	Use when the user wants to contribute to skillet, understand its architecture, or run its test suite
license	MIT OR Apache-2.0
author	Josh Rotenberg
categories	["development","tools"]
tags	["skillet","contributing","rust","architecture","testing"]

Contributing to Skillet

Architecture

Skillet is a single Rust binary (skillet) that serves as both CLI and MCP server. Package name is skillet-mcp, binary name is skillet.

Module map:

src/
  main.rs        # CLI (clap), MCP server setup
  lib.rs         # Library root, re-exports
  state.rs       # AppState, SkillIndex, SkillEntry, SkillVersion, SkillMetadata
  index.rs       # Directory walking, SKILL.md/frontmatter parsing, config loading
  search.rs      # SkillSearch: BM25 full-text search over skill metadata
  bm25.rs        # Vendored BM25 engine
  cache.rs       # Persistent disk cache for SkillIndex
  config.rs      # Configuration loading (SkilletConfig)
  error.rs       # Error types (thiserror)
  git.rs         # Git operations: clone, pull, head
  prompts.rs     # DynamicPromptRegistry integration, skills as MCP prompts
  project.rs     # skillet.toml unified manifest types and loading
  repo.rs        # Repo management: init, load, merge
  resolve.rs     # Release model resolution (tags/releases/main)
  scaffold.rs    # init-skill, init-registry, init-project scaffolding
  suggest.rs     # [[suggest]] decentralized discovery graph walker
  tools/         # MCP tools: search_skills, list_categories, etc.

Key types:

• AppState -- holds RwLock<SkillIndex>, RwLock<SkillSearch>, repo paths, config
• SkillIndex -- maps (owner, name) to SkillEntry with merge() for multi-repo
• SkillSearch -- wraps BM25 index, rebuilt on refresh
• SkillSource -- variants: Registry, Embedded

Data flow: repos (local/remote) are loaded into SkillIndex, merged first-match-wins, then SkillSearch is built from the merged index. MCP tools query the search index; skills are served as MCP prompts.

Development Setup

git clone https://github.com/joshrotenberg/skillet.git
cd skillet
cargo build
cargo test --lib --all-features

Running Tests

The test suite is organized across multiple files:

# Unit tests (in src/)
cargo test --lib --all-features

# CLI integration tests
cargo test --test cli --all-features

# Scenario tests (multi-step workflows)
cargo test --test scenarios --all-features

# MCP integration tests
cargo test --test mcp --all-features

# HTTP transport tests
cargo test --test http --all-features

# All tests
cargo test --test '*' --all-features

Test fixtures are dynamically generated via testutil.rs.

Pre-commit Checklist

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --lib --all-features
cargo test --test '*' --all-features

PR Workflow

1. Create a feature branch: git checkout -b feat/description
2. Make changes, run the pre-commit checklist
3. Commit with conventional format: feat: add thing, fix: resolve issue
4. Push and open a PR against main
5. Ensure CI passes (fmt, clippy, all tests)

Branch naming conventions:

• feat/ -- new features
• fix/ -- bug fixes
• refactor/ -- code refactoring
• test/ -- test improvements
• docs/ -- documentation

Design Principles

• Tool-first: skillet is the tool, repos are data
• Zero-config-first: only SKILL.md is truly required
• Frontmatter-primary: metadata lives in SKILL.md YAML frontmatter
• Owner/name namespacing: owner/skill-name directories
• Git-backed: repos are git repos, auditable by default