Kulaxyz/self-learning-skills

self‑learning‑skills – a meta‑skill for AI coding agents

What it is

• A tiny “skill” that can be added to any AI‑driven coding assistant (Claude Code, Cursor, Codex, Aider, Gemini‑CLI, Zed, etc.).
• Its purpose is not to write code itself but to remember the steps an agent discovers during a debugging or deployment session and automatically replay them in future sessions.

Why it matters

• When you work with an LLM‑powered agent you often have to repeat the same “how do I reach the prod DB?” or “what is the deploy command?” discovery process each time you start a new session. This skill captures those hard‑won “golden paths” (including what didn’t work) and stores them where the agent can load them automatically next time, turning ad‑hoc troubleshooting into reusable knowledge.

How it works

1. Recognition – The skill watches the agent’s output for a cue (e.g., you say “remember this” or the agent finally succeeds after several attempts).
2. Capture – It creates a concise, self‑contained description of the procedure (or a single fact) and, if relevant, a note about the failed attempts that were avoided.
3. Reuse – On the next session the stored entry is loaded automatically, either as a new skill (for multi‑step workflows) or as a lightweight note (for single facts). The agent can then apply it without re‑deriving the steps.

Tool‑specific persistence

Agent / tool	Where the knowledge is written	How it is auto‑loaded
Claude Code, Codex, other Agent Skills clients	skills/<name>/SKILL.md	Skill‑matching logic of the Agent Skills framework
Cursor	.cursor/rules/learned/<name>.mdc	Cursor’s rule‑globbing mechanism
Zed, Aider, Gemini‑CLI, any that read AGENTS.md	AGENTS.md (or project‑wide notes)	The file is read on every start

Installation options

• One‑liner via npx (recommended) – Detects installed agents and drops the appropriate files:

  npx skills add kulaxyz/self-learning-skills          # local to current project
  npx skills add kulaxyz/self-learning-skills -g      # global for all projects
  npx skills add kulaxyz/self-learning-skills -a claude-code  # only Claude Code
  

• Claude Code plugin – Add through the built‑in marketplace:

  /plugin marketplace add kulaxyz/self-learning-skills
  /plugin install self-learning@self-learning-skills
  

• Manual copy – Clone the repo and copy the relevant directories/files into the appropriate locations (see the README’s “Manual” section).

Promotion rule (quality guard) A captured entry becomes a skill only if all three conditions are met:

1. The procedure was verified (tests passed, build succeeded, etc.).
2. The failure pattern it avoids is explicitly named.
3. At least one dead‑end that was tried and ruled out is recorded. If any condition is missing, the entry stays a tentative note or is discarded, preventing unverified guesses from polluting the skill set.

Safety considerations

• The skill never writes actual secret values. It only records where a secret can be found (e.g., env‑var name, secret‑manager lookup).
• Because the generated files are meant to be committed, the design deliberately avoids leaking credentials.

Repo layout (quick map)

self-learning-skills/
├─ AGENTS.md                # generic loop description for any AGENTS‑aware tool
├─ skills.sh.json           # manifest for the `npx skills` installer
├─ .claude-plugin/…         # Claude Code marketplace metadata
├─ skills/self-learning/    # core skill files (SKILL.md, template, docs)
└─ .cursor/rules/…          # Cursor rule and learned‑rules folder

Typical use case

1. You start a debugging session with your LLM agent.
2. After several attempts you finally discover the correct command to migrate a database.
3. You say “remember this” (or the skill detects the success automatically).
4. The skill writes a SKILL.md (or .mdc for Cursor) describing the migration steps and the failed attempts.
5. In the next session, the agent loads the skill automatically and can run the migration without you walking through the trial‑and‑error again.

Limitations

• It relies on the underlying agent supporting the Agent‑Skills standard or reading AGENTS.md; tools that do not have such hooks cannot benefit.
• The “recognize the moment” detection is heuristic; if the cue is missed, the knowledge won’t be captured.
• The promotion rule requires a passing verification step, so purely informational facts (e.g., “the prod DB URL is in DATABASE_URL”) will be stored only as lightweight notes, not as executable skills.

License

• MIT © kulaxyz (see LICENSE).