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.
chat2skill-plugin-runtime · DSH Hub
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:
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.
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:
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.
# 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:
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.
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 snapshot used for the current project skill version
For frontend development, run the Vite shell separately:
cd admin/frontend
npm install
npm run dev
Keep the Python admin server running on 127.0.0.1:8765 while using the Vite
dev server; Vite proxies /api requests to the Python backend.
Environment variable
JSON key
Default
Description
CHAT2SKILL_API_URL
api_url
https://api.chat2skill.com
Chat2Skill API endpoint used for stateless learn/extract calls.
CHAT2SKILL_MEMORY_TARGET_MODEL
memory.target_model
generic
Reserved renderer target for API-compatible payloads.
CHAT2SKILL_MEMORY_TOKEN_BUDGET
memory.token_budget
4000
Total prompt-injection token budget for memory plus skills.
CHAT2SKILL_MEMORY_MEMORY_RATIO
memory.memory_ratio
0.6
Fraction of retrieval budget initially allocated to memory.
CHAT2SKILL_MEMORY_SKILL_TOP_K
memory.skill_top_k
6
Maximum detailed skills injected by local prompt retrieval.
OPENAI_API_KEY
llm.api_key
unset
Your OpenAI-compatible LLM API key.
OPENAI_BASE_URL
llm.base_url
null
Optional OpenAI-compatible base URL. Use null for OpenAI; use https://api.deepseek.com for DeepSeek.
CHAT2SKILL_LLM_AUTH_TYPE
llm.auth_type
api_key
Set to oauth to send an OAuth bearer token instead of an API key.
CHAT2SKILL_LLM_ACCESS_TOKEN
llm.access_token
unset
Optional OAuth bearer-token fallback. An inline llm.access_token is checked first.
CHAT2SKILL_LLM_ACCESS_TOKEN_FILE
llm.access_token_file
unset
Host-managed JSON or text file containing the current OAuth access token.
CHAT2SKILL_LLM_ACCESS_TOKEN_FIELD
llm.access_token_field
access_token
Dot-separated JSON field used when reading CHAT2SKILL_LLM_ACCESS_TOKEN_FILE.
CHAT2SKILL_LLM_PROVIDER
llm.provider
inferred
Chat provider. Supported values are openai and anthropic.
CHAT2SKILL_MODEL
llm.model
gpt-4.1
Model used for detect/analyze/generate/judge calls.
CHAT2SKILL_USER_ID
user_id
system username
Base namespace for local skills and profile data. Project-specific skills use __project__.
CHAT2SKILL_RESPONSE_GUARD
unset
strict
Stop response guard mode. true enables strict blocking; false disables it. Advanced modes are adaptive, block-once, warn-only, and off. Structured response_guard.mode: evidence_based_terms allows explicit evidence-gap disclosure while still blocking unsupported hedging.
Agent notes: Claude Code
For local development, load the plugin for one session:
claude --plugin-dir ~/plugins/chat2skill
Claude Code installs hooks from the root hooks/hooks.json entrypoint. The
host-specific copy is also kept at hooks/claude-hooks.json, and
${CLAUDE_PLUGIN_ROOT} resolves to the installed plugin directory — no path
setup needed.
Agent notes: Codex
Codex installs hooks from the root hooks/hooks.json entrypoint. The
host-specific copy is also kept at hooks/codex-hooks.json. Codex installs
register the configurable blocking Stop response guard. The hook
entrypoints initialize the local data home on first hook run:
macOS/Linux: ~/.chat2skill/
Windows: %USERPROFILE%\.chat2skill\
For local development or manual hook generation:
git clone https://github.com/rxacc/chat2skill.git ~/plugins/chat2skill
cd ~/plugins/chat2skill && ./install.sh
install.sh refreshes known local plugin cache directories with agent-specific
hook files and creates the config file if missing.
Agent notes: Cursor
Cursor supports native plugins with .cursor-plugin/plugin.json.
In Cursor:
Open Settings -> Plugins.
Paste this repository URL into Search or Paste Link:
https://github.com/rxacc/chat2skill
The Cursor plugin uses:
.cursor-plugin/hooks.json for Cursor-format hooks.
${CURSOR_PLUGIN_ROOT} for installed plugin paths.
.cursor/rules/chat2skill.mdc as an always-on project rule.
sessionStart to provide the current project skill when Cursor
accepts hook context.
stop to learn from the newest Cursor agent transcript under
~/.cursor/projects/*/agent-transcripts/.
Important Cursor limitation: Cursor plugins do support hooks and skills,
but Cursor's beforeSubmitPrompt hook currently cannot inject dynamic
per-prompt context into the model. For prompt-specific retrieval in
Cursor, use the chat2skill skill. From a source checkout, you can also run:
python3 scripts/retrieve_for_prompt.py "your current task"
Agent notes: OpenCode
Run OpenCode from a checkout of this repository. opencode.json loads
.opencode/plugins/chat2skill.mjs, which calls the same retrieval CLI and
adds relevant snippets to the system prompt.
The adapter uses Harness agent/pre-step for retrieval and
agent/turn-stopping for the shared response guard and learning. It invokes
the existing local Python runtime, so the algorithm project and its API do not
need a change for this integration. See
adapters/deepseek-harness/README.md
for environment overrides.
Agent notes: Other agents
For manual integrations from a source checkout, point hook-capable agents at:
# after a session: learn from the newest transcript
python3 scripts/update_from_transcript.py --latest
# before a task: print a prompt snippet with relevant skills
python3 scripts/retrieve_for_prompt.py "refactor the auth module"
For agents that only support repository instructions, copy or keep the
matching adapter file:
Cursor: .cursor/rules/chat2skill.mdc
Windsurf/Cascade: .windsurf/rules/chat2skill.md
Cline: .clinerules/chat2skill.md
GitHub Copilot: .github/copilot-instructions.md
Kiro: .kiro/steering/chat2skill.md
Generic agents/Aider: AGENTS.md
Agent Support
Chat2Skill needs two capabilities for the full automatic loop:
Learn after a session: a stop/session-end hook that can run
scripts/hook_stop.py.
Retrieve before work: a prompt/session-start hook or skill workflow
that can inject or load the output of scripts/retrieve_for_prompt.py.
Enforce hard wording rules: a stop/session-end hook with access to
the final assistant message that can run scripts/hook_stop_response_guard.py.
The default strict mode continues every violation for correction;
CHAT2SKILL_RESPONSE_GUARD=false disables it. Evidence-based rules
distinguish verified conclusions from missing-evidence disclosures.
The repository currently ships native final-response guard registration for
Claude Code, Codex, Cursor, and DeepSeek Harness. The other adapters below are partial: a rule,
retrieval plugin, or manual CLI path does not provide final-response
interception by itself.
Agent
Current support
Notes
Claude Code
Native plugin marketplace
Full automatic support through .claude-plugin/marketplace.json, root hooks/hooks.json, hooks/claude-hooks.json, the chat2skill skill, UserPromptSubmit, Stop learning, and Stop response guard.
Codex
Native plugin/local installer
Automatic retrieval, Stop learning, and configurable Stop response guarding through .codex-plugin/plugin.json, root hooks/hooks.json, hooks/codex-hooks.json, and local cache refresh through install.sh.
DeepSeek Harness
Native Cordis bundle
Add the Chat2Skill repository root with `dsh plugin --profile add
. The adapter uses agent/pre-stepfor retrieval,agent/turn-stopping` for the shared guard and learning, and the current Chat2Skill algorithm API without algorithm-project changes.
Cursor
Native plugin + project rule
Supported through .cursor-plugin/plugin.json, .cursor-plugin/hooks.json, .cursor/rules/chat2skill.mdc, and the chat2skill skill. Stop learning works from Cursor transcripts, and the response guard runs when Cursor provides final response text. Dynamic per-prompt context injection is limited by Cursor's current beforeSubmitPrompt hook behavior.
OpenCode
Server plugin + command
opencode.json loads .opencode/plugins/chat2skill.mjs, which calls retrieve_for_prompt.py and appends relevant snippets to the system prompt. No final-response guard is registered.
GitHub Copilot
Repository instructions
.github/copilot-instructions.md provides the CLI workflow. No final-response guard is registered.
Kimi Code CLI
Skills/manual hooks
The project ships no native Kimi hook manifest. Manual hook configuration can call the shared scripts.
Windsurf / Cascade
Project rule
.windsurf/rules/chat2skill.md provides instructions only. No final-response guard is registered.
Kiro
Steering rule
.kiro/steering/chat2skill.md provides instructions only. No final-response guard is registered.
Cline
Project rule
.clinerules/chat2skill.md provides instructions only. No final-response guard is registered.
Aider / generic agents
AGENTS.md
AGENTS.md gives portable instructions for agents that read repository guidance.
Gemini CLI
Manual integration
A dedicated extension manifest and final-response guard registration are not included.
Google Antigravity
Manual integration
A dedicated plugin manifest and final-response guard registration are not included.
Continue
Manual/partial
Rules, prompts, and MCP are useful, but no verified lifecycle hook path for the full Chat2Skill loop is included.
Roo Code
Manual/legacy
Use the CLI scripts only unless your local fork exposes compatible hooks.
Skills are namespaced per project (__project__), so what
you learn in one repo doesn't leak into another.
Privacy
Stop-hook transcripts are sent to the Chat2Skill API for stateless
analysis, processed in memory, and not persisted server-side. Server logs
contain metadata only (session id, error type) — never message content or
API keys or OAuth access tokens.
Prompt retrieval does not call the cloud API. It loads top-K project
memory and skills from local ~/.chat2skill/c2s.db, applies the configured
budget, and injects the compact result into the prompt.
Agent system prompts, environment banners, and tool noise are stripped
locally before upload (see scripts/chat2skill/transcripts.py).
To stop all uploads, remove the Stop hook or unset api_url.