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:

1. Check if repository structure changed (new skills, modified Makefile, updated scripts)
2. If changes detected → UPDATE THIS FILE before finishing your task
3. 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

1. Concise is Key: SKILL.md must be under 500 lines
2. Progressive Disclosure: Metadata → SKILL.md → Scripts/References
3. IDE Awareness: Absolute paths, task_boundary for long tasks
4. 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:

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

Phase 2: Scaffold

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

Phase 3: Refine

1. Fill the Decision Tree in SKILL.md
2. Write the Workflow with clear phases
3. Adapt the checklist in references/checklist.md
4. Move large code examples to examples/
5. 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