anthropics / anthropics/skills

[bug] Add Environment setup to skills

Open
#1,009 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
176k
Forks
20.9k
Avg merge
7h 21m
Merged PRs (30d)
5

Description

# Proposal: Add Environment Setup Sections to Skills

## Problem Statement

Many skills in this repository contain Python scripts that depend on third-party packages, but lack clear instructions for setting up the required environment. This leads to:

- **ModuleNotFoundError** when users try to run scripts
- Inconsistent dependency management across skills
- Poor user experience for newcomers
- Time wasted troubleshooting import errors

For example, skills that use libraries like `pandas`, `requests`, `numpy`, `opencv`, `beautifulsoup4`, or other packages require users to figure out the setup process themselves.

## Proposed Solution

Add standardized **Environment Setup** sections to skills that use Python dependencies, following the pattern established in the `pdf` skill:

### Template Structure
```markdown
## Environment Setup

Before running any Python scripts from this skill, you **must** set up a virtual environment and install dependencies.

1. **Create a venv** in the project root (if `.venv` doesn't already exist):
```bash
python3 -m venv .venv
```

2. **Scan the scripts** in this skill's `scripts/` subdirectory for `import` statements to determine which third-party packages are needed.

3. **Install the discovered dependencies** into the venv:
```bash
.venv/bin/pip install
```

4. **Run scripts** using the venv's Python:
```bash
.venv/bin/python
```

If a script fails with `ModuleNotFoundError`, install the missing package into the same venv and retry.
```

## Example: Good Implementation

The **pdf skill** already implements this pattern well and should serve as the template for other skills.

## Scope

Skills that likely need environment setup sections include those using:
- **Data processing**: pandas, numpy, scipy
- **Web scraping**: requests, beautifulsoup4, selenium
- **Computer vision**: opencv, pillow, scikit-image
- **Machine learning**: scikit-learn, tensorflow, pytorch
- **File processing**: openpyxl, python-docx
- **API clients**: specific SDK packages
- **Database connections**: psycopg2, pymongo, sqlalchemy

## Benefits

1. **Better User Experience**: Clear, upfront instructions prevent frustration
2. **Consistency**: Standardized approach across all skills
3. **Faster Onboarding**: New users can get started immediately
4. **Reduced Support Overhead**: Fewer questions about setup issues
5. **Professional Polish**: Shows attention to detail and user needs

## Implementation Notes

- Environment setup should appear early in each skill's README/guide
- Use the same venv naming convention (`.venv`) across all skills
- Include troubleshooting guidance for common issues
- Consider adding a requirements.txt file for skills with many dependencies

## Action Items

- [ ] Audit existing skills to identify which need environment setup sections
- [ ] Add environment setup sections following the template
- [ ] Consider creating a shared environment setup guide that skills can reference
- [ ] Update skill creation guidelines to include environment setup requirements

---

**Labels**: enhancement, documentation, user-experience
**Priority**: Medium
**Effort**: Low-Medium (mostly documentation updates)

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.