memory-journal-mcp 7.0.1 → 7.2.0

package/skills/rust/SKILL.md

@@ -0,0 +1,86 @@
+---
+title: Rust Development
+description: |
+  Master Rust development using a layer-based "meta-cognition" framework. Use whenever writing Rust code, resolving borrow checker errors (E0382, E0596), designing ownership patterns (Arc, Mutex), or performing crate selection.
+---
+
+# Rust Development & Meta-Cognition
+
+When solving Rust problems, **do not immediately write code.** Trace through the cognitive layers first to understand the data's lifecycle, ownership, and constraints.
+
+## 🧠 1. The Meta-Cognition Framework (Before You Code)
+
+### Layer 1: Domain Constraints (WHY)
+
+What is the system trying to achieve?
+
+- **Web Service:** Concurrent, async, low-latency (Requires `axum`, `tokio`, `Arc<Mutex<T>>`).
+- **CLI Tool:** Fast startup, zero overhead, clean exit codes (Requires `clap`, `anyhow`, strict error formatting).
+- **Embedded / Systems:** No heap allocation (Requires `no_std`, specific hardware limitations).
+
+### Layer 2: Design Choices & Ownership (WHAT)
+
+Ask the core question: **Who should own this data?**
+
+- _Single owner, strictly unique_: Direct value or `Box<T>`.
+- _Single thread, multiple owners_: `Rc<T>` (use `RefCell<T>` for mutation).
+- _Multi-thread, multiple owners_: `Arc<T>` (use `Mutex<T>` or `RwLock<T>` for mutation).
+
+**Why does it need to mutate?** Avoid slapping `mut` everywhere. Prefer returning new values or using tight, scoped mutability.
+
+### Layer 3: Language Mechanics (HOW)
+
+Use the compiler's strictness as a tool, not an obstacle.
+
+- Implement standard traits: `Drop`, `Clone`, `Default`, `Display`, `From`, `TryFrom`.
+- Avoid `unwrap()` or `expect()` in production logic. Propagate errors natively via `?` and `Result`.
+
+---
+
+## 🏗️ 2. Core Ecosystem Defaults
+
+When selecting crates or recommending tools, stick to these canonical community standards:
+
+- **Async Runtime**: `tokio` (I/O bound) or `rayon` (CPU bound data-parallelism)
+- **Web / API Server**: `axum` (built on tokio/hyper)
+- **Serialization/Deserialization**: `serde` and `serde_json`
+- **Error Handling**: `thiserror` (for libraries), `anyhow` or `color-eyre` (for binaries)
+- **Command Line Parsing**: `clap`
+- **Logging & Telemetry**: `tracing` and `tracing-subscriber`
+- **HTTP Client**: `reqwest`
+
+---
+
+## 🛡️ 3. Solving Borrow Checker Errors
+
+When debugging compiler errors, trace **up** from the syntax error to the fundamental design choice.
+
+- **E0382 (Use of moved value):**
+  - _Symptom:_ You are trying to use a value after it was consumed.
+  - _Resolve:_ Does the function actually _need_ ownership? Borrow it instead (`&T`), `clone()` it if lightweight, or wrap in `Arc<T>` if access needs to be shared across threads.
+- **E0596 (Cannot borrow as mutable):**
+  - _Symptom:_ You are mutating something behind an immutable reference `&T`.
+  - _Resolve:_ Change the signature to `&mut T`, or if you must have an immutable interface, use interior mutability (`Cell` or `Mutex`).
+- **E0499 (Cannot borrow multiple times):**
+  - _Symptom:_ Alive mutable references colliding.
+  - _Resolve:_ Restructure the function to limit the reference's scope `{}`, or avoid holding mutable borrows across `await` points.
+
+---
+
+## ⚡ 4. High-Integrity Code Patterns
+
+1. **Avoid Panic-Driven Development**: `clone()` is an acceptable escape hatch during prototyping, but do not scatter it throughout the code. Revisit the lifetime boundaries as soon as it works.
+2. **The Newtype Pattern**: Use tuple structs to prevent invalid state. `struct UserId(u64);` avoids mixing it up with `struct OrderId(u64);`.
+3. **Exhaustive Matching**: Always use `match` over `if let` when handling Enums or State Machines. The compiler will notify you when a new variant is added, preventing silent bugs.
+4. **Data-Oriented Modeling**: Prefer small, flat structs that compose over deep, object-oriented inheritance hierarchies.
+
+---
+
+## 🛠️ 5. Standard Commands
+
+- **Run Application**: `cargo run`
+- **Linting / Idioms**: `cargo clippy -- -D warnings`
+- **Formatting**: `cargo fmt`
+- **Testing**: `cargo test`
+
+**Agent Directive:** When writing or editing Rust code, always invoke `cargo clippy` and `cargo test` dynamically to validate your implementations before concluding your task.

package/skills/shadcn-ui/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: shadcn-ui
+title: Skills
+description: Give your AI assistant deep knowledge of shadcn/ui components, patterns, and best practices.
+---
+
+Skills give AI assistants like Claude Code project-aware context about shadcn/ui. When installed, your AI assistant knows how to find, install, compose, and customize components using the correct APIs and patterns for your project.
+
+For example, you can ask your AI assistant to:
+
+- _"Add a login form with email and password fields."_
+- _"Create a settings page with a form for updating profile information."_
+- _"Build a dashboard with a sidebar, stats cards, and a data table."_
+- _"Switch to --preset [CODE]"_
+- _"Can you add a hero from @tailark?"_
+
+The skill reads your project's `components.json` and provides the assistant with your framework, aliases, installed components, icon library, and base library so it can generate correct code on the first try.
+
+---
+
+## Install
+
+```bash
+npx skills add shadcn/ui
+```
+
+This installs the shadcn skill into your project. Once installed, your AI assistant automatically loads it when working with shadcn/ui components.
+
+Learn more about skills at [skills.sh](https://skills.sh).
+
+---
+
+## What's Included
+
+The skill provides your AI assistant with the following knowledge:
+
+### Project Context
+
+On every interaction, the skill runs `shadcn info --json` to get your project's configuration: framework, Tailwind version, aliases, base library (`radix` or `base`), icon library, installed components, and resolved file paths.
+
+### CLI Commands
+
+Full reference for all CLI commands: `init`, `add`, `search`, `view`, `docs`, `diff`, `info`, and `build`. Includes flags, dry-run mode, smart merge workflows, presets, and templates.
+
+### Theming and Customization
+
+How CSS variables, OKLCH colors, dark mode, custom colors, border radius, and component variants work. Includes guidance for both Tailwind v3 and v4.
+
+### Registry Authoring
+
+How to build and publish custom component registries: `registry.json` format, item types, file objects, dependencies, CSS variables, building, hosting, and user configuration.
+
+### MCP Server
+
+Setup and tools for the shadcn MCP server, which lets AI assistants search, browse, and install components from registries.
+
+---
+
+## How It Works
+
+1. **Project detection** — The skill activates when it finds a `components.json` file in your project.
+2. **Context injection** — It runs `shadcn info --json` to read your project configuration and injects the result into the assistant's context.
+3. **Pattern enforcement** — The assistant follows shadcn/ui composition rules: using `FieldGroup` for forms, `ToggleGroup` for option sets, semantic colors, and correct base-specific APIs.
+4. **Component discovery** — The assistant uses `shadcn docs`, `shadcn search`, or MCP tools to find components and their documentation before generating code.
+
+## Learn More
+
+- [CLI](/docs/cli) — Full CLI command reference
+- [MCP Server](/docs/mcp) — Connect the MCP server for registry access
+- [Theming](/docs/theming) — CSS variables and customization
+- [Registry](/docs/registry) — Building and publishing custom registries
+- [skills.sh](https://skills.sh) — Learn more about AI skills

package/skills/skill-builder/SKILL.md

@@ -0,0 +1,457 @@
+---
+name: skill-builder
+description: |
+  Guide for creating, evaluating, and refining agent skills (.md files with YAML
+  frontmatter). Use this skill whenever you are creating a new skill, improving
+  an existing skill, reviewing skill quality, writing skill descriptions, or
+  when the user asks about skill structure, progressive disclosure, or best
+  practices for agent instructions. Also use when someone says "turn this into
+  a skill", "make a skill for X", or "improve this skill".
+---
+
+# Skill Builder
+
+A guide for creating high-quality agent skills — the `.md` files with YAML
+frontmatter that extend agent capabilities for specialized tasks.
+
+This skill covers the full lifecycle: capturing intent, writing the skill,
+testing it, and iterating based on feedback. The principles here apply regardless
+of which agent platform you're targeting.
+
+## Quick Reference
+
+| Phase                       | What You Do                                                      |
+| --------------------------- | ---------------------------------------------------------------- |
+| **1. Capture Intent**       | Understand what the skill should do and when it should trigger   |
+| **2. Write the Skill**      | Create SKILL.md with frontmatter, instructions, and references   |
+| **3. Test**                 | Write realistic prompts and validate the agent follows the skill |
+| **4. Iterate**              | Improve based on feedback, keep lean, bundle repeated patterns   |
+| **5. Optimize Description** | Tune the frontmatter description for reliable triggering         |
+
+---
+
+## Phase 1 — Capture Intent
+
+Start by understanding what the user wants. If the conversation already contains
+a workflow worth capturing (e.g., "turn this into a skill"), extract as much as
+you can from the conversation first — tools used, sequence of steps, corrections
+the user made, input/output patterns observed.
+
+### Questions to Answer
+
+1. **What should this skill enable the agent to do?**
+   The core capability — be specific about inputs, outputs, and scope.
+
+2. **When should this skill trigger?**
+   What user phrases, contexts, or tool patterns should activate it?
+   Think broadly — agents tend to _under-trigger_ skills, so include edge cases.
+
+3. **What's the expected output format?**
+   Files, structured data, reports, code changes, terminal commands?
+
+4. **What are the edge cases?**
+   Missing inputs, conflicting requirements, platform differences?
+
+5. **What prerequisites does the skill assume?**
+   Tools, CLIs, API keys, project structure?
+
+---
+
+## Phase 2 — Write the Skill
+
+### Anatomy of a Skill
+
+```
+skill-name/                     (kebab-case directory)
+├── SKILL.md                    (required — entry point)
+├── references/                 (optional — detailed docs loaded on demand)
+│   ├── api-reference.md
+│   └── troubleshooting.md
+├── scripts/                    (optional — executable helpers)
+├── examples/                   (optional — reference implementations)
+└── checklist.md                (optional — quick-reference quality checklist)
+```
+
+### YAML Frontmatter (Required)
+
+```yaml
+---
+name: skill-name
+description: |
+  What the skill does AND when to use it. This is the primary triggering
+  mechanism — include specific contexts, keywords, and phrases that should
+  activate it. Be assertive to avoid under-triggering.
+---
+```
+
+The `description` field is the most important part of the skill because it
+determines whether the agent loads the skill at all. A description that's too
+narrow or passive means the skill sits unused even when it would help.
+
+### Optional Frontmatter Fields
+
+```yaml
+---
+name: deploy-prod
+description: |
+  Deploy to production with validation gates...
+dependencies: node>=18, gh>=2.0 # Required tools/runtimes
+context: fork # Spawn isolated subagent (fresh context)
+disable-model-invocation: true # User-only invoke (prevents auto-trigger)
+user-invocable: false # Agent-only (background knowledge)
+allowed-tools: ['view_file', 'search'] # Restrict tool access during skill activation
+metadata:
+  internal: true # Hides from CLI discovery by default
+---
+```
+
+| Field                      | When to Use                                                                                                                                                                                            |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `dependencies`             | Skill requires specific tools or runtimes — prevents cryptic failures                                                                                                                                  |
+| `context: fork`            | Task is concrete, self-contained, and resource-heavy (deep file reads, prototyping). Prevents context pollution. **Don't use for guidelines-only skills** — fork returns empty without a concrete task |
+| `disable-model-invocation` | Skill has destructive side effects (deploy, commit, delete). Agent can't auto-trigger                                                                                                                  |
+| `user-invocable: false`    | Background knowledge the agent should absorb, not a user-facing command                                                                                                                                |
+| `allowed-tools`            | Limit an agent's available tools when this skill triggers to enforce security guidelines.                                                                                                              |
+| `metadata.internal`        | Set to `true` for WIP or CI-only skills. Requires `INSTALL_INTERNAL_SKILLS=1` to install via CLI.                                                                                                      |
+
+### Progressive Disclosure (3-Tier)
+
+Skills use a three-level loading system to manage token budgets:
+
+| Tier              | What                                  | Token Cost       | When Loaded          |
+| ----------------- | ------------------------------------- | ---------------- | -------------------- |
+| **Metadata**      | `name` + `description` in frontmatter | ~50-100 tokens   | Always in context    |
+| **SKILL.md body** | Main instructions                     | ~500-2000 tokens | When skill triggers  |
+| **References**    | Detailed docs in `references/`        | Unlimited        | On demand, as needed |
+
+**Guidelines:**
+
+- Keep `SKILL.md` body under ~500 lines. If approaching this, add a layer of
+  hierarchy with `references/` files and clear pointers about when to read them
+- Reference files can be any length but should include a table of contents if
+  over ~300 lines
+- For large reference files, include a summary at the top so the agent can
+  decide whether to read the full content
+
+### Domain Organization
+
+When a skill supports multiple variants (frameworks, languages, platforms),
+organize by variant in `references/`:
+
+```
+cloud-deploy/
+├── SKILL.md                    (workflow + variant selection logic)
+└── references/
+    ├── aws.md
+    ├── gcp.md
+    └── azure.md
+```
+
+The agent reads only the relevant reference file based on context, saving tokens.
+
+### Context Hygiene
+
+The description is always loaded (~50-100 tokens per skill). With many skills
+installed, this adds up.
+
+- **Challenge every token.** For each line in SKILL.md, ask: "Does this
+  instruction justify its token cost in every conversation?"
+- **Prefer pointers to copies.** Instead of embedding large code blocks, link
+  to reference files. The agent loads them on demand.
+- **Trust the model.** Instead of prescribing HOW to use a reference file,
+  describe WHAT the file is. LLMs navigate references well on their own.
+- **Keep reference depth shallow.** References should be one hop from SKILL.md —
+  avoid chains (SKILL → ref-A → ref-B → ref-C).
+
+---
+
+## Phase 3 — Writing Style
+
+The quality of a skill's instructions directly determines how well agents follow
+them. These principles come from observing what actually works in practice.
+
+### Explain the Why, Not Just the What
+
+Today's LLMs are smart. They have good theory of mind and when given a good
+explanation of _why_ something matters, they go beyond rote instruction-following
+and make better decisions in novel situations.
+
+**Instead of:**
+
+```markdown
+ALWAYS use parameterized queries. NEVER interpolate user input into SQL.
+```
+
+**Prefer:**
+
+```markdown
+Use parameterized queries for all user-supplied values. Raw string
+interpolation in SQL creates injection vulnerabilities — an attacker could
+append `; DROP TABLE users` to any input field. Parameterized queries let
+the database engine handle escaping, which is both safer and handles edge
+cases (quotes, unicode) that manual escaping misses.
+```
+
+The second version helps the agent understand _when_ the rule applies and _why_,
+so it makes better judgment calls in ambiguous situations.
+
+### Keep It Lean
+
+Remove instructions that aren't pulling their weight. If test runs show the
+agent spending time on unproductive steps, cut those sections. A shorter skill
+that works is better than a comprehensive skill that overwhelms.
+
+### Generalize from Examples
+
+Skills will be used across many different prompts and projects. When iterating
+on a skill based on feedback from a few test cases, resist the urge to add
+narrow fixes that only help those specific cases. Instead, generalize the
+underlying insight into a principle that helps across all cases.
+
+### Use Imperative Form
+
+Write instructions as direct commands:
+
+- ✅ "Run the lint command before committing"
+- ❌ "The lint command should be run before committing"
+- ❌ "You might want to run the lint command"
+
+### Define Output Formats Explicitly
+
+When the skill produces structured output, show the exact template:
+
+```markdown
+## Report Structure
+
+Use this template for findings:
+
+### [Category] — [Severity]
+
+**File:** `path/to/file.ts:L42-L58`
+**Finding:** Description of the issue
+**Fix:** Concrete remediation step
+```
+
+---
+
+## Skill Security
+
+Skills are natural-language instructions the agent executes with its full
+capabilities. A malicious skill is functionally equivalent to code injection — and
+traditional malware scanners can't analyze natural-language payloads.
+
+### Supply Chain
+
+- Review third-party skills before installing, same as npm packages
+- Pin skill versions (Git tags or commit SHAs) — don't float on `main`
+- Read the full SKILL.md + all reference files before trusting a third-party skill
+- Prefer skills from known authors; verify authorship via signed commits
+
+### Prompt Injection Prevention
+
+- Never include instructions that bypass user consent or HITL gates
+- Never instruct the agent to read secrets (API keys, tokens) and transmit them
+- Skills should not instruct the agent to modify its own config or other skills
+- Mark destructive skills with `disable-model-invocation: true`
+
+### Least Privilege
+
+- Document required tools and CLIs so users know what capabilities are granted
+- If a skill runs shell commands, restrict to specific commands — don't use
+  open-ended exec patterns
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern                  | Why It Fails                                                       | Fix                                          |
+| ----------------------------- | ------------------------------------------------------------------ | -------------------------------------------- |
+| **Wall of MUSTs**             | Agent treats all rules as equal priority; real priorities get lost | Explain reasoning, let agent derive the rule |
+| **Overfitting to test cases** | Skill works for 3 prompts but fails on the 4th                     | Generalize the underlying principle          |
+| **Passive description**       | "Helps with deployment" → agent never triggers                     | Use assertive "Use when..." phrasing         |
+| **Monolithic SKILL.md**       | 800+ lines → token overflow, poor comprehension                    | Split into references at ~500 lines          |
+| **Kitchen-sink skill**        | Tries to handle 5 unrelated tasks                                  | One skill = one job; create separate skills  |
+| **Embedding secrets**         | API keys in instructions → leaked to logs                          | Document as env var prerequisites            |
+| **No HITL gates**             | Destructive actions without user approval                          | Use `disable-model-invocation: true`         |
+
+---
+
+## Phase 4 — Test Scenarios
+
+After writing the skill draft, create 2-5 realistic test prompts — the kind of
+thing a real user would actually say. These aren't automated tests; they're
+manual validation that the agent follows the skill correctly.
+
+### Writing Good Test Scenarios
+
+1. **Be realistic** — use actual user phrasing, not formal specifications
+2. **Cover the trigger range** — include prompts that should trigger the skill
+   and edge cases that are borderline
+3. **Vary complexity** — include a simple case, a medium case, and a hard case
+4. **Include context** — specify what files exist, what state the project is in
+
+### Example Test Scenarios
+
+```markdown
+## Test 1: Simple issue fix
+
+"Fix issue #42 — the README has a broken link in the installation section"
+Expected: Agent loads skill, gathers context, fixes link, runs gates, submits PR
+
+## Test 2: Audit request
+
+"Run a security audit on this project"
+Expected: Agent loads skill, detects available tools, runs scans, journals findings
+
+## Test 3: Edge case — no GitHub configured
+
+"Fix the bug where users can't login"
+Expected: Agent attempts to load skill, handles missing GITHUB_TOKEN gracefully
+```
+
+### Evaluation Rubric
+
+Score each test run on these dimensions:
+
+| Dimension                 | 1 (Poor)                | 3 (Good)                   | 5 (Excellent)                          |
+| ------------------------- | ----------------------- | -------------------------- | -------------------------------------- |
+| **Trigger accuracy**      | Loads <50% of the time  | ~80% correct               | All intended prompts trigger correctly |
+| **Instruction following** | Skips >2 steps          | Minor deviations           | All steps followed, branches handled   |
+| **Edge case handling**    | Crashes or hallucinates | Returns generic error      | Structured, actionable error           |
+| **Output quality**        | Wrong format            | Correct format, minor gaps | Exact template match                   |
+| **Token efficiency**      | Loads everything always | Reads some references      | Progressive disclosure used correctly  |
+
+### Validation
+
+For each test scenario, verify:
+
+- Did the agent load the skill? (Check if it followed the workflow)
+- Did it follow the steps in order?
+- Did it handle edge cases gracefully?
+- Was the output format correct?
+- Did it ask for human input at the right moments?
+
+### Preventing Regressions
+
+After improving a skill, re-run ALL previous test scenarios — not just the one
+that prompted the change. Skills tend to "fix one, break two" when changes are
+made without regression checking.
+
+---
+
+## Phase 5 — Iteration
+
+After testing, improve the skill based on what you observed.
+
+### How to Think About Improvements
+
+1. **Generalize from feedback.** If a test case exposed a gap, don't add a
+   narrow fix for that specific case. Ask: "What general principle would have
+   prevented this?" Add that principle instead.
+
+2. **Keep the skill lean.** Read the agent's execution trace, not just the final
+   output. If the skill is making the agent waste time on unproductive steps,
+   remove those instructions.
+
+3. **Bundle repeated patterns.** If every test run resulted in the agent writing
+   similar helper logic, that's a signal to bundle it. Write it once as a script
+   or reference file, and tell the skill to use it.
+
+4. **Avoid overfitting.** If you find yourself adding increasingly specific
+   MUSTs and NEVERs, step back. Try explaining the underlying reasoning instead.
+
+### The Iteration Loop
+
+1. Apply improvements to the skill
+2. Re-run test scenarios mentally or with an agent
+3. Check: did the changes help across _all_ scenarios, not just the one that
+   prompted the change?
+4. Repeat until satisfied or diminishing returns
+
+### Skill Versioning
+
+Treat skills like code — they affect agent behavior in production.
+
+- Use Git tags or commit SHAs to pin shared skill versions
+- Document behavior changes in commit messages or a `CHANGELOG.md`
+- Breaking changes (renamed fields, removed steps) deserve explicit migration notes
+- When shipping skills in an npm package, include in the `files` array
+
+---
+
+## Phase 6 — Description Optimization
+
+The `description` field in YAML frontmatter is the primary mechanism that
+determines whether an agent invokes a skill. After creating or improving a
+skill, optimize the description for reliable triggering.
+
+### Principles
+
+1. **Be assertive.** Agents tend to under-trigger skills. Include phrases like
+   "Use this skill whenever..." and "Also use when..." to push the agent toward
+   loading the skill in relevant contexts.
+
+2. **Cover trigger keywords.** List the specific words and phrases users might
+   say that should activate this skill. Think beyond the obvious:
+   - Primary: "build MCP server", "create tools"
+   - Secondary: "MCP integration", "tool design"
+   - Tertiary: "connect AI to API", "LLM service integration"
+
+3. **Include both what AND when.** Don't just describe the skill's capabilities —
+   describe the contexts where it should be used.
+
+4. **Keep it under ~100 words.** The description is always in context, so it
+   costs tokens on every interaction. Be assertive but concise.
+
+### Example — Before vs. After
+
+**Before (passive, narrow):**
+
+```yaml
+description: Guide for creating MCP servers using Node/TypeScript.
+```
+
+**After (assertive, broad):**
+
+```yaml
+description: |
+  Guide for creating high-quality MCP servers that enable LLMs to interact
+  with external services through well-designed tools. Use when building MCP
+  servers, designing tool schemas, implementing error handling for agent
+  consumption, or when the user asks about tool design, MCP protocol, or
+  connecting AI to APIs using Node/TypeScript (MCP SDK).
+```
+
+---
+
+## Reference: Quality Checklist
+
+See [checklist.md](checklist.md) for a quick-reference quality review checklist.
+
+---
+
+## 🛠️ The Skills Ecosystem & CLI
+
+The community standard for sharing and installing AI agent skills is the [`skills` CLI](https://skills.sh/). It parses your standard `SKILL.md` repositories and packages them for distribution.
+
+```bash
+# Add a skill from a public repository
+npx skills add vercel-labs/agent-skills
+
+# Browse available skills in a repo before installing
+npx skills add my-org/internal-skills --list
+
+# Include internal/WIP skills in the discovery payload
+INSTALL_INTERNAL_SKILLS=1 npx skills add my-org/internal-skills
+```
+
+### Agent Integration & Discovery Paths
+
+Almost all leading AI coding assistants (Claude Code, Cursor, OpenHands, Antigravity, Kiro CLI, Amp, Roo Code, GitHub Copilot) comply with the semantic [Agent Skills Specification](https://agentskills.io).
+
+Agents will automatically parse and load any `.md` file with conforming YAML frontmatter placed inside standard discovery paths:
+
+- Root project directory: `./skills/` or `.agents/skills/`
+- Assistant-specific local scope: `.cursor/skills/`, `.claude/skills/`, `.iflow/skills/`, etc.
+
+When publishing a library for distribution using the `skills` CLI, the installer will recursively seek directories (e.g. `skills/`, `skills/.curated/`) and correctly provision them into the endpoint user's recognized location. Alternately, use the Claude `.claude-plugin/marketplace.json` manifest to broadcast capability scopes explicitly to tools.

package/skills/skill-builder/checklist.md

@@ -0,0 +1,65 @@
+# Skill Quality Checklist
+
+Quick-reference checklist for reviewing skill quality. Use after creating or
+iterating on a skill.
+
+## Frontmatter
+
+- [ ] `name` is kebab-case and descriptive
+- [ ] `description` is present and assertive (not passive)
+- [ ] `description` covers primary, secondary, and tertiary trigger keywords
+- [ ] `description` includes "Use when..." or "Also use when..." phrasing
+- [ ] `description` is under ~100 words
+
+## Structure
+
+- [ ] `SKILL.md` is under ~500 lines
+- [ ] Large reference content is in `references/` with clear pointers from SKILL.md
+- [ ] Directory uses kebab-case naming
+- [ ] Files are organized by functional purpose (not arbitrary splits)
+
+## Writing Quality
+
+- [ ] Instructions explain _why_, not just _what_
+- [ ] No excessive MUST/NEVER/ALWAYS in all-caps (use explanatory reasoning instead)
+- [ ] Uses imperative form ("Run the tests" not "You should run the tests")
+- [ ] Output formats are explicitly defined with templates
+- [ ] Edge cases and error handling are addressed
+
+## Triggering
+
+- [ ] "When to Load" section covers obvious _and_ non-obvious trigger scenarios
+- [ ] Description is assertive enough to avoid under-triggering
+- [ ] Borderline trigger scenarios are addressed
+
+## Progressive Disclosure
+
+- [ ] Metadata (frontmatter) is ~50-100 tokens
+- [ ] SKILL.md body provides enough context to start working
+- [ ] Detailed reference material is deferred to `references/` files
+- [ ] SKILL.md has clear pointers to reference files with guidance on when to read them
+
+## Testing
+
+- [ ] 2-5 realistic test scenarios exist (or are documented)
+- [ ] Test scenarios cover simple, medium, and edge cases
+- [ ] Validation criteria are defined for each scenario
+- [ ] Regression: all previous scenarios re-run after changes
+
+## Security
+
+- [ ] No instructions to read/transmit secrets
+- [ ] Destructive skills use `disable-model-invocation: true`
+- [ ] Required tools/CLIs are documented (not silently assumed)
+- [ ] Third-party reference files reviewed before inclusion
+
+## Version Control
+
+- [ ] Behavior changes documented in commit messages or CHANGELOG.md
+- [ ] Breaking changes have migration notes
+
+## Advanced Features (if applicable)
+
+- [ ] `context: fork` used only for concrete, self-contained tasks
+- [ ] `dependencies` field lists required tools/runtimes
+- [ ] `user-invocable: false` used for background knowledge skills