# Repo Scanner

> Estimate a repository score from its owner/name string and optionally scaffold a local specialist directory. Use when exercising OSS Agent Lab's offline repo intake prototype. Trigger with scan repo prototype.

- Skill: `jeremylongshore/repo-scanner` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add jeremylongshore/repo-scanner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jeremylongshore/repo-scanner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: jeremylongshore (https://skillmd.com/u/jeremylongshore)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jeremylongshore/repo-scanner

---


# Repo Scanner Specialist

## Overview

A meta-specialist that exercises OSS Agent Lab's repository-intake shape. It derives a score from the
literal slug and can copy the local skeleton when the synthetic score crosses the threshold.

Wraps [jeremylongshore/oss-agent-lab](https://github.com/jeremylongshore/oss-agent-lab).

The scanner does not contact GitHub. Structure flags, scores, and recommendations are derived from the
repository string. Only scaffolding can write, by copying `_template` inside this checkout.

## Prerequisites

- Use Python 3.11+ in a local OSS Agent Lab checkout and run `pip install -e .`.
- Provide a literal `owner/repo` slug and a safe snake_case target name.
- Obtain explicit user approval before a scaffold write and read
  [the runtime contract](references/runtime-contract.md).

## Capabilities

- **auto_scaffold**: Materialise a new specialist directory from the `_template`
  skeleton when a repo's composite score reaches >= 80.
- **repo_analysis**: Simulate structural flags and infer likely capabilities from repo naming.
- **specialist_generation**: Orchestrate the full scan → score → scaffold pipeline
  and surface a unified result with provenance metadata.

## Tools

| Tool | Description | Side Effects |
|------|-------------|--------------|
| `scan_repo` | Structural analysis: name suggestion, detected capabilities, has_python/tests/readme, recommendation | None |
| `evaluate_score` | Composite capability score (0-100) with action and signal breakdown | None |
| `scaffold_specialist` | Copy `_template/` into `agents/specialists/<name>/` | Creates files on disk |

## Parameters

All parameters are passed via `request.intent.parameters`:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `repo` | `str` | *(query text)* | GitHub repo in `owner/name` format |
| `name` | `str` | *(from scan)* | Override for the scaffolded specialist directory name |

## Instructions

1. Validate the literal `owner/repo` slug and run scan/score without claiming GitHub was queried.
2. Present the deterministic score, recommendation, proposed target path, and intended file set.
3. Ask for explicit approval before `scaffold_specialist` creates a directory.
4. After creation, report the exact path and files; the generated skeleton still requires review.

## Examples

### Python API

```python
from agents.specialists.repo_scanner.agent import RepoScannerSpecialist
from oss_agent_lab.contracts import Intent, Query, SpecialistRequest

specialist = RepoScannerSpecialist()

request = SpecialistRequest(
    intent=Intent(
        action="scan",
        domain="meta",
        confidence=0.95,
        parameters={"repo": "openai/swarm"},
    ),
    query=Query(user_input="openai/swarm"),
    specialist_name="repo_scanner",
)

response = await specialist.execute(request)
print(response.result["score"]["action"])   # "auto_scaffold" | "evaluate" | "watch" | "skip"
print(response.result.get("scaffold"))      # None or {"status": "created", "path": ..., "files": [...]}
```

### CLI

```bash
oss-lab run repo_scanner "openai/swarm"
```

### Output shape

```json
{
  "repo": "openai/swarm",
  "scan": {
    "repo": "openai/swarm",
    "name_suggestion": "swarm",
    "capabilities_detected": ["agent_orchestration"],
    "has_python": true,
    "has_tests": true,
    "has_readme": true,
    "recommendation": "auto_scaffold"
  },
  "score": {
    "repo": "openai/swarm",
    "estimated_score": 87.04,
    "action": "auto_scaffold",
    "signals": {
      "discovery": 32.1,
      "quality": 28.5,
      "durability": 26.44,
      "github_star_velocity": 0.87,
      "readme_quality": 0.91,
      "test_coverage": 0.75,
      "maintenance_activity": 0.60,
      "community_depth": 0.44
    }
  },
  "scaffold": {
    "status": "created",
    "path": "/home/jeremy/000-projects/oss-agent-lab/agents/specialists/swarm",
    "files": ["__init__.py", "agent.py", "SKILL.md", "tools.py"]
  }
}
```

## Scoring Thresholds

| Score | Action | Description |
|-------|--------|-------------|
| >= 80 | `auto_scaffold` | Immediately scaffold specialist + flag for review |
| 60-79 | `evaluate` | Queue for human evaluation |
| 40-59 | `watch` | Add to watch list; re-score weekly |
| < 40  | `skip` | Not ready for wrapping |

## Output

Read-only operations return simulated structural signals and scores. Scaffolding returns `created`
only after copying the local template; if the template is absent it returns `simulated` and writes
nothing. Neither status proves that the source repository exists or is suitable.

## Error Handling

- Reject malformed repository slugs, unsafe names, and an existing target directory.
- Treat a missing template as no-write simulation, not successful creation.
- Never overwrite a specialist or broaden the destination beyond `agents/specialists/<name>`.

## Resources

Wraps [jeremylongshore/oss-agent-lab](https://github.com/jeremylongshore/oss-agent-lab).
See [the runtime contract](references/runtime-contract.md) for scoring and write boundaries.