From 788e1b0a82ebb1aebb7535a6b5d89d91561a5466 Mon Sep 17 00:00:00 2001 From: Fatih Date: Sun, 12 Apr 2026 14:00:18 +0000 Subject: [PATCH] feat: add feature-extract skill for extracting complete feature implementations from repos This skill enables users to extract working feature implementations from open-source repositories to use as blueprints for their own projects. Key capabilities: - Extract complete feature implementations (UI + logic + types + tests) - Learn patterns from production-grade codebases - Get reference implementations for building similar features - Uses btca for repository operations Includes: - SKILL.md with workflow, usage, and best practices - references/examples.md with example extractions - references/patterns.md with common React patterns Usage: feature-extract --from --feature --- skills/feature-extract/SKILL.md | 184 ++++++++++++++++++ skills/feature-extract/references/examples.md | 108 ++++++++++ skills/feature-extract/references/patterns.md | 163 ++++++++++++++++ 3 files changed, 455 insertions(+) create mode 100644 skills/feature-extract/SKILL.md create mode 100644 skills/feature-extract/references/examples.md create mode 100644 skills/feature-extract/references/patterns.md diff --git a/skills/feature-extract/SKILL.md b/skills/feature-extract/SKILL.md new file mode 100644 index 00000000..cb68f736 --- /dev/null +++ b/skills/feature-extract/SKILL.md @@ -0,0 +1,184 @@ +--- +name: feature-extract +description: Extract complete feature implementations from open-source repositories. Use when you need to understand how a feature works in a production app, learn patterns from excellent codebases, or get reference implementations for building similar features. Do NOT use for general code search or documentation lookup - use btca directly for that. +--- + +# Feature Extract + +Extract working feature implementations from reference repositories to use as blueprints for your own projects. + +## When to Use + + + + Use when building a feature similar to one in an open-source project + + + Use when learning patterns from production-grade codebases + + + Use when you need complete implementation context (UI + logic + types + tests) + + + Use when you want to understand how features integrate, not just API docs + + + Do NOT use for simple code search - use btca grep/glob directly + + + Do NOT use for documentation lookup - use Context7 or read docs directly + + + +## Workflow + + + + Clone the reference repository to ~/.btca/agent/sandbox if not already present + + + Search for feature-related files using: + - Keywords (e.g., "dark mode", "theme", "useTheme") + - File patterns (e.g., *theme*.tsx, *dark*.ts) + - Import analysis (what files import theme-related modules) + + + Identify complete feature boundaries: + - Core implementation files + - Type definitions + - Test files + - Utility functions + - Dependencies (what imports what) + + + Build minimal complete context: + - Include all files needed to understand the feature + - Exclude unrelated code + - Preserve imports and structure + - Add explanatory comments + + + Format as markdown documentation with: + - Feature summary and architecture + - File contents with explanations + - Key patterns identified + - Adaptation guidance + + + +## Usage + +### Basic Command + +``` +feature-extract --from --feature +``` + +### Examples + +```bash +# Extract dark mode system +feature-extract --from https://github.com/shadcn-ui/ui --feature "dark mode" + +# Extract navigation patterns +feature-extract --from https://github.com/calcom/cal.com --feature "navigation" + +# Extract hero section with tests +feature-extract --from https://github.com/shadcn/taxonomy --feature "hero section" --include-tests +``` + +### Options + +- `--from, -f`: Repository URL (required) +- `--feature, -t`: Feature name to extract (required) +- `--output, -o`: Output format: context|files|summary (default: context) +- `--depth, -d`: Extraction depth: minimal|complete|full (default: complete) +- `--include-tests`: Include test files (default: true) +- `--include-types`: Include type definitions (default: true) +- `--max-files, -m`: Maximum files to include (default: 20) + +## Output Format + +```markdown +# Feature: [Name] + +**Source**: [Repo URL] +**Files**: [N] files + +## Summary +**Purpose**: What this feature does +**Architecture**: How it's structured +**Key Patterns**: Important patterns used + +## Files + +### [path/to/file.tsx] ([role]) +**Description**: What this file does + +```typescript +[file content] +``` + +## Dependencies +- [package-name]: [purpose] + +## Adaptation Notes +How to use this in your project... +``` + +## Best Practices + + + + Be specific with feature names ("dark mode" not "theming system") + + + Always include test files to understand usage patterns + + + Follow import chains to find all related files + + + Include only what's needed - exclude unrelated code + + + Use as reference for adaptation, not exact copy-paste + + + +## Common Features + +- **UI Components**: Buttons, modals, forms, navigation, cards +- **State Management**: Stores, contexts, custom hooks +- **Animations**: Transitions, scroll effects, interactions +- **Data Handling**: Fetching, caching, synchronization +- **Authentication**: Login flows, session management +- **Layout**: Dashboards, sidebars, responsive grids +- **Forms**: Validation, submission, error handling + +## Integration with btca + +This skill uses btca for repository operations: +- `btca add ` - Clone repository +- `btca grep ` - Search content +- `btca glob ` - Find files +- `btca read ` - Read files +- `btca list ` - List directories + +## Error Handling + + + + If feature not found: Try different keywords or check if repo has the feature + + + If too many files: Be more specific with feature name or use --max-files + + + If circular dependencies: Include both files and note the interdependency + + + +## References + +See `references/examples.md` for example extractions and `references/patterns.md` for common patterns. diff --git a/skills/feature-extract/references/examples.md b/skills/feature-extract/references/examples.md new file mode 100644 index 00000000..f9e1768f --- /dev/null +++ b/skills/feature-extract/references/examples.md @@ -0,0 +1,108 @@ +# Feature Extract - Example Extractions + +## Example 1: Dark Mode from shadcn/ui + +**Command**: +```bash +feature-extract --from https://github.com/shadcn-ui/ui --feature "dark mode" +``` + +**Output**: +```markdown +# Feature: Dark Mode System + +**Source**: https://github.com/shadcn-ui/ui +**Files**: 6 files + +## Summary +**Purpose**: Complete dark mode with theme provider, toggle, and CSS variables +**Architecture**: React Context for state, CSS variables for styling, next-themes for persistence +**Key Patterns**: Context pattern, custom hooks, CSS variables, system preference detection + +## Files + +### components/theme-provider.tsx (core) +**Description**: React Context provider for theme state + +```typescript +import { ThemeProvider as NextThemesProvider } from "next-themes" + +export function ThemeProvider({ children, ...props }) { + return {children} +} +``` + +### hooks/use-theme.ts (hook) +**Description**: Custom hook to access theme + +```typescript +import { useTheme as useNextTheme } from "next-themes" + +export function useTheme() { + return useNextTheme() +} +``` + +### components/theme-toggle.tsx (ui) +**Description**: Toggle button component + +```typescript +export function ThemeToggle() { + const { theme, setTheme } = useTheme() + + return ( + + ) +} +``` + +## Dependencies +- next-themes: Theme management for Next.js +- lucide-react: Icons + +## Adaptation Notes +1. Install: `npm install next-themes` +2. Wrap app with ThemeProvider +3. Use useTheme hook in components +4. Add dark: variants in Tailwind +``` + +## Example 2: Hero Section from Taxonomy + +**Command**: +```bash +feature-extract --from https://github.com/shadcn/taxonomy --feature "hero section" +``` + +**Key Files**: +- `app/page.tsx` - Hero component usage +- `components/hero.tsx` - Hero implementation +- `components/animated-text.tsx` - Typewriter effect +- `lib/animations.ts` - Framer Motion variants + +**Patterns**: +- Staggered children animations +- Gradient text effects +- Scroll-triggered effects +- CTA button animations + +## Example 3: Navigation from Cal.com + +**Command**: +```bash +feature-extract --from https://github.com/calcom/cal.com --feature "navigation" +``` + +**Key Files**: +- `components/layout.tsx` - Main layout with nav +- `components/sidebar.tsx` - Sidebar navigation +- `components/user-menu.tsx` - User dropdown +- `hooks/use-navigation.ts` - Navigation state + +**Patterns**: +- Responsive navigation +- Mobile menu with animation +- User menu dropdown +- Active state management diff --git a/skills/feature-extract/references/patterns.md b/skills/feature-extract/references/patterns.md new file mode 100644 index 00000000..e83c42f3 --- /dev/null +++ b/skills/feature-extract/references/patterns.md @@ -0,0 +1,163 @@ +# Feature Extract - Common Patterns Guide + +## Pattern 1: React Context for Global State + +**When to use**: Theme, auth, user preferences + +**Structure**: +``` +context/ +├── provider.tsx # Context provider component +├── hook.ts # Custom hook to access context +└── types.ts # Type definitions +``` + +**Example**: Dark mode, authentication, settings + +## Pattern 2: Custom Hooks for Logic + +**When to use**: Reusable logic, data fetching, animations + +**Naming**: `use[Feature]` (useTheme, useAuth, useAnimation) + +**Structure**: +```typescript +export function useFeature() { + // State + // Effects + // Handlers + return { data, loading, error, actions } +} +``` + +## Pattern 3: Component Composition + +**When to use**: Complex UI components (forms, modals, cards) + +**Structure**: +``` +Component/ +├── index.tsx # Main component +├── parts.tsx # Sub-components +├── types.ts # Types +└── utils.ts # Helpers +``` + +**Example**: Form (Form, Field, Label, Error), Card (Card, Header, Content, Footer) + +## Pattern 4: Feature-Based Organization + +**When to use**: Large features with multiple files + +**Structure**: +``` +features/ +├── auth/ +│ ├── components/ # UI components +│ ├── hooks/ # Custom hooks +│ ├── lib/ # Utilities +│ ├── types.ts # Types +│ └── index.ts # Public API +``` + +## Pattern 5: Animation Variants + +**When to use**: Framer Motion animations + +**Structure**: +```typescript +// lib/animations.ts +export const fadeIn = { + hidden: { opacity: 0 }, + visible: { opacity: 1 } +} + +export const staggerContainer = { + hidden: {}, + visible: { + transition: { + staggerChildren: 0.1 + } + } +} +``` + +**Usage**: +```tsx + +``` + +## Pattern 6: Form Handling + +**When to use**: Forms with validation + +**Structure**: +``` +Form/ +├── index.tsx # Form component +├── schema.ts # Validation schema (zod/yup) +├── fields.tsx # Field components +└── types.ts # Form types +``` + +**Libraries**: react-hook-form + zod (common pattern) + +## Pattern 7: Responsive Design + +**When to use**: Mobile-first responsive layouts + +**Approach**: +- Use Tailwind responsive prefixes: `sm:`, `md:`, `lg:`, `xl:` +- Mobile-first: base styles for mobile, enhance for larger screens +- Container queries for component-level responsiveness + +## Pattern 8: Dark Mode with CSS Variables + +**When to use**: Theme switching + +**Structure**: +```css +/* globals.css */ +:root { + --background: 0 0% 100%; + --foreground: 222.2 84% 4.9%; +} + +.dark { + --background: 222.2 84% 4.9%; + --foreground: 210 40% 98%; +} +``` + +```tsx +// Usage +
+``` + +## Pattern 9: Data Fetching with SWR/React Query + +**When to use**: API data fetching + +**Structure**: +```typescript +// hooks/use-data.ts +export function useData() { + return useSWR('/api/data', fetcher) +} + +// Usage +const { data, error, isLoading } = useData() +``` + +## Pattern 10: Error Boundaries + +**When to use**: Graceful error handling + +**Structure**: +```typescript +// components/error-boundary.tsx +export class ErrorBoundary extends React.Component { + // Error handling logic + // Fallback UI +} +```