@mohammadhprp/system-prompt 0.10.1

package/framework/skills/diagram-design/references/type-radar.md

@@ -0,0 +1,80 @@
+# Radar / Spider
+
+**Best for:** comparing 3–5 entities across 3–5 quantitative criteria on a single normalized 0–N scale. Capability matrices, product or backend evaluations, framework/team scorecards. Where a comparison table starts running out of horizontal room, radar makes the shape of each option legible at a glance.
+
+## Layout conventions
+
+- **N axes (3–5).** Equally spaced on a regular polygon-N. First axis at the top (`-90°`), going clockwise. **Above 5 → split or use a comparison table.**
+- **Five concentric grid rings** at fractions `0.2 / 0.4 / 0.6 / 0.8 / 1.0` of the radius. Drawn as closed polygons connecting the axis vertices at that fraction. Inner four at `rule` 0.10 opacity, outer ring at `rule-solid` 0.20 (a hint stronger to anchor the chart).
+- **Axis spokes** from center to each outer vertex. `rule-solid` 0.20 opacity. **No arrowheads.**
+- **Axis labels:** one word per spoke (Jobs-minimal). Geist sans 11px weight 600. Place 16px outside the outer ring along the axis vector. Top/bottom = `text-anchor="middle"`; right side = `start`; left side = `end`.
+- **Scale ticks** (e.g. `2 4 6 8 10`) only on the **first (top) axis** — putting numbers on every spoke clutters the chart fast. Geist Mono 8px, `muted`, anchored end at `cx − 6`.
+- **Series polygon:** stroke 1.5px at the series color, fill the same color at `0.18` opacity (`0.22` in dark). Stroke 1.8px on the focal series — a subtle weight bump.
+- **Vertex dots:** **only on the focal series**, `r=4` filled with the series color. Non-focal series are stroke-and-fill only. This is the load-bearing rule that keeps the chart readable at 4–5 series.
+- **Drawing order:** dots-pattern bg → grid rings → axis spokes → axis labels → scale ticks → non-focal series (smallest area first) → focal series → focal vertex dots → legend.
+- **Legend:** horizontal strip at the bottom (per the global rule). Swatch is a 16×8 rectangle (matches the polygon stroke+fill, not a circle), then the entity name. ~140px between entries. Optional italic tail on the right with the rationale (`"One coral. Position is the signal — color reserved for the recommended option."`).
+
+## Math
+
+For axis `i` (0-indexed) of `N`, value `v` on scale `S`, center `(cx, cy)`, outer radius `R`:
+
+```
+angle = -π/2 + 2π · i / N
+x = cx + (v / S) · R · cos(angle)
+y = cy + (v / S) · R · sin(angle)
+```
+
+A series with values `[v0, v1, ..., v(N-1)]` becomes a `<polygon>` with `points="x0,y0 x1,y1 ..."`.
+
+### Pre-computed reference (N=5, cx=500, cy=240, R=160, S=10, integer-rounded)
+
+| Fraction `f` | i=0 (top) | i=1 | i=2 | i=3 | i=4 |
+|---|---|---|---|---|---|
+| 0.2 | 500,208 | 530,230 | 519,266 | 481,266 | 470,230 |
+| 0.4 | 500,176 | 561,220 | 538,292 | 462,292 | 439,220 |
+| 0.6 | 500,144 | 591,211 | 556,317 | 444,317 | 409,211 |
+| 0.8 | 500,112 | 622,201 | 575,343 | 425,343 | 378,201 |
+| 1.0 | 500,80  | 652,191 | 594,369 | 406,369 | 348,191 |
+
+For an arbitrary value `v` on axis `i`, take the unit offset from the row above for that axis (e.g. axis 1: offset `(152, -49)` from center) and scale by `v/S`. **Drop coords as integers — fractional pixels in SVG render fine, but integers keep the file scannable.**
+
+### Worked example (N=5)
+
+Series `[9, 8, 9, 9, 9]` on a 0–10 scale becomes:
+
+```svg
+<polygon points="500,96 622,201 585,356 415,356 363,196"
+         fill="rgba(235,108,54,0.18)" stroke="#eb6c36" stroke-width="1.8"/>
+```
+
+Each vertex: `center + (v/10) · (outer_i − center)`, rounded to the nearest pixel.
+
+## Series palette
+
+The skill's "1-focal" rule still holds: `accent` is reserved for the focal series, and a small editorial palette (`series-1` through `series-5`, defined in [`style-guide.md`](style-guide.md)) covers the non-focal series. Don't reach for free-form colors.
+
+| Slot | Token | Light | Dark |
+|---|---|---|---|
+| Focal | `accent` | `#eb6c36` | `#f08a59` |
+| 1 | `series-1` (sage) | `#7c8f6f` | `#9caf8f` |
+| 2 | `series-2` (dusty-blue) | `#5e7a9b` | `#82a0c0` |
+| 3 | `series-3` (mustard) | `#b8915a` | `#d3ad7a` |
+| 4 | `series-4` (rust-brown) | `#9c6b50` | `#b88670` |
+| 5 | `series-5` (slate) | `#6e6479` | `#8d8298` |
+
+## Anti-patterns
+
+- **More than 5 series** → mush. Split into two charts (e.g. "best by latency" + "best by ops") or switch to a comparison table.
+- **Axes on inconsistent native scales** (one 0–100, another 0–1) without normalization. **Always normalize to 0–N first** — radar polygons compare *shapes*, not absolute values.
+- **Zero-baseline tricks** — starting the inner ring at v=5 to amplify differences. The grid starts at 0; if differences look small, that's the truthful reading.
+- **Dots on every series.** Only the focal carries dots. Adding them to all 4–5 series turns the chart into a bead curtain.
+- **Radar with 2 series** — a comparison bar chart or a 2-row table is clearer.
+- **Non-quantitative axes.** All axes must be measurable on the same normalized scale. "Speed" + "color" + "year" mixes don't belong on a radar.
+- **Mono-font axis labels.** Names go in Geist sans (the global rule). Mono is for technical sublabels only.
+- **Rainbow palette.** Even with the new `series-*` tokens, you don't need all 5 in one chart — use only as many as you have non-focal entities.
+
+## Examples
+
+- `assets/example-radar.html` — minimal light. 4 storage backends × 5 workload dimensions, MinIO focal.
+- `assets/example-radar-dark.html` — minimal dark, same data.
+- `assets/example-radar-full.html` — full editorial: container framing + 4 cards (one per backend) with varied widths + footer.

package/framework/skills/diagram-design/references/type-scatter.md

@@ -0,0 +1,39 @@
+# Scatter Plot
+
+**Best for:** correlation and distribution — two continuous variables plotted against each other. Use when the relationship (or lack of one) between variables is the message, or when you need to identify clusters, outliers, and high/low performers.
+
+## Layout conventions
+
+- **Plot area margins:** left 80px, bottom 60px, top 40px, right 40px — inside `0 0 1000 500` viewBox.
+- **Point count:** 5–30 points. Fewer → just describe the relationship in prose; more → bin into a density contour.
+- **Axes:** X at y=420 (baseline), Y at x=80. Both use Geist Mono 8px gridline labels. Gridlines 4–6 per axis at equal intervals.
+- **Point shape:** `<circle>` r=5 for standard points, r=6 for focal. Focal point in `accent` fill. Others in `muted @ 0.20` fill + `muted` stroke.
+- **Labels on points (optional):** Geist Mono 8px next to a point. Use a paper-fill rect mask behind the label. Label at most 2–3 points; not all.
+- **Trend line (optional):** `<line>` from lower-left to upper-right, stroke `rgba(45,49,66,0.25)` dashed 4,3. Never force a perfect fit — only add if the trend is visually obvious.
+- **Quadrant dividers (optional):** light dashed lines at the median x and y to split into quadrants. Label each quadrant in Geist Mono 8px, muted.
+
+### Point pattern
+
+```svg
+<!-- Non-focal point — paper mask + circle -->
+<circle cx="X" cy="Y" r="5" fill="#f5f5f5"/>
+<circle cx="X" cy="Y" r="5" fill="rgba(79,93,117,0.20)" stroke="#4f5d75" stroke-width="1"/>
+
+<!-- Focal point -->
+<circle cx="X" cy="Y" r="6" fill="#f5f5f5"/>
+<circle cx="X" cy="Y" r="6" fill="rgba(235,108,54,0.15)" stroke="#eb6c36" stroke-width="1.2"/>
+```
+
+## Anti-patterns
+
+- More than 30 points without clustering (jitter/mush).
+- Forced trend line when the data is genuinely scattered — dishonest.
+- Point labels on every point (label the focal and 1–2 notable outliers only).
+- Bubble size encoding (use a third axis label or color instead; bubble area perception is unreliable).
+- Axes that don't include zero when the absolute position matters; axes that do include zero when the range is tiny and far from zero.
+
+## Examples
+
+- `assets/example-scatter.html` — minimal light
+- `assets/example-scatter-dark.html` — minimal dark
+- `assets/example-scatter-full.html` — full editorial

package/framework/skills/diagram-design/references/type-sequence.md

@@ -0,0 +1,35 @@
+# Sequence
+
+**Best for:** request/response flows, protocol exchanges, multi-actor interactions over time, API call traces, incident reconstructions.
+
+## Layout conventions
+- Actors as boxes in a horizontal row at the top.
+- **Lifelines**: dashed vertical lines descending from each actor to the bottom.
+- Messages: horizontal arrows between lifelines; time flows top→down.
+- **Activation bar**: narrow rectangle (`w=8`, muted fill, 0.8 hairline stroke) on a lifeline spanning the interval that actor holds control. Stack for nested calls.
+- Self-messages: short U-shaped loop returning to the same lifeline; label right of the loop.
+- Return messages: dashed line in the same color as the originating call.
+- Coral on the primary success response or headline message — one, maybe two.
+
+## Anti-patterns
+- Message arrow pointing *upward* (reverses time — never).
+- Activation bars that never close.
+- Labels sitting over another lifeline — shorten or shift y into a gap.
+- Swimlane-style lanes instead of lifelines (different grammar).
+
+## Lifeline primitive
+```svg
+<line x1="CX" y1="TOP" x2="CX" y2="BOTTOM"
+      stroke="rgba(45,49,66,0.20)" stroke-width="1" stroke-dasharray="3,3"/>
+```
+
+## Activation bar primitive
+```svg
+<rect x="CX-4" y="TOP" width="8" height="H"
+      fill="rgba(45,49,66,0.06)" stroke="#4f5d75" stroke-width="0.8"/>
+```
+
+## Examples
+- `assets/example-sequence.html` — minimal light
+- `assets/example-sequence-dark.html` — minimal dark
+- `assets/example-sequence-full.html` — full editorial

package/framework/skills/diagram-design/references/type-state.md

@@ -0,0 +1,21 @@
+# State Machine
+
+**Best for:** finite state logic — order status, auth state, connection lifecycle, form wizard, job queue status.
+
+## Layout conventions
+- States are rounded rectangles (`rx=8`), labeled in Geist.
+- **Start**: filled ink dot (`r=6`). **End**: ringed dot (outer `r=8` outline, inner filled `r=5`).
+- Transitions: curved arrows labeled in Geist Mono as `event [guard] / action` (omit sections you don't need).
+- Self-loops curve above the state.
+- Orient along the dominant flow direction (left→right or top→down); rearrange before crossing transitions.
+- Coral on the state the reader should notice — typically the error state, or "happy completion".
+
+## Anti-patterns
+- More transitions than states × 2 → likely two state machines.
+- "From any state" transitions drawn from every state — use a single annotation (`* → Error on timeout`) instead.
+- Unlabeled transitions (the whole point is *what triggers this*).
+
+## Examples
+- `assets/example-state.html` — minimal light
+- `assets/example-state-dark.html` — minimal dark
+- `assets/example-state-full.html` — full editorial

package/framework/skills/diagram-design/references/type-swimlane.md

@@ -0,0 +1,20 @@
+# Swimlane
+
+**Best for:** cross-functional processes, RACI-style flows, vendor handoffs, multi-team shipping workflows.
+
+## Layout conventions
+- Horizontal lanes (or vertical columns) — one per actor/team. Label each lane in the left margin (or top) with a Geist Mono eyebrow.
+- Lane dividers: 1px hairlines.
+- Process steps are rectangles placed inside the lane of the actor performing them; arrows show flow.
+- Handoffs (arrows crossing lane boundaries) are the most important edges — consider coral on the handoff that introduces the most coupling or latency.
+- Don't force equal step count per lane; a lane with one step is fine.
+
+## Anti-patterns
+- Lanes without labels.
+- A step drawn across two lanes (pick one owner).
+- Arrows that snake back and forth — reorder steps so the flow is mostly straight.
+
+## Examples
+- `assets/example-swimlane.html` — minimal light
+- `assets/example-swimlane-dark.html` — minimal dark
+- `assets/example-swimlane-full.html` — full editorial

package/framework/skills/diagram-design/references/type-timeline.md

@@ -0,0 +1,20 @@
+# Timeline
+
+**Best for:** release history, project milestones, incident timelines, roadmaps, changelog visualizations.
+
+## Layout conventions
+- Horizontal hairline baseline across the middle (`stroke-width=1`).
+- Tick marks at time boundaries (quarters, months, sprints) with date labels below in Geist Mono.
+- Events: small filled circles (`r=4`) on the baseline. Labels alternate above and below to prevent collision, connected to the circle with a 1px hairline drop.
+- Major milestones: coral circle (`r=6`) + bold Geist label.
+- Time scale must be honest: if intervals are non-equal, space the circles non-equally. Don't fake linear spacing for aesthetics. Break the axis visibly if a region is too dense.
+
+## Anti-patterns
+- Equal-spacing events that aren't equally spaced in time.
+- Missing axis labels ("what unit is this?").
+- Crowded labels without vertical offset — illegible.
+
+## Examples
+- `assets/example-timeline.html` — minimal light
+- `assets/example-timeline-dark.html` — minimal dark
+- `assets/example-timeline-full.html` — full editorial

package/framework/skills/diagram-design/references/type-tree.md

@@ -0,0 +1,24 @@
+# Tree / Hierarchy
+
+**Best for:** org charts, dependency trees, taxonomy, file trees, decision breakdowns, skill trees.
+
+## Layout conventions
+- Root at top, children fan out below (or root at left, children to right).
+- Nodes are small labeled rectangles (`rx=6`), Geist 12px 600 name + optional Geist Mono 9px sublabel. Width 120–180px, height 40–52px.
+- **Connectors are orthogonal (elbow-style), never diagonal.** Parent drops a short vertical line, then a horizontal bus connects siblings, then each child has a short vertical drop into its top edge. 1px muted stroke.
+- Leaf indicator: thinner stroke (0.8) or different fill — OR let terminal position do the work.
+- Max depth: 4 (root + 3 tiers). Max breadth per level: 5.
+- Coral on **one** node: root OR critical leaf. Not both.
+- Draw connectors before nodes.
+
+## Anti-patterns
+- Tree 5+ levels deep on a single page (illegible — split).
+- Nodes of wildly varying widths — pick 2 widths max.
+- Diagonal connector lines.
+- Skipped levels (parent connected to grandchild with no middle).
+- Coral on root AND a leaf.
+
+## Examples
+- `assets/example-tree.html` — minimal light
+- `assets/example-tree-dark.html` — minimal dark
+- `assets/example-tree-full.html` — full editorial

package/framework/skills/diagram-design/references/type-venn.md

@@ -0,0 +1,26 @@
+# Venn / Set Overlap
+
+**Best for:** intersection of concepts/domains, shared attributes between categories, "where A meets B", ikigai-style frames (desirable × feasible × viable).
+
+## Layout conventions
+- **Prefer 2 or 3 circles.** Avoid 4+ (unreadable — use a matrix instead).
+- Circle stroke: 1px hairline, color per-set (ink, muted, soft).
+- Circle fill: very low-opacity tint — `rgba(45,49,66,0.04)` for ink set, `rgba(79,93,117,0.05)` for muted. Tints compound naturally in overlap regions.
+- Radii: equal when sets are comparable in size; proportional when sets are meaningfully different. Don't fake equal sizes for aesthetics.
+- **Set labels** placed outside the circle, NEVER crossing the stroke. Geist 12–14px 600 for the set name, optional Geist Mono 9px sublabel.
+- **Intersection labels** placed inside the overlap region, Geist 12px 600, centered. For small overlaps, use a leader line to a label in clear space.
+- **Coral accent** on the ONE focal intersection — the "sweet spot". Either coral label stroke OR clipPath-bounded coral fill tint (`rgba(235,108,54,0.10)`).
+- Circle centers and radii divisible by 4.
+
+## Anti-patterns
+- Unlabeled regions — reader can't tell which set is which.
+- Circles that don't overlap when overlap is the point.
+- Equal-sized circles when sets are obviously different (dishonest).
+- Coral on multiple overlap regions (focal signal dies).
+- Labels sitting on top of circle strokes (illegible).
+- 4+ circles where 2–3 would do.
+
+## Examples
+- `assets/example-venn.html` — minimal light
+- `assets/example-venn-dark.html` — minimal dark
+- `assets/example-venn-full.html` — full editorial

package/framework/skills/documentation/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: documentation
+description: Create ADRs, design docs, runbooks, API docs, and operational knowledge that stays useful.
+version: 0.1.0
+---
+# Purpose
+Create ADRs, design docs, runbooks, API docs, and operational knowledge that stays useful. This skill guides an AI agent to act with senior backend judgment: clarify the outcome, identify constraints, choose the least complex safe path, and make production impact visible.
+
+# When to Activate
+Use this skill when the task involves ADRs, design documents, runbooks, API documentation, operational documentation, architecture diagrams, or knowledge transfer. It is also useful when a request is vague, risky, touches production behavior, changes contracts, changes data, or needs a reviewable engineering plan. Do not activate it for trivial text edits unless the edit changes engineering guidance.
+
+# Principles
+- Correctness and data integrity come before speed of implementation.
+- Simplicity is a feature: fewer moving parts means fewer failure modes.
+- Existing contracts must remain compatible unless a breaking change is approved.
+- Every important decision should have a reason, an alternative considered, and an operational consequence.
+- Work should be testable, observable, deployable, and reversible.
+- Prefer explicit boundaries, clear names, and local reasoning over clever shared abstractions.
+- Security and privacy are design inputs, not final review steps.
+
+- ADRs record decisions, context, consequences, and alternatives.
+- Design documents explain proposed behavior before expensive implementation.
+- Runbooks explain how to operate, diagnose, mitigate, and escalate.
+- API documentation must define contracts, errors, authorization, examples, limits, and compatibility.
+- Architecture diagrams should show boundaries, data flow, ownership, and failure paths.
+- Documentation should be close to the workflow where it is used.
+
+# Workflow
+1. Identify the audience and their primary use case for the document.
+2. Choose the right document type: ADR, design doc, runbook, API reference, README.
+3. Define the scope: what decisions, behavior, or procedures are covered.
+4. Write the document starting with the summary for busy readers.
+5. Include concrete examples, not just abstract descriptions.
+6. Add failure modes and operational notes where relevant.
+7. Cross-reference related documentation, code, and standards.
+8. Place the document close to where it is used (same repo, same directory).
+9. Review for accuracy with someone who was not involved in the writing.
+
+# Rules
+- Never assume hidden requirements, traffic scale, compliance needs, or data retention rules.
+- Do not introduce new infrastructure unless the current requirement cannot be met safely without it.
+- Do not hide breaking changes in refactors.
+- Do not weaken authorization, validation, transaction safety, or error handling to make implementation easier.
+- Keep public contracts, migrations, and operational changes explicit in the deliverable.
+- Reference related standards: references/standards/documentation.md.
+
+# Deliverables
+- Document with clear audience, purpose, and type.
+- Concrete examples reflecting real usage.
+- Failure modes and operational notes where relevant.
+- Cross-references to related code, standards, and docs.
+- Ownership and update cadence defined.
+
+# Common Mistakes
+- Writing documents that repeat what the code already expresses without adding decision context.
+- Creating documentation that is too long or too vague to be useful under time pressure.
+- Letting documentation become stale because there is no ownership or review process.
+- Writing for an imaginary audience instead of actual readers.
+- Including implementation details that change frequently while omitting stable design decisions.
+
+# Failure Modes
+- A runbook is too long to read during an incident.
+- An ADR describes what was decided but not why alternatives were rejected.
+- Documentation lives in a separate wiki that no one updates after the initial write.
+- Critical operational knowledge exists only in the head of one team member.
+
+# Checklist
+- [ ] The document has a clear audience and purpose.
+- [ ] The document type matches the content (ADR, runbook, design doc, etc.).
+- [ ] Examples are concrete and reflect real usage.
+- [ ] Failure modes and operational notes are included where applicable.
+- [ ] Cross-references to code, standards, or related docs are accurate.
+- [ ] The document is reviewable by someone not involved in its creation.
+- [ ] Ownership and update cadence are defined.

package/framework/skills/documentation/examples.md

@@ -0,0 +1,31 @@
+# Documentation Examples
+
+## Example 1: ADR for Cache Strategy
+
+Write an ADR documenting the decision to add Redis caching for product catalog reads. Good agent behavior:
+
+- State the context: product catalog reads are 500 req/s, each takes 50ms from PostgreSQL, and latency spikes during flash sales.
+- List alternatives considered: in-memory cache (lost on restart, per-node inconsistency), read replicas (cost, replication lag), CDN (static data only).
+- Describe the decision: Redis cache-aside with 5-minute TTL and immediate invalidation on price or stock changes.
+- Record consequences: increased operational complexity (need Redis cluster, monitoring), cache hit ratio must be >90% to justify cost.
+- Link to related ADRs for deployment topology and monitoring setup.
+
+## Example 2: Runbook for Payment Failure
+
+Write a runbook for diagnosing payment processing failures. Good agent behavior:
+
+- Start with the alert trigger (e.g., >5% payment failures in 5 minutes) and the severity level.
+- Provide step-by-step diagnosis: check the payment provider status page, then look at the circuit breaker state, then inspect dead-letter queue.
+- List the dashboards and log queries needed (payment error rate by provider, latency p95, DLQ count).
+- Include remediation steps: toggle the kill switch to fallback provider, reset circuit breaker after provider recovers, replay DLQ messages.
+- End with escalation contacts and a post-mortem template link for the follow-up.
+
+## Example 3: API Docs for Public Endpoint
+
+Document a public POST /orders endpoint for external developers. Good agent behavior:
+
+- Show a complete request example with all fields, including `Idempotency-Key` in the header and `X-Api-Version`.
+- Show success (201), validation error (422), and conflict (409) response bodies with annotated fields.
+- Document authentication: `Bearer` token in the `Authorization` header with required scopes.
+- Note rate limits (100 req/min per token) and include `X-RateLimit-Remaining` in the response.
+- List every error code with a human-readable message, a likely cause, and a recovery action.

package/framework/skills/find-skills/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query] [--owner <owner>]` - Search for skills interactively or by keyword, optionally scoped to a GitHub owner
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Check the Leaderboard First
+
+Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
+
+For example, top skills for web development include:
+- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
+- `anthropics/skills` — Frontend design, document processing (100K+ installs)
+
+### Step 3: Search for Skills
+
+If the leaderboard doesn't cover the user's need, run the find command:
+
+```bash
+npx skills find [query] [--owner <owner>]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+### Step 4: Verify Quality Before Recommending
+
+**Do not recommend a skill based solely on search results.** Always verify:
+
+1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
+2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
+3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
+
+### Step 5: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install count and source
+3. The install command they can run
+4. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+(185K installs)
+
+To install it:
+npx skills add vercel-labs/agent-skills@react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
+```
+
+### Step 6: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```

package/framework/skills/find-skills/examples.md

@@ -0,0 +1,35 @@
+# Find Skills Examples
+
+## Discover a React performance skill
+
+User: "How can I make my React app faster?"
+
+Good agent behavior:
+
+- Recognize that the user may benefit from an existing performance skill.
+- Check the skills.sh leaderboard for established React and performance skills.
+- Search with `npx skills find react performance` if the leaderboard does not provide a clear match.
+- Compare install counts and source reputation before recommending an option.
+- Present the skill name, purpose, source, install command, and skills.sh link.
+
+## Find a deployment workflow
+
+User: "Is there a skill that can help me deploy a Docker app to Kubernetes?"
+
+Good agent behavior:
+
+- Identify the domain as DevOps and the task as Docker-to-Kubernetes deployment.
+- Search with specific terms such as `npx skills find docker kubernetes deployment`.
+- Verify that recommended skills are maintained and come from credible sources.
+- Explain what each candidate covers and avoid presenting unverified search results as trusted guidance.
+
+## No suitable skill exists
+
+User: "Find a skill for our internal release process."
+
+Good agent behavior:
+
+- Search for relevant release and workflow skills using the user's terminology.
+- State clearly when no suitable existing skill is found.
+- Offer to help with the release process directly.
+- Suggest `npx skills init internal-release` if the workflow is recurring and worth packaging as a skill.

package/framework/skills/gitlab-mcp/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: gitlab-mcp
+description: Use this skill when working with the GitLab MCP server tools for merge requests, issues, repositories, pipelines, work items, webhooks, search, and related GitLab workflows.
+---
+
+# gitlab-mcp
+
+GitLab MCP server providing 173 tools: 171 tools across 16 toolsets, plus `execute_graphql` and the always-available `discover_tools` meta-tool.
+
+## Toolsets
+
+| Toolset                   | Default | Enable with                                          |
+|---------------------------|---------|------------------------------------------------------|
+| merge_requests (41 tools) | yes     | -                                                    |
+| issues (23 tools)         | yes     | -                                                    |
+| repositories (7 tools)    | yes     | -                                                    |
+| branches (6 tools)        | yes     | -                                                    |
+| projects (8 tools)        | yes     | -                                                    |
+| labels (5 tools)          | yes     | -                                                    |
+| ci (2 tools)              | yes     | -                                                    |
+| users (5 tools)           | yes     | -                                                    |
+| pipelines (19 tools)      | no      | `USE_PIPELINE=true` or `GITLAB_TOOLSETS=pipelines`   |
+| milestones (9 tools)      | no      | `USE_MILESTONE=true` or `GITLAB_TOOLSETS=milestones` |
+| wiki (10 tools)           | no      | `USE_GITLAB_WIKI=true` or `GITLAB_TOOLSETS=wiki`     |
+| releases (7 tools)        | no      | `GITLAB_TOOLSETS=releases`                           |
+| tags (5 tools)            | no      | `GITLAB_TOOLSETS=tags`                               |
+| workitems (18 tools)      | no      | `GITLAB_TOOLSETS=workitems`                          |
+| webhooks (3 tools)        | no      | `GITLAB_TOOLSETS=webhooks`                           |
+| search (3 tools)          | no      | `GITLAB_TOOLSETS=search`                             |
+
+Enable all: `GITLAB_TOOLSETS=all`. Use `GITLAB_TOOLS` to enable individual tools outside their toolset. `discover_tools` can activate opt-in categories for the current session.
+
+## Key Workflows
+
+### Code Review (see references/code-review.md)
+
+1. `list_merge_request_changed_files` - get file paths only (no diffs)
+2. `get_merge_request_file_diff` - get diffs for 3-5 files per call (batch)
+3. `create_merge_request_thread` or `create_draft_note` - leave review comments
+4. `bulk_publish_draft_notes` - publish all drafts at once
+
+### MR Lifecycle (see references/merge-requests.md)
+
+`create_merge_request` -> review -> `approve_merge_request` -> `merge_merge_request`
+
+### Issue Management (see references/issues.md)
+
+`create_issue` -> `create_issue_link` -> `create_issue_note` -> `update_issue`
+
+### Work Items (see references/work-items.md)
+
+`list_work_items` -> `get_work_item` -> `update_work_item` -> `create_work_item_note`
+
+### Webhooks & Search
+
+- Webhooks: see references/webhooks.md
+- Code search: see references/search.md
+
+### File Operations
+
+- Read: `get_file_contents`, `get_repository_tree`
+- Write: `create_or_update_file` (single file), `push_files` (multiple files in one commit)
+
+## Parameter Hints
+
+- **project_id**: numeric ID or URL-encoded path (`group/subgroup/project`)
+- **MR lookup**: provide `mergeRequestIid` OR `branchName` (not both)
+- **list_issues**: default scope = created by current user. Use `scope: "all"` for all issues
+- **list_merge_requests**: without project_id returns user's MRs across all projects
+- **emoji reactions**: merge request, issue, and work item reaction tools use GitLab emoji names like `thumbsup`, `rocket`, or `eyes`
+- **work items**: status and custom fields require GitLab Premium/Ultimate features
+- **execute_graphql**: escape double quotes in query strings
+
+## Destructive Tools (require caution)
+
+`delete_issue`, `delete_label`, `delete_wiki_page`, `delete_group_wiki_page`, `delete_milestone`, `delete_release`, `delete_tag`, `delete_merge_request_note`, `delete_merge_request_discussion_note`, `delete_draft_note`, `delete_issue_link`, `delete_merge_request_emoji_reaction`, `delete_merge_request_note_emoji_reaction`, `delete_issue_emoji_reaction`, `delete_issue_note_emoji_reaction`, `delete_work_item_emoji_reaction`, `delete_work_item_note_emoji_reaction`, `merge_merge_request`, `push_files`
+
+## Advanced
+
+- **Dynamic discovery**: `discover_tools` lists and activates opt-in toolsets at runtime
+- **GraphQL**: `execute_graphql` for queries not covered by REST tools
+- **Zoekt search**: `search_code`, `search_project_code`, `search_group_code` (requires advanced search enabled)
+- **Work Items**: GraphQL-based alternative to issues (Premium/Ultimate features)