Learn

中文文档

Learn is an AI skill for Cursor, Claude Code, and Codex: it records repeated successful actions, auto-creates reusable skills (SKILL.md), and prefers those learned skills for future similar tasks.

Features

• Record: After a task succeeds, write a task summary and step outline to .learn/patterns.json in the project.
• Merge: If the same kind of task is detected, merge into an existing pattern and increment success count.
• Generate skills: When a pattern has succeeded at least three times, create learned-<slug>/SKILL.md in the tool’s skills directory (4th similar request uses the skill; e.g. .cursor/skills/learned-<slug>/ for Cursor).
• Prefer learned skills: At task start, if the current request matches an existing learned skill’s taskSummary, follow that skill first.
• User-triggered: You can say “save that as a skill” (or “把刚才的操作存成技能”) to create or merge a pattern and generate a skill when appropriate.

Installation

Via npm (recommended)

Install into Cursor, Codex, or Claude Code skills directory (one or all):

# Install to Cursor
npx learn-skill-ai install --cursor

# Install to Codex
npx learn-skill-ai install --codex

# Install to Claude Code
npx learn-skill-ai install --claude

# Install to all three
npx learn-skill-ai install --all

Restart the IDE after installing so it picks up the skill. When you run the install from a project root, you will be prompted: Input your name (name you want AI to call you). Enter a preferred form of address (e.g. “小明” or “Tom”); it is saved to .learn/config.json. The AI will then greet you with that name at task start (e.g. “尊敬的xxx” / “Dear xxx”) and use it when saving a skill (e.g. “好的，xxx～” / “Okay, xxx!”). You can skip by pressing Enter, or set LEARN_USER_NAME when running non-interactively. From a project root, each tool also gets a rule so the agent is forced to run Learn after every successful task: Cursor → .cursor/rules/learn-after-task.mdc; Claude Code → .claude/rules/learn-after-task.md; Codex → Learn section appended to project AGENTS.md.

You can also install the package globally and then run the install command:

npm install -g learn-skill-ai
learn-skill-ai install --cursor
# or
learn-skill-ai install --all

Skill paths per tool

Tool	Install target path
Cursor	~/.cursor/skills/learn/ (Windows: %USERPROFILE%\.cursor\skills\learn\)
Codex	$CODEX_HOME/skills/learn/ (default ~/.codex/skills/learn/)
Claude Code	~/.claude/skills/learn/ (Windows: %USERPROFILE%\.claude\skills\learn\)

Manual install

Copy the repo’s learn/ directory to the path above for your tool, or to a project-level skills dir (e.g. .cursor/skills/learn/ inside a Cursor project). The directory should contain:

learn/
├── SKILL.md
└── reference.md

Usage

No extra config after install. In any project where Learn is installed:

1. Normal use: Ask the AI for tasks as usual; it will record patterns on success and, after the same kind of task succeeds at least three times, auto-create .cursor/skills/learned-<slug>/SKILL.md (4th similar request uses the skill; or the equivalent path for your tool).
2. Auto-reuse: When a new request matches an existing learned skill’s taskSummary, the AI will prefer that skill and may say something like “Using learned skill learned-xxx”.
3. Save on demand: Say “save that as a skill” or “把刚才的操作存成技能” to create or merge a pattern and generate a skill when the threshold is met.

Learning data lives in the current project: .learn/patterns.json and .cursor/skills/learned-*/ (or the tool’s equivalent).

Optional config

• Success threshold: Skills are created when the same pattern has succeeded at least 3 times (4th request uses the skill). To change this, edit learn/SKILL.md or learn/reference.md (search for successCount >= 3).
• Committing .learn/:
  • Don’t commit: Add .learn/ to .gitignore so learning stays local.
  • Commit: Commit .learn/ and .cursor/skills/learned-*/ (or equivalent) to share learned skills with the team.

Storage and naming

• Pattern store: .learn/patterns.json; see learn/reference.md for the schema.
• Learned skills: .cursor/skills/learned-<slug>/SKILL.md (or tool equivalent). <slug> is derived from the task summary: lowercase letters, numbers, hyphens only; total length including learned- ≤ 64 chars; numeric suffix on conflict (e.g. learned-add-pytest-2).
• Vs hand-written skills: All Learn-generated skills use the learned- prefix for directory and frontmatter name, so they’re easy to tell apart.

More format details and edge cases: learn/reference.md.

Example snippets

patterns.json example:

{
  "version": 1,
  "patterns": [
    {
      "id": "add-pytest-and-run",
      "taskSummary": "Add pytest to the project and run tests",
      "stepsSummary": ["Check deps", "Add pytest", "Write/run tests"],
      "successCount": 2,
      "lastDoneAt": "2025-02-02T12:00:00Z",
      "skillCreated": true
    }
  ]
}

Generated SKILL.md location and frontmatter:

• Path: .cursor/skills/learned-add-pytest-and-run/SKILL.md
• Frontmatter example: name: learned-add-pytest-and-run, description: ... (what it does and when to use it, third person, ≤1024 chars).

Testing

1. Local install script

From the repo root:

# Show help (no install)
node bin/install.js

# Install to Cursor skills dir (copies learn/ to ~/.cursor/skills/learn)
node bin/install.js install --cursor

Then check the target dir for SKILL.md and reference.md, e.g.:

• Cursor: %USERPROFILE%\.cursor\skills\learn\ (Windows) or ~/.cursor/skills/learn/ (macOS/Linux).

2. npm commands

Check package contents (for development or before publishing):

From the repo root, run npm test. The script checks that learn/SKILL.md exists in the package; if it passes, the package is complete and ready to publish or install.

Test the install command like a user (either option is enough):

• Option A: npx (no global install, quick try)
  From any directory run: npx learn-skill-ai install --cursor
  This fetches and runs the package once, copying learn/ into Cursor’s skills directory. Same effect as a user installing from npm and running learn-skill-ai install --cursor.

• Option B: npm link (simulate a global install while developing locally)

  1. From this repo root run: npm link
  2. Then from any directory run: learn-skill-ai install --cursor
     This “links” the current project as the global learn-skill-ai command so you can test the install. When done, run npm unlink -g learn-skill-ai to remove the link.

3. End-to-end in Cursor

1. Install Learn into Cursor (e.g. npx learn-skill-ai install --cursor) and restart Cursor.
2. Open a project and give the AI a clear task (e.g. “Add pytest to this project and run tests”), wait for success.
3. Repeat the same kind of task (or say “do that again”); then check:
   • Project root has .learn/patterns.json;
   • If the same pattern succeeded ≥2 times, .cursor/skills/ has learned-<slug>/SKILL.md.
4. Or say “save that as a skill” and confirm a skill and .learn/patterns.json are created.

Scope and dependencies

• Supported: Cursor, Claude Code, Codex; skill format follows each tool’s SKILL.md conventions (e.g. Cursor create-skill).
• Scope: Learning is per project (.learn/ and learned-* skills). Personal-level learning could be added later by reading/writing user-level learned-* dirs.

License and contributing

This repo implements the Learn skill for Cursor, Claude Code, and Codex. To change behavior or naming, edit learn/SKILL.md or learn/reference.md.

---