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 |
SKILL.md
View on GitHub---
name: skills-managing
description: 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.
---
# ASE Skill Management Guide (V3.1)
## Purpose
Comprehensive guide for creating and managing skills in the Antigravity Skill Engine (ASE), following the **Registry V3.1** architecture with domain-based organization and semantic matching.
## When to Use This Skill
- Creating or adding new skills
- Importing skills from external sources
- Understanding registry structure and routing
- Debugging skill activation issues
- Maintaining skill documentation
---
## System Architecture (V3.1)
### Directory Structure
Skills are organized by **domain categories**:
```
.agent/skills/
├── registry.json # V3.1 索引 (唯一真理来源)
│
├── 1-dev/ # 开发域
│ └── {skill-name}/SKILL.md
├── 2-audit/ # 审计域
│ └── {skill-name}/SKILL.md
├── 3-sys/ # 系统域
│ └── {skill-name}/SKILL.md
├── 4-tools/ # 工具域
│ └── {skill-name}/SKILL.md
└── external/ # 外部依赖
└── {skill-name}/SKILL.md
```
### Skill Folder Structure
```
{skill-name}/
├── SKILL.md (required) # Main skill content
├── resources/ # Templates, guides, assets
└── scripts/ # Optional executable tooling
```
### Registry V3.1 Schema
```json
{
"version": "3.1.0",
"categories": {
"1-dev": "DEV (开发域)",
"2-audit": "AUDIT (审计域)",
"3-sys": "SYS (系统域)",
"4-tools": "TOOLS (工具域)",
"external": "EXTERNAL (外部依赖)"
},
"skills": {
"X.Y": {
"id": "skill-name",
"name": "X.Y Display Name",
"category": "category-id",
"description": "Copied from SKILL.md frontmatter",
"skill_path": ".agent/skills/{category}/{skill-name}/SKILL.md"
}
}
}
```
> **关键变更 (V3.1)**: 移除了 `intent_keywords`,仅使用 `description` 进行语义匹配。
---
## Mode Selection
| Mode | Trigger | Description |
|------|---------|-------------|
| **CREATE** | create, new, add | Create a new skill from scratch |
| **INGEST** | import, clone, ingest | Import an existing skill from git |
| **HARVEST** | harvest, archive, save resource | Archive a reusable resource to a skill |
---
## 1. CREATE Mode (Protocol)
### Step 1: Determine Category
| Category | Use When |
|----------|----------|
| `1-dev` | 功能架构、开发规范、会话管理 |
| `2-audit` | 代码审计、调试、测试 |
| `3-sys` | 生态维护、技能管理、文档初始化 |
| `4-tools` | 文档处理、视觉设计 |
| `external` | 公司专属、外部依赖 |
### Step 2: Create Directory
```bash
mkdir -p .agent/skills/{category}/{skill-name}/resources
```
### Step 3: Write SKILL.md
**Required Frontmatter:**
```yaml
---
name: skill-name
description: Clear description including trigger scenarios. This is used for semantic matching - be descriptive!
---
```
**Body Structure:**
1. Purpose (what this skill does)
2. When to Use (activation conditions)
3. Mode Selection (if multi-mode)
4. Protocols (step-by-step instructions)
5. Resources (links to reference files)
6. Anti-Patterns (what to avoid)
### Step 4: Register in registry.json
```json
"X.Y": {
"id": "skill-name",
"name": "X.Y Display Name",
"category": "{category}",
"description": "Copy from SKILL.md frontmatter",
"skill_path": ".agent/skills/{category}/{skill-name}/SKILL.md"
}
```
---
## 2. INGEST Mode (Protocol)
1. **Clone**: `git clone {repo} .agent/skills/_import`
2. **Select**: Ask user which skill to import
3. **Categorize**: Determine target category (1-dev, 2-audit, etc.)
4. **Install**: Move to `.agent/skills/{category}/{skill-name}/`
5. **Register**: Add entry to `registry.json`
6. **Clean**: Remove `_import` directory
---
## 3. HARVEST Mode (Protocol)
When reusable resources are identified during task execution (or manually triggered):
### Step 1: Identify Target Skill
- Which skill produced or would benefit from this resource?
- If unclear, default to the currently active skill.
### Step 2: Generalize Content
- Remove project-specific references (file paths, names)
- Replace hardcoded values with `{{PLACEHOLDER}}` syntax
- Add usage instructions as YAML frontmatter or comments
### Step 3: Archive
```bash
write_to_file .agent/skills/{category}/{skill}/resources/{resource-name}.md
```
### Step 4: Document
Update the skill's SKILL.md `Resource Files` section with a link to the new resource.
## Key Principles
| Principle | Rule |
|-----------|------|
| **500-Line Rule** | SKILL.md 不超过 500 行 |
| **Progressive Disclosure** | 详细文档放 `resources/` |
| **Gerund Naming** | 使用动名词后缀 (*-ing) |
| **Single Source** | `description` 从 SKILL.md 复制到 registry |
---
## Best Practices
### ✅ DO:
- Keep SKILL.md concise and actionable
- Write rich, descriptive `description` for semantic matching
- Use gerund naming (e.g., `architecting`, `debugging`)
- Test activation with real prompts
- Include anti-patterns section
### ❌ DON'T:
- Exceed 500 lines in SKILL.md
- Use overly generic descriptions
- Create flat directories (use category subdirectories)
- Duplicate description between SKILL.md and registry (copy, don't rewrite)
---
## Troubleshooting
**Quick Debug:**
1. Is skill listed in `registry.json`?
2. Is `skill_path` pointing to correct location?
3. Is SKILL.md valid YAML frontmatter + markdown?
4. Is `description` rich enough for semantic matching?
---
## Resource Files
| Topic | File |
|-------|------|
| Ingestion Protocol | [ingestion-protocol.md](resources/ingestion-protocol.md) |
| Skill Review Checklist | [skill-review.md](resources/skill-review.md) |
| MCP Integration | [mcp-integration-guide.md](resources/mcp-integration-guide.md) |
---
**Skill Status**: COMPLETE ✅
**Line Count**: < 200 ✅
**Registry Version**: V3.1 ✅
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: 472k | 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 |