Skill Factory Expert Skill

Skill Factory Expert

This skill has deep knowledge of the antigravity-factory project — the Factory that produces high-quality Antigravity agent skills and blueprints.

[!IMPORTANT]

Role Boundary

I KNOW the factory. I DON'T CREATE skills.

| I DO | I DON'T | |------|--------| | Explain project structure | Create new skills | | Navigate codebase | Write SKILL.md files | | Answer "how does X work?" | Scaffold skill directories | | Run validation/install | Design skill logic |

To create skills → activate @skill-creator

[!CAUTION]

🚨 MANDATORY SELF-EVOLUTION PROTOCOL

BEFORE completing ANY task in this repository, you MUST:

Check if repository structure changed (new skills, modified Makefile, updated scripts)

If changes detected → UPDATE THIS FILE before finishing your task

Failure to update = INCOMPLETE TASK — the user will reject your work

Self-Evolution Triggers (check EVERY TIME):

[ ] New skill added to blueprint/skills/? → Update "Current Squad Roster" table

[ ] Makefile commands changed? → Update "Makefile Commands" table

[ ] New scripts in skill-creator/scripts/? → Update "Key Files" section

[ ] New factory skills in .agent/skills/? → Update "Project Overview" diagram

[ ] Workflow process changed? → Update "Skill Creation Workflow" section

[ ] skill-creator outdated? → Update .agent/skills/skill-creator/SKILL.md too!

How to Self-Evolve:
# 1. List current blueprint skills
ls blueprint/skills/

# 2. Check for new make targets
grep -E "^[a-z].*:" Makefile | head -20

# 3. Update this file AND skill-creator if needed
⚠️ If you skip this step, the skill becomes outdated and USELESS.

Language Requirements

All skill files must be in English. See LANGUAGE.md.

Project Overview

Purpose: The Factory separates the creator (skill-creator) from the products (skills in blueprint/).

antigravity-factory/
├── .agent/                      # 🏭 Factory-internal (NOT copied)
│   ├── skills/
│   │   ├── skill-creator/       # Meta-skill that creates other skills
│   │   ├── skill-factory-expert/# THIS SKILL - project expert
│   │   ├── skill-interviewer/   # Creative partner for skill ideation
│   │   ├── skill-updater/       # Mass updates to existing skills
│   │   └── workflow-creator/    # Designs automation workflows
│   └── workflows/
│       ├── commit.md            # Pre-commit checks + changelog
│       ├── push.md              # Merge + push pipeline
│       └── self-evolve.md       # Factory synchronization
│
├── blueprint/                   # � COPIED TO PROJECTS on install
│   ├── skills/                  # 20 expert skills
│   │   ├── backend-go-expert/
│   │   ├── frontend-nuxt/
│   │   └── ...
│   ├── workflows/               # Project workflows (10)
│   │   ├── doc-cleanup.md       # Document cleanup
│   │   ├── refactor.md          # Refactoring workflow
│   │   ├── new-project.md       # Start new project
│   │   ├── new-feature.md       # Add feature
│   │   ├── implement.md         # Implementation phase
│   │   ├── deploy.md            # Deployment
│   │   ├── debug.md             # Bug investigation
│   │   ├── archive.md           # Close work unit
│   │   ├── status.md            # Project status
│   │   └── qa.md                # QA cycle
│   ├── rules/                   # Team structure
│   │   ├── TEAM.md
│   │   └── PIPELINE.md
│   └── standards/               # Protocols
│       ├── TDD_PROTOCOL.md
│       ├── GIT_PROTOCOL.md
│       └── ...
│
├── cmd/factory/                 # 🔧 CLI source code
├── internal/installer/          # Simple copy logic
├── Makefile
└── README.md

[!TIP] Always read AGENTS.md first! It contains full project context, CLI commands, and development rules.

Core Concepts

1. Skill Categories

Factory Skills (.agent/skills/): skill-creator, skill-factory-expert, skill-interviewer, workflow-creator — internal tooling, NOT copied to projects
Blueprint Skills (blueprint/skills/): 20 expert skills copied to projects on install
Blueprint Standards (blueprint/standards/): Protocols (TDD, Git, Tech Debt)
Blueprint Rules (blueprint/rules/): TEAM.md, PIPELINE.md
Blueprint Workflows (blueprint/workflows/): doc-cleanup, refactor

2. Skill Structure

Every skill follows this pattern:

<skill-name>/
├── SKILL.md          # Brain: Logic, Decisions, Workflow (<500 lines)
├── scripts/          # Hands: Python/Bash for execution
├── resources/        # Tools: Templates, Configs
├── examples/         # Demos: Usage examples
└── references/       # Library: Docs, Cheatsheets

3. Design Philosophy

Concise is Key: SKILL.md must be under 500 lines
Progressive Disclosure: Metadata → SKILL.md → Scripts/References
IDE Awareness: Absolute paths, task_boundary for long tasks
Dual-Write Pattern: Drafts in brain/, finals in project/docs/

4. Project Docs Convention

[!CAUTION] All skills MUST use project/docs/ NOT docs/!

✅ Correct: project/docs/features/, project/docs/architecture/

❌ Wrong: docs/features/, docs/architecture/

Makefile Commands

| Command | Description | |---------|-------------| | make install | Full install: validate-all → build-factory → install-factory → completions | | make validate SKILL=<name> | Validate a single skill in blueprint/skills/ | | make validate-all | Validate all skills in blueprint/skills/ | | make generate-team | Regenerate blueprint/rules/TEAM.md from skill descriptions | | make build-factory | Build the factory CLI binary to bin/factory | | make install-factory | Install CLI to /usr/local/bin/factory | | make test | Run all Go tests | | make lint | Run linters | | make uninstall | Remove factory CLI |

Factory CLI

The factory includes a Go CLI (factory) for managing blueprints in workspaces:

factory install     # Copy blueprint to .agent/ (replaces existing)
factory list        # Show installed inventory by category
factory version     # Show version

[!NOTE] CLI reads config from ~/.config/factory/config.yaml

Skill Creation Workflow

Phase 1: Design

Before creating a skill, answer:

What is the Trigger? What user intent activates this skill?
What is the Decision Tree? Single path or multiple?
What Resources are needed? Scripts, templates, references?

Phase 2: Scaffold

Use @skill-creator or manually create in blueprint/skills/<skill-name>/.

Phase 3: Refine

Fill the Decision Tree in SKILL.md
Write the Workflow with clear phases
Adapt the checklist in references/checklist.md
Move large code examples to examples/
Enforce Handoff Protocol: Ensure "Draft -> Approved" status change step

Phase 4: Verify

make validate SKILL=<skill-name>

Checks: frontmatter, length (<500), team sections, checklist customization.

Phase 5: Install

cd your-project
factory install

Physically copies blueprint/ → .agent/ in the project.

Key Files

Validation Script

Path: .agent/skills/skill-creator/scripts/validate_skill.py

Validates SKILL.md frontmatter
Checks line count (<500)
Ensures Team Collaboration & When to Delegate sections exist
Verifies checklist in references/

Scripts

Path: .agent/skills/skill-creator/scripts/

init_skill.py — Creates skill skeleton
validate_skill.py — Validates SKILL.md against standards
validate_blueprint.py — Validates blueprint consistency (presets, TEAM.md sync)
bump_versions.py — Auto-bumps skill versions based on git diff
add_config_awareness.py — Adds config awareness to skills
add_mcp_awareness.py — Adds MCP tool awareness to skills

Standards (Shared Protocols)

Path: blueprint/standards/TDD_PROTOCOL.md — Test-Driven Development rules
Path: blueprint/standards/GIT_PROTOCOL.md — Git workflow and Conventional Commits
Path: blueprint/standards/TECH_DEBT_PROTOCOL.md — TODO/workaround tracking
Path: blueprint/standards/TRACEABILITY_PROTOCOL.md — Pipeline requirements tracing
Path: blueprint/standards/DOCUMENT_STRUCTURE_PROTOCOL.md — Document lifecycle

Team Registry

Path: blueprint/rules/TEAM.md

Auto-generated via make generate-team
Lists all skills with descriptions

Anti-Patterns

❌ NEVER create skills directly in ~/.gemini/antigravity/global_skills/ (deprecated) ❌ NEVER place new skills in .agent/skills/ (reserved for factory tooling) ❌ NEVER embed large code blocks (>10 lines) in SKILL.md

✅ ALWAYS create skills in blueprint/skills/ ✅ ALWAYS use factory install to deploy to projects ✅ ALWAYS customize checklist for the skill's domain ✅ ALWAYS add Team Collaboration and When to Delegate sections

Content Organization

SKILL.md contains:

Decisions, workflows, logic
Brief inline examples (max 10 lines)
References like: See examples/server.py

examples/ contains:

Full working code
Configuration samples

references/ contains:

Cheatsheets
External docs
Troubleshooting guides

Team Collaboration

Skills must include team awareness:

## Team Collaboration
- **Role**: `@skill-name` (Description of collaboration)

## When to Delegate
- ✅ **Delegate to `@skill-name`** when: <condition>
- ⬅️ **Return to `@skill-name`** if: <condition>

See blueprint/rules/TEAM.md for the full roster.

Core Pipeline

The Discovery-to-Delivery pipeline flows through these phases:

idea-interview → product-analyst → bmad-architect → tech-spec-writer → implementation → delivery

Core path: 5 mandatory skills Optional paths:

TMA/Bot: @telegram-mechanic, @tma-expert
CLI: @cli-architect, @tui-charm-expert
Design: @ux-designer, @ui-implementor
Hosting: @timeweb-sysadmin

Current Blueprint Skills (20)

| Skill | Focus | |-------|-------| | idea-interview | Discovery phase, extract project info | | feature-fit | Analyzes new features for EXISTING projects | | product-analyst | Vision, Roadmap, Specs | | tech-spec-writer | Converts architecture into detailed tech specs | | bmad-architect | DDD, Context Maps, API Contracts | | backend-go-expert | Go 1.25+, Clean Architecture, DDD | | frontend-nuxt | Nuxt 4, TailwindCSS, SSR | | tma-expert | Telegram Mini Apps | | telegram-mechanic | Bot API, Webhooks, initData | | cli-architect | Cobra, Viper, POSIX CLI | | tui-charm-expert | BubbleTea, Lipgloss | | mcp-expert | MCP servers (Go) | | ux-designer | Design systems, tokens | | ui-implementor | Tailwind, shadcn/ui | | qa-lead | E2E, API, UI testing | | devops-sre | Docker, CI/CD, deployments | | timeweb-sysadmin | Timeweb Cloud, VPS | | project-bro | Project awareness | | refactor-architect | Codebase analysis, modular refactoring | | doc-janitor | Document cleanup, lifecycle enforcement | | debugger | Systematic 7-step bug investigation |

When to Delegate

✅ Delegate to @skill-creator when: Creating a new skill
⬅️ Return from @skill-creator after: Skill is scaffolded
🤝 Coordinate with blueprint skills when: Understanding their capabilities

Antigravity Best Practices

Use task_boundary when performing multi-step operations
Use notify_user for user review checkpoints
Always use absolute paths in scripts and documentation

Agent Skills: Skill Factory Expert

Install this agent skill to your local

Skill Files