This skill is a lightweight operating guide: it does not bundle Python source code, but instead instructs the code agent to fetch and invoke coc-cardwright Python CLI from GitHub. The model handles character editing, character arc, stat tendencies, and background writing; point budgets, occupational skills, caps, derived values, and rendering must be validated by the CLI.
Engine repository
First read this directory's ENGINE_REPO.txt to get the Python CLI repository address. The default is:
https://github.com/tanis90/coc-cardwright.git
If ENGINE_REPO.txt does not exist or the repository address is unavailable, confirm the repository address with the user; do not guess a new GitHub URL.
Install or reuse the CLI
Prefer reusing the existing coc-cardwright / coc_generator project in the current workspace. If there is none, clone from the repository pointed to by ENGINE_REPO.txt .
It is recommended to place it in the current workspace's tools directory, for example:
git clone <ENGINE_REPO> .coc-cardwright
python -m pip install -e .coc-cardwright
If the user does not want a global install, create a project-local virtual environment and then install:
python -m venv .coc-cardwright-venv
.coc-cardwright-venv/Scripts/python -m pip install -e .coc-cardwright
On Windows you can also use:
py -3 -m pip install -e .coc-cardwright
After installation, prefer calling the coc command; if PATH has not refreshed or coccannot be found, enter the repository and invoke it as a Python module:
python -m coc_generator --help
What the CLI can do
The CLI is this skill's rules entry point. It can do four kinds of things:
jobs: List all available Chinese occupation names, returning a JSON array.job "<职业名>": View a given occupation's occupation point formula, Credit Rating range, occupational skills, and skill descriptions.verify <json>: Validate the character JSON, returningvalid/errors/warnings/derived. This is a step that must be passed before generating a character sheet.render <json> -o <html>: After JSON validation passes, render a double-sided A4 printable HTML character sheet, color mode by default.render <json> --style mono -o <html>: Render pure black-and-white print mode, suitable for low-ink or non-color printing scenarios.render <json> --blank-luck -o <html>: When rendering, leave the Luck value blank on the sheet, suitable for players rolling Luck on the spot; the JSON must still contain a validluckand pass validation.
When unsure about commands or parameters, first call the CLI's built-in help rather than guessing parameters:
coc --help
coc verify --help
coc render --help
coc job --help
If coc is unavailable, invoke it in the Python repository directory:
python -m coc_generator --help
python -m coc_generator verify --help
python -m coc_generator render --help
python -m coc_generator job --help
Common examples:
coc jobs
coc job "私家侦探"
coc verify character.json
coc render character.json -o character_card.html
coc render character.json --style mono -o character_card_mono.html
coc render character.json --blank-luck -o character_card_blank_luck.html
Character editing goals
A good sheet is not a patchwork of "occupation + points + background paragraphs," but a person the player can immediately pick up and roleplay. When generating, first build the character's inner tension, then translate that tension into stats and sheet fields.
Each sheet must have at least the following four layers:
- Surface identity: who he appears to be now, what he does for a living, what others call him.
- Desire: what he actively wants to obtain, such as reputation, atonement, truth, freedom, or his family's safety.
- Wound or fear: why he is stuck in place, such as shame, debt, class anxiety, survivor's guilt, or fear of losing control.
- Arc question: the question the scenario is most likely to force him to answer, such as "Would he sacrifice innocents for the truth?" or "Can he admit that he is not always right?"
Writing should be concrete; avoid vague phrases like “calm and rational but kind inside,” “carrying a mysterious past,” or “fate draws him into events.” Every important setting should be grounded as much as possible in visible objects, specific people, specific places, playable habits, or testable choices.
Socratic character interview
When the user gives only a broad concept, or says “you decide,” do not immediately write a complete character. First use Socratic questioning to help the user discover the character’s core. Ask 3 to 5 short questions each round, and the questions should force the user to make choices, not fill out a setting sheet.
Advance the question order according to screenwriting logic:
- External goal: What does the character want right now?
- Internal lack: Why must he have this?
- False belief: What has he always believed that keeps him trapped?
- Relationship pressure: Who is most able to force him to expose his true self?
- Costly choice: What is he willing to sacrifice for the goal, and what would he never sacrifice?
- Arc question: Which judgment will the story force him to change?
First round: Capture the character seed
When the user’s concept is very vague, prioritize these questions:
- What does he most want to preserve, obtain, or prove right now?
- What about himself is he most afraid others will discover?
- If this card serves only one investigation style, does it lean toward investigation, social, combat, academic, medical, technical, or survival?
- Do you want him at the start of the story to be more like “someone actively pursuing the truth,” or “someone dragged into events by the past”?
Second round: Create internal contradiction
Once identity and goal are established, probe the contradictions:
- What does he say he believes, but often betray through his actions?
- Whom has his strongest ability once harmed, or what has it made him lose?
- Would he hide the truth for someone important? If so, how would he explain it to himself?
- What kind of person does he most look down on? Does he also have a bit of that trait himself?
Third round: Establish back-side fields
Back-side fields affect roleplay more than stats; use questions to draw them out:
important_person: Whose one sentence is most likely to make him lose his composure? What claim does this person have on him?important_place: What place, once destroyed, sold, or polluted, would make him act irrationally?important_item: Which item on him is not the most expensive, yet is the one he cannot lose? What does it prove, and what does it conceal?belief: What sentence does he use to convince himself to keep going when in danger?trait: What small action or habit can the players at the table repeatedly perform?scar: Which failure or injury is he still paying for now?madness: When pressure comes, does he control, avoid, appease, attack, go numb, or repeatedly confirm something?
Fourth round: Compress the arc into a choice
Before writing the card, confirm the arc with one multiple-choice question:
- If the truth would harm someone important, will he make the truth public, modify the truth, or destroy the evidence?
- If a precious thing is proven to come from a lie, will he keep it, return it, or destroy it with his own hands?
- If a place of great significance hides mythic pollution, will he protect the location, protect people, or protect his own reputation?
- If his strength fails, will he ask teammates for help, or double down on the old method?
Questioning method
- Do not ask more than 5 questions at once.
- When the user gives few answers, proactively offer 2 to 3 optional directions, but preserve room for user customization.
- When the user does not want to interact, you may ask and answer yourself, but in the final summary you must state, "The core of the role I adopted is..."
- Every question must be able to affect at least one field or value; if a question will not change the sheet, do not ask it.
Values and narrative aligned
Decide the character arc first, then decide the values, rather than piling up strengths first. Attributes and skills should become evidence for the character.
- High EDU/INT: explain how he acquired knowledge, and the blind spots that knowledge brings. High intelligence does not mean always being right; it can manifest as overexplaining, being unable to trust intuition, or habitually treating people as problems to be handled.
- High POW: explain what belief he relies on to hold himself up. The stronger the belief, the more you need to design something that will shake it.
- High APP/Credit Rating: explain how he is seen in society, and also explain what kind of dignity he is afraid of losing.
- High DEX/STR/CON/SIZ: write physical advantages into occupation, scars, habits, or fighting style; do not leave physical attribute values hanging in the air.
- Low attributes should also have drama: low STR may make him rely on tools and negotiation; low APP may make him used to being underestimated; low POW may make him develop an elaborate avoidance strategy in fear.
- Occupational skills show "what he makes a living from"; interest skills show "where he truly spends his time." The difference between the two is usually the character's tension.
- Credit Rating is not a pure point tax. It should reflect class, disposable resources, social thresholds, and his confidence when facing authority.
- Weapons, carried items, and assets should serve the character; do not just list generic equipment. Ideally, one object can simultaneously explain occupation, relationships, or psychological defenses.
If values and narrative conflict, prioritize changing one of them so they match. For example, if the background says "clumsy study-bound scholar," then you should not give unexplained high DEX and a large number of melee skills; if high DEX is genuinely needed, clearly state that it comes from bookbinding, cartography, surgery, magic, or some other specific training.
Field writing requirements
By default, all writable parts of the character sheet must be filled; do not leave empty strings, empty arrays, or fields containing only placeholders, unless the user explicitly requests a blank sheet.
Must be written completely:
basic: name, player, occupation, age, gender, hometown, era. When the player is unknown, use the user's provided form of address; if still unknown, use "Player".weapons: provide at least one attack or self-defense method consistent with the character. Non-combat characters may also have a cane, small knife, boxing, or carried tools; do not force in a gun that does not fit their identity.items: write 5 to 8 carried items; each one should feel like something this person would bring.assets: cash, spending level, total assets, and asset details must all be filled in and consistent with Credit Rating.friends: write 2 to 4 contacts, preferably including at least one relationship tension that the Keeper can use.experienced_modules: for a new character, you may write "has not yet experienced a formal module"; for an experienced character, write specific experiences.backgroundAll 9 fields of must be written: appearance description, thoughts and beliefs, significant person, meaningful place, treasured possession, traits, wounds and scars, mental disorders, personal description.
Backstory fields are the roleplaying engine
The backstory fields on the back are not decorative text; they are buttons the player presses when making choices at the table. When writing these fields, prioritize "how will the player act after seeing this item" rather than "does this passage look good".
Every key background item must carry a table function:
beliefBeliefs and convictions: give the player a principle for making decisions. It must be able to be challenged in a crisis; for example, "testimony is more reliable than blood" becomes a conflict when a relative lies.important_personSignificant people: give the Keeper a relationship that can be pressured. Write clearly the love, debt, rivalry, misunderstanding, or control, and avoid writing only "a very important friend."important_placeMeaningful places: give the character a place of belonging or a weak spot. The location should be able to be polluted, taken away, burned down, sold, or have its secrets revealed.important_itemTreasured possessions: give the player a tangible psychological anchor. The object is best if it can be brought out, hidden, exchanged, damaged, or mistaken in a scene.traitTraits: give the player a small repeatable action, way of speaking, or decision preference to perform. It must be able to affect the method of investigation, not just be an adjective.scarWounds and scars: give the character a trace from the past that is still demanding payment. It can be a physical scar, professional stain, family rift, public humiliation, or failed case.madnessMental symptoms: give the fear state a performable expression. A new character does not have to already be insane, but you should write the reaction pattern under stress, such as insomnia, compulsive tidying, repeatedly checking door locks, or freezing when hearing a certain kind of sound.appearanceAppearance description: give the other players performance clues they can grasp at first glance, including posture, worn clothing, speech pauses, personal smell, and hand habits.descriptionPersonal introduction: string the above items into a person who can be played in a campaign, rather than writing a separate resume.
When designing the back-page fields, first do a "relationship stress test":
- If a significant person gets into trouble, betrays the character, or asks for help, what will the character sacrifice?
- If an important place exposes traces of the Mythos, will the character protect it, destroy it, or flee?
- If a treasured possession is proven to come from a lie, will the character admit the truth or maintain their self-narrative?
- If belief conflicts with survival, to what extent will the character hold on?
- If a trait causes trouble during an investigation, how will it make teammates see the character?
Have at least 3 back-page fields implicate each other, forming a playable triangle. For example: the treasured possession given by a significant person comes from a meaningful place, and the scar was left precisely to protect that person. In this way, every time the player touches the object, returns to the location, or meets the contact, they will face the same arc question again.
Back-page fields should constrain the stats in reverse:
- If the significant person is a high-society patron, Credit Rating, Charm/Persuade/Psychology, or Assets should reflect it.
- If the important place is a library, newspaper office, clinic, dock, theater, church, or police station, the occupation and core skills should explain why the character belongs there.
- If the treasured possession is a weapon, tool, medical case, negative, ledger, amulet, or old key, the corresponding skill, item, or investigation hook should appear.
- If the scar comes from violence, explain the combat skill, low POW, cautious trait, or specific weapon; if the scar comes from a failed case, explain the Law, Psychology, Spot Hidden, Credit change, or contact.
- Mental symptoms cannot just write atmosphere; they must affect how the player investigates, socializes, flees, fights, or is alone.
If the back-page fields and stats conflict, do not just change the text to paper over it. Either adjust the stats, or write a reasonable source for the conflict and turn it into part of the arc.
Quality standards for background fields:
appearance: Write an appearance, posture, clothing, or small action that can be drawn.belief: Write beliefs that can guide choices, not abstract slogans.important_person: Write clearly about relationships, debts, or conflicts.important_place: Write why this place cannot be lost.important_item: Write the object's origin and emotional function.trait: Write playable habits or flaws.scar: It can be a physical scar or a social wound, but it must be specific.madness: New characters must also fill this in; you may write a potential stress response or "no clear symptoms yet, but will... when..."; do not leave it blank.description: Use a 120 to 220 Chinese-character paragraph to summarize the character, covering identity, desire, wound, arc question, and the hook for entering the investigation.
The writing style should be restrained, playable, and detailed. Do not write every field as a novel monologue; a character sheet needs clues that players and the Keeper can quickly grasp.
Workflow
- Collect or reasonably complete the investigator concept: name, era, occupation, age, personality, background, and play role.
- When information is insufficient, first conduct a Socratic character interview, asking 3 to 5 questions per round that create choice pressure; only ask and answer yourself when the user does not want to interact.
- Write a brief editorial proposal: surface identity, desire, wound or fear, false belief, arc question, the triangular relationship of the back-page fields, and stat tendencies. Unless the user only wants mechanical generation, do not skip this step.
- Install or locate
coc-cardwrightCLI, then first runcoc --helpto confirm the command is available. - When choosing an occupation, run
coc jobs; before allocating occupational points, runcoc job "<职业名>"to look up the occupation formula, credit rating range, and occupational skills. - Translate the editorial proposal into characteristics, credit rating, occupational skills, interest skills, weapons, items, and assets. Occupation names and skill names must use the Chinese names returned by the CLI; avoid English names or self-made translations.
- Draft the JSON character file according to the structure below. All writable fields must be filled in completely, and check whether each background entry can tie back to the character arc.
- Run
coc verify <json>. Ifvalidis nottrue, modify the JSON according to the error message and validate again; when correcting values, do not break the character logic already established. - Only after validation passes, run
coc render <json> -o <html>, generating printable double-sided A4 HTML. Use color mode by default; when the user requests black-and-white, pure black-and-white, low ink, or suitability for an ordinary printer, usecoc render <json> --style mono -o <html>; when the user requests rolling Luck live, leaving Luck blank, or rolling Luck at the start, use--blank-luck. When the user explicitly requests both sets, output two HTML files, one color and one black-and-white. - When replying to the user, provide the JSON path, HTML path, rendering style, character arc summary, how the values support the character, and point usage.
Rules reminders
- The total of the eight characteristics must be exactly 480.
- Each characteristic must be an integer between 20 and 80.
- Luck does not count toward the 480 point buy and ranges from 15 to 90.
- Occupational points can only be spent on that occupation's occupational skills, and credit rating also counts toward occupational point expenditure.
- Interest points can be spent on any skill, but cannot be spent on Cthulhu Mythos.
- The final value of an occupational skill cannot exceed 80.
- The final value of an interest skill cannot exceed 60.
- Credit rating must fall within the range allowed by the occupation.
- The Cthulhu Mythos cannot be increased through normal point allocation.
These reminders are only memory aids; the final rules are subject to the result of coc verify .
JSON Structure
Use the following structure as the file contract:
{
"basic": {
"name": "角色姓名",
"player": "玩家名",
"job": "职业名",
"age": 32,
"gender": "男",
"hometown": "故乡",
"era": "1920s"
},
"attributes": {
"str": 50,
"con": 50,
"dex": 60,
"app": 55,
"pow": 50,
"siz": 65,
"edu": 70,
"int": 80
},
"luck": 60,
"credit_rating": 25,
"skill_allocations": {
"pro": {},
"interest": {}
},
"weapons": [],
"items": [],
"assets": {
"cash": "",
"consumption": "",
"assets": "",
"items": ""
},
"mythos": 0,
"friends": "",
"experienced_modules": "",
"background": {
"appearance": "",
"belief": "",
"important_person": "",
"important_place": "",
"important_item": "",
"trait": "",
"scar": "",
"madness": "",
"description": ""
}
}
Output Requirements
When the user requests generation of a character sheet, by default create the file in the current workspace; if the user specifies a directory, write to the specified directory. File names should be clear and readable, for example investigator.json and investigator_card.html。
If the user only wants the character data, stop after generating and validating the JSON; if the user requests a printable character sheet, also render HTML. When no style is specified, output the default color HTML; when the user mentions black-and-white printing, pure black and white, ink saving, photocopy-friendly, or an ordinary laser printer, output --style mono black-and-white HTML; when the user mentions rolling Luck at the table, leaving Luck blank, or setting Luck at the start of the session, add during rendering --blank-luck, but the luck in the JSON still needs to be legal to pass validation; when the user requests "both color and black-and-white", render two HTML versions from the same JSON.
Acceptance Checklist
Check each item before completion:
coc verifyreturnsvalid: true。- The rendering style of the printable HTML meets the user's requirements: default color, use
--style monofor black-and-white requirements, and output two versions for dual-version requirements. - When the user requests rolling Luck at the table, the HTML uses
--blank-luckleaves Luck blank; the validation rules still require legalluck。 - in the JSON. All writable fields in the character sheet are filled in, with no meaningless blanks, template placeholders, or generic filler.
descriptioncan explain identity, desire, wound, and arc question within one paragraph.- At least 3 numeric choices can find evidence from the background, such as high EDU, low POW, Credit Rating, core skills, or weapon choices.
- At least 3 background entries can be contradicted by the numbers or items, such as treasured possession, significant person, scar, interest skill, or asset details.
- Occupational skills should resemble a way of making a living, and interest skills should resemble private obsessions; the two should not be completely homogeneous.
- Items, assets, and contacts can provide usable hooks for the Keeper.
- The character has problems that can change during the scenario, rather than a already-completed static persona.