Two files, one repository

SkeneTechnologies/skene-cookbook ships 2 formats across 2 indexed files. The question worth asking is whether the second one says anything the first does not.

CompareAGENTS.md ↔ .cursorrules

A · AGENTS.md · 661 words B · .cursorrules · 1320 words

What each file covers, counted
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

+328 added−110 removed50 unchanged13.2% identical

SkeneTechnologies/skene-cookbook · AGENTS.md

@@ −1 @@

1# AGENTS.md

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

5## Quick Context

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)

12## Build & Test Commands

14```bash

15# Install dependencies

16npm ci

18# Run tests (full suite)

19pytest tests/ -v

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)

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

33# Verify metrics consistency (skill counts, badges)

34npm run verify:metrics

36# Run pre-release checks

37bash scripts/pre_release_check.sh # Comprehensive verification

39# Pre-commit hooks

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

41```

43## Test Requirements

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)

50## Project Structure

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```

74## Key Conventions

76### Skill Structure

78Every skill follows this pattern:

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```

87### Risk Levels

89Skills are classified by risk level:

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

96### Skill Chain Format

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

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

3## Project Context

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

10## Architecture Patterns

12### Skill Structure (Non-Negotiable)

14Every skill MUST follow this exact structure:

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```

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`

28### Registry Auto-Generation

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

35### Risk Level Classification

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

43**Rule:** When creating a skill that makes external API calls, uses credentials, or modifies data, always set `risk_level: "High"` or `"Critical"`.

45## Naming Conventions

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)

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

58### Domain Categories

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

72## Testing Patterns

74### Test Organization

76```

77tests/

78├── unit/ # Fast, isolated tests (< 1s each)

79├── integration/ # Multi-component tests (< 5s each)

80└── e2e/ # Full user workflows (< 30s each)

81```

83### Required Test Coverage

85- Minimum: 60% overall coverage

86- Target: 80%+ coverage

87- Critical paths (eval_harness, tracer): 90%+ coverage

89### Testing Commands

91```bash

92# Run full suite

93pytest tests/ -v

95# Run fast tests only

96pytest tests/unit -v -m "not slow"

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

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

3+## Project Context

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