| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 56 | 23 | 0% |
| Commands | 7 | 8 | 2 | 41% |
| Section tags | 10 | 5 | 1 | 63% |
What each file covers
Sections
0 shared · 56 only in A · 23 only in B- − 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
- + 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?
Commands
7 shared · 8 only in A · 2 only in B- − 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
- + pytest tests/integration -v -m "not slow"
- + pytest tests/e2e -v
- pytest tests/ -v
- pytest tests/unit -v -m "not slow"
- npm run lint
- npm run format
- black
- npm ci
- npm run verify:metrics
Section tags
10 shared · 5 only in A · 1 only in B- − types
- − testing-strategy
- − database
- − performance
- − agent-behaviour
- + build
- setup
- test
- lint-format
- code-style
- architecture
- git-pr
- security
- dependencies
- deployment
- do-not
Line diff
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
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
@@ −1 +1 @@
1−# Cursor Rules for skene-cookbook
1+# AGENTS.md
22
3−## Project Context
3+AI agent instructions for `skene-cookbook` - 764 skill library with 36 skill chain recipes.
44
5−**Repository:** skene-cookbook - 764 AI skill library with 36 skill chain recipes
6−**Package:** @skene/skills-directory v0.2.0
7−**License:** MIT
5+## Quick Context
6+
7+**Repository:** Single npm package `@skene/skills-directory` v0.2.0
88 **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)
911
10−## Architecture Patterns
12+## Build & Test Commands
1113
12−### Skill Structure (Non-Negotiable)
13−
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−
9114 ```bash
92−# Run full suite
15+# Install dependencies
16+npm ci
17+
18+# Run tests (full suite)
9319 pytest tests/ -v
9420
95−# Run fast tests only
96−pytest tests/unit -v -m "not slow"
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)
9725
98−# Run specific domain tests
99−pytest tests/unit/test_dedupe_skills.py -v
100−```
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
10132
102−**Rule:** All PRs must pass `pytest tests/ -v` before merging.
33+# Verify metrics consistency (skill counts, badges)
34+npm run verify:metrics
10335
104−## Code Quality Standards
36+# Run pre-release checks
37+bash scripts/pre_release_check.sh # Comprehensive verification
10538
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 .
39+# Pre-commit hooks
40+pre-commit run --all-files # Run all hooks (includes detect-secrets)
12841 ```
12942
130−## Workflow Blueprints
43+## Test Requirements
13144
132−### Blueprint Schema
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)
13349
134−Blueprints in `registry/blueprints/` follow `schemas/workflow_blueprint.json`:
50+## Project Structure
13551
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
14952 ```
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...'
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
17272 ```
17373
174−See `registry/integration_schemas/README.md` for schema format.
74+## Key Conventions
17575
176−## Security Rules (Blocking)
76+### Skill Structure
17777
178−### Never Commit
78+Every skill follows this pattern:
17979
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
19480 ```
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'
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
27585 ```
27686
277−### Error Handling
87+### Risk Levels
27888
279−```yaml
280−error_handling:
281− on_failure: 'stop' # Options: stop, continue, retry
282− max_retries: 2
283− retry_delay_seconds: 5
284−```
89+Skills are classified by risk level:
28590
286−## Commit Message Format
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
28795
288−Follow Conventional Commits:
96+### Skill Chain Format
28997
290−```
291−<type>(<scope>): <subject>
98+36 recipes in `docs/SKILL_CHAINS.md` follow this format:
29299
293−<body>
294−
295−<footer>
296100 ```
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:**
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}
307107 ```
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−```
312108
313−## Quick Reference Commands
109+## Boundaries & Constraints
314110
315−```bash
316−# Setup
317−npm ci
111+### Do NOT Touch
318112
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
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`
323116
324−# Quality
325−npm run lint # ESLint + Prettier
326−npm run format # Auto-fix formatting
327−npm run verify:metrics # Sync skill counts/badges
117+### Always Update Together
328118
329−# Pre-release
330−bash scripts/pre_release_check.sh # Comprehensive check
119+When changing skill counts or categories:
331120
332−# Pre-commit
333−pre-commit run --all-files # Run all hooks
334−```
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
335124
336−## Questions or Unclear Patterns?
125+### Security
337126
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
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
343131
344−## AI Agent Execution Context
132+## Pull Request Checklist
345133
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
134+Before submitting PR:
352135
353−## Emergency Commands
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
354144
355−If something breaks:
145+## CI/CD
356146
357−```bash
358−# Reset to clean state
359−git status
360−git restore .
361−git clean -fd
147+GitHub Actions workflow (`.github/workflows/lint-and-build.yml`):
362148
363−# Rebuild registry
364−npm run verify:metrics
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
365154
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−```
155+## Questions?
373156
374−---
375−
376−**Last Updated:** 2026-02-15 (v0.2.0 - Open Source Release)
377−**Maintained By:** Skene Technologies (opensource@skene.ai)
157+- User documentation: `README.md`, `docs/SKILL_CHAINS.md`
158+- Contributing guidelines: `CONTRIBUTING.md`
159+- Issue templates: `.github/ISSUE_TEMPLATE/`
378160
