.cursorrules (deprecated)

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 &quot;not slow&quot;
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 = &quot;postgresql://user:pass@localhost&quot;  # 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 &quot;not slow&quot;        # 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