Claude Skill

scope

Guide for working with Scope, a developer environment management tool that automates environment checks, detects known errors, and provides automated fixes. Use when creating Scope configurations (ScopeKnownError, ScopeDoctorGroup, ScopeReportLocation), debugging environment issu

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download technicalpickles-pickled-claude-plugins-plugins_dev-tools_skills_working-with-scope-8d13327.zip · 19 KB

Install

skills CLI npx skills add https://github.com/technicalpickles/pickled-claude-plugins/tree/main/plugins/dev-tools/skills/working-with-scope
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install technicalpickles-pickled-claude-plugins@llmmart
Git git clone https://github.com/technicalpickles/pickled-claude-plugins.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole technicalpickles/pickled-claude-plugins collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Scope - Developer Environment Management

Scope is a DevEx tool that helps maintain consistent development environments through automated checks, error detection, and fixes.

Core Commands

scope doctor

Run automated environment checks and fixes.

scope doctor run                   # Run all checks
scope doctor run --only group-name # Run specific group
scope doctor run --fix=false       # Check only, no fixes
scope doctor run --no-cache        # Disable caching
scope doctor list                  # List available checks

scope analyze

Detect known errors in logs or command output.

scope analyze logs file.log                # Analyze log file
scope analyze command -- cmd args          # Analyze command output
scope analyze --extra-config path file.log # Use additional configs

scope report

Generate bug reports with automatic secret redaction.

scope report ./script.sh     # Run and report on script
scope report -- command args # Run and report on command

scope-intercept

Monitor script execution in real-time (used as shebang).

#!/usr/bin/env scope-intercept bash
# Script content here

Configuration Resources

All Scope configurations use Kubernetes-inspired YAML format:

apiVersion: scope.github.com/v1alpha
kind: <ResourceType>
metadata:
  name: unique-identifier
  description: Human-readable description
spec:
  # Resource-specific configuration

ScopeKnownError

Define error patterns and provide automated help/fixes for common issues.

Structure

apiVersion: scope.github.com/v1alpha
kind: ScopeKnownError
metadata:
  name: descriptive-error-name
  description: Brief description of what this error means
spec:
  pattern: 'regex pattern to match the error'
  help: |
    Clear explanation of the issue.

    Steps to resolve:
    1. First step
    2. Second step
    3. Where to get help if needed
  fix:
    prompt:
      text: User-friendly prompt asking permission
    commands:
      - first-fix-command
      - second-fix-command

Key Fields

  • pattern: Regex pattern using ripgrep syntax to match error text
  • help: Multi-line markdown explanation with resolution steps
  • fix (optional): Automated remediation configuration
    • commands: List of commands to run to fix the error (required)
    • helpText: Descriptive text shown if the fix fails (optional)
    • helpUrl: Documentation link for manual resolution (optional)
    • prompt: User approval before running fix (optional)
      • text: Question asking for user permission
      • extraContext: Additional context about what the fix does and why approval is needed

Note: When a fix is defined, it only runs when the error pattern is detected. The fix is optional - if not provided, only the help text is shown.

File Organization

Place files in categorized directories:

  • Location: {config-root}/known-errors/{category}/{error-name}.yaml
  • Common categories: docker/, ruby/, git/, github/, mysql/, postgres/, dns/, aws/
  • Include matching .txt file with example error for testing

Example

apiVersion: scope.github.com/v1alpha
kind: ScopeKnownError
metadata:
  name: gem-missing-file
  description: A gem source file is missing and fails to be loaded
spec:
  pattern: "/lib/ruby/.* `require': cannot load such file --.*/lib/ruby/gems/.*(LoadError)"
  help: |
    A gem source file is missing. The solution is to reinstall the gems:
    1. Run `bundle pristine`
  fix:
    commands:
      - bundle pristine
    helpText: |
      Bundle pristine failed. Try these steps:
      1. Check your bundle config: bundle config list
      2. Reinstall bundler: gem install bundler
      3. Contact #help-ruby if issues persist
    helpUrl: https://bundler.io/man/bundle-pristine.1.html
    prompt:
      text: |-
        This will reinstall all gems from your Gemfile.
        Do you wish to continue?
      extraContext: >-
        bundle pristine reinstalls gems without changing versions,
        which resolves missing file errors but preserves your lock file

Validation

Validate schema structure:

brew install sourcemeta/apps/jsonschema
jsonschema validate schema.json known-error.yaml

Test pattern matching:

scope analyze logs --extra-config config-dir/ test-error.txt

Additional Resources

Pattern Writing Tips

  • Use ripgrep regex syntax (similar to PCRE)
  • Escape special characters: \\., \\[, \\(
  • Use character classes: [[:digit:]], [[:alpha:]]
  • Test patterns: echo "error text" | rg "pattern"
  • Balance specificity vs flexibility to avoid false positives/negatives

ScopeDoctorGroup

Define environment setup and maintenance checks with automated fixes.

Structure

apiVersion: scope.github.com/v1alpha
kind: ScopeDoctorGroup
metadata:
  name: tool-name
  description: Brief description of what this group does
spec:
  include: when-required # or "by-default"
  needs:
    - dependency-1
    - dependency-2
  actions:
    - name: action-name
      description: What this action checks/fixes
      required: true # default true; false for optional checks
      check:
        paths:
          - 'file-to-watch.txt'
          - '**/*.config'
        commands:
          - ./bin/check-script.sh
      fix:
        commands:
          - ./bin/fix-script.sh
        helpText: |
          What to do if the fix fails.
          Where to get help.
        helpUrl: https://docs.example.com/help

Key Components

Include Modes

  • by-default: Always runs with scope doctor run
  • when-required: Only runs when explicitly specified or as dependency

Dependencies

List other groups that must run first in needs array. Creates execution graph.

Actions

Each action is an atomic check/fix operation that runs in order.

Check Logic

Determines if fix should run. Fix runs when:

  • No check defined: Fix always runs
  • paths specified: Any file changed or no files match globs
  • commands specified: Any command exits non-zero
  • Both can be combined (OR logic)

Fix Section

  • commands: List of commands to run in order
  • helpText: Shown if fix fails (markdown supported)
  • helpUrl: Optional link to documentation

File Organization

  • Application setup: {config-root}/application/
  • Environment setup: {config-root}/environment/
  • Project-specific: .scope/ in project root

Example

apiVersion: scope.github.com/v1alpha
kind: ScopeDoctorGroup
metadata:
  name: ruby-version
  description: Set up Ruby with correct version
spec:
  include: when-required
  needs:
    - ruby-manager
    - homebrew
  actions:
    - name: install
      description: Ensures correct version of ruby is installed
      check:
        paths:
          - '{{ working_dir }}/.ruby-version'
        commands:
          - ./bin/ruby-version.sh verify
      fix:
        commands:
          - ./bin/ruby-version.sh install
        helpText: |
          Ruby installation failed.
          Contact: #help-channel

Script Conventions

Create helper scripts following check/fix pattern:

#!/usr/bin/env bash
set -euo pipefail

ACTION="${1:-check}"

check() {
  # Return 0 if check passes, non-zero if fix needed
  if [[ condition ]]; then
    echo "Check passed"
    return 0
  else
    echo "Check failed" >&2
    return 1
  fi
}

fix() {
  # Perform fix, return 0 on success
  echo "Running fix..."
  # Fix commands here
  return 0
}

case "$ACTION" in
  check) check ;;
  fix) fix ;;
  *)
    echo "Usage: $0 [check|fix]" >&2
    exit 1
    ;;
esac

Script best practices:

  • Use relative paths with ./ prefix (relative to YAML file)
  • Make scripts idempotent (safe to run multiple times)
  • Exit 0 for success, non-zero for failure
  • Write errors to stderr
  • Include helpful error messages

Caching

File-based checks use content hashing:

  • Cache stores file path and content hash
  • Only re-runs if file contents change
  • Persists between runs
  • Disable with --no-cache

ScopeReportLocation

Configure where and how bug reports are uploaded.

GitHub Issues

apiVersion: scope.github.com/v1alpha
kind: ScopeReportLocation
metadata:
  name: github
spec:
  destination:
    githubIssue:
      owner: org-name
      repo: repo-name
  additionalData:
    nodeVersion: node -v
    rubyPath: which ruby

Authentication via environment variables:

  • GitHub App: SCOPE_GH_APP_ID + SCOPE_GH_APP_KEY
  • Personal Access Token: SCOPE_GH_TOKEN

Local File System

apiVersion: scope.github.com/v1alpha
kind: ScopeReportLocation
metadata:
  name: local
spec:
  destination:
    local:
      directory: /tmp/scope-reports
  additionalData:
    pwd: pwd
    username: id -un
    scopeVersion: scope version

RustyPaste

apiVersion: scope.github.com/v1alpha
kind: ScopeReportLocation
metadata:
  name: rustypaste
spec:
  destination:
    rustyPaste:
      url: http://localhost:8000

Additional Data

Capture environment context with arbitrary commands:

additionalData:
  diskSpace: df -h
  gitBranch: git branch --show-current
  envVars: env | sort

Commands execute at report generation time. Scope automatically redacts secrets.

Common Patterns

Version checks, file-exists checks, service health, dependency installs, and path-triggered auto-run each have a ready YAML snippet in references/quick-reference.md ("Common Patterns"). An orchestration group is a ScopeDoctorGroup whose needs: lists other groups and whose actions: is empty.

Workflow: Creating a Known Error

A known error is a YAML definition plus a .txt file of real error output, side by side under {config-root}/known-errors/{category}/. It's done when scope analyze logs --extra-config {config-root} <the .txt> matches the sample and jsonschema validate schema.json <the .yaml> passes.

Workflow: Creating a Doctor Group

A doctor group is a YAML file in {config-root}/application/, {config-root}/environment/, or .scope/ (project-specific), plus any helper scripts under .scope/bin/, referenced by relative path and executable. Add it to its parent group's needs if it's a new dependency. It's done when scope doctor list shows it and scope doctor run --only <name> passes with and without --no-cache.

Debugging

See "Debugging Checklist" in references/quick-reference.md. The usual causes: a regex that needs escaping (test with rg "pattern" file), paths globs that match nothing, check commands that don't exit 0 on success, stale cache (--no-cache), non-executable scripts, script paths not relative to the YAML (./ prefix), and needs naming a missing group (scope doctor list shows order).

Security Features

Automatic Redaction

Scope automatically redacts sensitive information:

  • GitHub API tokens
  • AWS credentials
  • SSH keys
  • Environment variable values containing secrets
  • Uses patterns from ripsecrets

This makes it safe to capture full environment in reports and share debug output publicly.

Reference

Configuration Structure

config-repository/
├── {config-root}/
│   ├── application/          # App-level (ruby, node, postgres)
│   ├── environment/          # System-level (homebrew, docker, github)
│   ├── known-errors/         # Error definitions by category
│   │   ├── docker/
│   │   ├── ruby/
│   │   ├── git/
│   │   └── ...
│   └── reports/              # Report locations

Additional Resources

See references directory for:

  • quick-reference.md - Command cheat sheet and pattern examples
  • real-world-examples.md - Production-tested configurations
  • testing-guide.md - Comprehensive validation workflows
Files (pickled-claude-plugins)
  • references
    • quick-reference.md 7.7 KB
      Loading…
    • real-world-examples.md 14.6 KB
      Loading…
    • testing-guide.md 13 KB
      Loading…
  • scripts
    • create-doctor-group.sh 4.6 KB
      Loading…
    • create-known-error.sh 2.8 KB
      Loading…
  • SKILL.md 12.3 KB
    ---
    name: scope
    description: Guide for working with Scope, a developer environment management tool that automates environment checks, detects known errors, and provides automated fixes. Use when creating Scope configurations (ScopeKnownError, ScopeDoctorGroup, ScopeReportLocation), debugging environment issues, or writing rules for error detection and remediation.
    ---
    
    # Scope - Developer Environment Management
    
    Scope is a DevEx tool that helps maintain consistent development environments through automated checks, error detection, and fixes.
    
    ## Core Commands
    
    ### scope doctor
    
    Run automated environment checks and fixes.
    
    ```bash
    scope doctor run                   # Run all checks
    scope doctor run --only group-name # Run specific group
    scope doctor run --fix=false       # Check only, no fixes
    scope doctor run --no-cache        # Disable caching
    scope doctor list                  # List available checks
    ```
    
    ### scope analyze
    
    Detect known errors in logs or command output.
    
    ```bash
    scope analyze logs file.log                # Analyze log file
    scope analyze command -- cmd args          # Analyze command output
    scope analyze --extra-config path file.log # Use additional configs
    ```
    
    ### scope report
    
    Generate bug reports with automatic secret redaction.
    
    ```bash
    scope report ./script.sh     # Run and report on script
    scope report -- command args # Run and report on command
    ```
    
    ### scope-intercept
    
    Monitor script execution in real-time (used as shebang).
    
    ```bash
    #!/usr/bin/env scope-intercept bash
    # Script content here
    ```
    
    ## Configuration Resources
    
    All Scope configurations use Kubernetes-inspired YAML format:
    
    ```yaml
    apiVersion: scope.github.com/v1alpha
    kind: <ResourceType>
    metadata:
      name: unique-identifier
      description: Human-readable description
    spec:
      # Resource-specific configuration
    ```
    
    ## ScopeKnownError
    
    Define error patterns and provide automated help/fixes for common issues.
    
    ### Structure
    
    ```yaml
    apiVersion: scope.github.com/v1alpha
    kind: ScopeKnownError
    metadata:
      name: descriptive-error-name
      description: Brief description of what this error means
    spec:
      pattern: 'regex pattern to match the error'
      help: |
        Clear explanation of the issue.
    
        Steps to resolve:
        1. First step
        2. Second step
        3. Where to get help if needed
      fix:
        prompt:
          text: User-friendly prompt asking permission
        commands:
          - first-fix-command
          - second-fix-command
    ```
    
    ### Key Fields
    
    - **pattern**: Regex pattern using ripgrep syntax to match error text
    - **help**: Multi-line markdown explanation with resolution steps
    - **fix** (optional): Automated remediation configuration
      - **commands**: List of commands to run to fix the error (required)
      - **helpText**: Descriptive text shown if the fix fails (optional)
      - **helpUrl**: Documentation link for manual resolution (optional)
      - **prompt**: User approval before running fix (optional)
        - **text**: Question asking for user permission
        - **extraContext**: Additional context about what the fix does and why approval is needed
    
    **Note:** When a fix is defined, it only runs when the error pattern is detected. The fix is optional - if not provided, only the help text is shown.
    
    ### File Organization
    
    Place files in categorized directories:
    
    - Location: `{config-root}/known-errors/{category}/{error-name}.yaml`
    - Common categories: `docker/`, `ruby/`, `git/`, `github/`, `mysql/`, `postgres/`, `dns/`, `aws/`
    - Include matching `.txt` file with example error for testing
    
    ### Example
    
    ```yaml
    apiVersion: scope.github.com/v1alpha
    kind: ScopeKnownError
    metadata:
      name: gem-missing-file
      description: A gem source file is missing and fails to be loaded
    spec:
      pattern: "/lib/ruby/.* `require': cannot load such file --.*/lib/ruby/gems/.*(LoadError)"
      help: |
        A gem source file is missing. The solution is to reinstall the gems:
        1. Run `bundle pristine`
      fix:
        commands:
          - bundle pristine
        helpText: |
          Bundle pristine failed. Try these steps:
          1. Check your bundle config: bundle config list
          2. Reinstall bundler: gem install bundler
          3. Contact #help-ruby if issues persist
        helpUrl: https://bundler.io/man/bundle-pristine.1.html
        prompt:
          text: |-
            This will reinstall all gems from your Gemfile.
            Do you wish to continue?
          extraContext: >-
            bundle pristine reinstalls gems without changing versions,
            which resolves missing file errors but preserves your lock file
    ```
    
    ### Validation
    
    Validate schema structure:
    
    ```bash
    brew install sourcemeta/apps/jsonschema
    jsonschema validate schema.json known-error.yaml
    ```
    
    Test pattern matching:
    
    ```bash
    scope analyze logs --extra-config config-dir/ test-error.txt
    ```
    
    ### Additional Resources
    
    - [Complete example with fix and prompt](https://github.com/oscope-dev/scope/blob/main/examples/.scope/known-error-with-fix.yaml)
    - [ScopeKnownError model documentation](https://oscope-dev.github.io/scope/docs/models/ScopeKnownError)
    
    ### Pattern Writing Tips
    
    - Use ripgrep regex syntax (similar to PCRE)
    - Escape special characters: `\\.`, `\\[`, `\\(`
    - Use character classes: `[[:digit:]]`, `[[:alpha:]]`
    - Test patterns: `echo "error text" | rg "pattern"`
    - Balance specificity vs flexibility to avoid false positives/negatives
    
    ## ScopeDoctorGroup
    
    Define environment setup and maintenance checks with automated fixes.
    
    ### Structure
    
    ```yaml
    apiVersion: scope.github.com/v1alpha
    kind: ScopeDoctorGroup
    metadata:
      name: tool-name
      description: Brief description of what this group does
    spec:
      include: when-required # or "by-default"
      needs:
        - dependency-1
        - dependency-2
      actions:
        - name: action-name
          description: What this action checks/fixes
          required: true # default true; false for optional checks
          check:
            paths:
              - 'file-to-watch.txt'
              - '**/*.config'
            commands:
              - ./bin/check-script.sh
          fix:
            commands:
              - ./bin/fix-script.sh
            helpText: |
              What to do if the fix fails.
              Where to get help.
            helpUrl: https://docs.example.com/help
    ```
    
    ### Key Components
    
    #### Include Modes
    
    - **by-default**: Always runs with `scope doctor run`
    - **when-required**: Only runs when explicitly specified or as dependency
    
    #### Dependencies
    
    List other groups that must run first in `needs` array. Creates execution graph.
    
    #### Actions
    
    Each action is an atomic check/fix operation that runs in order.
    
    #### Check Logic
    
    Determines if fix should run. Fix runs when:
    
    - **No check defined**: Fix always runs
    - **paths specified**: Any file changed or no files match globs
    - **commands specified**: Any command exits non-zero
    - Both can be combined (OR logic)
    
    #### Fix Section
    
    - **commands**: List of commands to run in order
    - **helpText**: Shown if fix fails (markdown supported)
    - **helpUrl**: Optional link to documentation
    
    ### File Organization
    
    - Application setup: `{config-root}/application/`
    - Environment setup: `{config-root}/environment/`
    - Project-specific: `.scope/` in project root
    
    ### Example
    
    ```yaml
    apiVersion: scope.github.com/v1alpha
    kind: ScopeDoctorGroup
    metadata:
      name: ruby-version
      description: Set up Ruby with correct version
    spec:
      include: when-required
      needs:
        - ruby-manager
        - homebrew
      actions:
        - name: install
          description: Ensures correct version of ruby is installed
          check:
            paths:
              - '{{ working_dir }}/.ruby-version'
            commands:
              - ./bin/ruby-version.sh verify
          fix:
            commands:
              - ./bin/ruby-version.sh install
            helpText: |
              Ruby installation failed.
              Contact: #help-channel
    ```
    
    ### Script Conventions
    
    Create helper scripts following check/fix pattern:
    
    ```bash
    #!/usr/bin/env bash
    set -euo pipefail
    
    ACTION="${1:-check}"
    
    check() {
      # Return 0 if check passes, non-zero if fix needed
      if [[ condition ]]; then
        echo "Check passed"
        return 0
      else
        echo "Check failed" >&2
        return 1
      fi
    }
    
    fix() {
      # Perform fix, return 0 on success
      echo "Running fix..."
      # Fix commands here
      return 0
    }
    
    case "$ACTION" in
      check) check ;;
      fix) fix ;;
      *)
        echo "Usage: $0 [check|fix]" >&2
        exit 1
        ;;
    esac
    ```
    
    Script best practices:
    
    - Use relative paths with `./` prefix (relative to YAML file)
    - Make scripts idempotent (safe to run multiple times)
    - Exit 0 for success, non-zero for failure
    - Write errors to stderr
    - Include helpful error messages
    
    ### Caching
    
    File-based checks use content hashing:
    
    - Cache stores file path and content hash
    - Only re-runs if file contents change
    - Persists between runs
    - Disable with `--no-cache`
    
    ## ScopeReportLocation
    
    Configure where and how bug reports are uploaded.
    
    ### GitHub Issues
    
    ```yaml
    apiVersion: scope.github.com/v1alpha
    kind: ScopeReportLocation
    metadata:
      name: github
    spec:
      destination:
        githubIssue:
          owner: org-name
          repo: repo-name
      additionalData:
        nodeVersion: node -v
        rubyPath: which ruby
    ```
    
    Authentication via environment variables:
    
    - GitHub App: `SCOPE_GH_APP_ID` + `SCOPE_GH_APP_KEY`
    - Personal Access Token: `SCOPE_GH_TOKEN`
    
    ### Local File System
    
    ```yaml
    apiVersion: scope.github.com/v1alpha
    kind: ScopeReportLocation
    metadata:
      name: local
    spec:
      destination:
        local:
          directory: /tmp/scope-reports
      additionalData:
        pwd: pwd
        username: id -un
        scopeVersion: scope version
    ```
    
    ### RustyPaste
    
    ```yaml
    apiVersion: scope.github.com/v1alpha
    kind: ScopeReportLocation
    metadata:
      name: rustypaste
    spec:
      destination:
        rustyPaste:
          url: http://localhost:8000
    ```
    
    ### Additional Data
    
    Capture environment context with arbitrary commands:
    
    ```yaml
    additionalData:
      diskSpace: df -h
      gitBranch: git branch --show-current
      envVars: env | sort
    ```
    
    Commands execute at report generation time. Scope automatically redacts secrets.
    
    ## Common Patterns
    
    Version checks, file-exists checks, service health, dependency installs, and path-triggered auto-run each have a ready YAML snippet in [references/quick-reference.md](references/quick-reference.md) ("Common Patterns"). An orchestration group is a `ScopeDoctorGroup` whose `needs:` lists other groups and whose `actions:` is empty.
    
    ## Workflow: Creating a Known Error
    
    A known error is a YAML definition plus a `.txt` file of real error output, side by side under `{config-root}/known-errors/{category}/`. It's done when `scope analyze logs --extra-config {config-root} <the .txt>` matches the sample and `jsonschema validate schema.json <the .yaml>` passes.
    
    ## Workflow: Creating a Doctor Group
    
    A doctor group is a YAML file in `{config-root}/application/`, `{config-root}/environment/`, or `.scope/` (project-specific), plus any helper scripts under `.scope/bin/`, referenced by relative path and executable. Add it to its parent group's `needs` if it's a new dependency. It's done when `scope doctor list` shows it and `scope doctor run --only <name>` passes with and without `--no-cache`.
    
    ## Debugging
    
    See "Debugging Checklist" in [references/quick-reference.md](references/quick-reference.md). The usual causes: a regex that needs escaping (test with `rg "pattern" file`), `paths` globs that match nothing, check commands that don't exit 0 on success, stale cache (`--no-cache`), non-executable scripts, script paths not relative to the YAML (`./` prefix), and `needs` naming a missing group (`scope doctor list` shows order).
    
    ## Security Features
    
    ### Automatic Redaction
    
    Scope automatically redacts sensitive information:
    
    - GitHub API tokens
    - AWS credentials
    - SSH keys
    - Environment variable values containing secrets
    - Uses patterns from [ripsecrets](https://github.com/sirwart/ripsecrets)
    
    This makes it safe to capture full environment in reports and share debug output publicly.
    
    ## Reference
    
    ### Configuration Structure
    
    ```
    config-repository/
    ├── {config-root}/
    │   ├── application/          # App-level (ruby, node, postgres)
    │   ├── environment/          # System-level (homebrew, docker, github)
    │   ├── known-errors/         # Error definitions by category
    │   │   ├── docker/
    │   │   ├── ruby/
    │   │   ├── git/
    │   │   └── ...
    │   └── reports/              # Report locations
    ```
    
    ## Additional Resources
    
    See references directory for:
    
    - `quick-reference.md` - Command cheat sheet and pattern examples
    - `real-world-examples.md` - Production-tested configurations
    - `testing-guide.md` - Comprehensive validation workflows
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.