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

   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

   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

   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