Component Types¶

This page documents each component type that a package can contain: the manifest format, file format, and how the component is installed.

Practices (v2)¶

Practices are abstract declarations of coding standards. They are the primary component type in v2 packages and are processed by AI during extraction and installation.

v2 Manifest Entry¶

practices:
  - name: type-safety
    intent: Enforce strict type annotations
    principles:
      - All functions must have type hints
      - Use modern syntax (list[str] not List[str])
    enforcement_patterns:
      - Run mypy in strict mode
    examples:
      - "def process(items: list[str]) -> int: ..."
    tags: [python, types]

How Practices Are Installed¶

With AI enabled, practices are adapted to the target project's existing rules:

• If no existing rule covers the same topic, a new file is created
• If an existing rule overlaps, the AI merges the practice into it
• Each IDE gets its own adapted version in the correct format

Without AI (--no-ai), the raw practice content is written as a markdown file to each tool's directory.

Instructions (v1)¶

Instructions are Markdown files that guide AI coding assistant behavior. They are the v1 equivalent of practices -- raw file content rather than abstract declarations.

Manifest Entry¶

components:
  instructions:
    - name: code-quality
      file: instructions/code-quality.md
      description: Code quality and review guidelines
      tags: [quality, review]

Installation Paths¶

MCP Servers¶

MCP (Model Context Protocol) server configurations define external tool integrations. Each MCP component is a JSON file that tells the IDE how to launch and connect to an MCP server.

v2 Manifest Entry¶

mcp_servers:
  - name: github
    description: GitHub API access
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    credentials:
      - name: GITHUB_TOKEN
        description: GitHub personal access token
        required: true

v1 Manifest Entry¶

components:
  mcp_servers:
    - name: filesystem
      file: mcp/filesystem.json
      description: Local filesystem access via MCP
      credentials:
        - name: ALLOWED_DIRECTORIES
          description: Directories to expose
          required: false
          default: "."

Credential Descriptors¶

Each credential entry describes an environment variable:

Supported IDEs¶

Claude Code, Cursor, Windsurf, Roo Code, GitHub Copilot, and others. See IDE Compatibility.

Hooks¶

Hooks are shell scripts triggered by IDE lifecycle events. Currently, only Claude Code supports hooks.

Manifest Entry¶

components:
  hooks:
    - name: pre-commit
      file: hooks/pre-commit.sh
      description: Run linting before commits
      hook_type: pre-commit

Installation Path¶

Commands¶

Commands are shell scripts or slash commands that users invoke on demand.

Manifest Entry¶

components:
  commands:
    - name: test
      file: commands/test.sh
      description: Run test suite with coverage
      command_type: shell

Installation Paths¶

Resources¶

Resources are arbitrary files -- configuration templates, .gitignore files, editor configs, or any other file that should be part of the project setup.

Manifest Entry¶

components:
  resources:
    - name: gitignore
      file: resources/.gitignore
      description: Python-specific gitignore
      install_path: .gitignore
      checksum: sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
      size: 450

Resources are copied verbatim (both text and binary files are supported).