# AGENTS.md

AI agent instructions for `skene-cookbook` - 764 skill library with 36 skill chain recipes.

## Quick Context

**Repository:** Single npm package `@skene/skills-directory` v0.2.0
**Purpose:** Pre-built AI skill chains for PLG, sales, customer success, security, and more
**License:** MIT
**Stack:** Node.js 18+ (npm CLI), Python 3.10+ (testing/validation), Pytest (80%+ coverage)

## Build & Test Commands

```bash
# Install dependencies
npm ci

# Run tests (full suite)
pytest tests/ -v

# Run specific test suites
pytest tests/unit -v -m "not slow"        # Unit tests (fast)
pytest tests/integration -v -m "not slow" # Integration tests
pytest tests/e2e -v                       # End-to-end tests (slow)

# Run linting and formatting
npm run lint                              # ESLint + Prettier
npm run format                            # Auto-fix formatting
black .                                   # Python formatting
flake8 .                                  # Python linting
isort .                                   # Python import sorting

# Verify metrics consistency (skill counts, badges)
npm run verify:metrics

# Run pre-release checks
bash scripts/pre_release_check.sh         # Comprehensive verification

# Pre-commit hooks
pre-commit run --all-files                # Run all hooks (includes detect-secrets)
```

## Test Requirements

- All tests must pass before merging
- Minimum 60% coverage (target: 80%+)
- No failing lint/format checks
- `npm run verify:metrics` must pass (ensures docs match registry)

## Project Structure

```
skene-cookbook/
├── bin/                          # npm CLI entry point
│   └── skills-directory.js       # Main CLI
├── skills-library/
│   ├── executable/               # 382 executable skills
│   └── reference/                # 382 reference guides
├── docs/
│   ├── SKILL_CHAINS.md           # 36 ready-to-use recipes (PRIMARY USER DOC)
│   ├── PLAYBOOKS.md              # Workflows with data wiring examples
│   └── directory.md              # Full skill catalog
├── registry/
│   ├── blueprints/               # Workflow blueprints (JSON)
│   └── integration_schemas/      # CRM/billing schemas
├── tests/                        # Pytest test suite
│   ├── unit/                     # Fast unit tests
│   ├── integration/              # Integration tests
│   └── e2e/                      # End-to-end user workflows
├── scripts/                      # Python automation scripts
└── eval_harness/                 # Evaluation harness implementation
```

## Key Conventions

### Skill Structure

Every skill follows this pattern:

```
skills-library/executable/{domain}/{skill-name}/
├── skill.json          # Metadata (name, description, category, risk_level)
├── instructions.md     # AI agent instructions
└── tests/              # Optional: skill-specific tests
```

### Risk Levels

Skills are classified by risk level:

- `Low` - Read-only operations, no external dependencies
- `Medium` - Write operations, requires configuration
- `High` - External API calls, requires credentials
- `Critical` - System-level operations, requires manual review

### Skill Chain Format

36 recipes in `docs/SKILL_CHAINS.md` follow this format:

```
Recipe N: {Title}
├── Use Case: {problem it solves}
├── Skills: {2-7 skills chained together}
├── ROI: {time/cost savings}
├── Setup Instructions: {step-by-step}
└── Expected Outcomes: {success metrics}
```

## Boundaries & Constraints

### Do NOT Touch

- `skills-library/` content - 764 skills, managed by scripts
- `registry/` - Auto-generated from skills library
- `METRICS.md` - Auto-generated by `npm run verify:metrics`

### Always Update Together

When changing skill counts or categories:

1. Update skill metadata in `skills-library/`
2. Run `npm run verify:metrics` to sync badges and counts
3. Verify `README.md`, `METRICS.md`, and `docs/directory.md` updated

### Security

- Never commit `.env` files (blocked by pre-commit hooks)
- Run `pre-commit run --all-files` before every commit
- `detect-secrets` is enforced in CI/CD
- Skills with `risk_level: Critical` require manual review

## Pull Request Checklist

Before submitting PR:

- [ ] All tests pass (`pytest tests/ -v`)
- [ ] Lint checks pass (`npm run lint`, `black .`, `flake8 .`)
- [ ] Metrics verified (`npm run verify:metrics`)
- [ ] Pre-commit hooks pass (`pre-commit run --all-files`)
- [ ] Coverage ≥ 60% (check `coverage.xml`)
- [ ] No secrets detected (checked by CI)
- [ ] README.md updated if adding features
- [ ] SKILL_CHAINS.md updated if adding recipes

## CI/CD

GitHub Actions workflow (`.github/workflows/lint-and-build.yml`):

- Linting (Python: Black, Flake8, isort | JS: ESLint, Prettier)
- Schema validation (skills, metadata, workflows)
- Testing (unit, integration, e2e) with coverage
- Security scanning (npm audit, pip-audit, detect-secrets)
- Dependency vulnerability checks

## Questions?

- User documentation: `README.md`, `docs/SKILL_CHAINS.md`
- Contributing guidelines: `CONTRIBUTING.md`
- Issue templates: `.github/ISSUE_TEMPLATE/`