search-context

Files (15)

• .gitignore
• LICENSE
• SKILL.md
• VERSION
• openai.yaml · agents/
• example-ios-progress-ring-output.md · examples/
• usage.md · examples/
• package.json
• generic.json · presets/
• ios-swift.json · presets/
• web-react.json · presets/
• security.md · references/
• workflow.md · references/
• search-context.mjs · scripts/
• reference-manifest.md · templates/

SKILL.md (first lines)

# Search Context

Use this skill when the user wants an agent to find useful GitHub reference projects for a feature, UI pattern, implementation pattern, platform, framework, or library.

Trigger examples:

- `$search-context visual progress indicator ring for ios app latest 2026`
- `find GitHub references for a SwiftUI circular progress ring`
- `how do good projects implement this pattern?`
- `clone a few reference repos and tell me which files to inspect`
- `give this agent GitHub context before implementing the feature`

The goal is not faster raw code search. The goal is better reference selection, fewer cloned repositories, less context noise, and a clean manifest that tells the coding agent what to inspect.

## Default workflow

1. Convert the user request into concise GitHub search phrases. For broad app/product requests, split the request into stack, domain, and pattern facets instead of running one overloaded query.
2. If the user asks for local/third-party references, search the local reference library first.
3. Use GitHub repository discovery for fresh references, not GitHub code search.
4. Prefer recent, maintained, readable repositories.
5. Clone only the top candidate pool using blobless shallow clone.
6. Inspect local and cloned repositories with `rg`.
7. Verify candidates with local proof terms and reject generic/noisy references.
8. Write a compact Markdown reference manifest with rejected/noisy references.
9. Tell the agent which files are worth reading and why.

## Required local tools

This skill expects these tools to be available in the shell:

- `gh`, authenticated with GitHub
- `git`
- `rg`, also known as ripgrep
- `node` version 18 or newer

Before running a search, use:

```bash
node scripts/search-context.mjs check
```

## Main command

From the skill directory:

```bash
node scripts/search-context.mjs run "visual progress indicator ring for ios app latest 2026" \
  --preset ios-swift \
  --max-repos 5
```

If the package has been linked with `npm link`, use:

```bash
search-context run "visual progress indicator ring for ios app latest 2026" --preset ios-swift
```

## Presets

Use a preset when the platform or stack is clear.

- `ios-swift`: iOS, Swift, SwiftUI, UIKit, Apple UI components.
- `web-react`: React, Next.js, Vite, Tailwind, component patterns.
- `generic`: fallback when the stack is unknown.

The preset controls GitHub language filters, query expansion, local `rg` terms, file globs, and scoring hints. Presets are hints, not the whole plan: broad requests should still be decomposed into narrower searches such as framework architecture, domain examples, and UI/workflow patterns.

## Local reference library

Use the local library for existing third-party folders or previously curated references:

```bash
node scripts/search-context.mjs library add ../third-party/some-repo --tags react,ui --presets web-react --project current
node scripts/search-context.mjs library search "ProgressRing"
node scripts/search-context.mjs run "React progress ring" --sources library,github --project current
```

Library metadata is stored in the OS user cache at `<cache>/library/repositories.json`. Project-specific clusters are stored in the same registry when `--project current` or `--project <id>` is used.

Keep FFF or any future long-lived index as an optional search backend under this library workflow. Do not make FFF a hard requirement and do not split this into a separate skill unless the goal changes from reference selection to general code search.

## Clone policy

Use blobless shallow clones for reference repositories:

```bash
git clone --depth=1 --filter=blob:none --single-branch --no-tags <repo-url> <user-cache>/search-context/refs/owner__repo
```

Do not use normal full clones by default.
Do not clone more than 5 repositories unless the user explicitly asks.
Do not install dependencies from cloned reference repos.
Do not execute cloned project code.
Do not copy large code blocks into the agent context.

By default, keep cloned repositories and manifests in the OS user cache, not in the current project. Use `--project-local` only when the user explicitly wants `.refs/` and `.context/` in the current directory. Inside a Git worktree, those project-local paths must be ignored or the CLI will refuse to write them.

## Search policy

Use repository discovery first.
Avoid using `gh search code` as the primary source.
Use local `rg` after cloning to verify that the repository actually contains relevant implementation files. GitHub Code Search can be used as an optional pre-clone proof gate, but do not depend on it by default because the API is rate-limited.

Good reference selection beats raw search speed.

For mixed requests, prefer several narrow repository searches over one broad query. Example: "habit life app with TanStack Start" should produce stack queries like `tanstack start`, domain queries like `habit life`, and pattern queries like `habit life tanstack start`. Do not let a general React preset drown the run in unrelated component libraries.

Proof gates should reject or down-rank candidates that only match generic terms like `react`, `start`, or `full`. For known stacks/domains, require concrete code proof where possible:

- TanStack Start: `@tanstack/react-start`, `createServerFn`, `StartServer`, `StartClient`, `routeTree.gen`, `vinxi`.
- Habit apps: `habit`, `streak`, `completion`, `calendar`, `routine`.
- Noise: raw GitHub zip links, default secrets, and README-only bait.

Score repositories by:

- intent match
- language and stack match
- recent `pushed_at`
- not archived

From instructa/agent-skills, MIT.

More from instructa/agent-skills