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
Install
npx skills add https://github.com/technicalpickles/pickled-claude-plugins/tree/main/plugins/dev-tools/skills/working-with-scope
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install technicalpickles-pickled-claude-plugins@llmmart
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
.txtfile 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 examplesreal-world-examples.md- Production-tested configurationstesting-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.
Reviews (0)
No reviews yet.
No comments yet.