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

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

[!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.

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