Chat2Skill

Automatically learn reusable skills and project memory from your assistant conversations.

After each session, Chat2Skill analyzes the conversation for corrections, preferences, constraints, and project facts, distills them into local memory and SKILL.md files, and injects the relevant ones into your future sessions. It is domain-general: coding workflows are the first-class integration target, while the same mechanism works for support, research, writing, operations, sales, education, and other assistant domains that produce usable transcripts.

Works best with Claude Code, Codex, and Cursor. Other agents can use Chat2Skill when they support lifecycle hooks or can run the included CLI scripts.

What the Algorithm Produces

Chat2Skill extracts reusable project context in two stores:

Atomized skills: focused SKILL.md files for one interaction preference, procedure, constraint, success pattern, or failure pattern.
Project memory: project facts, decisions, procedures, and warnings stored in the local SQLite database and retrieved dynamically.
Project skill: a synthesized PROJECT_SKILL.md that merges active atomized skills into a compact project-level instruction file for human review and response-guard policy.

A skill is not meant to remember one transcript. It captures a generalizable behavior that would change future assistant behavior across similar situations.

Core Concepts

Concept	Meaning
Conversation	Recent assistant/user messages for one session. Long sessions are trimmed to the latest analysis window.
Signal	Evidence that something should be learned: correction, explicit constraint, negative feedback, or stable behavioral preference.
Analysis	A structured diagnosis of what went wrong or what worked, including failure type, root cause, confidence, and proposed action.
Proposal	The create/edit/discard decision for a skill candidate.
Memory item	Evidence extracted before materializing a skill, such as failure cause, failure memory, success, or constraint.
Skill	A validated, actionable `SKILL.md` with metadata such as confidence, evidence count, language, replay score, and status.
Response guard	Optional frontmatter policy for hard wording constraints, such as evidence-based deterministic wording.

Learning Loop

+---------------------------------------------------------+
| 1. Retrieve relevant project memory and active skills    |
+---------------------------+-----------------------------+
                            |
                            v
+---------------------------------------------------------+
| 2. Inject retrieved project memory + skills into prompt  |
+---------------------------+-----------------------------+
                            |
                            v
+---------------------------------------------------------+
| 3. Assistant works; user accepts, corrects, or constrains |
+---------------------------+-----------------------------+
                            |
                            v
+---------------------------------------------------------+
| 4. Extract learning signals at session end               |
+---------------------------+-----------------------------+
                            |
                            v
+---------------------------------------------------------+
| 5. Create / edit / discard atomized skill candidates     |
+---------------------------+-----------------------------+
                            |
                            v
+---------------------------------------------------------+
| 6. Validate, replay, merge, and store active skills      |
+---------------------------+-----------------------------+
                            |
                            v
+---------------------------------------------------------+
| 7. Rebuild PROJECT_SKILL.md and update local profile     |
+---------------------------+-----------------------------+
                            |
                            +------------- back to step 1

The algorithm is a feedback loop, not a one-shot workflow. Each completed session can change project memory and the skill bank; the next session retrieves from those updated local stores; later user feedback reinforces, edits, rejects, or ages out earlier context.

There is still a single extraction pass inside the loop. That pass is:

recent conversation + existing skills + profile
  -> detect signals
  -> analyze root cause
  -> propose create/edit/discard
  -> generate SKILL.md
  -> quality gate
  -> judge
  -> optional replay
  -> active/rejected/no-action result

The LLM path uses Proposer, Generator, and Judge style stages. When no LLM is available, the loop still runs with keyword detection and template-based generation.

Loop Layers

Chat2Skill has three nested loops:

Session learning loop: retrieve skills before work, observe user feedback during work, extract or update skills after work, then use the updated skill bank next time.
Candidate refinement loop: if the judge rejects a generated skill, feed the judge weakness back into generation and retry up to two times.
Maintenance loop: score active skills by utilization, replay effectiveness, recency, and overlap; merge near-duplicates and archive old weak skills instead of letting the prompt grow forever.

How it works

your machine                                Chat2Skill cloud
─────────────────────────────────────       ─────────────────────────
Stop hook ──► response guard ──► continue on violation
     │
     └────► queue ──► worker ─────────────► POST /v1/extract
                          │                 (stateless algorithm,
   ~/.chat2skill/ ◄───────┘                  your own LLM credential)
   skills + profile + history     ◄──────── skill + profile + replay
                                            POST /v1/project-skill
UserPromptSubmit hook ◄── local retrieval   (project skill + detailed skills)

Your data stays local. Skills, profile, and history live in ~/.chat2skill/ (SQLite + markdown files). The cloud runs the extraction algorithm statelessly and stores nothing.
Bring your own credential. Extraction LLM calls support an API key or a short-lived OAuth bearer token acquired by the host. The credential is sent with each request, used in memory, never persisted or logged server-side. Without a usable credential, the server falls back to lower-quality heuristics.
Response guard. When a project skill contains a high-confidence deterministic wording constraint, the Stop hook checks the final assistant message locally. The learned rule is evidence-based: verified facts must use definitive wording; evidence gaps must name the missing source material, data, record, document, log, test, command output, or code and the next validation step. The guard only reads explicit response_guard frontmatter, never prose examples or code identifiers. The default guard mode is strict: every violation is continued for correction. Set CHAT2SKILL_RESPONSE_GUARD=false to disable the guard.
Cost. A typical extraction makes ~4 LLM calls on your key (detect, analyze, generate, judge); replay validation against your history adds up to 5 more. Conversations are windowed (last ~40 messages) so long sessions stay cheap. Extraction only triggers when a correction/constraint signal is detected, not on every session.

Install

1. Install the plugin

Normal users should install Chat2Skill from their agent's plugin marketplace. Do not clone this repository just to run scripts/chat2skill_init.py.

Codex:

codex plugin marketplace add rxacc/chat2skill
codex

Then open /plugins, select the chat2skill marketplace, and install chat2skill.

Claude Code:

claude plugin marketplace add https://github.com/rxacc/chat2skill
claude plugin install chat2skill@chat2skill

Cursor:

Open Settings -> Plugins, paste this repository URL, and install the Chat2Skill plugin.

Chat2Skill hooks run Python code, so the machine running the agent must have Python 3 available as python3, python, or py -3. If Python is missing, the plugin cannot initialize local storage or run retrieval/learning.

After the plugin is installed and trusted, the first hook run initializes the local data directory:

macOS/Linux: ~/.chat2skill/
Windows: %USERPROFILE%\.chat2skill\

The initialization creates the config file, SQLite database, and skills directory:

config.json
c2s.db
skills/

2. Configure local settings

Edit the config file created under the local data directory. Chat2Skill calls the stateless learn API for extraction and stores returned project memory, conversations, skills, and profiles in ~/.chat2skill/c2s.db. Prompt retrieval runs locally from that database and always injects retrieved project memory plus relevant skills. Rendered skill files stay under ~/.chat2skill/skills/.

If you are developing from a source checkout or using the CLI scripts manually, you can initialize the same local data directory yourself:

python3 scripts/chat2skill_init.py

From a source checkout on Windows:

python .\scripts\chat2skill_init.py

From a source checkout, manual setup is equivalent:

mkdir -p ~/.chat2skill
cp config.example.json ~/.chat2skill/config.json
# edit ~/.chat2skill/config.json: set api_url and an llm credential

Without a source checkout, create the same config file yourself using one of the JSON examples below.

For OpenAI-compatible models, write ~/.chat2skill/config.json like this:

{
  "api_url": "https://api.chat2skill.com",
  "user_id": "alice",
  "memory": {
    "target_model": "generic",
    "token_budget": 4000,
    "memory_ratio": 0.6,
    "skill_top_k": 6,
    "prompt_memory_top_k": 12,
    "prompt_memory_min_score": 0.3,
    "prompt_skill_min_score": 0.2,
    "learn_memory_top_k": 40,
    "learn_skill_top_k": 20
  },
  "llm": {
    "api_key": "your-openai-compatible-api-key",
    "provider": "openai",
    "base_url": null,
    "model": "gpt-4.1"
  },
  "embedding": {
    "provider": "local_transformers",
    "model": "Snowflake/snowflake-arctic-embed-xs",
    "dimensions": 384
  }
}

For DeepSeek, write ~/.chat2skill/config.json like this:

{
  "api_url": "https://api.chat2skill.com",
  "user_id": "alice",
  "memory": {
    "target_model": "generic",
    "token_budget": 4000,
    "memory_ratio": 0.6,
    "skill_top_k": 6,
    "prompt_memory_top_k": 12,
    "learn_memory_top_k": 40,
    "learn_skill_top_k": 20
  },
  "llm": {
    "api_key": "your-deepseek-api-key",
    "provider": "openai",
    "base_url": "https://api.deepseek.com",
    "model": "deepseek-chat"
  },
  "embedding": {
    "provider": "local_transformers",
    "model": "Snowflake/snowflake-arctic-embed-xs",
    "dimensions": 384
  }
}

For Anthropic, use the native provider adapter rather than Anthropic's OpenAI compatibility layer:

{
  "api_url": "https://api.chat2skill.com",
  "user_id": "alice",
  "llm": {
    "api_key": "your-anthropic-api-key",
    "provider": "anthropic",
    "base_url": "https://api.anthropic.com/v1/",
    "model": "claude-sonnet-5"
  },
  "embedding": {
    "provider": "local_transformers",
    "model": "Snowflake/snowflake-arctic-embed-xs",
    "dimensions": 384
  }
}

The server also infers anthropic from an api.anthropic.com base URL for older configs that do not yet contain llm.provider.

For an OAuth-enabled LLM, put the actual access token in llm.access_token:

{
  "llm": {
    "access_token": "paste-your-oauth-token-here",
    "provider": "anthropic",
    "base_url": "https://api.anthropic.com/v1/",
    "model": "claude-sonnet-5"
  }
}

The inline value is checked before the environment variable and token file, so no environment variable is required. auth_type: "oauth" is still accepted explicitly. access_token_env and llm.access_token_file remain compatibility fallbacks; the file is read for each hook invocation so a host-managed token refresh is picked up. Chat2Skill does not implement provider-specific browser login or store refresh tokens.

Claude Code's correct OAuth command is claude setup-token. It walks through OAuth authorization and prints a one-year CLAUDE_CODE_OAUTH_TOKEN; it does not save the token. However, Chat2Skill's default architecture sends llm.access_token to the remote api_url, so a Claude subscription token must not be pasted into this config for remote extraction. Anthropic documents these tokens for Claude Code and native Anthropic applications, and prohibits third-party services from routing Claude subscription credentials on behalf of users. Use an Anthropic Console API key or an approved workload identity for remote Chat2Skill extraction. A local Claude Code/Agent SDK adapter is required to keep the subscription token on the host.

See the Claude Code authentication guide for claude setup-token and the credential-use policy.

For OpenAI/Codex, the provider login is:

# Browser OAuth flow.
codex login

# Headless/device-code OAuth flow.
codex login --device-auth

# Verify the active mode.
codex login status

Codex stores and refreshes its ChatGPT credentials locally in ~/.codex/auth.json. Do not copy that file or its token into Chat2Skill's remote llm.access_token field. ChatGPT-managed Codex OAuth is for Codex account usage, while the OpenAI Platform API path used by the remote extractor uses an OpenAI API key. A local Codex adapter is required to use the former without forwarding the credential to api.chat2skill.com.

For a remote OpenAI-compatible embedding endpoint, replace the embedding block with:

{
  "embedding": {
    "api_key": "your-embedding-api-key",
    "base_url": "http://127.0.0.1:8080/v1",
    "model": "BAAI/bge-large-en-v1.5"
  }
}

These are the equivalent environment variables. You only need environment variables if you prefer shell config or need to override the JSON file.

Local Admin UI

Chat2Skill includes a local-only management page for reviewing and managing stored project memory and skills. This section is for source checkout or manual CLI users; ordinary plugin installation does not require running this server.

From a source checkout on macOS, Linux, or WSL:

python3 scripts/chat2skill_admin.py

From a source checkout on Windows PowerShell:

python .\scripts\chat2skill_admin.py

From an installed Codex plugin, every system must first enter the installed plugin directory. The path includes the marketplace name, plugin name, and version.

macOS, Linux, or WSL installed plugin:

cd ~/.codex/plugins/cache/chat2skill/chat2skill/
python3 scripts/chat2skill_admin.py

Windows PowerShell installed plugin:

cd "$env:USERPROFILE\.codex\plugins\cache\chat2skill\chat2skill\"
python .\scripts\chat2skill_admin.py

The command initializes .chat2skill if needed, prints a one-time URL such as http://127.0.0.1:8765/?token=..., and opens it in your browser by default. If the browser does not open, copy the printed URL exactly; the token is required.

Useful options:

python3 scripts/chat2skill_admin.py --port 8766
python3 scripts/chat2skill_admin.py --no-open

The admin server binds to 127.0.0.1 by default and reads/writes only the local ~/.chat2skill/c2s.db database. It can:

list Chat2Skill projects discovered from the local database
view and rebuild the project-level PROJECT_SKILL.md
search, edit, archive, activate, and delete atomized skills
search, edit, archive, activate, and delete project memories
inspect the source skill snapsh

chat2skill-plugin-runtime

AI Analysis

Install

README

Chat2Skill

What the Algorithm Produces

Core Concepts

Learning Loop

Loop Layers

How it works

Install

1. Install the plugin

2. Configure local settings

Local Admin UI