Skip to content

feat: add feature-extract skill for complete feature implementation extraction #222

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Fatih0234 wants to merge 1 commit into
base: main
Choose a base branch
from
+455 −0
Open

feat: add feature-extract skill for complete feature implementation extraction #222

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
184 changes: 184 additions & 0 deletions skills/feature-extract/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

<guidelines>
<guideline>
Use when building a feature similar to one in an open-source project
</guideline>
<guideline>
Use when learning patterns from production-grade codebases
</guideline>
<guideline>
Use when you need complete implementation context (UI + logic + types + tests)
</guideline>
<guideline>
Use when you want to understand how features integrate, not just API docs
</guideline>
<guideline>
Do NOT use for simple code search - use btca grep/glob directly
</guideline>
<guideline>
Do NOT use for documentation lookup - use Context7 or read docs directly
</guideline>
</guidelines>

## Workflow

<workflow>
<step name="clone">
Clone the reference repository to ~/.btca/agent/sandbox if not already present
</step>
<step name="search">
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)
</step>
<step name="analyze">
Identify complete feature boundaries:
- Core implementation files
- Type definitions
- Test files
- Utility functions
- Dependencies (what imports what)
</step>
<step name="extract">
Build minimal complete context:
- Include all files needed to understand the feature
- Exclude unrelated code
- Preserve imports and structure
- Add explanatory comments
</step>
<step name="format">
Format as markdown documentation with:
- Feature summary and architecture
- File contents with explanations
- Key patterns identified
- Adaptation guidance
</step>
</workflow>

## Usage

### Basic Command

```
feature-extract --from <repo-url> --feature <feature-name>
```

Comment on lines +71 to +76
Copy link

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation uses a CLI-style invocation (feature-extract --from ...), but there’s no implementation of a feature-extract executable/command in this repo—only a skill definition under skills/. To avoid confusing users, clarify how this skill is actually invoked (e.g., via the agent’s skill invocation mechanism) and, if applicable, differentiate that from any future btca CLI command.

Copilot uses AI. Check for mistakes.
### 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

<guidelines>
<guideline>
Be specific with feature names ("dark mode" not "theming system")
</guideline>
<guideline>
Always include test files to understand usage patterns
</guideline>
<guideline>
Follow import chains to find all related files
</guideline>
<guideline>
Include only what's needed - exclude unrelated code
</guideline>
<guideline>
Use as reference for adaptation, not exact copy-paste
</guideline>
</guidelines>

## 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 <repo>` - Clone repository
- `btca grep <repo> <keyword>` - Search content
- `btca glob <repo> <pattern>` - Find files
- `btca read <repo> <file>` - Read files
- `btca list <repo> <dir>` - List directories

Comment on lines +162 to +167
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps Bot Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Undocumented btca subcommands

btca grep, btca glob, btca read, and btca list don't appear anywhere in the existing btca-cli skill or the btca docs reference. The documented interface uses btca add, btca ask, and btca resources. If these subcommands don't exist, an agent following this skill will fail silently or call non-existent commands — the btca-local skill instead just clones the repo and uses standard shell tools directly.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: skills/feature-extract/SKILL.md
Line: 162-167

Comment:
**Undocumented btca subcommands**

`btca grep`, `btca glob`, `btca read`, and `btca list` don't appear anywhere in the existing `btca-cli` skill or the btca docs reference. The documented interface uses `btca add`, `btca ask`, and `btca resources`. If these subcommands don't exist, an agent following this skill will fail silently or call non-existent commands — the `btca-local` skill instead just clones the repo and uses standard shell tools directly.

How can I resolve this? If you propose a fix, please make it concise.

## Error Handling

<guidelines>
<guideline>
If feature not found: Try different keywords or check if repo has the feature
</guideline>
<guideline>
If too many files: Be more specific with feature name or use --max-files
</guideline>
<guideline>
If circular dependencies: Include both files and note the interdependency
</guideline>
</guidelines>

## References

See `references/examples.md` for example extractions and `references/patterns.md` for common patterns.
108 changes: 108 additions & 0 deletions skills/feature-extract/references/examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <NextThemesProvider {...props}>{children}</NextThemesProvider>
}
```
Comment on lines +24 to +33
Copy link

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The examples include verbatim-looking code snippets from third-party repositories (e.g., shadcn/ui). This repo is MIT-licensed, but embedding third-party source in docs can still require attribution and/or license notice depending on the upstream license and how substantial the excerpt is. Consider replacing these with clearly labeled pseudocode/abbreviated snippets, or add explicit attribution + a link to the exact upstream files/commit and note the upstream license terms.

Copilot uses AI. Check for mistakes.

### 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 (
<button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
{theme === "dark" ? <Sun /> : <Moon />}
</button>
)
}
Comment on lines +46 to +58
Copy link

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This example output is presented as a “complete” working feature extraction, but the shown file contents are incomplete (e.g., ThemeToggle uses useTheme, Sun, and Moon without imports/definitions). Either include the full file contents (consistent with the repo’s own guidance to not omit imports in code snippets, see skills/btca-local/SKILL.md:22-24) or clearly mark the snippets as abbreviated (with ...) so the example doesn’t imply it would run as-is.

Copilot uses AI. Check for mistakes.
```

## 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
Loading
Loading