Project Context Discovery Skill

Provides expertise in discovering project characteristics through exploration rather than assumptions.

Purpose

This skill equips agents with strategies for:

• •Identifying package managers and build systems
• •Discovering test frameworks and commands
• •Finding automation scripts and tooling
• •Learning project conventions from configuration

When to Use

Use this skill when:

• •Need to run tests but don't know the framework
• •Setting up a new project environment
• •Installing dependencies without hardcoded assumptions
• •Discovering how CI/CD runs commands

Discovery Strategy

Phase 1: Project Structure Exploration

1. •

   List root directory contents

   bash

   ls -la
   

2. •

   Identify language(s) from file extensions

   • •.rb → Ruby
   • •.js/.ts → JavaScript/TypeScript
   • •.py → Python
   • •.go → Go
   • •.rs → Rust
   • •Multiple languages? Note all
3. •

   Find configuration files

   Look for package manager indicators:

   • •package.json + package-lock.json → npm
   • •package.json + yarn.lock → yarn
   • •package.json + pnpm-lock.yaml → pnpm
   • •Gemfile + Gemfile.lock → Bundler (Ruby)
   • •Cargo.toml + Cargo.lock → Cargo (Rust)
   • •go.mod + go.sum → Go modules
   • •pyproject.toml + poetry.lock → Poetry
   • •requirements.txt → pip

Phase 2: Test Framework Discovery

1. •

   Check CI configuration first

   CI config is the source of truth for what actually runs:

   • •.github/workflows/*.yml → GitHub Actions
   • •.gitlab-ci.yml → GitLab CI
   • •.circleci/config.yml → CircleCI
   • •.travis.yml → Travis CI
   • •Jenkinsfile → Jenkins
   • •azure-pipelines.yml → Azure Pipelines
2. •

   Parse CI test commands

   Look for run: or script: sections with test commands Identify job names like: test, tests, unit-test, integration-test, ci

3. •

   Check package manager configuration

   • •package.json → check scripts.test field
   • •Gemfile → check for test-related gems
   • •Cargo.toml → check for test dependencies
   • •pyproject.toml → check test tool configuration
4. •

   Look for test directories

   bash

   ls -d test/ tests/ spec/ __tests__/ 2>/dev/null
   

5. •

   Check for framework config files

   Common test framework indicators:

   • •jest.config.js, vitest.config.js → JavaScript test frameworks
   • •.rspec, spec/spec_helper.rb → RSpec
   • •pytest.ini, test/test_helper.rb → pytest or minitest
   • •Config in package.json, pyproject.toml, or setup.cfg

Phase 3: Automation Script Discovery

1. •

   Check documented commands (prefer explicit over implicit)

   • •README.md → look for "Testing", "Development", "Getting Started"
   • •CONTRIBUTING.md → look for contribution workflow
   • •Makefile → look for test targets
2. •

   Check automation directories

   bash

   ls bin/ scripts/ script/ .local/bin/ 2>/dev/null
   

3. •

   Check package manager scripts

   • •npm: npm run (lists all scripts)
   • •Bundler: bundle exec rake -T
   • •Make: make help or make -n

Phase 4: Dependency Installation

Based on discovered package manager, use appropriate install command:

General strategy:

• •Prefer lockfile-based installs (reproducible, CI-friendly)
• •Use CI-optimized commands when available (npm ci vs npm install)
• •Check for frozen-lockfile options to prevent unexpected updates

Example decision tree for Node.js:

if [ -f package-lock.json ]; then npm ci
elif [ -f yarn.lock ]; then yarn install --frozen-lockfile
elif [ -f pnpm-lock.yaml ]; then pnpm install --frozen-lockfile
else npm install; fi

Other languages follow similar patterns:

• •Ruby: Check for Gemfile.lock → use bundle install
• •Python: Check for poetry.lock or pyproject.toml → use poetry install or pip install
• •Go: Check for go.sum → use go mod download
• •Rust: Check for Cargo.lock → use cargo build

Phase 5: Test Command Construction

Preference order (highest to lowest priority):

1. •Explicit documentation (README/CONTRIBUTING) - what humans are told to run
2. •CI configuration (source of truth) - what automation actually runs
3. •Package manager scripts (npm test, rake test) - defined shortcuts
4. •Framework defaults (only as fallback) - conventions when nothing explicit exists

Decision process:

If CI config defines test command → use that (it's what's actually running in production)

If package.json/Gemfile/etc has test script → use the defined script

If neither, infer from framework detection:

• •JavaScript with Jest config → likely npx jest
• •Ruby with RSpec directories → likely bundle exec rspec
• •Python with pytest.ini → likely pytest
• •Go with test files → likely go test ./...
• •Rust with tests/ → likely cargo test

Graceful Degradation

If discovery fails at any phase:

1. •Note what couldn't be determined
2. •Make best-effort guess with caveats
3. •Provide fallback options
4. •Report incomplete discovery to user

Never fail completely - always provide a path forward.

Example Usage

Agent using this skill:

1. Read project root directory
2. Identify languages: JavaScript (package.json found)
3. Check CI: .github/workflows/test.yml exists
4. Parse CI: runs "npm run test:unit && npm run test:integration"
5. Check package.json scripts: confirms test:unit and test:integration exist
6. Determine package manager: package-lock.json exists → npm
7. Discovery complete:
   - Language: JavaScript
   - Package manager: npm
   - Install command: npm ci (uses lockfile)
   - Test command: npm run test:unit && npm run test:integration (from CI)
8. Execute: npm ci && npm run test:unit && npm run test:integration

Key Principles

• •Discover, don't assume: Never hardcode project-specific commands
• •Prefer explicit over implicit: Use documented/configured commands over framework defaults
• •CI is truth: What runs in CI is what the project actually uses
• •Multiple indicators: Combine signals from configs, directories, and dependencies
• •Priority order matters: Check sources in order of reliability (CI → docs → conventions)
• •Graceful degradation: Provide best-effort fallbacks when discovery is incomplete