Skip to main content

Fragments

A fragment is a reusable context snippet within a bundle. Fragments contain the actual content that gets sent to AI assistants.

Fragment Structure​

Fragments are defined within bundles:

fragments:
  coding-standards:
    tags: [python, style]
    content: |
      # Python Coding Standards
      - Use ruff for formatting and linting
      - Follow PEP 8 guidelines
      - Use type hints for function signatures

  error-handling:
    tags: [python, errors]
    content: |
      # Error Handling Patterns
      - Use specific exception types
      - Add context when re-raising exceptions
      - Log errors with appropriate levels

Using Fragments​

Include Specific Fragments​

# Include a specific fragment
scm run -f python-tools#fragments/coding-standards "review this code"

# Combine multiple fragments
scm run -f security#fragments/owasp -f python#fragments/errors "audit this code"

Include by Tag​

# Include all fragments with a tag
scm run -t security "check for vulnerabilities"

# Combine tags
scm run -t python -t security "review Python security"

Editing Fragments​

# Edit fragment content in your editor
scm bundle fragment edit my-bundle coding-standards

This opens the fragment content in your $VISUAL or $EDITOR.

Tags​

Tags help organize and filter fragments:

  • Bundle-level tags apply to all fragments in the bundle
  • Fragment-level tags are specific to that fragment
  • Use -t <tag> to include all fragments with a matching tag
# Bundle-level tags
tags:
  - python

fragments:
  # Fragment-level tags
  typing:
    tags: [typing, mypy]
    content: ...

Templating​

Fragments support Mustache templating for dynamic content.

Basic Variables​

fragments:
  project-context:
    variables: [PROJECT_NAME, LANGUAGE]  # Document required variables
    content: |
      # {{ PROJECT_NAME }} Development

      This {{ LANGUAGE }} project follows these standards:
      - Use standard formatting tools
      - Write tests for all new code

Variables are defined in profiles:

# .scm/profiles/my-project.yaml
variables:
  PROJECT_NAME: "my-api"
  LANGUAGE: "Go"
bundles:
  - my-standards

Conditional Sections​

Mustache supports conditional sections:

  • #VAR - renders section if VAR is truthy
  • ^VAR - renders section if VAR is falsy
  • /VAR - closes a section
## Deployment

{#USE_DOCKER}
### Docker Build
docker build -t app .
docker push registry/app
{/USE_DOCKER}

{#CI_PLATFORM}
CI/CD runs on {CI_PLATFORM}.
{/CI_PLATFORM}

{^USE_DOCKER}
Deploy directly without containerization.
{/USE_DOCKER}

Note: In actual YAML, use double braces: { becomes {{ and } becomes }}.

Built-in Variables​

These are always available:

VariableDescription
SCM_ROOTProject root directory
SCM_DIRPath to .scm directory
fragments:
  paths:
    content: |
      Project: {{ SCM_ROOT }}
      Config: {{ SCM_DIR }}/config.yaml

See the Templating Guide for complete syntax and advanced features.

Distillation​

Fragments can be distilled (AI-compressed) to reduce token usage. See the Distillation Guide for details.

fragments:
  verbose-guide:
    content: |
      [Long, detailed content...]
    distilled: |
      [AI-compressed version...]
    content_hash: "sha256:abc123..."
    no_distill: false  # Set true to prevent distillation