Skip to content

Commit 90380be

Browse files
codeaholicguycodeaholicguy
committed
Add skill explore on web
1 parent c1e4c46 commit 90380be

8 files changed

Lines changed: 788 additions & 0 deletions

File tree

‎docs/ai/design/feature-web-skill-search.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
phase: design
3+
title: System Design & Architecture
4+
description: Define the technical architecture, components, and data models
5+
---
6+
7+
# System Design & Architecture
8+
9+
## Architecture Overview
10+
**What is the high-level system structure?**
11+
12+
```mermaid
13+
graph TD
14+
User([User]) --> SkillsPage["/skills Page"]
15+
SkillsPage --> SearchInput["Search Input"]
16+
SkillsPage --> SkillGrid["Skill Grid"]
17+
SearchInput -->|filters| SkillGrid
18+
SkillGrid --> SkillCard["Skill Cards"]
19+
SkillCard -->|click| SkillModal["Install Modal"]
20+
SkillsPage -->|fetch| RemoteJSON["GitHub JSON"]
21+
```
22+
23+
### Key Components
24+
- **Skills Page** (`/skills`): Container page with search and grid
25+
- **Search Input**: Text input for real-time filtering
26+
- **Skill Grid**: Responsive grid displaying skill cards
27+
- **Skill Card**: Individual skill display with name and description preview
28+
- **Install Modal**: Overlay showing full details and install command
29+
30+
### Technology Stack
31+
- Next.js 14+ (existing framework)
32+
- React hooks for state management
33+
- Tailwind CSS for styling (matching existing patterns)
34+
- Fetch API for data loading
35+
36+
## Data Models
37+
**What data do we need to manage?**
38+
39+
### Skill Data Structure (from JSON)
40+
```typescript
41+
interface Skill {
42+
name: string;
43+
registry: string;
44+
path: string;
45+
description: string;
46+
lastIndexed: number;
47+
}
48+
49+
interface SkillIndex {
50+
meta: {
51+
version: number;
52+
createdAt: number;
53+
updatedAt: number;
54+
registryHeads: Record<string, string>;
55+
};
56+
skills: Skill[];
57+
}
58+
```
59+
60+
### Component State
61+
```typescript
62+
interface SkillsPageState {
63+
skills: Skill[];
64+
searchQuery: string;
65+
selectedSkill: Skill | null;
66+
isLoading: boolean;
67+
error: string | null;
68+
copied: boolean; // Copy-to-clipboard feedback
69+
}
70+
```
71+
72+
## API Design
73+
**How do components communicate?**
74+
75+
No custom API required. The page fetches directly from the remote JSON endpoint:
76+
- **Endpoint**: `https://raw.githubusercontent.com/codeaholicguy/ai-devkit/main/skills/index.json`
77+
- **Method**: GET (static file)
78+
- **Auth**: None required (public endpoint)
79+
80+
## Component Breakdown
81+
**What are the major building blocks?**
82+
83+
### Page Component: `app/skills/page.tsx`
84+
- Fetches skill data on mount
85+
- Manages search state and filtering
86+
- Renders search input, grid, and conditional modal
87+
88+
### Subcomponents (inline)
89+
- **SearchInput**: Controlled input with 200ms debounce for smoother filtering
90+
- **SkillCard**: Displays skill name, truncated description, click handler
91+
- **SkillModal**: Full details view with copy-to-clipboard for install command
92+
93+
## Design Decisions
94+
**Why did we choose this approach?**
95+
96+
| Decision | Rationale | Alternatives Considered |
97+
|----------|-----------|------------------------|
98+
| Client-side fetch | Simple, no API needed | SSG with revalidation |
99+
| Client-side filtering | Real-time UX, small dataset | Server-side search |
100+
| Modal for details | Focus on one skill, copy command | Separate detail page |
101+
| Inline components | Simple feature, fewer files | Component folder structure |
102+
103+
## Non-Functional Requirements
104+
**How should the system perform?**
105+
106+
### Performance
107+
- Initial load < 2 seconds
108+
- Search filtering < 100ms response
109+
110+
### Accessibility
111+
- Keyboard navigation for search and modal
112+
- Screen reader support for skill cards
113+
- Focus trap in modal
114+
115+
### Responsive Design
116+
- Grid: 1 col mobile, 2 cols tablet, 3-4 cols desktop
117+
- Modal: Full width on mobile, centered on desktop

‎docs/ai/implementation/feature-web-skill-search.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
phase: implementation
3+
title: Implementation Guide
4+
description: Technical implementation notes, patterns, and code guidelines
5+
---
6+
7+
# Implementation Guide
8+
9+
## Development Setup
10+
**How do we get started?**
11+
12+
```bash
13+
cd web
14+
npm install
15+
npm run dev
16+
```
17+
18+
Navigate to `http://localhost:3000/skills` to test.
19+
20+
## Code Structure
21+
**How is the code organized?**
22+
23+
```
24+
web/
25+
├── app/
26+
│ └── skills/
27+
│ └── page.tsx # Main skills page
28+
├── components/ # (optional: extract if needed)
29+
└── lib/ # (optional: types)
30+
```
31+
32+
## Implementation Notes
33+
**Key technical details to remember:**
34+
35+
### Data Fetching
36+
- Use `fetch` in `useEffect` for client-side loading
37+
- Parse JSON and extract `skills` array
38+
- Handle loading and error states
39+
40+
### Search Filtering
41+
```typescript
42+
const filteredSkills = skills.filter(skill =>
43+
skill.name.toLowerCase().includes(searchQuery.toLowerCase()) ||
44+
skill.description.toLowerCase().includes(searchQuery.toLowerCase())
45+
);
46+
```
47+
48+
### Modal Implementation
49+
- Use React state for `selectedSkill`
50+
- Render conditionally when skill is selected
51+
- Close on backdrop click or Escape key
52+
53+
### Copy to Clipboard
54+
```typescript
55+
navigator.clipboard.writeText(`npx ai-devkit skill add ${skill.name}`);
56+
```
57+
58+
## Integration Points
59+
**How do pieces connect?**
60+
61+
- Page fetches from: `https://raw.githubusercontent.com/codeaholicguy/ai-devkit/main/skills/index.json`
62+
- Follows existing page patterns from `app/page.tsx`
63+
- Uses existing CSS variables from `globals.css`
64+
65+
## Error Handling
66+
**How do we handle failures?**
67+
68+
- Network error → show retry button
69+
- Empty results → show "No skills found" message
70+
- Clipboard API failure → show fallback (select text)
71+
72+
## Performance Considerations
73+
**How do we keep it fast?**
74+
75+
- Client-side filtering is fast for <1000 items
76+
- Debounce search input if needed (usually not for <500 items)
77+
- Lazy load images if skill icons are added later

‎docs/ai/planning/feature-web-skill-search.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
phase: planning
3+
title: Project Planning & Task Breakdown
4+
description: Break down work into actionable tasks and estimate timeline
5+
---
6+
7+
# Project Planning & Task Breakdown
8+
9+
## Current Status: ✅ Complete
10+
11+
**Last Updated:** 2026-02-07
12+
13+
Implementation is complete and verified. All milestones achieved.
14+
15+
---
16+
17+
## Milestones
18+
**What are the major checkpoints?**
19+
20+
- [x] Milestone 1: Documentation complete and approved
21+
- [x] Milestone 2: Basic page with data loading
22+
- [x] Milestone 3: Search and filtering working
23+
- [x] Milestone 4: Modal and install command copy
24+
- [x] Milestone 5: Polish and responsive design
25+
26+
## Task Breakdown
27+
**What specific work needs to be done?**
28+
29+
### Phase 1: Foundation ✅
30+
- [x] Task 1.1: Create `/skills` route directory and page.tsx
31+
- [x] Task 1.2: Implement skill data fetching from remote JSON
32+
- [x] Task 1.3: Add loading and error states
33+
34+
### Phase 2: Core Features ✅
35+
- [x] Task 2.1: Build skill card component with name and description
36+
- [x] Task 2.2: Implement responsive grid layout
37+
- [x] Task 2.3: Add search input with real-time filtering (with 200ms debounce)
38+
- [x] Task 2.4: Create install modal component
39+
- [x] Task 2.5: Add copy-to-clipboard for install command
40+
41+
### Phase 3: Integration & Polish ✅
42+
- [x] Task 3.1: Style components to match existing website design
43+
- [x] Task 3.2: Add responsive breakpoints
44+
- [x] Task 3.3: Handle empty search results
45+
- [x] Task 3.4: Update sitemap.ts to include /skills
46+
- [x] Task 3.5: Add SEO meta tags (layout.tsx with OpenGraph/Twitter)
47+
48+
## Dependencies
49+
**What needs to happen in what order?**
50+
51+
```mermaid
52+
graph LR
53+
T1.1[Create Route] --> T1.2[Fetch Data]
54+
T1.2 --> T1.3[Loading States]
55+
T1.2 --> T2.1[Skill Card]
56+
T2.1 --> T2.2[Grid Layout]
57+
T2.2 --> T2.3[Search Input]
58+
T2.1 --> T2.4[Modal]
59+
T2.4 --> T2.5[Copy Command]
60+
T2.3 --> T3.1[Styling]
61+
T2.5 --> T3.1
62+
T3.1 --> T3.2[Responsive]
63+
T3.2 --> T3.3[Empty States]
64+
T3.3 --> T3.4[Sitemap]
65+
T3.4 --> T3.5[SEO]
66+
```
67+
68+
### External Dependencies
69+
- Remote JSON must be accessible ✅
70+
- Existing CSS patterns in globals.css ✅
71+
72+
## Timeline & Estimates
73+
**When will things be done?**
74+
75+
| Phase | Estimated | Actual |
76+
|-------|-----------|--------|
77+
| Phase 1: Foundation | 30 min | ✅ |
78+
| Phase 2: Core Features | 1 hour | ✅ |
79+
| Phase 3: Polish | 30 min | ✅ |
80+
| **Total** | ~2 hours | ✅ Complete |
81+
82+
## Risks & Mitigation
83+
**What could go wrong?**
84+
85+
| Risk | Status | Notes |
86+
|------|--------|-------|
87+
| JSON endpoint unavailable | ✅ Mitigated | Error state with retry button |
88+
| Large skill count (~1400) | ✅ Handled | Client-side filtering works well with debounce |
89+
| Modal accessibility | ✅ Addressed | Escape key, click outside, aria-labels |
90+
91+
## Implementation Summary
92+
93+
**Files Created/Modified:**
94+
- `web/app/skills/page.tsx` - Main skills page component
95+
- `web/app/skills/layout.tsx` - SEO metadata
96+
- `web/app/sitemap.ts` - Added /skills route
97+
98+
**Key Enhancements Made:**
99+
- Added 200ms debounce for search (not originally planned, improves UX)
100+
- Install command includes registry (user requirement)
101+
- Elegant modal design with backdrop blur
102+
103+
## Resources Needed
104+
**What do we need to succeed?**
105+
106+
- ✅ Existing web codebase patterns (page.tsx, globals.css)
107+
- ✅ Remote JSON endpoint for skill data
108+
- ✅ Understanding of Next.js App Router

‎docs/ai/requirements/feature-web-skill-search.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
phase: requirements
3+
title: Requirements & Problem Understanding
4+
description: Clarify the problem space, gather requirements, and define success criteria
5+
---
6+
7+
# Requirements & Problem Understanding
8+
9+
## Problem Statement
10+
**What problem are we solving?**
11+
12+
- Users currently need to use the CLI (`ai-devkit skill find`) to discover available skills
13+
- There's no web-based way to browse and search the skill ecosystem
14+
- Developers visiting the website cannot easily explore what skills are available before installing AI DevKit
15+
16+
## Goals & Objectives
17+
**What do we want to achieve?**
18+
19+
### Primary Goals
20+
- Provide a web page at `/skills` to browse and search available skills
21+
- Enable real-time filtering/search by skill name
22+
- Display skill details (description, registry, install command) via modal
23+
24+
### Secondary Goals
25+
- Make it easy to copy the install command
26+
- Showcase the breadth of the skill ecosystem to potential users
27+
28+
### Non-Goals
29+
- Installing skills directly from the web (requires CLI)
30+
- User accounts or saved favorites
31+
- Skill rating/reviews system
32+
33+
## User Stories & Use Cases
34+
**How will users interact with the solution?**
35+
36+
### User Stories
37+
- As a developer, I want to search skills by name so I can quickly find relevant ones
38+
- As a developer, I want to see skill descriptions so I understand what each skill does
39+
- As a developer, I want to click a skill card to see detailed installation instructions
40+
- As a developer, I want to copy the CLI install command (including registry) so I can quickly install a skill
41+
42+
### Key Workflows
43+
1. **Browse skills**: User visits `/skills` → sees grid of skill cards → scrolls to explore
44+
2. **Search skills**: User types in search box → results filter in real-time
45+
3. **View details**: User clicks skill card/install button → modal shows details with install command
46+
47+
### Edge Cases
48+
- No skills match search query → show "No results" message
49+
- JSON fails to load → show error state with retry option
50+
- Large number of skills → consider pagination or virtual scrolling (future)
51+
52+
## Success Criteria
53+
**How will we know when we're done?**
54+
55+
- [x] Page loads skill data from remote JSON endpoint
56+
- [x] Search filters results in real-time as user types
57+
- [x] Clicking a skill opens modal with description, registry, and install command
58+
- [x] Install command includes registry and is easily copyable
59+
- [x] Page shows loading state while fetching data
60+
- [x] Page is responsive on mobile and desktop
61+
- [x] Page follows existing website design patterns
62+
63+
## Constraints & Assumptions
64+
**What limitations do we need to work within?**
65+
66+
### Technical Constraints
67+
- Must use Next.js (existing web framework)
68+
- Data source is remote JSON at `https://raw.githubusercontent.com/codeaholicguy/ai-devkit/main/skills/index.json`
69+
- Static site generation preferred for performance
70+
71+
### Assumptions
72+
- JSON structure contains `skills` array with `name`, `description`, `registry`, `path` fields
73+
- Skill count (~1,400+) is manageable for client-side filtering
74+
75+
## Questions & Open Items
76+
**What do we still need to clarify?**
77+
78+
- [x] Route path confirmed: `/skills`
79+
- [x] Real-time search confirmed
80+
- [x] Modal for install details confirmed

0 commit comments

Comments
 (0)