AGENTS.md

1# AGENTS.md
2 
3AI agent instructions for `skene-cookbook` - 764 skill library with 36 skill chain recipes.
4 
5## Quick Context
6 
7**Repository:** Single npm package `@skene/skills-directory` v0.2.0
8**Purpose:** Pre-built AI skill chains for PLG, sales, customer success, security, and more
9**License:** MIT
10**Stack:** Node.js 18+ (npm CLI), Python 3.10+ (testing/validation), Pytest (80%+ coverage)
11 
12## Build & Test Commands
13 
14```bash
15# Install dependencies
16npm ci
17 
18# Run tests (full suite)
19pytest tests/ -v
20 
21# Run specific test suites
22pytest tests/unit -v -m "not slow"        # Unit tests (fast)
23pytest tests/integration -v -m "not slow" # Integration tests
24pytest tests/e2e -v                       # End-to-end tests (slow)
25 
26# Run linting and formatting
27npm run lint                              # ESLint + Prettier
28npm run format                            # Auto-fix formatting
29black .                                   # Python formatting
30flake8 .                                  # Python linting
31isort .                                   # Python import sorting
32 
33# Verify metrics consistency (skill counts, badges)
34npm run verify:metrics
35 
36# Run pre-release checks
37bash scripts/pre_release_check.sh         # Comprehensive verification
38 
39# Pre-commit hooks
40pre-commit run --all-files                # Run all hooks (includes detect-secrets)
41```
42 
43## Test Requirements
44 
45- All tests must pass before merging
46- Minimum 60% coverage (target: 80%+)
47- No failing lint/format checks
48- `npm run verify:metrics` must pass (ensures docs match registry)
49 
50## Project Structure
51 
52```
53skene-cookbook/
54├── bin/                          # npm CLI entry point
55│   └── skills-directory.js       # Main CLI
56├── skills-library/
57│   ├── executable/               # 382 executable skills
58│   └── reference/                # 382 reference guides
59├── docs/
60│   ├── SKILL_CHAINS.md           # 36 ready-to-use recipes (PRIMARY USER DOC)
61│   ├── PLAYBOOKS.md              # Workflows with data wiring examples
62│   └── directory.md              # Full skill catalog
63├── registry/
64│   ├── blueprints/               # Workflow blueprints (JSON)
65│   └── integration_schemas/      # CRM/billing schemas
66├── tests/                        # Pytest test suite
67│   ├── unit/                     # Fast unit tests
68│   ├── integration/              # Integration tests
69│   └── e2e/                      # End-to-end user workflows
70├── scripts/                      # Python automation scripts
71└── eval_harness/                 # Evaluation harness implementation
72```
73 
74## Key Conventions
75 
76### Skill Structure
77 
78Every skill follows this pattern:
79 
80```
81skills-library/executable/{domain}/{skill-name}/
82├── skill.json          # Metadata (name, description, category, risk_level)
83├── instructions.md     # AI agent instructions
84└── tests/              # Optional: skill-specific tests
85```
86 
87### Risk Levels
88 
89Skills are classified by risk level:
90 
91- `Low` - Read-only operations, no external dependencies
92- `Medium` - Write operations, requires configuration
93- `High` - External API calls, requires credentials
94- `Critical` - System-level operations, requires manual review
95 
96### Skill Chain Format
97 
9836 recipes in `docs/SKILL_CHAINS.md` follow this format:
99 
100```
101Recipe N: {Title}
102├── Use Case: {problem it solves}
103├── Skills: {2-7 skills chained together}
104├── ROI: {time/cost savings}
105├── Setup Instructions: {step-by-step}
106└── Expected Outcomes: {success metrics}
107```
108 
109## Boundaries & Constraints
110 
111### Do NOT Touch
112 
113- `skills-library/` content - 764 skills, managed by scripts
114- `registry/` - Auto-generated from skills library
115- `METRICS.md` - Auto-generated by `npm run verify:metrics`
116 
117### Always Update Together
118 
119When changing skill counts or categories:
120 
1211. Update skill metadata in `skills-library/`
1222. Run `npm run verify:metrics` to sync badges and counts
1233. Verify `README.md`, `METRICS.md`, and `docs/directory.md` updated
124 
125### Security
126 
127- Never commit `.env` files (blocked by pre-commit hooks)
128- Run `pre-commit run --all-files` before every commit
129- `detect-secrets` is enforced in CI/CD
130- Skills with `risk_level: Critical` require manual review
131 
132## Pull Request Checklist
133 
134Before submitting PR:
135 
136- [ ] All tests pass (`pytest tests/ -v`)
137- [ ] Lint checks pass (`npm run lint`, `black .`, `flake8 .`)
138- [ ] Metrics verified (`npm run verify:metrics`)
139- [ ] Pre-commit hooks pass (`pre-commit run --all-files`)
140- [ ] Coverage ≥ 60% (check `coverage.xml`)
141- [ ] No secrets detected (checked by CI)
142- [ ] README.md updated if adding features
143- [ ] SKILL_CHAINS.md updated if adding recipes
144 
145## CI/CD
146 
147GitHub Actions workflow (`.github/workflows/lint-and-build.yml`):
148 
149- Linting (Python: Black, Flake8, isort | JS: ESLint, Prettier)
150- Schema validation (skills, metadata, workflows)
151- Testing (unit, integration, e2e) with coverage
152- Security scanning (npm audit, pip-audit, detect-secrets)
153- Dependency vulnerability checks
154 
155## Questions?
156 
157- User documentation: `README.md`, `docs/SKILL_CHAINS.md`
158- Contributing guidelines: `CONTRIBUTING.md`
159- Issue templates: `.github/ISSUE_TEMPLATE/`
160