# v3.1.0 — Skill Registry & Validation Runner

Reusable tool collections and pre-apply validation quality gates.

---

## Skill Registry

Persistent storage for named, reusable tool collections in SQLite.

### Item Types

| Type | Description |
|------|-------------|
| `tool_ref` | Reference to a named tool |
| `include` | Recursive inclusion of another skill |
| `inline_tool` | Anonymous tool defined inline |
| `mcp_source` | MCP server tool source |
| `agent_source` | Agent Skills Standard folder source |

### CLI Commands

```bash
agents skill list                                    # all skills
agents skill tools local/devops-toolkit              # show skill's tools
agents skill add --config ./my-skill.yaml            # register from YAML
agents skill remove local/my-skill                   # remove a skill
```

### Service API

```python
from cleveragents.application.services import SkillRegistryService
svc = SkillRegistryService(skill_repo=SkillRepository(session_factory))
svc.add_skill(skill)           # register
skill = svc.get_skill("local/code-tools")  # retrieve
skills = svc.list_skills(namespace="local")      # filter
svc.remove_skill("local/code-tools")            # delete
```

### Agent Skills Standard Integration

Filesystem-based tool bundles with `SKILL.md` + YAML front-matter.

**Default discovery path:** `~/.cleveragents/agent_skills`

**SKILL.md format:**

```markdown
---
name: my-tool
description: A custom agent skill
input_schema: {type: object, properties: {query: {type: string}}}
---

# My Tool  
Additional documentation.
```

### Configuration

```toml
[skills]
agent_skills_paths = "/home/user/.cleveragents/agent_skills,/opt/skills"
```

---

## Validation Runner

Executes validations against plan resources before Apply phase.

### Modes

| Mode | Pass Behavior | Fail Behavior |
|------|---------------|----------------|
| `required` | OK | **Blocks apply** — sets `all_required_passed = False` |
| `informational` | Logged | Logged only — does NOT block apply |

### Attachment Scopes

| Scope | Active When |
|-------|-------------|
| direct | Always for the resource |
| project | Resource accessed via a project |
| plan | Only for specific plan |

### Apply Validation Gate

```python
from cleveragents.validation.gate import ApplyValidationGate
gate = ApplyValidationGate(runner=DefaultValidationRunner())
summary = gate.run(plan_id, attachments, context)
if gate.should_block_apply(summary):
    # report failure reasons, block apply
else:
    # proceed
```

### Blocking vs Allowed Output

**Blocked:**
```
Validation Gate: BLOCKED
  Required: 1 passed, 1 failed
  Failures: lint-check on res-001: 3 lint errors found
```

**Allowed:**
```
Validation Gate: PASSED
  Required: 2 passed, 0 failed
  Informational: 1 passed, 0 failed
```

### Concurrency

Uses `ThreadPoolExecutor` with configurable `max_workers` (default 4).

---

## See Also

- [Skill Registry Reference](../../reference/skill_registry.md)
- [Validation Pipeline Reference](../../reference/validation_pipeline.md)
- [ADR-012](../../adr/ADR-012-skill-system.md): Skill System
- [ADR-013](../../adr/ADR-013-validation-abstraction.md): Validation Abstraction
