@robosoft/skillhub-cli 0.1.1 → 0.3.2

package/skillhub-registry/docs/cost-hygiene.md

@@ -0,0 +1,175 @@
+# Cost Hygiene Guide
+
+**Status:** Recommended practices for all developers using this template
+**Last updated:** 2026-05-06
+**Owner:** [Your name / team]
+
+This guide explains how Claude API pricing actually works and the habits that keep org costs predictable. None of these rules affect *what* you build — only *how much* it costs to build it.
+
+> **TL;DR:** Use Sonnet by default. Start fresh chats for new tasks. Don't edit CLAUDE.md mid-session. Don't switch models mid-session. Active sessions are cheap; long-idle sessions waste cache. That's most of it.
+
+---
+
+## Why This Matters
+
+Claude Code charges per token. Bad habits at the individual level multiply across a team:
+
+- One dev wasting $5/day on cache misses → $25/week → $1,250/year
+- Multiply by 50 devs → **$62,500/year wasted** with zero benefit
+
+Most of these wastes are invisible — they don't slow you down or break anything. They just quietly inflate the bill. This guide is how we avoid that.
+
+---
+
+## How Pricing Works (Quick Version)
+
+Claude charges for **input tokens** (everything sent to the model) and **output tokens** (everything the model writes).
+
+Every message in a Claude Code session sends:
+1. Your CLAUDE.md and auto-loaded rules
+2. Tool definitions
+3. The **entire conversation history so far**
+4. Your new message
+
+So your tenth message costs more than your first — because it re-sends the previous nine exchanges.
+
+### The Saving Grace: Prompt Caching
+
+Anthropic caches stable content (CLAUDE.md, tools, earlier conversation) at 10% of normal price after the first message. The cache stays warm for 5 minutes per hit.
+
+This means:
+- **Active session messages are cheap** (~10% of full price)
+- **First message of a session pays full price** (rebuilds the cache)
+- **Cache breaks** if you change CLAUDE.md, switch models, or modify tools mid-session
+
+Claude Code handles caching automatically — you don't configure anything. But you can break it accidentally.
+
+---
+
+## The Six Habits
+
+### 1. Use Sonnet by default. Switch to Opus only when needed.
+
+| Model | Input cost | Output cost | When to use |
+|---|---|---|---|
+| **Haiku 4.5** | $1/M | $5/M | Simple tasks, classification, summarization |
+| **Sonnet 4.6** | $3/M | $15/M | **Default for daily coding work** |
+| **Opus 4.7** | $5/M | $25/M | Hard reasoning, complex multi-file refactors |
+
+**Rule of thumb:** Start with Sonnet. If it produces low-quality output on a hard task, switch to Opus *for that task* in a new session. Don't switch mid-session — it invalidates the cache.
+
+### 2. One task = one session
+
+Don't pile unrelated tasks into one chat to "save tokens." The opposite happens:
+
+- ❌ One long chat with 5 tasks → message 50 sends history of all 4 prior tasks
+- ✅ Five focused chats → each only carries its own task's history
+
+When you start a new task, start a new session — or use `/clear` inside Claude Code to reset conversation while preserving the warm cache.
+
+### 3. Don't switch models mid-session
+
+Switching from Sonnet to Opus partway through a conversation **rebuilds the cache for the new model from scratch**. Every cached token now costs full price again.
+
+If you realize the task needs Opus, finish what you're doing, then start a new session with Opus.
+
+### 4. Don't edit CLAUDE.md while teammates are working
+
+Editing CLAUDE.md invalidates the cache for everyone who has an active session in that project. Their next message pays the full re-cache cost.
+
+**Best practice:**
+- Make CLAUDE.md changes in a PR
+- Merge during off-hours when possible
+- Announce major changes in the team channel
+
+For per-developer experiments, use `CLAUDE.local.md` — it loads alongside CLAUDE.md but is gitignored and personal.
+
+### 5. Use `/compact` for long sessions
+
+When a session gets long (you'll feel it slowing down), run `/compact` in Claude Code. It summarizes earlier messages while preserving the conversation flow.
+
+Why it matters: long histories cost a lot to re-send every turn. Compaction shrinks the history while keeping the warm cache intact.
+
+Run `/compact` when:
+- The session feels sluggish
+- You've completed a sub-task and want to continue with more
+- Claude starts referencing details that no longer matter
+
+### 6. Don't leave sessions idle
+
+The cache expires after 5 minutes of inactivity. If you walk away for 30 minutes and come back, your next message rebuilds the entire cache at full price.
+
+If you're stepping away:
+- For short breaks (<5 min): no problem, cache stays warm
+- For longer breaks: just close the session, start fresh when you're back
+
+---
+
+## Monitoring Your Usage
+
+Inside Claude Code, run: /cost
+
+This shows the current session's:
+- Total input/output tokens
+- Cache write vs. cache read tokens (high cache reads = good)
+- Total dollar cost
+- Wall-clock duration
+
+Get in the habit of checking this at the end of long sessions. If you see mostly cache writes and few cache reads, something is invalidating the cache repeatedly — investigate.
+
+---
+
+## Org-Level Controls
+
+These are administrator concerns, not individual dev concerns:
+
+- **Spending limits** can be set in the Anthropic Console (per-org and per-user caps)
+- **Usage alerts** can notify when spend exceeds thresholds
+- **Batch API** offers 50% discount for non-urgent workloads (build pipelines, doc generation)
+- **Workspaces** isolate caches between teams within the same org
+
+Talk to your admin if you need these configured.
+
+---
+
+## Common Mistakes (And What They Cost)
+
+| Mistake | Why it costs more | Fix |
+|---|---|---|
+| Long single chat for many tasks | History grows linearly per message | New session per task |
+| Switching Sonnet ↔ Opus mid-session | Cache rebuilds for the new model | Pick one, stick with it |
+| Editing CLAUDE.md while teammates work | Invalidates their caches too | PR merges, announce changes |
+| Leaving session idle 30+ min | Cache expires, full reprocess on return | Close idle sessions |
+| Default to Opus for routine work | 1.7x cost vs Sonnet for similar quality | Sonnet first, Opus when proven needed |
+| Pasting whole files when `@filename` works | Re-pastes entire file every message | Use `@` references |
+
+---
+
+## Anti-Patterns We Don't Recommend
+
+These sound clever but actually cost more:
+
+- ❌ "Keep one mega-chat to save tokens" — wrong direction; long history is expensive
+- ❌ "Use Haiku for everything to save money" — false economy; Haiku produces worse code on complex tasks, leading to rework and more total tokens
+- ❌ "Disable CLAUDE.md to save context" — defeats the entire template's purpose; the cost is negligible
+
+---
+
+## When Cost Is Genuinely a Concern
+
+If your team is hitting real budget limits:
+
+1. **Run `/cost` for a week**, log the data, find which sessions are expensive
+2. **Look for cache-miss patterns** — investigate whether CLAUDE.md is being edited frequently or models are being swapped
+3. **Move bulk work to Batch API** (50% discount) for things like documentation generation, large refactors planned overnight
+4. **Consider Haiku for narrow, simple workflows** like commit message generation, PR description drafts
+
+Don't optimize until you have data. Most teams overestimate their token costs and underestimate the value of fast iteration.
+
+---
+
+## Questions / Reporting Issues
+
+- Cost questions or alerts: [your-team-channel]
+- Template issues: see `docs/contributing.md`
+- Anthropic billing dashboard: https://console.anthropic.com/settings/billing

package/skillhub-registry/docs/customization.md

@@ -0,0 +1,321 @@
+# Customization Guide
+
+**Status:** Pilot — guidance for extending the v0.1.0 template
+**Last updated:** 2026-05-06
+**Owner:** Raj Shah
+
+This guide explains how to extend the template — adding a new skill for a new tech stack, documenting org-specific decisions in `domain/`, or layering personal preferences on top — without breaking the existing rules or forcing a major version bump. Read [`installation.md`](installation.md) first if you haven't already; this guide assumes the template is installed and working.
+
+> **TL;DR:** Universal rules go in `rules/` and must be added to `CLAUDE.md` `@import` lines. Topic-specific guidance goes in a skill folder under `skills/<name>/SKILL.md` with matching `name:` frontmatter. Org-specific decisions go in `domain/`. Personal-only tweaks go in `CLAUDE.local.md` (gitignored). Test every addition with a real prompt before committing.
+
+---
+
+## When to Customize
+
+Three common scenarios. Each has a "right place" — putting customizations in the wrong location is the biggest source of confusion.
+
+### 1. New domain skill for a new tech stack
+
+You start a Vue.js project, or a Python service, or AWS infrastructure work — and the existing skills don't cover it.
+
+**Where it goes:** `skills/<stack-name>/SKILL.md`
+
+**Why:** Skills are loaded *on demand* when their topic comes up. Adding stack-specific guidance as a skill keeps it out of the always-on path (so it doesn't bloat every session) but still automatically applies when relevant.
+
+### 2. Org-specific decisions
+
+Your team standardizes on a specific database pattern, deployment workflow, or API envelope shape. These aren't universal best practices — they're *our* choices, valid only inside this org.
+
+**Where it goes:** `domain/<topic>.md` (e.g., `domain/database.md`, `domain/deployment.md`)
+
+**Why:** `rules/` and `skills/` are meant to be portable across orgs. `domain/` is the explicit "this is our shop" layer. Skills reference `domain/` files when relevant, keeping universal advice and org-specific advice cleanly separated.
+
+### 3. Personal preferences
+
+You like Claude to use British spelling. You prefer two-line function signatures. You want Claude to always remind you to commit before refactoring. None of that belongs in the shared template — your teammates didn't sign up for it.
+
+**Where it goes:** `CLAUDE.local.md` (in the project root, gitignored)
+
+**Why:** `CLAUDE.local.md` loads alongside the project's shared `CLAUDE.md` but is per-developer. It's the right escape hatch for individual taste without polluting team conventions.
+
+---
+
+## How to Add a New Skill
+
+### Step 1 — Decide what kind of skill it is
+
+Skills come in two flavors:
+
+| Type | Triggers when | Example |
+|---|---|---|
+| **Topic-based** | The user's task touches the topic, even without an explicit command | `react` triggers on JSX/TSX work; `testing` triggers when writing tests |
+| **Action-based** | The user invokes a slash command | `/build`, `/refactor`, `/review`, `/fast`, `/strict` |
+
+Some skills are both — `/feature-dev` is action-based (slash command), but its existence shapes how Claude approaches multi-step work even when not invoked explicitly. Pick whichever framing fits the skill, and lean on the description to capture the trigger surface.
+
+### Step 2 — Create the folder
+
+```bash
+mkdir -p skills/<skill-name>
+touch skills/<skill-name>/SKILL.md
+```
+
+The folder name **must match** the `name:` field in the frontmatter. We hit a real bug during template creation where `skills/react/SKILL.md` had `name: react-frontend` — slash commands and triggering became unpredictable. Match them exactly.
+
+### Step 3 — Write the YAML frontmatter
+
+Every `SKILL.md` starts with a YAML block delimited by `---` on the very first line. Two fields are required:
+
+```yaml
+---
+name: <must match folder name>
+description: <one paragraph; under 1024 characters; pushy keyword coverage>
+---
+```
+
+**Description guidance — be pushy.** Claude tends to *under-trigger* skills, not over-trigger them. List every keyword, library name, file extension, abbreviation, and synonym that should make the skill load. The description is the only signal Claude uses to decide whether to apply the skill, so generic ("Vue conventions") is far worse than verbose ("Vue.js conventions for component structure, Composition API, Options API, Pinia, Vue Router, Nuxt, .vue files, single-file components...").
+
+Keep the total length under 1024 characters — Claude Code enforces this. The existing skills sit between 530 and 910 characters; that's a reasonable target range.
+
+### Step 4 — Write the content
+
+Use one of the existing skills as a template. `skills/api/SKILL.md` and `skills/react/SKILL.md` are good representatives — they show the standard layering pattern:
+
+> These rules layer on top of `rules/general.md`, `rules/code-standards.md`, and `rules/anti-patterns.md`.
+
+Always include that line near the top so readers (and Claude) understand the skill *adds to* the universal rules rather than replacing them.
+
+Section structure to follow:
+- Brief intro paragraph (what does this skill cover, when does it apply)
+- Substantive guidance in `##` sections, ordered most-to-least important
+- Concrete examples (good vs. bad) wherever the rule has a concrete shape
+- A "What's out of scope" section at the end pointing to other skills or docs
+
+### Step 5 — Test that it triggers
+
+After writing the skill, restart Claude Code in a project and ask something the skill should respond to. For a Vue skill:
+
+> "Review this `.vue` component: [paste a snippet]"
+
+Then ask Claude:
+
+> "Which skills did you load for that response?"
+
+If Claude lists your new skill, triggering works. If not, the description is too vague — add more keywords and try again.
+
+### Complete Minimal Example
+
+Save this as `skills/vue/SKILL.md` and adapt freely:
+
+```markdown
+---
+name: vue
+description: Vue.js conventions for component structure, Composition API usage, single-file components, and Vue-specific patterns. Use this skill whenever the user works with .vue files, mentions Vue, Composition API, Options API, script setup, Pinia, Vue Router, Vuex, Nuxt, or any Vue-related library. Apply when reviewing Vue components, building new components, debugging reactivity issues, or refactoring Vue applications. Trigger even when Vue is implied by file extension (.vue) or framework-specific syntax, even if the user does not explicitly mention "Vue".
+---
+
+# Vue Skill
+
+This skill applies our Vue conventions. It loads when the task involves Vue, single-file components, the Composition API, or Vue-adjacent libraries.
+
+These rules layer on top of `rules/general.md`, `rules/code-standards.md`, and `rules/anti-patterns.md`.
+
+---
+
+## Components
+
+- Use the Composition API for new code. Options API is acceptable in legacy files; do not mix the two within one component.
+- Use `<script setup>` syntax — it is shorter and avoids the `setup()` boilerplate.
+- Keep components under 200 lines. Above that, extract sub-components or composables.
+- One component per file. File name matches the component name in PascalCase (e.g., `UserProfile.vue`).
+
+## Reactivity
+
+- Prefer `ref()` for primitives, `reactive()` for objects with stable shape.
+- Never destructure a `reactive()` object — destructuring breaks reactivity. Use `toRefs()` if you need destructuring.
+- Use `computed()` for derived state, never inline expressions in templates for non-trivial logic.
+
+## State Management
+
+- For component-local state: `ref` / `reactive`.
+- For cross-component state: Pinia. Do not introduce Vuex in new code.
+- Stores live in `src/stores/<name>.ts` and export a single `useXStore` composable.
+
+## What's Out of Scope
+
+- **Component testing** → see `skills/testing/SKILL.md`.
+- **Performance and bundle size** → see `skills/performance/SKILL.md`.
+- **Org-specific API conventions used inside Vue components** → see `domain/api.md`.
+```
+
+---
+
+## How to Add a New Rule
+
+### Step 1 — Universal or topic-specific?
+
+Ask: does this rule apply to **every** language, framework, and codebase the team uses?
+
+- **Yes** → it goes in `rules/` (universal).
+- **No** → it goes in the relevant skill (e.g., a React-only rule belongs in `skills/react/SKILL.md`).
+
+If you can't articulate why a rule applies universally, it almost certainly doesn't.
+
+### Step 2a — Editing an existing rule file
+
+The simplest case. Open `rules/general.md`, `rules/code-standards.md`, or `rules/anti-patterns.md` and add the rule under the appropriate `##` section. No further wiring is needed — these three files are already loaded via `@import` from `CLAUDE.md`.
+
+### Step 2b — Creating a new rule file
+
+Sometimes the new rule is large enough to deserve its own file (e.g., `rules/security.md`, `rules/accessibility.md`).
+
+1. Create `rules/<name>.md` with the standard header (Status / Last updated / Owner / brief intro).
+2. **Add the import to `CLAUDE.md`:**
+
+```markdown
+@rules/general.md
+@rules/code-standards.md
+@rules/anti-patterns.md
+@rules/<your-new-file>.md
+```
+
+Without this step, the file exists on disk but Claude never loads it. This is the single most common rule-authoring bug.
+
+### Step 3 — Test that the rule actually changes behavior
+
+Vague rules don't change anything. After adding the rule:
+
+1. Pick a task that *should* be affected by the rule.
+2. Ask Claude to do that task in a fresh session.
+3. Verify the output reflects the rule.
+
+If Claude ignores the rule, it's almost always one of:
+- The rule is too abstract ("write good code" is not a rule)
+- The rule lacks a "Why" so Claude can't judge edge cases
+- The rule lacks a concrete example so Claude can't pattern-match
+
+Match the existing rule format: state the rule, give a `> **Why:**` blockquote, then a good vs. bad example where applicable.
+
+### Critical guidance
+
+- **Universal rules apply to ALL languages.** If a rule starts with "in JavaScript" or "in React", it does not belong in `rules/` — it belongs in a skill.
+- **Keep `rules/` lean.** As of v0.1.0, the three rule files plus `CLAUDE.md` total around 376 lines. Past roughly 500 total lines, individual rules start getting "lost in the noise" and Claude applies them less reliably. If you're tempted to add a fourth rule file, ask whether it's actually a skill in disguise.
+- **Don't contradict existing rules.** If a new rule conflicts with one already in `rules/`, Claude will pick arbitrarily turn-to-turn. Resolve the contradiction first.
+
+---
+
+## How to Add Org-Specific Knowledge to `domain/`
+
+`domain/` is for **decisions specific to this org's codebase** — your envelope shape, your auth header name, your canonical pagination style. These are not universal best practices and not portable to other orgs.
+
+The current template ships with `domain/api.md` as a worked example.
+
+### Adding a new domain file
+
+```bash
+touch domain/<topic>.md
+```
+
+Common topics teams add:
+
+- `domain/database.md` — naming conventions, migration policy, transaction boundaries
+- `domain/deployment.md` — environments, release workflow, rollback procedure
+- `domain/auth.md` — session model, token handling, role checks
+- `domain/logging.md` — log levels, structured fields, what to redact
+
+### Cross-referencing from a skill
+
+`domain/` files are **not** auto-loaded. They are referenced by skills that need them. Pattern from `skills/api/SKILL.md`:
+
+> **Important:** This skill covers universal best practices. Org-specific conventions (your envelope shape, your auth header, your pagination style) live in `domain/api.md` — read both when working in this codebase.
+
+When you add `domain/database.md`, edit whichever skill is most likely to involve database work (e.g., `skills/api/SKILL.md` if your APIs hit the DB directly, or a future `skills/persistence/SKILL.md`) and add a similar pointer.
+
+### Why not just put it all in a skill?
+
+Skills are meant to encode universal best practices that travel across orgs. Mixing org-specific decisions into them makes the template harder to share, harder to upstream, and harder to reason about. Keep the layers clean: `rules/` (universal foundations), `skills/` (universal topical expertise), `domain/` (this org's choices).
+
+---
+
+## Personal vs. Shared Customizations
+
+Claude Code supports a layered `CLAUDE.md` hierarchy. Each layer is loaded into every session in your project:
+
+| Location | Scope | Source-controlled? | Purpose |
+|---|---|---|---|
+| `~/.claude/CLAUDE.md` | All your projects | No (it's your own machine) | Global defaults — this is where the template installs to |
+| `<project>/CLAUDE.md` | This project, all contributors | Yes | Project-specific shared rules |
+| `<project>/CLAUDE.local.md` | This project, you only | No (gitignored) | Personal preferences |
+
+> [verify against current Claude Code docs] — the resolution order across these three layers (which overrides which) has shifted across Claude Code versions. Confirm the current behavior in the official docs before relying on a specific override pattern.
+
+### What goes in `CLAUDE.local.md`
+
+- "Always use British spelling in comments."
+- "When refactoring, remind me to run the test suite first — I forget."
+- "Default to `pnpm` not `npm` for any install command."
+- Per-project temporary overrides while you experiment with a rule change before proposing it for the shared template.
+
+### What does *not* go in `CLAUDE.local.md`
+
+- Anything your teammates need to follow too (that's project `CLAUDE.md` or a PR to the shared template).
+- API keys, tokens, or other secrets — `CLAUDE.local.md` is gitignored but still lives in your project tree.
+
+---
+
+## Testing Your Customizations
+
+The template's strength is that customizations apply automatically. The risk is that a broken customization fails *silently* — Claude just ignores it.
+
+### After adding a skill
+
+1. **Trigger test.** Open a fresh Claude Code session in a project and ask something the skill should match. Then ask "which skills did you load?" — your skill should be named.
+2. **Composition test.** Combine your new skill with `/strict` and `/fast` separately. Confirm the skill's content shows up under both modes.
+3. **Boundary test.** Ask something *outside* the skill's scope and confirm the skill does *not* trigger. An over-eager skill is as bad as one that doesn't trigger — it pollutes unrelated sessions with irrelevant guidance.
+
+### After adding a rule
+
+1. **Compliance test.** Pick a prompt that violates the new rule. Confirm Claude flags or avoids the violation.
+2. **Cache check.** After editing `CLAUDE.md` or any always-on rule file, the prompt cache invalidates — see [`cost-hygiene.md`](cost-hygiene.md). Avoid editing during teammates' active sessions.
+
+### Re-verification prompt
+
+A short "is the structure still correct" check is useful after non-trivial changes. The verification prompts used during initial template creation (folder structure, frontmatter validity, missing `@import`s, name/folder mismatches) work well as a recurring check — adapt them to whatever you just added.
+
+---
+
+## Common Pitfalls
+
+| Pitfall | Effect | Fix |
+|---|---|---|
+| Forgetting to add a new rule file to `CLAUDE.md` `@import`s | Rule never loads; you wonder why Claude ignores it | Add `@rules/<file>.md` to `CLAUDE.md` |
+| Frontmatter `name:` doesn't match folder name | Skill triggers unpredictably; slash commands may not register | Make them identical (e.g., both `vue`) |
+| Skill description too vague | Skill rarely triggers even on perfect prompts | Add every keyword, synonym, file extension, library name |
+| Mixing universal rules with language-specific rules in `rules/` | Future readers confused; rules feel arbitrary | Move language-specific rules into a skill |
+| New rule contradicts an existing rule | Claude picks arbitrarily, behavior is inconsistent | Reconcile before merging — delete or qualify the older rule |
+| Putting org-specific decisions in `skills/` | Template becomes non-portable; harder to share | Move to `domain/` and reference from the skill |
+| Editing `CLAUDE.md` mid-session while teammates work | Invalidates their prompt cache, costs more | Land changes via PR; announce major changes |
+| Adding a skill without testing triggering | You think it works; it doesn't fire on real prompts | Always run the trigger test before committing |
+
+---
+
+## When to Promote a Local Change to the Template
+
+A customization that proves useful in **more than one project**, or that **another developer has independently asked for**, is a candidate for the shared template.
+
+The eventual process will live in `docs/contributing.md` — that file does not yet exist in v0.1.0. Until it does:
+
+1. Open the customization (your `CLAUDE.local.md` snippet, your `domain/foo.md`, your draft skill) and clean it up.
+2. Message Raj Shah with a short pitch: what problem it solves, why it generalizes, what it would replace or extend.
+3. If accepted, it lands as a PR against the template repo and ships in the next minor or patch release per [`CHANGELOG.md`](../CHANGELOG.md).
+
+Don't sit on a useful customization out of politeness — the template is meant to grow, and proposals are how it grows.
+
+---
+
+## Where to Get Help
+
+- **Proposing a change to the shared template** → `docs/contributing.md` (not yet published in v0.1.0); for now, message Raj Shah directly.
+- **Installation reference** → [`installation.md`](installation.md)
+- **Cost implications of editing rules and skills** → [`cost-hygiene.md`](cost-hygiene.md)
+- **Overall context on what the template is** → [`README.md`](../README.md)
+- **Anything not covered here** → message Raj Shah