diff --git a/.claude/skills/create-skill/SKILL.md b/.claude/skills/create-skill/SKILL.md new file mode 100644 index 0000000..06bbd39 --- /dev/null +++ b/.claude/skills/create-skill/SKILL.md @@ -0,0 +1,205 @@ +--- +name: Skill Creator +description: > + Guidance for creating effective Claude Code skills (.skill packages). + Use when the user wants to create, build, design, or iterate on a skill — + including writing SKILL.md files, bundling scripts/references/assets, + initializing new skills, packaging skills, or improving existing ones. + Triggers on requests like "create a skill", "make a new skill", + "build a skill for X", "package this skill", or "improve my skill". +--- + + +# Skill Creator + +## About Skills + +Skills are modular, self-contained packages that extend Claude's capabilities +by providing specialized knowledge, workflows, and tools. They transform Claude +from a general-purpose agent into a specialized agent equipped with procedural +knowledge that no model can fully possess. + +### What Skills Provide + +- **Specialized workflows** — Multi-step procedures for specific domains +- **Tool integrations** — Instructions for working with specific file formats or APIs +- **Domain expertise** — Company-specific knowledge, schemas, business logic +- **Bundled resources** — Scripts, references, and assets for complex and repetitive tasks + +## Core Principles + +### Concise is Key + +The context window is a public good. Skills share it with everything else Claude +needs: system prompt, conversation history, other skills' metadata, and the +actual user request. + +Default assumption: Claude is already very smart. Only add context Claude doesn't +already have. Challenge each piece of information: "Does Claude really need this +explanation?" and "Does this paragraph justify its token cost?" + +Prefer concise examples over verbose explanations. + +### Set Appropriate Degrees of Freedom + +Match specificity to the task's fragility and variability: + +- **High freedom** (text-based instructions): Multiple approaches valid, decisions + depend on context, heuristics guide the approach. +- **Medium freedom** (pseudocode or scripts with parameters): Preferred pattern + exists, some variation acceptable, configuration affects behavior. +- **Low freedom** (specific scripts, few parameters): Operations are fragile and + error-prone, consistency is critical, specific sequence must be followed. + +Think of Claude as exploring a path: a narrow bridge with cliffs needs specific +guardrails (low freedom), while an open field allows many routes (high freedom). + +## Anatomy of a Skill + +``` +skill-name/ +├── SKILL.md (required) +│ ├── YAML frontmatter metadata (required) +│ │ ├── name: (required) +│ │ ├── description: (required) +│ │ └── compatibility: (optional, rarely needed) +│ └── Markdown instructions (required) +└── Bundled Resources (optional) + ├── scripts/ - Executable code (Python/Bash/etc.) + ├── references/ - Documentation loaded into context as needed + └── assets/ - Files used in output (templates, icons, fonts, etc.) +``` + +### SKILL.md (required) + +- **Frontmatter (YAML)**: `name` and `description` fields (required). Only these + are read by Claude to determine when the skill triggers — be clear and + comprehensive. The `compatibility` field is for environment requirements but + most skills don't need it. +- **Body (Markdown)**: Instructions and guidance. Only loaded AFTER the skill + triggers. + +### Bundled Resources (optional) + +**Scripts (`scripts/`)** — Executable code for tasks requiring deterministic +reliability or that are repeatedly rewritten. + +**References (`references/`)** — Documentation loaded as needed into context. +Keep SKILL.md lean; move detailed reference material, schemas, and examples here. +If files are large (>10k words), include grep search patterns in SKILL.md. + +**Assets (`assets/`)** — Files used in output, not loaded into context (templates, +images, icons, boilerplate code, fonts). + +### What to NOT Include + +Do NOT create extraneous files like README.md, INSTALLATION_GUIDE.md, +QUICK_REFERENCE.md, CHANGELOG.md, etc. The skill should only contain information +needed for an AI agent to do the job. + +## Progressive Disclosure + +Skills use a three-level loading system: + +1. **Metadata** (name + description) — Always in context (~100 words) +2. **SKILL.md body** — When skill triggers (<5k words) +3. **Bundled resources** — As needed (unlimited; scripts can run without reading) + +Keep SKILL.md body under 500 lines. Split content into separate files when +approaching this limit. Reference split files from SKILL.md with clear +descriptions of when to read them. + +### Disclosure Patterns + +**Pattern 1: High-level guide with references** — Keep overview in SKILL.md, +link to detail files loaded only when needed. + +**Pattern 2: Domain-specific organization** — Organize content by domain +(e.g., `references/finance.md`, `references/sales.md`) so only relevant content +is loaded. + +**Pattern 3: Conditional details** — Show basic content, link to advanced +content loaded only when the user needs those features. + +Guidelines: +- Avoid deeply nested references — keep one level deep from SKILL.md +- Structure longer reference files with a table of contents at the top + +## Skill Creation Process + +Follow these steps in order, skipping only with clear reason: + +### Step 1: Understand the Skill with Concrete Examples + +Skip only when usage patterns are already clearly understood. + +Ask the user for concrete examples of how the skill will be used: +- "What functionality should the skill support?" +- "Can you give some examples of how this skill would be used?" +- "What would a user say that should trigger this skill?" + +Avoid overwhelming users — start with the most important questions. + +### Step 2: Plan the Reusable Skill Contents + +Analyze each example by considering how to execute from scratch and identifying +what scripts, references, and assets would help with repeated execution. + +Establish a list of reusable resources: scripts, references, and assets. + +### Step 3: Initialize the Skill + +Run the init script to generate a template skill directory: + +``` +scripts/init_skill.py --path +``` + +Creates: skill directory, SKILL.md template with TODO placeholders, example +resource directories with sample files. + +Skip if iterating on an existing skill. + +### Step 4: Edit the Skill + +Remember the skill is for another Claude instance to use. Include beneficial, +non-obvious information. + +For design patterns, consult: +- `references/workflows.md` — Sequential workflows and conditional logic +- `references/output-patterns.md` — Template and example patterns + +**Implementation order:** +1. Start with reusable resources (`scripts/`, `references/`, `assets/`) +2. Test added scripts by running them +3. Delete unused example files from initialization +4. Update SKILL.md + +**Writing guidelines:** Always use imperative/infinitive form. + +**Frontmatter:** +- `name`: The skill name +- `description`: Primary triggering mechanism. Include what the skill does AND + specific triggers/contexts. All "when to use" info goes here (not in body). + +**Body:** Instructions for using the skill and its bundled resources. + +### Step 5: Package the Skill + +``` +scripts/package_skill.py +``` + +Optional output directory: +``` +scripts/package_skill.py ./dist +``` + +The script validates (frontmatter, naming, description, file organization) then +packages into a `.skill` file (zip with .skill extension). Fix any validation +errors and re-run if needed. + +### Step 6: Iterate + +After real usage, notice struggles or inefficiencies, identify needed updates, +implement changes, and test again. diff --git a/.claude/skills/create-skill/references/.gitkeep b/.claude/skills/create-skill/references/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.claude/skills/create-skill/scripts/.gitkeep b/.claude/skills/create-skill/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/bookmarks/the end of an empire/characters/.gitkeep b/docs/bookmarks/the end of an empire/characters/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/bookmarks/the rise of the ruler/characters/.gitkeep b/docs/bookmarks/the rise of the ruler/characters/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/ck3-modding/.gitkeep b/docs/ck3-modding/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/lore/mistborn-universe.md b/docs/lore/mistborn-universe.md new file mode 100644 index 0000000..5f2f0e0 --- /dev/null +++ b/docs/lore/mistborn-universe.md @@ -0,0 +1,193 @@ +# The Mistborn Universe + +## Setting + +The world of Scadrial is a planet shaped and sustained by two opposing cosmic +forces — Preservation and Ruin. For a thousand years it was ruled by the +immortal Lord Ruler, a tyrant who reshaped the planet itself during his +Ascension at the Well of Ascension. His reign is known as the Final Empire. + +### The Final Empire +#### Bookmarks 1 & 2 + +The Lord Ruler's world is one of ash and darkness. Ash falls constantly from +the sky, belched from the ashmounts — massive volcanic peaks scattered across +the landscape. Plant life is brown and withered. The sun is red and dim. At +night, thick rolling mists blanket the land, and most people fear to go +outside. + +Society is divided into two rigid classes: + +- **Nobility** — Descendants of the Lord Ruler's original allies. They live in + keeps and manors, hold political and economic power, and attend elaborate + balls. Many noble bloodlines carry the genetic potential for Allomancy. +- **Skaa** — The vast peasant underclass, descended from those who opposed the + Lord Ruler. They labor in fields, mines, and factories under brutal + conditions. Forbidden from mixing with the nobility, though it happens in + secret — and the Lord Ruler mandates that any skaa who bear noble children + must be killed. + +### Key Locations + +- **Luthadel** — The capital city and seat of the Lord Ruler. Home to Kredik + Shaw (the Hill of a Thousand Spires), the Lord Ruler's palace. The city is + ringed by a massive wall and divided into noble and skaa districts. +- **The Pits of Hathsin** — A brutal prison camp where skaa are worked to death + mining atium geodes from crystalline caverns. Considered inescapable. +- **The Ashmounts** — Volcanic peaks that spew ash across the land. Their + eruptions are controlled by the Lord Ruler to maintain the planet's ecology. +- **The Well of Ascension** — A hidden reservoir of Preservation's concentrated + power, located beneath Kredik Shaw. It refills every thousand years. + +## The Metallic Arts + +Scadrial's magic systems are all tied to metals. There are three distinct +disciplines, each connected to one of the cosmic forces. + +### Allomancy (Preservation) + +Allomancers ingest and "burn" metals to fuel supernatural abilities. The power +is genetic, passed through noble bloodlines. Most Allomancers can burn only a +single metal (Mistings). Rare individuals called Mistborn can burn all metals. + +The basic Allomantic metals come in pairs — one that "pushes" and one that +"pulls" — organized into four groups: + +**Physical metals** (affect the Allomancer's body): +- **Iron** (Lurcher) — Pulls on nearby metals +- **Steel** (Coinshot) — Pushes on nearby metals +- **Tin** (Tineye) — Enhances senses +- **Pewter** (Thug/Pewterarm) — Enhances physical strength, speed, durability + +**Mental metals** (affect other people's minds): +- **Zinc** (Rioter) — Inflames emotions +- **Brass** (Soother) — Dampens emotions +- **Copper** (Smoker) — Hides Allomantic pulses from detection +- **Bronze** (Seeker) — Detects Allomantic pulses nearby + +**Temporal metals** (affect time): +- **Gold** — Shows the Allomancer's past self / alternate lives +- **Electrum** — Shows the Allomancer's own future shadows +- **Cadmium** — Creates a bubble of slowed time +- **Bendalloy** — Creates a bubble of sped-up time + +**Enhancement metals** (enhance other Allomantic abilities): +- **Aluminum** — Wipes the burner's own metal reserves +- **Duralumin** — Explosively enhances the next metal burned +- **Chromium** — Wipes another Allomancer's metal reserves on contact +- **Nicrosil** — Enhances another Allomancer's burn on contact + +**God metals:** +- **Atium** (Ruin's body) — Reveals opponents' future movements, granting + near-perfect combat precognition. Extremely rare and valuable. +- **Lerasium** (Preservation's body) — Transforms anyone who ingests it into a + Mistborn. Almost mythically rare. +- **Malatium** — An alloy of atium and gold. Shows another person's past + selves. + +### Feruchemy (Balance) + +Feruchemists store attributes in metalpieces (called metalminds) for later use. +The system is balanced — you can only withdraw what you previously stored. While +storing, you diminish the attribute; while tapping, you enhance it. + +Each metal stores a different attribute (e.g., iron stores weight, steel stores +speed, pewter stores strength, tin stores senses, zinc stores mental speed, +copper stores memories, gold stores health). + +Feruchemy is native to the Terris people, a scholarly and peaceful culture +nearly eradicated by the Lord Ruler. Terris stewards serve the nobility but +are systematically bred to remove Feruchemic abilities through the Lord Ruler's +eugenics programs. + +### Hemalurgy (Ruin) + +The darkest of the three arts. Hemalurgy uses metal spikes driven through one +person's body to steal their abilities, then those spikes are hammered into +another person to grant those stolen powers. The process always involves death +and always results in some power being lost. + +Hemalurgy is Ruin's art — each spike creates a crack in the recipient's soul +that Ruin can use to influence or control them. The more spikes, the greater +Ruin's hold. + +The Steel Inquisitors are the most visible products of Hemalurgy — former +humans transformed into terrifying enforcers by having numerous metal spikes +driven through their bodies, including the signature spikes through their eye +sockets. They possess stolen Allomantic and Feruchemical abilities and serve +the Lord Ruler and the Steel Ministry. + +### Compounding + +When a person has both Allomantic and Feruchemical access to the same metal, +they can "compound" — burning a metalmind Allomanically to produce a +Feruchemical effect at Allomantic (effectively unlimited) power levels. This +bypasses Feruchemy's balance requirement. The Lord Ruler used compounding of +all metals to achieve functional immortality, among other things. + +## Cosmic Forces + +### The Shards: Preservation and Ruin + +Before the events of the series, a cosmic entity called Adonalsium was +shattered into sixteen Shards of immense power. Two of these Shards came to +Scadrial: + +- **Preservation** — The force of stability, stasis, and continuation. Its + intent is to preserve all things. Preservation sacrificed much of its power + to create humanity on Scadrial with Ruin, giving humans a larger portion of + its own essence — which is why humans have free will and sentience. +- **Ruin** — The force of entropy, decay, and destruction. Its intent is to + break all things down. Not evil in a cosmic sense — destruction is necessary + for change — but utterly single-minded in its purpose. + +Each Shard was originally held by a person (a Vessel). Preservation's original +Vessel was Leras; Ruin's was Ati. + +### The Mists + +The mists are a manifestation of Preservation's power. They blanket the land +each night and are generally harmless, though feared by most people. The mists +occasionally "snap" people — putting them through intense stress that awakens +latent Allomantic abilities. The Mistborn are named for their ability to move +fearlessly through the mists. + +## Key Organizations + +- **The Steel Ministry** — The Lord Ruler's theocratic government and state + religion. Headed by obligators (bureaucrat-priests who oversee contracts and + governance) and enforced by Steel Inquisitors. +- **The Canton of Inquisition** — The Steel Ministry's enforcement and + investigation arm. Led by the Steel Inquisitors. Hunts skaa Allomancers. +- **The Keepers (Terris)** — A secret society of Feruchemists who use + copperminds to preserve forbidden knowledge — history, religion, and lore + that the Lord Ruler tried to destroy. +- **Skaa rebellion / thieving crews** — Underground resistance networks in + Luthadel and beyond. Organized loosely around thieving crews — small, + specialized teams that operate like heist groups, often including Mistings + or Mistborn. +- **The Kandra** — Shapeshifting creatures created by the Lord Ruler from + mistwraiths using Hemalurgic blessings (pairs of spikes). They can absorb + a person's bones to perfectly mimic their appearance. Bound by strict + Contracts to serve humans, governed by their own secretive society in the + Homeland. +- **The Koloss** — Massive, violent blue-skinned creatures created through + Hemalurgy. Used as shock troops by the Lord Ruler. Driven by rage and + controlled through emotional Allomancy or direct Hemalurgic command. + +## Tone and Themes + +The Mistborn universe blends epic fantasy with heist fiction and political +intrigue. Core themes include: + +- **Oppression and revolution** — The struggle against a seemingly invincible + tyranny, and the messy reality of what comes after. +- **Trust and betrayal** — In a world of shapeshifters, mind-influencing + Allomancy, and secret agendas, trust is both precious and dangerous. +- **Faith and belief** — Prophecy, religion, and the power of belief drive much + of the conflict. What does it mean to be a "hero of ages"? +- **Sacrifice** — Power always has a cost. Hemalurgy demands death. Preservation + gave up its mind to imprison Ruin. The heroes repeatedly face choices where + winning requires losing something essential. +- **The nature of power** — From the metallic arts to the Shards themselves, + the universe explores how power shapes and corrupts those who wield it.