simp-skill: a Claude Code skill for courtship analysis, chat parsing and confession prep

What simp-skill actually does, and who it is written for

simp-skill is a skill package for Claude Code, not a standalone application. It installs into a Claude Code skills directory and adds a /simp command family. The README is explicit about the audience: people who already know who they like and cannot work out how to say it. The tagline is 不教 PUA，只教真心, and the design principles repeat that no manipulative or insecurity-inducing scripts are generated.

The feature table lists ten capabilities, and they fall into three groups. Interpretation: signal reading from chat logs, MBTI inference, interaction timing. Production: message and confession drafting in two tones, sweet and strategic. Management: a per-person profile with an append-only event stream, progress scoring and versioned backups. The crisis section covers eleven named scenarios, from C-1 (clear rejection) through C-11 (the other person has started a new relationship).

The framing matters more than the feature list. This is a tool for someone who is already emotionally invested and wants help expressing it, not a lead-generation or matchmaking system. There is no account, no server, no shared database.

How the skill is structured: prompts, tools and a per-person dossier

The repository root contains SKILL.md, a prompts/ directory, a tools/ directory and a docs/ directory. SKILL.md is the entry point Claude Code reads; prompts/ holds the instruction text behind each subcommand; tools/ holds the Python scripts the skill calls out to.

State lives under crushes/{slug}/. The README's directory diagram defines each file. profile.md holds basic information and a portrait, with YAML frontmatter plus prose. state.md is a current snapshot: stage, score, recent signals, next step. events.jsonl is append-only and, per the README, never deleted. interactions.jsonl records meetings, messages and reply timing. strategy.md holds the personalised plan. meta.json holds stage, score, mode and event count. snapshots/ stores daily snapshots for fast recovery across sessions, and versions/ stores historical backups.

The memories/ subtree separates raw inputs by type: chats/, social/ and photos/. That split is the actual data flow. A parser reads a file from one of those directories, emits an analysis document, and the skill reads the analysis rather than the raw export. The README points to docs/MEM-SYS.md for the read and write protocol, which is worth reading before you write anything into events.jsonl by hand.

Installing simp-skill into Claude Code and running a first analysis

The README gives two install paths. A global install makes the skill available in every project; a project-level install scopes it to one repository. Both are a single git clone.

git clone https://github.com/BeamusWayne/simp-skill ~/.claude/skills/simp-skill

For a project-scoped copy, the README shows the same clone targeting .claude/skills/simp-skill instead. After cloning, the skill is invoked as a slash command inside Claude Code. The main menu is /simp; creating a profile is /simp create 小美.

/simp create 小美
/simp analyze
/simp progress

The first command builds the dossier directory. The second reads recent signals and reports the stage. The third gives a progress assessment and a next step. The README does not document what happens if you run /simp analyze before any events exist, so expect an empty or thin report on a fresh profile.

The optional Python tools need a chat export first. The README says to export WeChat or QQ history and place it under crushes/{name}/memories/chats/, then run the parser with the target's name.

python3 tools/chat_parser.py 导出的聊天记录.txt 小美
python3 tools/chat_parser.py 导出的聊天记录.txt 小美 --output crushes/xiaomei/memories/chats/analysis.md

Supported inputs are WeChat TXT, HTML and CSV (the README names WeChatMsg and PyWxDump as export tools), QQ TXT and MHT, and generic JSON. The photo analyzer needs Pillow installed separately.

pip install Pillow
python3 tools/photo_analyzer.py --dir crushes/xiaomei/memories/photos --target 小美

That command extracts a shooting timeline from EXIF data. The README describes one of its outputs as detecting possible date records, which is an inference from timestamps and locations, not a fact about the person.

The dossier model is the strongest idea and the biggest commitment

Most advice tools are stateless: you ask, you get an answer, nothing persists. simp-skill does the opposite. Every interaction can append to events.jsonl, bump a score in meta.json, and roll into a daily snapshot. The README describes snapshots as existing for fast recovery across sessions, which tells you the intended use is a long-running relationship, not a one-off question.

That design has a real payoff. A confession draft generated after three months of recorded signals is different from one generated cold, because strategy.md and state.md carry context the model would otherwise have to be told again. The backup and rollback commands reinforce this: skill_writer.py supports --action backup, --action versions and --action rollback --slug xiaomei --version v2.

The cost is equally real. You are maintaining a structured record about a specific person, including their chat messages, their social media posts and the timestamps of their photos. The README's fourth design principle says all analysis is local and chat logs are never uploaded to any server. That is a claim about the tool's behaviour, and it holds only as long as you run it locally and do not paste the outputs into a hosted model yourself. The privacy boundary is your machine, not the project.

Where simp-skill is the wrong tool

The project is honest about one boundary and silent about several others. C-1 in the crisis list is clear rejection, and the stated handling is how to accept gracefully plus when a restart is possible. That is the right posture, but it also means the tool is not built to help you pursue someone who has said no. If that is your situation, the correct output is the one the README already gives, and there is nothing further to configure.

The second limitation is input quality. The parsers consume exports from third-party tools such as WeChatMsg and PyWxDump. The README lists supported formats but does not describe how the parser behaves on a partially exported file, a group chat mixed into a direct conversation, or messages containing only images. A signal report built on a truncated export is a confident-sounding report about the wrong data.

The third is the MBTI feature. Inferring a type from chat descriptions and then selecting one of sixteen pursuit strategies is a heuristic dressed as a category. The README presents it as inference, which is fair, but the output format makes it look more settled than it is.

Finally, there is no release history in the repository metadata, and the last push was on 2026-07-09. That is recent enough that the code is not abandoned, but the README does not document a rollback path for a bad skill upgrade, only for profile versions.

How it differs from general-purpose chat analysis and from the project it credits

The README credits colleague-skill as inspiration. The difference is domain: colleague-skill models workplace relationships, where the constraints are professional and the goal is usually coexistence. simp-skill models courtship, where the goal is a change in the relationship and the failure modes are rejection, coldness and the friend zone. The eleven crisis codes are the clearest expression of that shift. There is no equivalent of C-11 (the other person has started a new relationship) in a workplace tool.

The other comparison is against using Claude Code directly with no skill. You can paste a chat log into a model and ask what it means. What you lose is the persistence layer: the append-only event stream, the score history, the daily snapshots and the versioned rollback. You also lose the fixed crisis taxonomy, which forces the advice into one of eleven named situations instead of a generic response. Whether that structure helps or distorts is the real question, and the README's own framing suggests it is meant to be a scaffold for someone who is already unsure what to say.

Licence, maintenance and what an upgrade costs

simp-skill is MIT licensed. The README states it plainly and adds no additional terms. In practice that means you can fork it, modify the prompts, and redistribute, provided the licence text travels with it. It does not mean the project takes responsibility for how you use the output. Nothing here is legal advice, and the more relevant question is not copyright but data protection: chat logs and photo metadata about a third party who has not consented to being analysed are a different category of file from ordinary source code, regardless of what the licence permits.

On maintenance, the last push was on 2026-07-09, so the repository is not archived and not stale. There are no retrieved releases, which means upgrades happen by pulling the default branch. That has a concrete consequence for anyone with existing profiles: the tools write into crushes/{slug}/, and a pull that changes the schema of meta.json or events.jsonl could affect profiles created before it. The README documents rollback for profile versions via skill_writer.py, not for the skill code itself, so keeping your own git history of the checkout is the safer habit.

Editorial conclusion

Adopt simp-skill if you already run Claude Code, are comfortable keeping a structured per-person dossier under crushes/, and want the signal interpretation and crisis playbooks rather than generic advice. Do not adopt it if you would be uncomfortable storing chat exports and photo EXIF data on disk, or if the person has already clearly refused you: the project's own C-1 entry is about accepting that gracefully, not restarting. Before you commit, verify three things: that your Claude Code version loads skills from ~/.claude/skills/, that python3 tools/chat_parser.py accepts your export format, and that you have read docs/PRD.md, which is where the project states its ethical boundaries.

Frequently asked questions

Official sources

1. BeamusWayne/simp-skill on GitHub
2. Issues
3. License: MIT
4. README