@deck-ui/skills 0.2.0

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@deck-ui/skills",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": ["src"],
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@deck-ui/core": "^0.1.0"
+  },
+  "dependencies": {
+    "lucide-react": "^0.577.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/community-skill-row.tsx

@@ -0,0 +1,67 @@
+import type { CommunitySkill } from "./types"
+import { cn } from "@deck-ui/core"
+import { Plus, Loader2, Check } from "lucide-react"
+
+export interface CommunitySkillRowProps {
+  skill: CommunitySkill
+  installing: boolean
+  installed: boolean
+  onInstall: () => void
+}
+
+function formatInstalls(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`
+  return String(n)
+}
+
+/** Convert "vercel-react-best-practices" to "Vercel React Best Practices" */
+function kebabToTitle(s: string): string {
+  return s
+    .split("-")
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ")
+}
+
+export function CommunitySkillRow({
+  skill,
+  installing,
+  installed,
+  onInstall,
+}: CommunitySkillRowProps) {
+  return (
+    <div
+      className="flex items-center gap-3 px-4 py-3 rounded-xl border border-black/[0.08]
+                 bg-white hover:border-black/[0.15] transition-all"
+    >
+      <div className="flex-1 min-w-0">
+        <p className="text-sm font-medium text-[#0d0d0d] truncate">
+          {kebabToTitle(skill.name)}
+        </p>
+        <p className="text-xs text-[#9b9b9b] truncate mt-0.5">
+          {skill.source} · {formatInstalls(skill.installs)} installs
+        </p>
+      </div>
+      <button
+        onClick={onInstall}
+        disabled={installing || installed}
+        className={cn(
+          "shrink-0 size-7 flex items-center justify-center rounded-lg transition-colors",
+          installed
+            ? "text-[#9b9b9b] cursor-default"
+            : "text-[#9b9b9b] hover:bg-black/[0.06] hover:text-[#0d0d0d]",
+          installing && "opacity-50 cursor-wait",
+        )}
+      >
+        {installing ? (
+          <Loader2 className="size-4 animate-spin" />
+        ) : installed ? (
+          <Check className="size-4" />
+        ) : (
+          <Plus className="size-4" />
+        )}
+      </button>
+    </div>
+  )
+}

package/src/community-skills-browser.tsx

@@ -0,0 +1,134 @@
+/**
+ * CommunitySkillsSection — Search and install skills from a community marketplace.
+ * Fully props-driven: host app provides search + install callbacks.
+ */
+import { useCallback, useEffect, useState } from "react"
+import type { CommunitySkill } from "./types"
+import { CommunitySkillRow } from "./community-skill-row"
+import { Search } from "lucide-react"
+
+const PAGE_SIZE = 20
+
+export interface CommunitySkillsSectionProps {
+  /** Called when the user types a search query (debounced internally at 350ms). */
+  onSearch: (query: string) => Promise<CommunitySkill[]>
+  /** Called when the user clicks install on a community skill. Should return the installed skill name. */
+  onInstall: (skill: CommunitySkill) => Promise<string>
+}
+
+export function CommunitySkillsSection({
+  onSearch,
+  onInstall,
+}: CommunitySkillsSectionProps) {
+  const [query, setQuery] = useState("")
+  const [results, setResults] = useState<CommunitySkill[]>([])
+  const [loading, setLoading] = useState(false)
+  const [showAll, setShowAll] = useState(false)
+  const [installingIds, setInstallingIds] = useState<Set<string>>(new Set())
+  const [installedIds, setInstalledIds] = useState<Set<string>>(new Set())
+
+  useEffect(() => {
+    const q = query.trim()
+    if (!q) {
+      setResults([])
+      return
+    }
+    const timer = setTimeout(() => {
+      doSearch(q)
+      setShowAll(false)
+    }, 350)
+    return () => clearTimeout(timer)
+  }, [query])
+
+  const doSearch = async (q: string) => {
+    setLoading(true)
+    try {
+      const skills = await onSearch(q)
+      setResults(skills)
+    } catch {
+      setResults([])
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  const handleInstall = useCallback(
+    async (skill: CommunitySkill) => {
+      setInstallingIds((prev) => new Set(prev).add(skill.id))
+      try {
+        await onInstall(skill)
+        setInstalledIds((prev) => new Set(prev).add(skill.id))
+      } finally {
+        setInstallingIds((prev) => {
+          const next = new Set(prev)
+          next.delete(skill.id)
+          return next
+        })
+      }
+    },
+    [onInstall],
+  )
+
+  const visible = showAll ? results : results.slice(0, PAGE_SIZE)
+  const hasMore = results.length > PAGE_SIZE && !showAll
+
+  return (
+    <section className="space-y-3">
+      <div>
+        <h2 className="text-sm font-medium text-[#0d0d0d]">
+          Discover skills from the community
+        </h2>
+        <p className="text-xs text-[#9b9b9b] mt-0.5">
+          Browse thousands of ready-made procedures on skills.sh
+        </p>
+      </div>
+
+      {/* Search bar */}
+      <div className="relative">
+        <Search className="absolute left-3 top-1/2 -translate-y-1/2 size-4 text-[#9b9b9b]" />
+        <input
+          type="text"
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          placeholder={'Search by what you want to achieve, like "sdr" or "writing"'}
+          className="w-full h-9 pl-9 pr-3 rounded-full border border-black/[0.10] bg-white text-sm
+                     placeholder:text-black/40 focus:outline-none focus:border-black/[0.25] transition-colors"
+        />
+      </div>
+
+      {/* Results grid */}
+      {loading && results.length === 0 && (
+        <p className="text-sm text-[#9b9b9b] animate-pulse">Loading...</p>
+      )}
+
+      {!loading && results.length === 0 && query.trim() && (
+        <p className="text-sm text-[#9b9b9b]">
+          No skills found for "{query.trim()}"
+        </p>
+      )}
+
+      {visible.length > 0 && (
+        <div className="grid grid-cols-1 lg:grid-cols-2 gap-2">
+          {visible.map((skill) => (
+            <CommunitySkillRow
+              key={skill.id}
+              skill={skill}
+              installing={installingIds.has(skill.id)}
+              installed={installedIds.has(skill.id)}
+              onInstall={() => handleInstall(skill)}
+            />
+          ))}
+        </div>
+      )}
+
+      {hasMore && (
+        <button
+          onClick={() => setShowAll(true)}
+          className="text-sm text-[#5d5d5d] hover:text-[#0d0d0d] transition-colors"
+        >
+          Show {results.length - PAGE_SIZE} more
+        </button>
+      )}
+    </section>
+  )
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+// Types
+export type {
+  Skill,
+  CommunitySkill,
+  LearningCategory,
+  SkillLearning,
+} from "./types"
+export { CATEGORY_LABELS } from "./types"
+
+// Components
+export { SkillsGrid } from "./skills-grid"
+export type { SkillsGridProps } from "./skills-grid"
+export { SkillRow } from "./skill-row"
+export type { SkillRowProps } from "./skill-row"
+export { SkillDetailPage } from "./skill-detail-page"
+export type { SkillDetailPageProps } from "./skill-detail-page"
+export { CommunitySkillsSection } from "./community-skills-browser"
+export type { CommunitySkillsSectionProps } from "./community-skills-browser"
+export { CommunitySkillRow } from "./community-skill-row"
+export type { CommunitySkillRowProps } from "./community-skill-row"
+export { LearningRow } from "./learning-row"
+export type { LearningRowProps } from "./learning-row"

package/src/learning-row.tsx

@@ -0,0 +1,51 @@
+import { CATEGORY_LABELS } from "./types"
+import type { LearningCategory } from "./types"
+import { Trash2 } from "lucide-react"
+
+export interface LearningRowProps {
+  content: string
+  category: LearningCategory
+  sourceTitle: string | null
+  createdAt: string
+  onDelete: () => void
+}
+
+export function LearningRow({
+  content,
+  category,
+  sourceTitle,
+  createdAt,
+  onDelete,
+}: LearningRowProps) {
+  const label = CATEGORY_LABELS[category] ?? category
+  const date = new Date(createdAt).toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+  })
+
+  return (
+    <div className="rounded-xl border border-black/[0.06] p-4 group">
+      <div className="flex items-start gap-3">
+        <p className="text-sm text-[#0d0d0d] flex-1 leading-relaxed">
+          {content}
+        </p>
+        <button
+          onClick={onDelete}
+          className="shrink-0 size-7 flex items-center justify-center rounded-lg text-[#9b9b9b] hover:text-red-500 hover:bg-red-50 transition-colors"
+          aria-label="Delete learning"
+        >
+          <Trash2 className="size-3.5" />
+        </button>
+      </div>
+      <div className="flex items-center gap-2 mt-2 text-xs text-[#9b9b9b]">
+        <span className="px-1.5 py-0.5 rounded-md bg-black/[0.04] text-[#5d5d5d]">
+          {label}
+        </span>
+        {sourceTitle && (
+          <span className="truncate max-w-[200px]">{sourceTitle}</span>
+        )}
+        <span>{date}</span>
+      </div>
+    </div>
+  )
+}

package/src/skill-detail-page.tsx

@@ -0,0 +1,117 @@
+/**
+ * SkillDetailPage — View and edit a skill's instructions + learnings.
+ * Fully props-driven: host app provides the skill data and save callback.
+ */
+import { useCallback, useEffect, useState } from "react"
+import type { Skill } from "./types"
+import { ArrowLeft, FileText } from "lucide-react"
+
+export interface SkillDetailPageProps {
+  skill: Skill | undefined
+  onBack: () => void
+  onSave: (skillName: string, instructions: string) => Promise<void>
+}
+
+export function SkillDetailPage({
+  skill,
+  onBack,
+  onSave,
+}: SkillDetailPageProps) {
+  const [instructions, setInstructions] = useState("")
+  const [saving, setSaving] = useState(false)
+
+  useEffect(() => {
+    if (skill) setInstructions(skill.instructions)
+  }, [skill?.id])
+
+  const handleSave = useCallback(async () => {
+    if (!skill) return
+    setSaving(true)
+    try {
+      await onSave(skill.name, instructions)
+    } finally {
+      setSaving(false)
+    }
+  }, [skill, instructions, onSave])
+
+  if (!skill) {
+    return (
+      <div className="flex-1 flex items-center justify-center">
+        <p className="text-sm text-[#9b9b9b]">Skill not found</p>
+      </div>
+    )
+  }
+
+  const isDirty = instructions !== skill.instructions
+
+  return (
+    <div className="flex-1 flex flex-col min-h-0 overflow-hidden">
+      {/* Header */}
+      <div className="shrink-0 px-6 py-3 border-b border-black/[0.06]">
+        <div className="max-w-2xl mx-auto flex items-center gap-3">
+          <button
+            onClick={onBack}
+            className="size-8 flex items-center justify-center rounded-lg text-[#9b9b9b] hover:text-[#0d0d0d] hover:bg-black/[0.05] transition-colors"
+          >
+            <ArrowLeft className="size-4" />
+          </button>
+          <div className="flex-1 min-w-0">
+            <h1 className="text-sm font-medium text-[#0d0d0d] truncate">
+              {skill.name}
+            </h1>
+            <p className="text-xs text-[#9b9b9b] flex items-center gap-1 truncate">
+              <FileText className="size-3" />
+              {skill.file_path}
+            </p>
+          </div>
+        </div>
+      </div>
+
+      {/* Body */}
+      <div className="flex-1 overflow-y-auto px-6 py-6">
+        <div className="max-w-2xl mx-auto space-y-8">
+          {/* Instructions */}
+          <section>
+            <label className="block text-xs font-medium text-[#9b9b9b] tracking-wider mb-2">
+              Instructions
+            </label>
+            <textarea
+              value={instructions}
+              onChange={(e) => setInstructions(e.target.value)}
+              rows={12}
+              className="w-full rounded-xl border border-black/[0.08] bg-white px-4 py-3 text-sm text-[#0d0d0d] placeholder:text-[#9b9b9b] focus:outline-none focus:border-black/[0.2] resize-y font-mono"
+              placeholder="Instructions for this skill..."
+            />
+            <div className="flex items-center gap-3 mt-3">
+              <button
+                onClick={handleSave}
+                disabled={!isDirty || saving}
+                className="px-4 py-2 rounded-full text-sm font-medium bg-[#0d0d0d] text-white hover:bg-[#2d2d2d] disabled:opacity-40 disabled:cursor-not-allowed transition-colors"
+              >
+                {saving ? "Saving..." : "Save"}
+              </button>
+              {isDirty && (
+                <span className="text-xs text-[#9b9b9b]">Unsaved changes</span>
+              )}
+            </div>
+          </section>
+
+          {/* Learnings */}
+          {skill.learnings.trim() && (
+            <section>
+              <label className="block text-xs font-medium text-[#9b9b9b] tracking-wider mb-2">
+                Learnings
+              </label>
+              <div className="rounded-xl border border-black/[0.08] bg-[#fafafa] px-4 py-3 text-sm text-[#5d5d5d] whitespace-pre-wrap font-mono">
+                {skill.learnings}
+              </div>
+              <p className="text-xs text-[#9b9b9b] mt-2">
+                Learnings are added automatically when you give feedback on completed tasks.
+              </p>
+            </section>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/skill-row.tsx

@@ -0,0 +1,27 @@
+import type { Skill } from "./types"
+
+export interface SkillRowProps {
+  skill: Skill
+  onClick: () => void
+}
+
+export function SkillRow({ skill, onClick }: SkillRowProps) {
+  return (
+    <button
+      onClick={onClick}
+      className="w-full flex items-center gap-3 px-4 py-3 rounded-xl border border-black/[0.08]
+                 bg-white hover:border-black/[0.15] transition-all text-left"
+    >
+      <div className="flex-1 min-w-0">
+        <p className="text-sm font-medium text-[#0d0d0d] truncate">
+          {skill.name}
+        </p>
+        {skill.description && (
+          <p className="text-xs text-[#9b9b9b] truncate mt-0.5">
+            {skill.description}
+          </p>
+        )}
+      </div>
+    </button>
+  )
+}

package/src/skills-grid.tsx

@@ -0,0 +1,70 @@
+/**
+ * SkillsGrid — Installed skills list + optional community skills section.
+ * Fully props-driven: host app provides data and callbacks.
+ */
+import { useMemo } from "react"
+import type { Skill, CommunitySkill } from "./types"
+import { SkillRow } from "./skill-row"
+import { CommunitySkillsSection } from "./community-skills-browser"
+
+export interface SkillsGridProps {
+  skills: Skill[]
+  loading: boolean
+  onSkillClick: (skill: Skill) => void
+  /** Community marketplace callbacks. Omit to hide the community section. */
+  community?: {
+    onSearch: (query: string) => Promise<CommunitySkill[]>
+    onInstall: (skill: CommunitySkill) => Promise<string>
+  }
+}
+
+export function SkillsGrid({
+  skills,
+  loading,
+  onSkillClick,
+  community,
+}: SkillsGridProps) {
+  const sorted = useMemo(() => {
+    return [...skills].sort((a, b) => a.name.localeCompare(b.name))
+  }, [skills])
+
+  if (loading && skills.length === 0) {
+    return (
+      <div className="flex-1 flex items-center justify-center">
+        <p className="text-sm text-[#9b9b9b] animate-pulse">
+          Loading skills...
+        </p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex-1 overflow-y-auto">
+      <div className="max-w-3xl mx-auto px-6 py-6 space-y-8">
+        {/* Installed section */}
+        {sorted.length > 0 && (
+          <section className="space-y-3">
+            <h2 className="text-sm font-medium text-[#0d0d0d] normal-case">Installed</h2>
+            <div className="grid grid-cols-1 lg:grid-cols-2 gap-2">
+              {sorted.map((skill) => (
+                <SkillRow
+                  key={skill.id}
+                  skill={skill}
+                  onClick={() => onSkillClick(skill)}
+                />
+              ))}
+            </div>
+          </section>
+        )}
+
+        {/* Community marketplace */}
+        {community && (
+          <CommunitySkillsSection
+            onSearch={community.onSearch}
+            onInstall={community.onInstall}
+          />
+        )}
+      </div>
+    </div>
+  )
+}

package/src/styles.css

@@ -0,0 +1,2 @@
+/* @deck-ui/skills — Tell Tailwind to scan this package's components */
+@source ".";

package/src/types.ts

@@ -0,0 +1,41 @@
+export interface Skill {
+  id: string
+  name: string
+  description: string
+  instructions: string
+  learnings: string
+  file_path: string
+}
+
+export interface CommunitySkill {
+  id: string
+  skillId: string
+  name: string
+  installs: number
+  source: string
+}
+
+export type LearningCategory =
+  | "pattern"
+  | "pitfall"
+  | "preference"
+  | "procedure"
+
+export const CATEGORY_LABELS: Record<LearningCategory, string> = {
+  pattern: "Pattern",
+  pitfall: "Pitfall",
+  preference: "Preference",
+  procedure: "Procedure",
+}
+
+export interface SkillLearning {
+  id: string
+  skill_id: string
+  project_id: string
+  content: string
+  rationale: string
+  category: LearningCategory
+  source_issue_id: string | null
+  source_issue_title: string | null
+  created_at: string
+}