---
name: score-api
description: Unified facade over the five Score suites ( parse , symbol , semantic , analysis , discovery ) providing a single LLM friendly surface for querying any Clef project s structure , symbols , semantics , data flows , and search indexes . Every Clef app gets ScoreApi registered automatically LLMs can immediately ask questions about the codebase without configuration . Actions are designed for natural language invocation : parameter names read as English , results are structured for tool use consumption , and error variants include actionable suggestions
argument-hint: [command] [pattern]
allowed-tools: Read, Grep, Glob, Bash
---

<!-- Auto-generated by Clef Clef Bind — claude-skills target -->
<!-- Concept: ScoreApi -->
<!-- Do not edit manually; regenerate with: clef interface generate -->

# ScoreApi

Unified facade over the five Score suites ( parse , symbol , semantic , analysis , discovery ) providing a single LLM friendly surface for querying any Clef project s structure , symbols , semantics , data flows , and search indexes . Every Clef app gets ScoreApi registered automatically LLMs can immediately ask questions about the codebase without configuration . Actions are designed for natural language invocation : parameter names read as English , results are structured for tool use consumption , and error variants include actionable suggestions

## Design Principles

- **Query, Don't Grep:** Score provides structured queries — use them instead of raw file reading.
- **Concepts Are Independent:** No concept references another — all coupling is through syncs.
- **Variants Over Exceptions:** Every action outcome is an explicit named variant.

## Step-by-Step Process

### Step 1: Survey the Architecture

List all concepts to understand the application's domain model and concept graph.

### Step 2: Inspect a Concept

Get full details of a concept — purpose, type parameters, actions, state fields, invariants.

**Arguments:** `$0` **name** (string)

### Step 3: Map the Sync Network

List all syncs to understand cross-concept coordination rules.

### Step 4: Trace Action Flows

Follow the chain of effects from any starting action through syncs to downstream actions.

**Arguments:** `$0` **startConcept** (string), `$1` **startAction** (string)

### Step 5: Search the Codebase

Use natural language search across the project. Combines embeddings, text, and symbols.

**Arguments:** `$0` **query** (string), `$1` **limit** (int)

### Step 6: Analyze Dependencies

Trace dependencies and dependents to understand impact before making changes.

**Arguments:** `$0` **symbol** (string), `$1` **edgeKinds** (string)

## Anti-Patterns

### Bypassing Score for raw file access
Reading .concept files directly instead of using Score queries — misses parsing, validation, and cross-references.

**Bad:**
```
# Manually grep for concept actions
grep -r "action create" repertoire/

```

**Good:**
```
# Use Score API
score listConcepts
score getConcept --name User
score getFlow --from User/create

```

### Assuming concept coupling
Looking for direct references between concepts — concepts are independent by design.

**Bad:**
```
# Wrong: searching for concept-to-concept imports
grep "import.*from.*User" repertoire/profile/

```

**Good:**
```
# Right: find syncs that connect User and Profile
score listSyncs --involves User,Profile

```