Skip to content

VidyFoo/antigravity-skill-engine / .agent/skills/3-sys/skills-managing

skills-managing

Verified

Create and manage ASE skills following best practices. Use when creating new skills, importing skills, understanding the Registry V3.1 structure, or debugging skill activation.

references/SKILL_RULES_REFERENCE.md

View on GitHub
# registry.json - Complete Reference

Complete schema and configuration reference for `.agent/skills/registry.json`.

## Table of Contents

- [File Location](#file-location)
- [Complete Schema](#complete-schema)
- [Field Guide](#field-guide)
- [Examples](#examples)
- [Validation](#validation)

---

## File Location

**Path:** `.agent/skills/registry.json`

This JSON file defines all skills and their trigger conditions for the auto-activation system.

---

## Complete Schema

```typescript
interface SkillRegistry {
    version: string;
    skills: SkillEntry[];
}

interface SkillEntry {
    id: string;                    // Unique identifier
    intent_keywords: string[];     // Trigger keywords
    skill_path: string;            // Path to SKILL.md
    description: string;           // Brief description (max 1024 chars)
}
```

---

## Field Guide

### id (required)
- **Type**: string
- **Purpose**: Unique identifier for the skill
- **Convention**: lowercase-with-dashes
- **Example**: `"frontend-design"`, `"pdf-processor"`

### intent_keywords (required)
- **Type**: string[]
- **Purpose**: Words/phrases that trigger this skill
- **Matching**: Case-insensitive substring match
- **Example**: `["pdf", "extract pdf", "merge pdf"]`

### skill_path (required)
- **Type**: string
- **Purpose**: Relative path to SKILL.md
- **Convention**: Always starts with `.agent/skills/`
- **Example**: `".agent/skills/pdf/SKILL.md"`

### description (required)
- **Type**: string
- **Purpose**: Brief description for routing decisions
- **Limit**: Max 1024 characters
- **Content**: Should match SKILL.md frontmatter description

---

## Examples

### Basic Skill Entry

```json
{
    "id": "pdf",
    "intent_keywords": ["pdf"],
    "skill_path": ".agent/skills/pdf/SKILL.md",
    "description": "Comprehensive PDF manipulation toolkit..."
}
```

### Multi-Keyword Skill

```json
{
    "id": "frontend-design",
    "intent_keywords": [
        "frontend design",
        "frontend",
        "ui",
        "ux",
        "dashboard",
        "react component"
    ],
    "skill_path": ".agent/skills/frontend-design/SKILL.md",
    "description": "Create distinctive, production-grade frontend interfaces..."
}
```

---

## Validation

### Check JSON Syntax

```bash
cat .agent/skills/registry.json | jq .
```

If valid, jq will pretty-print the JSON. If invalid, it will show the error.

### Common JSON Errors

**Trailing comma:**
```json
{
  "keywords": ["one", "two",]  // ❌ Trailing comma
}
```

**Missing quotes:**
```json
{
  id: "guardrail"  // ❌ Missing quotes on key
}
```

### Validation Checklist

- [ ] JSON syntax valid (use `jq`)
- [ ] All skill IDs are unique
- [ ] All skill_path files exist
- [ ] Descriptions under 1024 chars
- [ ] Keywords are relevant and specific
- [ ] No duplicate keywords across unrelated skills

---

**Related Files:**
- [SKILL.md](../SKILL.md) - Main skill guide
- [TRIGGER_TYPES.md](TRIGGER_TYPES.md) - Complete trigger documentation
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Debugging configuration issues
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall