Refactor skills agent

.yarnrc.yml

@@ -1,2 +1,6 @@
-nodeLinker: node-modules
+approvedGitRepositories:
+  - "**"
+
+enableScripts: true
 
+nodeLinker: node-modules

CLAUDE.md

@@ -10,4 +10,4 @@ Checks with `yarn lint` and `yarn test`.
 
 - **[guide.md](docs/guide.md)** - High level guide
 - **[examples.md](../examples.md)** - Practical usage examples for all functions
-- **[functional.md](docs/functional.md)** - Reference docs
+- **[reference.md](docs/reference.md)** - Reference docs

README.md

@@ -71,6 +71,29 @@ export default [
 ]
 ```
 
+## AI & Agentic Development
+
+Pipelean is "Agent-Ready." It ships with built-in **Skills** and an **Agent Persona** to help AI assistants (like Claude, Gemini CLI, or Cursor) write better code using this library.
+
+### 1. Install Skills
+
+The easiest way to install the skills is using the Vercel [agent-skills](https://github.com/vercel-labs/skills) CLI:
+
+```sh
+npx skills add https://github.com/ildella/pipelean/tree/refactor-skills-agent/skills
+```
+
+This will install:
+- `pipelean-core`
+- `pipelean-functional-programming`
+
+### 2. (Experimental) using [skills-npm](https://github.com/antfu/skills-npm/)
+
+```sh
+yarn add -D skills-npm
+yarn skills-npm
+```
+
 ## Documentation
 
   * [Architecture](docs/architecture.md) : The philosophy and design principles.

package.json

@@ -29,7 +29,8 @@
   },
   "files": [
     "src",
-    "SKILL.md",
+    "skills",
+    "pipelean-agent.md",
     "docs"
   ],
   "scripts": {
@@ -40,16 +41,16 @@
     "test": "vitest",
     "coverage": "vitest run --coverage"
   },
-  "packageManager": "yarn@4.13.0+sha512.5c20ba010c99815433e5c8453112165e673f1c7948d8d2b267f4b5e52097538658388ebc9f9580656d9b75c5cc996f990f611f99304a2197d4c56d21eea370e7",
+  "packageManager": "yarn@4.14.1+sha512.64df448055b2d37ba269d7db535a469b8da93f8ef1140c25fd7a83c00a8fbaacb214ca0e02553b92a2c54cef78bb67d0b4817fab02001df0e24fac0faccc3b42",
   "devDependencies": {
-    "@eslint/compat": "2.0.3",
+    "@eslint/compat": "2.0.5",
     "@eslint/js": "9.39.4",
     "@stylistic/eslint-plugin-js": "3.1.0",
-    "@vitest/eslint-plugin": "1.6.14",
+    "@vitest/eslint-plugin": "1.6.16",
     "eslint": "9.39.4",
     "eslint-nostandard": "0.6.0",
     "globals": "15.15.0",
-    "vitest": "4.1.2"
+    "vitest": "4.1.5"
   },
   "stableVersion": "0.5.0"
 }

pipelean-agent.md

@@ -0,0 +1,25 @@
+---
+name: Pipelean Architect
+description: "Expert agent for pragmatic async functional programming, architecture, and enforcing Pipelean standards."
+color: blue
+skills:
+  - modern-javascript-patterns
+  - architecture-patterns
+  - pipelean-core
+  - pipelean-functional-programming
+---
+
+# Pipelean Architect
+
+You are the Pipelean Library expert and a Senior Functional Architect. 
+
+Your goal is to build clean, predictable, and pragmatic asynchronous workflows using the Pipelean standard, and to enforce high-quality architectural patterns.
+
+## Your Workflow
+1. When designing new features, always prioritize functional composition (`pipe`) over imperative nesting.
+2. When iterating over data, use `series` or `scan`. Never use `forEach` or `reduce`.
+3. Handle errors explicitly using Pipelean's error strategies (`failFast`, `failLate`, `collect`, `skip`) rather than scattering `try/catch` blocks randomly.
+4. Utilize your `modern-javascript-patterns` and `architecture-patterns` skills to ensure the code remains idiomatic and loosely coupled.
+5. If you are unsure about the usage of a specific Pipelean function, invoke your `pipelean-core` skill or refer to the local `docs/reference.md` file.
+
+You do NOT guess the library syntax. You consult the skills and documentation.

skills/core/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: "Pipelean Core"
+description: "Pipelean core functionalities for iteration, composition and error management for pure FP in pure Javascript. Use this skill when you need to perform sequential async operations, control flow, error handling, or batch processing using the `pipelean` library"
+---
+
+## Available Functions
+
+1. **`series(items, fn, options)`**: Stateless sequential execution.
+   - Runs `fn` on each item one by one.
+   - `options`: `{ strategy: failFast | failLate | collect | skip, pause: ms, pauseOnErrors: boolean }`
+   - Returns: `{ results, errors, failure }`
+2. **`scan(items, scannerFn, initialValue)`**: Stateful sequential transformation.
+   - `scannerFn(acc, item, index)`
+   - Returns: `{ results, errors, failure }`
+3. **`filter(predicate, items, options)`**: Stateless selection.
+   - Predicate returns truthy to keep, falsy to drop.
+   - Returns original items where predicate matched in `results`.
+4. **`pipe(...fns)`**: Vertical composition.
+   - Chains functions left-to-right.
+   - If any step returns `undefined`, remaining steps are skipped (short-circuit).
+5. **`retry(fn, { attempts, delay })`**: Configurable retry logic.
+6. **`tryCatch(fn, { onStart, onSuccess, onError, onFinally, rethrow })`**: Single function lifecycle hooks.
+
+## Error Strategies
+- **`failFast`**: Stops immediately on first error. `failure: {item, error}`.
+- **`collect`**: Continues processing, collects all errors. `failure: null`. (Default for series)
+- **`failLate`**: Collects all errors, sets `failure: true` at the end if any occurred.
+- **`skip`**: Ignores errors entirely.
+
+**Documentation**: Read full examples in [docs/reference.md](../../docs/reference.md) (or [online](https://github.com/ildella/pipelean/blob/master/docs/reference.md)).

skills/fp-standards/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: "Pipelean Functional Programming"
+description: "General Functional Programming principles and patterns. Use this skill to enforce Pipelean's pragmatic functional programming standards and architectural principles on any codebase."
+---
+
+## Core Philosophy
+1. **No swallowed errors**: Do not swallow errors or inconsistencies (`undefined`, `null`) during array sync/async operations.
+2. **Pragmatism over Purity**: We prefer explicit results over lazy iterables. Execution is eager.
+3. **No Boilerplate**: Avoid writing repetitive `try/catch` or manual iteration loops. Use `series`, `pipe`, or `scan`.
+
+## Coding Rules
+- **No `Array.prototype.forEach`**: ForEach swallows promises and doesn't handle async errors correctly. Use `series` instead.
+- **No `Array.prototype.reduce`**: Reduce is often unreadable and mixes state with iteration. Use `scan` for stateful accumulation.
+- **Eager Execution**: Do not yield generators or use lazy execution unless strictly required by a specific framework boundary. Get a structured report `{ results, errors, failure }` back immediately.
+- **Undefined Short-Circuit**: When composing operations (via `pipe`), returning `undefined` signals dropping the item (selection/filtering).
+
+**Documentation**: Read the full architectural philosophy in [docs/architecture.md](../../docs/architecture.md) (or [online](https://github.com/ildella/pipelean/blob/master/docs/architecture.md)).