| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 23 | 56 | 0% |
| Commands | 7 | 2 | 8 | 41% |
| Section tags | 10 | 1 | 5 | 63% |
What each file covers
Sections
0 shared · 23 only in A · 56 only in B- − AGENTS.md
- − Quick Context
- − Build & Test Commands
- − Install dependencies
- − Run tests (full suite)
- − Run specific test suites
- − Run linting and formatting
- − Verify metrics consistency (skill counts, badges)
- − Run pre-release checks
- − Pre-commit hooks
- − Test Requirements
- − Project Structure
- − Key Conventions
- − Skill Structure
- − Risk Levels
- − Skill Chain Format
- − Boundaries & Constraints
- − Do NOT Touch
- − Always Update Together
- − Security
- − Pull Request Checklist
- − CI/CD
- − Questions?
- + Cursor Rules for skene-cookbook
- + Project Context
- + Architecture Patterns
- + Skill Structure (Non-Negotiable)
- + Registry Auto-Generation
- + Risk Level Classification
- + Naming Conventions
- + Skill IDs
- + File Naming
- + Domain Categories
- + Testing Patterns
- + Test Organization
- + Required Test Coverage
- + Testing Commands
- + Run full suite
- + Run fast tests only
- + Run specific domain tests
- + Code Quality Standards
- + Pre-Commit Hooks (Enforced)
- + Linting Commands
- + JavaScript
- + Python (if installed in venv)
- + Workflow Blueprints
- + Blueprint Schema
- + Playbook-Ready Features (Optional but Encouraged)
- + Security Rules (Blocking)
- + Never Commit
- + Handling Credentials
- + Good: Reference environment variables
- + Bad: Hardcoded credentials
- + AI Agent Boundaries
- + What AI Agents Can Access
- + What AI Agents Should NOT Touch
- + Development Workflow
- + Adding a New Skill
- + Modifying Existing Skills
- + Creating Skill Chains
- + Performance Guidelines
- + Skill Execution
- + Testing Performance
- + Common Patterns
- + Skill Chaining (Data Flow)
- + Error Handling
- + Commit Message Format
- + Quick Reference Commands
- + Setup
- + Testing
- + Quality
- + Pre-release
- + Pre-commit
- + Questions or Unclear Patterns?
- + AI Agent Execution Context
- + Emergency Commands
- + Reset to clean state
- + Rebuild registry
- + Reinstall dependencies
Commands
7 shared · 2 only in A · 8 only in B- − pytest tests/integration -v -m "not slow"
- − pytest tests/e2e -v
- + pytest tests/unit/test_dedupe_skills.py -v
- + pytest tests/integration -v
- + git status
- + git restore .
- + git clean -fd
- + python3 -m venv .venv
- + pip install -r requirements-dev.txt
- + prettier
- npm ci
- pytest tests/ -v
- pytest tests/unit -v -m "not slow"
- npm run lint
- npm run format
- black .
- npm run verify:metrics
Section tags
10 shared · 1 only in A · 5 only in B- − build
- + types
- + testing-strategy
- + database
- + performance
- + agent-behaviour
- setup
- test
- lint-format
- code-style
- architecture
- git-pr
- security
- dependencies
- deployment
- do-not
Line diff
SkeneTechnologies/skene-cookbook · AGENTS.md
@@ −1 @@
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
SkeneTechnologies/skene-cookbook · .cursorrules
@@ +1 @@
1# Cursor Rules for skene-cookbook
2
3## Project Context
4
5**Repository:** skene-cookbook - 764 AI skill library with 36 skill chain recipes
6**Package:** @skene/skills-directory v0.2.0
7**License:** MIT
8**Purpose:** Pre-built AI skill chains for PLG, sales, customer success, security, and more
9
10## Architecture Patterns
11
12### Skill Structure (Non-Negotiable)
13
14Every skill MUST follow this exact structure:
15
16```
17skills-library/{domain}/{skill-name}/
18├── skill.json # Metadata (name, description, category, risk_level)
19├── instructions.md # AI agent execution instructions
20└── tests/ # Optional: skill-specific tests
21```
22
23**Do NOT:**
24- Create skills outside `skills-library/executable/` or `skills-library/reference/`
25- Modify existing skill structure without updating registry
26- Add skills without `skill.json` and `instructions.md`
27
28### Registry Auto-Generation
29
30The `registry/` directory is AUTO-GENERATED from `skills-library/`:
31- Never manually edit files in `registry/`
32- Always run `npm run verify:metrics` after skill changes
33- Registry regeneration syncs badges and counts across README.md, METRICS.md, docs/directory.md
34
35### Risk Level Classification
36
37Skills are classified by risk level (defined in `skill.json`):
38- `Low` - Read-only operations, no external dependencies
39- `Medium` - Write operations, requires configuration
40- `High` - External API calls, requires credentials
41- `Critical` - System-level operations, requires manual review
42
43**Rule:** When creating a skill that makes external API calls, uses credentials, or modifies data, always set `risk_level: "High"` or `"Critical"`.
44
45## Naming Conventions
46
47### Skill IDs
48- Format: `{domain}_{action}_{target}` (e.g., `sales_analyze_pipeline`)
49- Use snake_case, all lowercase
50- Be descriptive but concise (3-5 words max)
51
52### File Naming
53- Skill directories: kebab-case (e.g., `analyze-customer-health/`)
54- Python files: snake_case (e.g., `analyze_skills.py`)
55- JavaScript files: kebab-case (e.g., `skills-directory.js`)
56- Documentation: SCREAMING_SNAKE_CASE for top-level (e.g., `AGENTS.md`), kebab-case for nested
57
58### Domain Categories
59
60Valid domains (don't invent new ones without discussion):
61- `ecosystem` - Partner, integration management
62- `marketing` - Campaigns, content, SEO
63- `sales` - Pipeline, deals, CRM
64- `customer_success` - Health, churn, onboarding
65- `product_ops` - Roadmap, releases
66- `security` - Security, compliance
67- `finops` - Billing, revenue
68- `data` - Analytics, reporting
69- `engineering` - DevOps, CI/CD
70- `hr` - Recruiting, onboarding
71
72## Testing Patterns
73
74### Test Organization
75
76```
77tests/
78├── unit/ # Fast, isolated tests (< 1s each)
79├── integration/ # Multi-component tests (< 5s each)
80└── e2e/ # Full user workflows (< 30s each)
81```
82
83### Required Test Coverage
84
85- Minimum: 60% overall coverage
86- Target: 80%+ coverage
87- Critical paths (eval_harness, tracer): 90%+ coverage
88
89### Testing Commands
90
91```bash
92# Run full suite
93pytest tests/ -v
94
95# Run fast tests only
96pytest tests/unit -v -m "not slow"
97
98# Run specific domain tests
99pytest tests/unit/test_dedupe_skills.py -v
100```
101
102**Rule:** All PRs must pass `pytest tests/ -v` before merging.
103
104## Code Quality Standards
105
106### Pre-Commit Hooks (Enforced)
107
108The following hooks run automatically on commit:
109- `detect-secrets` - Blocks commits with credentials
110- `prettier` - Formats JS/JSON/YAML/Markdown
111- `black` - Formats Python (if installed)
112- `flake8` - Lints Python (if installed)
113- `isort` - Sorts Python imports (if installed)
114
115**Rule:** Never use `--no-verify` to skip hooks. Fix the issues instead.
116
117### Linting Commands
118
119```bash
120# JavaScript
121npm run lint # ESLint + Prettier
122npm run format # Auto-fix formatting
123
124# Python (if installed in venv)
125black .
126flake8 .
127isort .
128```
129
130## Workflow Blueprints
131
132### Blueprint Schema
133
134Blueprints in `registry/blueprints/` follow `schemas/workflow_blueprint.json`:
135
136```yaml
137id: workflow_{name}
138version: 1.0.0
139name: 'Human Readable Name'
140chain_sequence:
141 - step_id: 'step_1'
142 skill_id: 'domain_action_target'
143 action: 'action_name'
144 input_mapping:
145 static_values: {}
146 error_handling:
147 on_failure: 'stop'
148 max_retries: 2
149```
150
151**Rule:** All workflow blueprints must validate against schema before committing.
152
153## Playbook-Ready Features (Optional but Encouraged)
154
155When creating blueprints, consider adding:
156
157```yaml
158icp:
159 company_size: '50-500'
160 motion: 'product-led-growth'
161 priorities: ['reduce_churn', 'increase_nrr']
162
163integration_reference:
164 - type: 'crm'
165 provider: 'salesforce'
166 schema_ref: 'registry/integration_schemas/salesforce_fields.yaml'
167
168opinionated_prompts:
169 - step_id: 'step_1'
170 system_context: 'You are analyzing a PLG motion with 30-day trials...'
171 input_guidance: 'Focus on trial-to-paid conversion metrics...'
172```
173
174See `registry/integration_schemas/README.md` for schema format.
175
176## Security Rules (Blocking)
177
178### Never Commit
179
180These patterns are BLOCKED by pre-commit hooks:
181- `.env` files (use `.env.example` for templates)
182- Files in `.ssh/`, `.aws/`, `secrets/`
183- Private keys (detected by `detect-private-key` hook)
184- API keys, tokens, passwords (detected by `detect-secrets`)
185
186### Handling Credentials
187
188```bash
189# Good: Reference environment variables
190DATABASE_URL = os.getenv('DATABASE_URL')
191
192# Bad: Hardcoded credentials
193DATABASE_URL = "postgresql://user:pass@localhost" # pragma: allowlist secret
194```
195
196## AI Agent Boundaries
197
198### What AI Agents Can Access
199
200- All files except `.ai/internal/` (gitignored, excluded in `.cursorignore`)
201- `AGENTS.md` for build commands and conventions
202- All skill schemas in `skills-library/`
203- Test suites in `tests/`
204
205### What AI Agents Should NOT Touch
206
207- `skills-library/` content (764 skills, managed by scripts)
208- `registry/` (auto-generated)
209- `METRICS.md` (auto-generated)
210
211**Rule:** If you modify skill counts or categories, run `npm run verify:metrics` to sync all dependent files.
212
213## Development Workflow
214
215### Adding a New Skill
216
2171. Create directory: `skills-library/executable/{domain}/{skill-name}/`
2182. Write `skill.json` (follow schema in `schemas/skill_definition.json`)
2193. Write `instructions.md` (clear execution steps)
2204. Run `npm run verify:metrics` to update registry
2215. Add tests in `tests/` if complex logic
2226. Run `pytest tests/ -v` to verify
2237. Commit with message: `feat(skills): add {skill-name} to {domain}`
224
225### Modifying Existing Skills
226
2271. Read the skill's `skill.json` and `instructions.md` first
2282. Make changes
2293. Run `npm run verify:metrics`
2304. Update tests if behavior changed
2315. Run `pytest tests/ -v`
2326. Commit with message: `fix(skills): update {skill-name} - {reason}`
233
234### Creating Skill Chains
235
2361. Identify 2-7 skills to chain together
2372. Create blueprint in `registry/blueprints/` (or use script: `scripts/recipe_to_blueprint.py`)
2383. Validate against `schemas/workflow_blueprint.json`
2394. Document in `docs/SKILL_CHAINS.md` (follow existing format)
2405. Add integration test in `tests/integration/`
2416. Commit with message: `feat(chains): add {chain-name} recipe`
242
243## Performance Guidelines
244
245### Skill Execution
246
247- Keep skills atomic (single responsibility)
248- Skills should complete in < 5 seconds (unless marked with `slow: true`)
249- Use caching for expensive operations (see `eval_harness/tracer.py` for examples)
250
251### Testing Performance
252
253- Unit tests: < 1 second each
254- Integration tests: < 5 seconds each
255- E2E tests: < 30 seconds each
256- Mark slow tests with `@pytest.mark.slow`
257
258## Common Patterns
259
260### Skill Chaining (Data Flow)
261
262Skills output data that becomes input for next skill:
263
264```yaml
265- step_id: 'analyze'
266 skill_id: 'sales_analyze_pipeline'
267 output: { health_score: 0.85 }
268
269- step_id: 'recommend'
270 skill_id: 'sales_recommend_actions'
271 input_mapping:
272 from_step: 'analyze'
273 field_mappings:
274 health_score: 'input.score'
275```
276
277### Error Handling
278
279```yaml
280error_handling:
281 on_failure: 'stop' # Options: stop, continue, retry
282 max_retries: 2
283 retry_delay_seconds: 5
284```
285
286## Commit Message Format
287
288Follow Conventional Commits:
289
290```
291<type>(<scope>): <subject>
292
293<body>
294
295<footer>
296```
297
298**Types:**
299- `feat` - New feature (skill, chain, tool)
300- `fix` - Bug fix
301- `docs` - Documentation only
302- `refactor` - Code refactoring (no behavior change)
303- `test` - Adding or updating tests
304- `chore` - Maintenance (deps, config, etc.)
305
306**Examples:**
307```
308feat(skills): add customer health scoring to customer_success domain
309fix(chains): correct data mapping in sales pipeline workflow
310docs(agents): update AGENTS.md with eval harness instructions
311```
312
313## Quick Reference Commands
314
315```bash
316# Setup
317npm ci
318
319# Testing
320pytest tests/ -v # All tests
321pytest tests/unit -v -m "not slow" # Fast unit tests
322pytest tests/integration -v # Integration tests
323
324# Quality
325npm run lint # ESLint + Prettier
326npm run format # Auto-fix formatting
327npm run verify:metrics # Sync skill counts/badges
328
329# Pre-release
330bash scripts/pre_release_check.sh # Comprehensive check
331
332# Pre-commit
333pre-commit run --all-files # Run all hooks
334```
335
336## Questions or Unclear Patterns?
337
338- Read `AGENTS.md` for build commands and testing workflows
339- Read `CONTRIBUTING.md` for contribution guidelines
340- Read `ARCHITECTURE.md` for design details
341- Check existing skills in `skills-library/` for examples
342- See `docs/SKILL_CHAINS.md` for 36 ready-to-use recipes
343
344## AI Agent Execution Context
345
346When executing code:
347- Use `source .venv/bin/activate` for Python commands
348- Use `npm ci` for fresh dependency install
349- Always run tests before committing: `pytest tests/ -v`
350- Check `git status` before and after operations
351- Use `npm run verify:metrics` after skill changes
352
353## Emergency Commands
354
355If something breaks:
356
357```bash
358# Reset to clean state
359git status
360git restore .
361git clean -fd
362
363# Rebuild registry
364npm run verify:metrics
365
366# Reinstall dependencies
367rm -rf node_modules .venv
368npm ci
369python3 -m venv .venv
370source .venv/bin/activate
371pip install -r requirements-dev.txt # if exists
372```
373
374---
375
376**Last Updated:** 2026-02-15 (v0.2.0 - Open Source Release)
377**Maintained By:** Skene Technologies (opensource@skene.ai)
378
@@ −1 +1 @@
1−# AGENTS.md
1+# Cursor Rules for skene-cookbook
22
3−AI agent instructions for `skene-cookbook` - 764 skill library with 36 skill chain recipes.
3+## Project Context
44
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
5+**Repository:** skene-cookbook - 764 AI skill library with 36 skill chain recipes
6+**Package:** @skene/skills-directory v0.2.0
97 **License:** MIT
10−**Stack:** Node.js 18+ (npm CLI), Python 3.10+ (testing/validation), Pytest (80%+ coverage)
8+**Purpose:** Pre-built AI skill chains for PLG, sales, customer success, security, and more
119
12−## Build & Test Commands
10+## Architecture Patterns
1311
14−```bash
15−# Install dependencies
16−npm ci
12+### Skill Structure (Non-Negotiable)
1713
18−# Run tests (full suite)
14+Every skill MUST follow this exact structure:
15+
16+```
17+skills-library/{domain}/{skill-name}/
18+├── skill.json # Metadata (name, description, category, risk_level)
19+├── instructions.md # AI agent execution instructions
20+└── tests/ # Optional: skill-specific tests
21+```
22+
23+**Do NOT:**
24+- Create skills outside `skills-library/executable/` or `skills-library/reference/`
25+- Modify existing skill structure without updating registry
26+- Add skills without `skill.json` and `instructions.md`
27+
28+### Registry Auto-Generation
29+
30+The `registry/` directory is AUTO-GENERATED from `skills-library/`:
31+- Never manually edit files in `registry/`
32+- Always run `npm run verify:metrics` after skill changes
33+- Registry regeneration syncs badges and counts across README.md, METRICS.md, docs/directory.md
34+
35+### Risk Level Classification
36+
37+Skills are classified by risk level (defined in `skill.json`):
38+- `Low` - Read-only operations, no external dependencies
39+- `Medium` - Write operations, requires configuration
40+- `High` - External API calls, requires credentials
41+- `Critical` - System-level operations, requires manual review
42+
43+**Rule:** When creating a skill that makes external API calls, uses credentials, or modifies data, always set `risk_level: "High"` or `"Critical"`.
44+
45+## Naming Conventions
46+
47+### Skill IDs
48+- Format: `{domain}_{action}_{target}` (e.g., `sales_analyze_pipeline`)
49+- Use snake_case, all lowercase
50+- Be descriptive but concise (3-5 words max)
51+
52+### File Naming
53+- Skill directories: kebab-case (e.g., `analyze-customer-health/`)
54+- Python files: snake_case (e.g., `analyze_skills.py`)
55+- JavaScript files: kebab-case (e.g., `skills-directory.js`)
56+- Documentation: SCREAMING_SNAKE_CASE for top-level (e.g., `AGENTS.md`), kebab-case for nested
57+
58+### Domain Categories
59+
60+Valid domains (don't invent new ones without discussion):
61+- `ecosystem` - Partner, integration management
62+- `marketing` - Campaigns, content, SEO
63+- `sales` - Pipeline, deals, CRM
64+- `customer_success` - Health, churn, onboarding
65+- `product_ops` - Roadmap, releases
66+- `security` - Security, compliance
67+- `finops` - Billing, revenue
68+- `data` - Analytics, reporting
69+- `engineering` - DevOps, CI/CD
70+- `hr` - Recruiting, onboarding
71+
72+## Testing Patterns
73+
74+### Test Organization
75+
76+```
77+tests/
78+├── unit/ # Fast, isolated tests (< 1s each)
79+├── integration/ # Multi-component tests (< 5s each)
80+└── e2e/ # Full user workflows (< 30s each)
81+```
82+
83+### Required Test Coverage
84+
85+- Minimum: 60% overall coverage
86+- Target: 80%+ coverage
87+- Critical paths (eval_harness, tracer): 90%+ coverage
88+
89+### Testing Commands
90+
91+```bash
92+# Run full suite
1993 pytest tests/ -v
2094
21−# Run specific test suites
22−pytest tests/unit -v -m "not slow" # Unit tests (fast)
23−pytest tests/integration -v -m "not slow" # Integration tests
24−pytest tests/e2e -v # End-to-end tests (slow)
95+# Run fast tests only
96+pytest tests/unit -v -m "not slow"
2597
26−# Run linting and formatting
27−npm run lint # ESLint + Prettier
28−npm run format # Auto-fix formatting
29−black . # Python formatting
30−flake8 . # Python linting
31−isort . # Python import sorting
98+# Run specific domain tests
99+pytest tests/unit/test_dedupe_skills.py -v
100+```
32101
33−# Verify metrics consistency (skill counts, badges)
34−npm run verify:metrics
102+**Rule:** All PRs must pass `pytest tests/ -v` before merging.
35103
36−# Run pre-release checks
37−bash scripts/pre_release_check.sh # Comprehensive verification
104+## Code Quality Standards
38105
39−# Pre-commit hooks
40−pre-commit run --all-files # Run all hooks (includes detect-secrets)
106+### Pre-Commit Hooks (Enforced)
107+
108+The following hooks run automatically on commit:
109+- `detect-secrets` - Blocks commits with credentials
110+- `prettier` - Formats JS/JSON/YAML/Markdown
111+- `black` - Formats Python (if installed)
112+- `flake8` - Lints Python (if installed)
113+- `isort` - Sorts Python imports (if installed)
114+
115+**Rule:** Never use `--no-verify` to skip hooks. Fix the issues instead.
116+
117+### Linting Commands
118+
119+```bash
120+# JavaScript
121+npm run lint # ESLint + Prettier
122+npm run format # Auto-fix formatting
123+
124+# Python (if installed in venv)
125+black .
126+flake8 .
127+isort .
41128 ```
42129
43−## Test Requirements
130+## Workflow Blueprints
44131
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)
132+### Blueprint Schema
49133
50−## Project Structure
134+Blueprints in `registry/blueprints/` follow `schemas/workflow_blueprint.json`:
51135
136+```yaml
137+id: workflow_{name}
138+version: 1.0.0
139+name: 'Human Readable Name'
140+chain_sequence:
141+ - step_id: 'step_1'
142+ skill_id: 'domain_action_target'
143+ action: 'action_name'
144+ input_mapping:
145+ static_values: {}
146+ error_handling:
147+ on_failure: 'stop'
148+ max_retries: 2
52149 ```
53−skene-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
150+
151+**Rule:** All workflow blueprints must validate against schema before committing.
152+
153+## Playbook-Ready Features (Optional but Encouraged)
154+
155+When creating blueprints, consider adding:
156+
157+```yaml
158+icp:
159+ company_size: '50-500'
160+ motion: 'product-led-growth'
161+ priorities: ['reduce_churn', 'increase_nrr']
162+
163+integration_reference:
164+ - type: 'crm'
165+ provider: 'salesforce'
166+ schema_ref: 'registry/integration_schemas/salesforce_fields.yaml'
167+
168+opinionated_prompts:
169+ - step_id: 'step_1'
170+ system_context: 'You are analyzing a PLG motion with 30-day trials...'
171+ input_guidance: 'Focus on trial-to-paid conversion metrics...'
72172 ```
73173
74−## Key Conventions
174+See `registry/integration_schemas/README.md` for schema format.
75175
76−### Skill Structure
176+## Security Rules (Blocking)
77177
78−Every skill follows this pattern:
178+### Never Commit
79179
180+These patterns are BLOCKED by pre-commit hooks:
181+- `.env` files (use `.env.example` for templates)
182+- Files in `.ssh/`, `.aws/`, `secrets/`
183+- Private keys (detected by `detect-private-key` hook)
184+- API keys, tokens, passwords (detected by `detect-secrets`)
185+
186+### Handling Credentials
187+
188+```bash
189+# Good: Reference environment variables
190+DATABASE_URL = os.getenv('DATABASE_URL')
191+
192+# Bad: Hardcoded credentials
193+DATABASE_URL = "postgresql://user:pass@localhost" # pragma: allowlist secret
80194 ```
81−skills-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
195+
196+## AI Agent Boundaries
197+
198+### What AI Agents Can Access
199+
200+- All files except `.ai/internal/` (gitignored, excluded in `.cursorignore`)
201+- `AGENTS.md` for build commands and conventions
202+- All skill schemas in `skills-library/`
203+- Test suites in `tests/`
204+
205+### What AI Agents Should NOT Touch
206+
207+- `skills-library/` content (764 skills, managed by scripts)
208+- `registry/` (auto-generated)
209+- `METRICS.md` (auto-generated)
210+
211+**Rule:** If you modify skill counts or categories, run `npm run verify:metrics` to sync all dependent files.
212+
213+## Development Workflow
214+
215+### Adding a New Skill
216+
217+1. Create directory: `skills-library/executable/{domain}/{skill-name}/`
218+2. Write `skill.json` (follow schema in `schemas/skill_definition.json`)
219+3. Write `instructions.md` (clear execution steps)
220+4. Run `npm run verify:metrics` to update registry
221+5. Add tests in `tests/` if complex logic
222+6. Run `pytest tests/ -v` to verify
223+7. Commit with message: `feat(skills): add {skill-name} to {domain}`
224+
225+### Modifying Existing Skills
226+
227+1. Read the skill's `skill.json` and `instructions.md` first
228+2. Make changes
229+3. Run `npm run verify:metrics`
230+4. Update tests if behavior changed
231+5. Run `pytest tests/ -v`
232+6. Commit with message: `fix(skills): update {skill-name} - {reason}`
233+
234+### Creating Skill Chains
235+
236+1. Identify 2-7 skills to chain together
237+2. Create blueprint in `registry/blueprints/` (or use script: `scripts/recipe_to_blueprint.py`)
238+3. Validate against `schemas/workflow_blueprint.json`
239+4. Document in `docs/SKILL_CHAINS.md` (follow existing format)
240+5. Add integration test in `tests/integration/`
241+6. Commit with message: `feat(chains): add {chain-name} recipe`
242+
243+## Performance Guidelines
244+
245+### Skill Execution
246+
247+- Keep skills atomic (single responsibility)
248+- Skills should complete in < 5 seconds (unless marked with `slow: true`)
249+- Use caching for expensive operations (see `eval_harness/tracer.py` for examples)
250+
251+### Testing Performance
252+
253+- Unit tests: < 1 second each
254+- Integration tests: < 5 seconds each
255+- E2E tests: < 30 seconds each
256+- Mark slow tests with `@pytest.mark.slow`
257+
258+## Common Patterns
259+
260+### Skill Chaining (Data Flow)
261+
262+Skills output data that becomes input for next skill:
263+
264+```yaml
265+- step_id: 'analyze'
266+ skill_id: 'sales_analyze_pipeline'
267+ output: { health_score: 0.85 }
268+
269+- step_id: 'recommend'
270+ skill_id: 'sales_recommend_actions'
271+ input_mapping:
272+ from_step: 'analyze'
273+ field_mappings:
274+ health_score: 'input.score'
85275 ```
86276
87−### Risk Levels
277+### Error Handling
88278
89−Skills are classified by risk level:
279+```yaml
280+error_handling:
281+ on_failure: 'stop' # Options: stop, continue, retry
282+ max_retries: 2
283+ retry_delay_seconds: 5
284+```
90285
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
286+## Commit Message Format
95287
96−### Skill Chain Format
288+Follow Conventional Commits:
97289
98−36 recipes in `docs/SKILL_CHAINS.md` follow this format:
290+```
291+<type>(<scope>): <subject>
99292
293+<body>
294+
295+<footer>
100296 ```
101−Recipe 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}
297+
298+**Types:**
299+- `feat` - New feature (skill, chain, tool)
300+- `fix` - Bug fix
301+- `docs` - Documentation only
302+- `refactor` - Code refactoring (no behavior change)
303+- `test` - Adding or updating tests
304+- `chore` - Maintenance (deps, config, etc.)
305+
306+**Examples:**
107307 ```
308+feat(skills): add customer health scoring to customer_success domain
309+fix(chains): correct data mapping in sales pipeline workflow
310+docs(agents): update AGENTS.md with eval harness instructions
311+```
108312
109−## Boundaries & Constraints
313+## Quick Reference Commands
110314
111−### Do NOT Touch
315+```bash
316+# Setup
317+npm ci
112318
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`
319+# Testing
320+pytest tests/ -v # All tests
321+pytest tests/unit -v -m "not slow" # Fast unit tests
322+pytest tests/integration -v # Integration tests
116323
117−### Always Update Together
324+# Quality
325+npm run lint # ESLint + Prettier
326+npm run format # Auto-fix formatting
327+npm run verify:metrics # Sync skill counts/badges
118328
119−When changing skill counts or categories:
329+# Pre-release
330+bash scripts/pre_release_check.sh # Comprehensive check
120331
121−1. Update skill metadata in `skills-library/`
122−2. Run `npm run verify:metrics` to sync badges and counts
123−3. Verify `README.md`, `METRICS.md`, and `docs/directory.md` updated
332+# Pre-commit
333+pre-commit run --all-files # Run all hooks
334+```
124335
125−### Security
336+## Questions or Unclear Patterns?
126337
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
338+- Read `AGENTS.md` for build commands and testing workflows
339+- Read `CONTRIBUTING.md` for contribution guidelines
340+- Read `ARCHITECTURE.md` for design details
341+- Check existing skills in `skills-library/` for examples
342+- See `docs/SKILL_CHAINS.md` for 36 ready-to-use recipes
131343
132−## Pull Request Checklist
344+## AI Agent Execution Context
133345
134−Before submitting PR:
346+When executing code:
347+- Use `source .venv/bin/activate` for Python commands
348+- Use `npm ci` for fresh dependency install
349+- Always run tests before committing: `pytest tests/ -v`
350+- Check `git status` before and after operations
351+- Use `npm run verify:metrics` after skill changes
135352
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
353+## Emergency Commands
144354
145−## CI/CD
355+If something breaks:
146356
147−GitHub Actions workflow (`.github/workflows/lint-and-build.yml`):
357+```bash
358+# Reset to clean state
359+git status
360+git restore .
361+git clean -fd
148362
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
363+# Rebuild registry
364+npm run verify:metrics
154365
155−## Questions?
366+# Reinstall dependencies
367+rm -rf node_modules .venv
368+npm ci
369+python3 -m venv .venv
370+source .venv/bin/activate
371+pip install -r requirements-dev.txt # if exists
372+```
156373
157−- User documentation: `README.md`, `docs/SKILL_CHAINS.md`
158−- Contributing guidelines: `CONTRIBUTING.md`
159−- Issue templates: `.github/ISSUE_TEMPLATE/`
374+---
375+
376+**Last Updated:** 2026-02-15 (v0.2.0 - Open Source Release)
377+**Maintained By:** Skene Technologies (opensource@skene.ai)
160378
