VidyFoo/antigravity-skill-engine / .agent/skills/3-sys/skills-managing
skills-managing
VerifiedCreate and manage ASE skills following best practices. Use when creating new skills, importing skills, understanding the Registry V3.1 structure, or debugging skill activation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.1 KB |
| references/ADVANCED.md | markdown | 2.4 KB |
| references/HOOK_MECHANISMS.md | markdown | 2.6 KB |
| references/PATTERNS_LIBRARY.md | markdown | 3.0 KB |
| references/SKILL_RULES_REFERENCE.md | markdown | 3.0 KB |
| references/TRIGGER_TYPES.md | markdown | 3.9 KB |
| references/TROUBLESHOOTING.md | markdown | 2.9 KB |
| resources/ingestion-protocol.md | markdown | 2.0 KB |
| resources/mcp-integration-guide.md | markdown | 1.6 KB |
| resources/skill-review.md | markdown | 1.7 KB |
| scripts/safe_replace.py | script | 1.3 KB |
references/TROUBLESHOOTING.md
View on GitHub# Troubleshooting - Skill Activation Issues
Complete debugging guide for skill activation problems.
## Table of Contents
- [Skill Not Triggering](#skill-not-triggering)
- [False Positives](#false-positives)
- [Performance Issues](#performance-issues)
---
## Skill Not Triggering
### Symptoms
Ask a question or start a task, but relevant skill doesn't activate.
### Common Causes
#### 1. Keywords Don't Match
**Check:**
- Look at `intent_keywords` in registry.json
- Are the keywords actually in your input?
- Remember: case-insensitive substring matching
**Example:**
```json
"intent_keywords": ["layout", "grid"]
```
- "how does the layout work?" → ✅ Matches "layout"
- "how does the grid system work?" → ✅ Matches "grid"
- "how does it work?" → ❌ No match
**Fix:** Add more keyword variations to registry.json
#### 2. Skill Not Registered
**Check:**
```bash
cat .agent/skills/registry.json | jq '.skills[] | select(.id == "your-skill")'
```
**Fix:** Add skill entry to registry.json
#### 3. Invalid SKILL.md
**Check:**
- YAML frontmatter is valid
- File exists at specified path
- No syntax errors
**Example Valid Frontmatter:**
```yaml
---
name: your-skill
description: Your description here
---
```
---
## False Positives
### Symptoms
Skill activates when it shouldn't.
### Common Causes
#### 1. Keywords Too Generic
**Problem:**
```json
"intent_keywords": ["work", "system", "create"]
```
These match almost everything!
**Fix:** Use more specific keywords:
```json
"intent_keywords": ["pdf work", "pdf system", "create pdf"]
```
#### 2. Overlapping Keywords
**Problem:** Two skills share the same keywords.
**Fix:**
- Make keywords more specific to each skill
- Add context words to disambiguate
---
## Performance Issues
### Symptoms
Noticeable delay before responses.
### Common Causes
#### 1. Too Many Patterns
**Problem:**
Every pattern = regex compilation + matching
**Solution:** Reduce patterns
- Combine similar patterns
- Remove redundant patterns
#### 2. Complex Regex
**Problem:**
```regex
(create|add|modify|update|implement|build).*?(feature|endpoint|route|service|controller|component)
```
Long alternations = slow
**Solution:** Simplify
```regex
(create|add).*?(feature|endpoint)
```
### Measure Performance
Performance should be imperceptible to users. If you notice delays:
1. Check number of registered skills
2. Review complexity of keywords
3. Consider caching strategies
---
## Quick Debug Checklist
1. [ ] Is skill listed in `registry.json`?
2. [ ] Do `intent_keywords` match your input?
3. [ ] Is `skill_path` correct?
4. [ ] Is SKILL.md valid frontmatter + markdown?
5. [ ] Are keywords specific enough?
6. [ ] Any JSON syntax errors?
---
**Related Files:**
- [SKILL.md](../SKILL.md) - Main skill guide
- [HOOK_MECHANISMS.md](HOOK_MECHANISMS.md) - How hooks work
- [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md) - Configuration reference
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |