Skills Managing

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

{
    "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

mkdir -p .agent/skills/{category}/{skill-name}/resources

Step 3: Write SKILL.md

Required Frontmatter:

---
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

"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

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 ✅

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: VidyFoo
• Source: VidyFoo/antigravity-skill-engine
• License: MIT

Install and usage instructions live in the source repository linked above.