mcs-cli/mcs/techpack-creator

TechPack Creator

You analyze repositories that already have Claude Code configuration and package them into MCS tech packs for distribution. A tech pack is a Git-distributable bundle of Claude Code configuration — MCP servers, hooks, skills, commands, agents, templates, and settings — defined in a single techpack.yaml manifest that the mcs CLI syncs and maintains.

Two approaches — choose based on what's available:

1. `mcs export` first (recommended when MCS is installed): Run mcs export ./pack-output to

capture the live Claude Code configuration as a starting point. Then review and improve the generated techpack.yaml — add brew components for runtimes, add prompts for env vars, add doctor checks, and wire up templates. This is the fastest path when the user already has a working Claude Code session.

1. Direct scan (when no live config or MCS is not installed): Analyze the repo's files and

directory structure directly — read hook scripts, skill directories, command files, settings JSON, CLAUDE.md content, and project manifests to understand what the repo provides. Generate the techpack.yaml and supporting files from scratch.

Both approaches produce the same output: a complete pack directory ready for mcs pack add.

Bundled references (read on demand, not upfront):

• references/techpack-schema.md — Complete field-by-field schema for techpack.yaml
• references/stack-detection.md — File-to-stack mapping and component recommendations
• references/examples/ — Realistic example techpacks (swift-ios.yaml, node-web.yaml, python-ml.yaml)

Remote documentation — use these for the latest info and link them in generated READMEs:

• MCS CLI: https://github.com/mcs-cli/mcs
• Schema reference: https://github.com/mcs-cli/mcs/blob/main/docs/techpack-schema.md
• Creating tech packs guide: https://github.com/mcs-cli/mcs/blob/main/docs/creating-tech-packs.md
• Claude Code hooks: https://code.claude.com/docs/en/hooks
• MCS CLI reference: https://github.com/mcs-cli/mcs/blob/main/docs/cli.md
• MCS troubleshooting: https://github.com/mcs-cli/mcs/blob/main/docs/troubleshooting.md

If the bundled references are unavailable (skill installed without reference files), fetch the remote documentation using WebFetch on the URLs above. The remote docs are the canonical source of truth.

Workflow

First, determine which approach to use:

• If the user has MCS installed and a working Claude Code session → start with `mcs export`:

``bash mcs export ./pack-output # project-scoped config mcs export ./pack-output --global # global-scoped config ` Then review the generated techpack.yaml` and improve it (add runtime brew components, prompts, doctor checks, templates). Skip to Phase 3 (Propose) with the export output as your starting point.

• If no live config is available → follow the full 5-phase workflow below.

Follow these 5 phases in order. Never skip the Propose phase.

Phase 1: Scan

Analyze the target directory.

Existing Claude Code config — this is the PRIMARY source of truth. Scan first:

• .claude/hooks/* — existing hook scripts (read each one to understand its event and purpose)
• .claude/skills/*/SKILL.md — existing skills (read frontmatter for name, description)
• .claude/commands/*.md — existing slash commands
• .claude/agents/*.md — existing subagents
• .claude/settings.json, .claude/settings.local.json — existing settings (permissions, env vars, hooks config)
• .claude.json — existing MCP server registrations
• CLAUDE.md, CLAUDE.local.md — existing instructions (extract sections for templates)

Settings cross-reference — read settings.json/settings.local.json to map hooks to events:

{"hooks": {"SessionStart": [{"command": "bash .claude/hooks/session_start.sh"}]}}

This tells you which hook file maps to which event — critical for the hookEvent field. The command is <interpreter> <path>: everything before the path is the interpreter, so node --experimental-strip-types .claude/hooks/gate.ts becomes hookInterpreter: node --experimental-strip-types. Omit hookInterpreter when it is plain bash or matches what the extension already implies.

Project manifests — detect language and dependencies: Package.swift, *.xcodeproj, *.xcworkspace, package.json, tsconfig.json, Cargo.toml, go.mod, Gemfile, requirements.txt, pyproject.toml, setup.py, Pipfile, build.gradle, build.gradle.kts, pom.xml, composer.json, pubspec.yaml, CMakeLists.txt, *.csproj, *.sln

Configuration files — detect tooling: .eslintrc*, .prettierrc*, biome.json, .swiftlint.yml, .swiftformat, rustfmt.toml, .rubocop.yml, .flake8, ruff.toml, docker-compose.yml, Dockerfile, .github/workflows/*.yml, Fastfile, .env, .env.example

Repository metadata: README.md, LICENSE, git remote URL

Consult references/stack-detection.md for additional file-to-stack mapping recommendations.

Phase 2: Detect

Build a detection report from scan results:

## Detection Report
 
**Repository**: {name}
**Primary language**: {language}
**Framework(s)**: {frameworks}
**Package manager(s)**: {managers}
**Build system**: {build system}
**Existing Claude Code config**: {yes/no, summary}
 
### Recommended Components
| Component | Type | Rationale |
|-----------|------|-----------|
| node      | brew | Required by MCP servers using npx |
| ...       | ...  | ... |
 
### Recommended Prompts
| Key | Type | Rationale |
|-----|------|-----------|
| API_KEY | input | Found in .env.example |
| ...     | ...   | ... |
 
### Recommended Templates
| Section | Content | Rationale |
|---------|---------|-----------|
| build-test | Build & test commands | Detected from package.json scripts |
| ...        | ...                   | ... |

Phase 3: Propose

Present the detection report. Ask for confirmation before generating:

1. Show the detection report and ask if the user wants to proceed or modify
2. Ask for the pack identifier (suggest one based on repo name — lowercase, hyphens only)
3. Ask for the display name and author (suggest from git config)
4. Confirm the output directory (default: current directory)

Do NOT generate files without explicit user confirmation.

Phase 4: Generate

Read references/techpack-schema.md now for the complete schema. If the bundled reference is unavailable, fetch the remote version: https://github.com/mcs-cli/mcs/blob/main/docs/techpack-schema.md

Generate the pack directory:

{pack-name}/
  techpack.yaml          # Main manifest
  README.md              # Installation instructions
  hooks/                 # Hook scripts (if any)
  templates/             # Template markdown files (if any)
  config/                # Settings JSON (if any)
  commands/              # Slash command files (if any)
  skills/                # Skill directories (if any)
  agents/                # Agent files (if any)
  scripts/               # Configure scripts (if any)

YAML Generation Rules

1. Always use shorthand syntax — brew: node not verbose type/installAction
2. schemaVersion must be 1
3. identifier: lowercase alphanumeric + hyphens, no leading hyphen
4. Component IDs: short names, NO dots (MCS auto-prefixes with <pack-id>.)
5. YAML field ordering:

• Root: schemaVersion → identifier → displayName → description → author → prompts → components → templates → supplementaryDoctorChecks → configureProject → ignore
• Components grouped: brew first → MCP servers → hooks → skills → commands → agents → settings → gitignore
• Each component: id → displayName → description → hookEvent/hookMatcher/hookTimeout/hookAsync/hookStatusMessage/hookInterpreter → shorthand key

1. Runtimes as components: npx MCP servers need a brew: node component, uvx/python servers need python, hooks using jq need jq. Install order is declaration order, so list what a component needs before it. Never write dependencies: or isRequired: — both are deprecated and ignored; a pack always installs every component
2. MCP scope: default to local (per-user, per-project isolation)
3. Prompts before components in the YAML for readability
4. Placeholders: __UPPER_SNAKE__ format. Every __KEY__ used in templates/settings MUST have a matching prompt
5. Populate `ignore:` for non-material paths: When the source repo contains docs/, examples/, design assets, screenshots, or any directories not referenced by a component/template, add them to a top-level ignore: list (POSIX globs, trailing / silences the directory tree). This silences mcs pack validate unreferenced-file warnings AND stops downstream "pack update available" notifications from firing on doc/CI commits. Never put techpack.yaml or referenced paths in ignore: — mcs pack validate rejects those. Example: ignore: [docs/, examples/, diagrams/*.png].

Hook Script Template

Hooks are not bash-only. The interpreter follows the file extension (.js/.mjs → node, .py → python3, .rb → ruby, .sh/no extension → bash); declare hookInterpreter for anything else, including arguments (node --experimental-strip-types, uv run). TypeScript infers nothing — always declare it there. Prefer bash when the logic is simple: it is the one runtime guaranteed to exist. Whatever the language, declare a brew component for the runtime and fail open on every error path.

Every hook script must follow this defensive pattern (hooks must NEVER crash the session):

#!/bin/bash
set -euo pipefail
trap 'exit 0' ERR
 
# {description}
# Hook event: {event}
 
# Fail gracefully if dependencies are missing
command -v {tool} >/dev/null 2>&1 || exit 0
 
# Read and validate JSON input from stdin (required for most hooks)
input_data=$(cat) || exit 0
echo "$input_data" | jq '.' >/dev/null 2>&1 || exit 0
 
# ... hook logic ...

SessionStart hooks that produce output must emit the hookSpecificOutput JSON contract:

jq -n --arg ctx "$context" '{
    hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: $ctx }
}'

UserPromptSubmit hooks can print plain text to stdout — it appears as a system reminder.

Two hooks can share one source file when they need the same logic for different events (e.g., SessionStart + UserPromptSubmit both running a sync/reindex script).

Template Content

Templates should be concise, actionable CLAUDE.local.md instructions:

## {Section Title}
 
{2-5 lines of project-specific context}
 
### Build & Test
-`{build command}` — build the project
-`{test command}` — run tests
 
### Conventions
-{convention from detected linter/formatter config}

Settings File

Always include baseline settings in config/settings.json:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Add env vars only when detected from .env.example or similar — use __KEY__ placeholders with matching prompts.

README.md

Generate a README with:

• Pack description
• Prerequisites (list brew dependencies)
• Installation: mcs pack add <github-user>/<repo> (or mcs pack add /path/to/pack for local)
• What it installs (component summary table)
• Configuration (prompt descriptions — what the user will be asked during mcs sync)
• Validation: mcs pack validate <path>
• Links to MCS documentation:
• MCS CLI: https://github.com/mcs-cli/mcs
• Schema: https://github.com/mcs-cli/mcs/blob/main/docs/techpack-schema.md
• Guide: https://github.com/mcs-cli/mcs/blob/main/docs/creating-tech-packs.md
• Troubleshooting: https://github.com/mcs-cli/mcs/blob/main/docs/troubleshooting.md

Phase 5: Validate

After generating, run mcs pack validate {path} if mcs is installed and fix what it reports. Without it, self-check: