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
Skill Review Checklist	skill-review.md
MCP Integration	mcp-integration-guide.md

---

Skill Status: COMPLETE ✅
Line Count: < 200 ✅
Registry Version: V3.1 ✅