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/HOOK_MECHANISMS.md

View on GitHub
# Hook Mechanisms - Deep Dive

Technical deep dive into how activation hooks work in the skill system.

## Table of Contents

- [Activation Flow](#activation-flow)
- [Exit Code Behavior](#exit-code-behavior)
- [Session State Management](#session-state-management)
- [Performance Considerations](#performance-considerations)

---

## Activation Flow

### Execution Sequence

```
User submits prompt
    ↓
System reads registry.json
    ↓
Matches keywords + intent patterns
    ↓
Groups matches by priority
    ↓
Outputs skill suggestion
    ↓
Skill content loaded into context
    ↓
Agent processes with skill knowledge
```

### Key Points

- **Timing**: Skill matching happens BEFORE processing
- **Behavior**: Non-blocking, advisory suggestions
- **Purpose**: Load relevant domain knowledge

---

## Exit Code Behavior

### For Suggestion Hooks

- **Exit 0**: Allow (always use this)
- **stdout**: Becomes context for the Agent

### For Guard Hooks

- **Exit 0**: Allow operation
- **Exit 2**: Block operation with message
- **stdout**: Message shown to user

### Critical Rule

> Never exit with code 1 - this is reserved for errors and will cause unexpected behavior.

---

## Session State Management

### Purpose

Track which skills have been activated in a session to avoid redundant suggestions.

### Implementation

```
.agent/hooks/state/
├── session-{id}.json
└── activated-skills.json
```

### State Structure

```json
{
  "sessionId": "abc123",
  "activatedSkills": ["skill-a", "skill-b"],
  "timestamp": "2024-01-01T00:00:00Z"
}
```

### Behavior

- First activation: Show full suggestion
- Repeat activation: Skip or show abbreviated
- Session end: Clear state

---

## Performance Considerations

### Target Metrics

- **Keyword matching**: < 50ms
- **Intent patterns**: < 100ms
- **File content patterns**: < 200ms

### Performance Bottlenecks

1. **Loading registry.json** (every check)
   - Solution: Cache in memory
   
2. **Reading file content**
   - Only when contentPatterns configured
   - Slow for large files
   
3. **Regex compilation**
   - Compile once, cache result
   - Avoid complex patterns

### Optimization Strategies

**Reduce patterns:**
- Use more specific patterns
- Combine similar patterns

**File path patterns:**
- More specific = fewer files to check
- Example: `src/services/**` better than `**/*`

**Content patterns:**
- Only add when truly necessary
- Simpler regex = faster matching

---

**Related Files:**
- [SKILL.md](../SKILL.md) - Main skill guide
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Debug hook issues
- [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md) - Configuration reference
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: 471kUpdated 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