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:

Purpose (what this skill does)
When to Use (activation conditions)
Mode Selection (if multi-mode)
Protocols (step-by-step instructions)
Resources (links to reference files)
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)

Clone: git clone {repo} .agent/skills/_import
Select: Ask user which skill to import
Categorize: Determine target category (1-dev, 2-audit, etc.)
Install: Move to .agent/skills/{category}/{skill-name}/
Register: Add entry to registry.json
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:

Is skill listed in registry.json?
Is skill_path pointing to correct location?
Is SKILL.md valid YAML frontmatter + markdown?
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 ✅

skills-managing