Skip to content

VidyFoo/antigravity-skill-engine / .agent/skills/3-sys/skills-managing

skills-managing

Verified

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

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

ModeTriggerDescription
CREATEcreate, new, addCreate a new skill from scratch
INGESTimport, clone, ingestImport an existing skill from git
HARVESTharvest, archive, save resourceArchive a reusable resource to a skill

1. CREATE Mode (Protocol)

Step 1: Determine Category

CategoryUse 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

PrincipleRule
500-Line RuleSKILL.md 不超过 500 行
Progressive Disclosure详细文档放 resources/
Gerund Naming使用动名词后缀 (*-ing)
Single Sourcedescription 从 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

TopicFile
Ingestion Protocolingestion-protocol.md
Skill Review Checklistskill-review.md
MCP Integrationmcp-integration-guide.md

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

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: 467kUpdated Claude CodeCodexVerifiedInstall
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: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 319kUpdated Claude CodeCodexVerifiedInstall