ag-cortex 0.1.0

package/.agent/skills/create-agent-skills/references/recommended-structure.md

@@ -0,0 +1,168 @@
+# Recommended Skill Structure
+
+The optimal structure for complex skills separates routing, workflows, and knowledge.
+
+<structure>
+```
+skill-name/
+├── SKILL.md              # Router + essential principles (unavoidable)
+├── workflows/            # Step-by-step procedures (how)
+│   ├── workflow-a.md
+│   ├── workflow-b.md
+│   └── ...
+└── references/           # Domain knowledge (what)
+    ├── reference-a.md
+    ├── reference-b.md
+    └── ...
+```
+</structure>
+
+<why_this_works>
+## Problems This Solves
+
+**Problem 1: Context gets skipped**
+When important principles are in a separate file, Antigravity may not read them.
+**Solution:** Put essential principles directly in SKILL.md. They load automatically.
+
+**Problem 2: Wrong context loaded**
+A "build" task loads debugging references. A "debug" task loads build references.
+**Solution:** Intake question determines intent → routes to specific workflow → workflow specifies which references to read.
+
+**Problem 3: Monolithic skills are overwhelming**
+500+ lines of mixed content makes it hard to find relevant parts.
+**Solution:** Small router (SKILL.md) + focused workflows + reference library.
+
+**Problem 4: Procedures mixed with knowledge**
+"How to do X" mixed with "What X means" creates confusion.
+**Solution:** Workflows are procedures (steps). References are knowledge (patterns, examples).
+</why_this_works>
+
+<skill_md_template>
+## SKILL.md Template
+
+```markdown
+---
+name: skill-name
+description: What it does and when to use it.
+---
+
+<essential_principles>
+## How This Skill Works
+
+[Inline principles that apply to ALL workflows. Cannot be skipped.]
+
+### Principle 1: [Name]
+[Brief explanation]
+
+### Principle 2: [Name]
+[Brief explanation]
+</essential_principles>
+
+<intake>
+**Ask the user:**
+
+What would you like to do?
+1. [Option A]
+2. [Option B]
+3. [Option C]
+4. Something else
+
+**Wait for response before proceeding.**
+</intake>
+
+<routing>
+| Response | Workflow |
+|----------|----------|
+| 1, "keyword", "keyword" | `workflows/option-a.md` |
+| 2, "keyword", "keyword" | `workflows/option-b.md` |
+| 3, "keyword", "keyword" | `workflows/option-c.md` |
+| 4, other | Clarify, then select |
+
+**After reading the workflow, follow it exactly.**
+</routing>
+
+<reference_index>
+All domain knowledge in `references/`:
+
+**Category A:** file-a.md, file-b.md
+**Category B:** file-c.md, file-d.md
+</reference_index>
+
+<workflows_index>
+| Workflow | Purpose |
+|----------|---------|
+| option-a.md | [What it does] |
+| option-b.md | [What it does] |
+| option-c.md | [What it does] |
+</workflows_index>
+```
+</skill_md_template>
+
+<workflow_template>
+## Workflow Template
+
+```markdown
+# Workflow: [Name]
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/relevant-file.md
+2. references/another-file.md
+</required_reading>
+
+<process>
+## Step 1: [Name]
+[What to do]
+
+## Step 2: [Name]
+[What to do]
+
+## Step 3: [Name]
+[What to do]
+</process>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+</success_criteria>
+```
+</workflow_template>
+
+<when_to_use_this_pattern>
+## When to Use This Pattern
+
+**Use router + workflows + references when:**
+- Multiple distinct workflows (build vs debug vs ship)
+- Different workflows need different references
+- Essential principles must not be skipped
+- Skill has grown beyond 200 lines
+
+**Use simple single-file skill when:**
+- One workflow
+- Small reference set
+- Under 200 lines total
+- No essential principles to enforce
+</when_to_use_this_pattern>
+
+<key_insight>
+## The Key Insight
+
+**SKILL.md is always loaded. Use this guarantee.**
+
+Put unavoidable content in SKILL.md:
+- Essential principles
+- Intake question
+- Routing logic
+
+Put workflow-specific content in workflows/:
+- Step-by-step procedures
+- Required references for that workflow
+- Success criteria for that workflow
+
+Put reusable knowledge in references/:
+- Patterns and examples
+- Technical details
+- Domain expertise
+</key_insight>

package/.agent/skills/create-agent-skills/references/skill-structure.md

@@ -0,0 +1,372 @@
+<overview>
+Skills have three structural components: YAML frontmatter (metadata), pure XML body structure (content organization), and progressive disclosure (file organization). This reference defines requirements and best practices for each component.
+</overview>
+
+<xml_structure_requirements>
+<critical_rule>
+**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
+</critical_rule>
+
+<required_tags>
+Every skill MUST have these three tags:
+
+- **`<objective>`** - What the skill does and why it matters (1-3 paragraphs)
+- **`<quick_start>`** - Immediate, actionable guidance (minimal working example)
+- **`<success_criteria>`** or **`<when_successful>`** - How to know it worked
+</required_tags>
+
+<conditional_tags>
+Add based on skill complexity and domain requirements:
+
+- **`<context>`** - Background/situational information
+- **`<workflow>` or `<process>`** - Step-by-step procedures
+- **`<advanced_features>`** - Deep-dive topics (progressive disclosure)
+- **`<validation>`** - How to verify outputs
+- **`<examples>`** - Multi-shot learning
+- **`<anti_patterns>`** - Common mistakes to avoid
+- **`<security_checklist>`** - Non-negotiable security patterns
+- **`<testing>`** - Testing workflows
+- **`<common_patterns>`** - Code examples and recipes
+- **`<reference_guides>` or `<detailed_references>`** - Links to reference files
+
+See [use-xml-tags.md](use-xml-tags.md) for detailed guidance on each tag.
+</conditional_tags>
+
+<tag_selection_intelligence>
+**Simple skills** (single domain, straightforward):
+- Required tags only
+- Example: Text extraction, file format conversion
+
+**Medium skills** (multiple patterns, some complexity):
+- Required tags + workflow/examples as needed
+- Example: Document processing with steps, API integration
+
+**Complex skills** (multiple domains, security, APIs):
+- Required tags + conditional tags as appropriate
+- Example: Payment processing, authentication systems, multi-step workflows
+</tag_selection_intelligence>
+
+<xml_nesting>
+Properly nest XML tags for hierarchical content:
+
+```xml
+<examples>
+<example number="1">
+<input>User input</input>
+<output>Expected output</output>
+</example>
+</examples>
+```
+
+Always close tags:
+```xml
+<objective>
+Content here
+</objective>
+```
+</xml_nesting>
+
+<tag_naming_conventions>
+Use descriptive, semantic names:
+- `<workflow>` not `<steps>`
+- `<success_criteria>` not `<done>`
+- `<anti_patterns>` not `<dont_do>`
+
+Be consistent within your skill. If you use `<workflow>`, don't also use `<process>` for the same purpose (unless they serve different roles).
+</tag_naming_conventions>
+</xml_structure_requirements>
+
+<yaml_requirements>
+<required_fields>
+```yaml
+---
+name: skill-name-here
+description: What it does and when to use it (third person, specific triggers)
+---
+```
+</required_fields>
+
+<name_field>
+**Validation rules**:
+- Maximum 64 characters
+- Lowercase letters, numbers, hyphens only
+- No XML tags
+- No reserved words: "antigravity", "agent"
+- Must match directory name exactly
+
+**Examples**:
+- ✅ `process-pdfs`
+- ✅ `manage-facebook-ads`
+- ✅ `setup-stripe-payments`
+- ❌ `PDF_Processor` (uppercase)
+- ❌ `helper` (vague)
+- ❌ `antigravity-helper` (reserved word)
+</name_field>
+
+<description_field>
+**Validation rules**:
+- Non-empty, maximum 1024 characters
+- No XML tags
+- Third person (never first or second person)
+- Include what it does AND when to use it
+
+**Critical rule**: Always write in third person.
+- ✅ "Processes Excel files and generates reports"
+- ❌ "I can help you process Excel files"
+- ❌ "You can use this to process Excel files"
+
+**Structure**: Include both capabilities and triggers.
+
+**Effective examples**:
+```yaml
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+```yaml
+description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
+```
+
+```yaml
+description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
+```
+
+**Avoid**:
+```yaml
+description: Helps with documents
+```
+
+```yaml
+description: Processes data
+```
+</description_field>
+</yaml_requirements>
+
+<naming_conventions>
+Use **verb-noun convention** for skill names:
+
+<pattern name="create">
+Building/authoring tools
+
+Examples: `create-agent-skills`, `create-hooks`, `create-landing-pages`
+</pattern>
+
+<pattern name="manage">
+Managing external services or resources
+
+Examples: `manage-facebook-ads`, `manage-zoom`, `manage-stripe`, `manage-supabase`
+</pattern>
+
+<pattern name="setup">
+Configuration/integration tasks
+
+Examples: `setup-stripe-payments`, `setup-meta-tracking`
+</pattern>
+
+<pattern name="generate">
+Generation tasks
+
+Examples: `generate-ai-images`
+</pattern>
+
+<avoid_patterns>
+- Vague: `helper`, `utils`, `tools`
+- Generic: `documents`, `data`, `files`
+- Reserved words: `antigravity-helper`, `agent-tools`
+- Inconsistent: Directory `facebook-ads` but name `facebook-ads-manager`
+</avoid_patterns>
+</naming_conventions>
+
+<progressive_disclosure>
+<principle>
+SKILL.md serves as an overview that points to detailed materials as needed. This keeps context window usage efficient.
+</principle>
+
+<practical_guidance>
+- Keep SKILL.md body under 500 lines
+- Split content into separate files when approaching this limit
+- Keep references one level deep from SKILL.md
+- Add table of contents to reference files over 100 lines
+</practical_guidance>
+
+<pattern name="high_level_guide">
+Quick start in SKILL.md, details in reference files:
+
+```markdown
+---
+name: pdf-processing
+description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+---
+
+<objective>
+Extract text and tables from PDF files, fill forms, and merge documents using Python libraries.
+</objective>
+
+<quick_start>
+Extract text with pdfplumber:
+
+```python
+import pdfplumber
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+</quick_start>
+
+<advanced_features>
+**Form filling**: See [forms.md](forms.md)
+**API reference**: See [reference.md](reference.md)
+</advanced_features>
+```
+
+Antigravity loads forms.md or reference.md only when needed.
+</pattern>
+
+<pattern name="domain_organization">
+For skills with multiple domains, organize by domain to avoid loading irrelevant context:
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+    ├── finance.md (revenue, billing metrics)
+    ├── sales.md (opportunities, pipeline)
+    ├── product.md (API usage, features)
+    └── marketing.md (campaigns, attribution)
+```
+
+When user asks about revenue, Antigravity reads only finance.md. Other files stay on filesystem consuming zero tokens.
+</pattern>
+
+<pattern name="conditional_details">
+Show basic content in SKILL.md, link to advanced in reference files:
+
+```xml
+<objective>
+Process DOCX files with creation and editing capabilities.
+</objective>
+
+<quick_start>
+<creating_documents>
+Use docx-js for new documents. See [docx-js.md](docx-js.md).
+</creating_documents>
+
+<editing_documents>
+For simple edits, modify XML directly.
+
+**For tracked changes**: See [redlining.md](redlining.md)
+**For OOXML details**: See [ooxml.md](ooxml.md)
+</editing_documents>
+</quick_start>
+```
+
+Antigravity reads redlining.md or ooxml.md only when the user needs those features.
+</pattern>
+
+<critical_rules>
+**Keep references one level deep**: All reference files should link directly from SKILL.md. Avoid nested references (SKILL.md → advanced.md → details.md) as Antigravity may only partially read deeply nested files.
+
+**Add table of contents to long files**: For reference files over 100 lines, include a table of contents at the top.
+
+**Use pure XML in reference files**: Reference files should also use pure XML structure (no markdown headings in body).
+</critical_rules>
+</progressive_disclosure>
+
+<file_organization>
+<filesystem_navigation>
+Antigravity navigates your skill directory using bash commands:
+
+- Use forward slashes: `reference/guide.md` (not `reference\guide.md`)
+- Name files descriptively: `form_validation_rules.md` (not `doc2.md`)
+- Organize by domain: `reference/finance.md`, `reference/sales.md`
+</filesystem_navigation>
+
+<directory_structure>
+Typical skill structure:
+
+```
+skill-name/
+├── SKILL.md (main entry point, pure XML structure)
+├── references/ (optional, for progressive disclosure)
+│   ├── guide-1.md (pure XML structure)
+│   ├── guide-2.md (pure XML structure)
+│   └── examples.md (pure XML structure)
+└── scripts/ (optional, for utility scripts)
+    ├── validate.py
+    └── process.py
+```
+</directory_structure>
+</file_organization>
+
+<anti_patterns>
+<pitfall name="markdown_headings_in_body">
+❌ Do NOT use markdown headings in skill body:
+
+```markdown
+# PDF Processing
+
+## Quick start
+Extract text...
+
+## Advanced features
+Form filling...
+```
+
+✅ Use pure XML structure:
+
+```xml
+<objective>
+PDF processing with text extraction, form filling, and merging.
+</objective>
+
+<quick_start>
+Extract text...
+</quick_start>
+
+<advanced_features>
+Form filling...
+</advanced_features>
+```
+</pitfall>
+
+<pitfall name="vague_descriptions">
+- ❌ "Helps with documents"
+- ✅ "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
+</pitfall>
+
+<pitfall name="inconsistent_pov">
+- ❌ "I can help you process Excel files"
+- ✅ "Processes Excel files and generates reports"
+</pitfall>
+
+<pitfall name="wrong_naming_convention">
+- ❌ Directory: `facebook-ads`, Name: `facebook-ads-manager`
+- ✅ Directory: `manage-facebook-ads`, Name: `manage-facebook-ads`
+- ❌ Directory: `stripe-integration`, Name: `stripe`
+- ✅ Directory: `setup-stripe-payments`, Name: `setup-stripe-payments`
+</pitfall>
+
+<pitfall name="deeply_nested_references">
+Keep references one level deep from SKILL.md. Antigravity may only partially read nested files (SKILL.md → advanced.md → details.md).
+</pitfall>
+
+<pitfall name="windows_paths">
+Always use forward slashes: `scripts/helper.py` (not `scripts\helper.py`)
+</pitfall>
+
+<pitfall name="missing_required_tags">
+Every skill must have: `<objective>`, `<quick_start>`, and `<success_criteria>` (or `<when_successful>`).
+</pitfall>
+</anti_patterns>
+
+<validation_checklist>
+Before finalizing a skill, verify:
+
+- ✅ YAML frontmatter valid (name matches directory, description in third person)
+- ✅ No markdown headings in body (pure XML structure)
+- ✅ Required tags present: objective, quick_start, success_criteria
+- ✅ Conditional tags appropriate for complexity level
+- ✅ All XML tags properly closed
+- ✅ Progressive disclosure applied (SKILL.md < 500 lines)
+- ✅ Reference files use pure XML structure
+- ✅ File paths use forward slashes
+- ✅ Descriptive file names
+</validation_checklist>

package/.agent/skills/create-agent-skills/references/using-scripts.md

@@ -0,0 +1,113 @@
+# Using Scripts in Skills
+
+<purpose>
+Scripts are executable code that Antigravity runs as-is rather than regenerating each time. They ensure reliable, error-free execution of repeated operations.
+</purpose>
+
+<when_to_use>
+Use scripts when:
+- The same code runs across multiple skill invocations
+- Operations are error-prone when rewritten from scratch
+- Complex shell commands or API interactions are involved
+- Consistency matters more than flexibility
+
+Common script types:
+- **Deployment** - Deploy to Vercel, publish packages, push releases
+- **Setup** - Initialize projects, install dependencies, configure environments
+- **API calls** - Authenticated requests, webhook handlers, data fetches
+- **Data processing** - Transform files, batch operations, migrations
+- **Build processes** - Compile, bundle, test runners
+</when_to_use>
+
+<script_structure>
+Scripts live in `scripts/` within the skill directory:
+
+```
+skill-name/
+├── SKILL.md
+├── workflows/
+├── references/
+├── templates/
+└── scripts/
+    ├── deploy.sh
+    ├── setup.py
+    └── fetch-data.ts
+```
+
+A well-structured script includes:
+1. Clear purpose comment at top
+2. Input validation
+3. Error handling
+4. Idempotent operations where possible
+5. Clear output/feedback
+</script_structure>
+
+<script_example>
+```bash
+#!/bin/bash
+# deploy.sh - Deploy project to Vercel
+# Usage: ./deploy.sh [environment]
+# Environments: preview (default), production
+
+set -euo pipefail
+
+ENVIRONMENT="${1:-preview}"
+
+# Validate environment
+if [[ "$ENVIRONMENT" != "preview" && "$ENVIRONMENT" != "production" ]]; then
+    echo "Error: Environment must be 'preview' or 'production'"
+    exit 1
+fi
+
+echo "Deploying to $ENVIRONMENT..."
+
+if [[ "$ENVIRONMENT" == "production" ]]; then
+    vercel --prod
+else
+    vercel
+fi
+
+echo "Deployment complete."
+```
+</script_example>
+
+<workflow_integration>
+Workflows reference scripts like this:
+
+```xml
+<process>
+## Step 5: Deploy
+
+1. Ensure all tests pass
+2. Run `scripts/deploy.sh production`
+3. Verify deployment succeeded
+4. Update user with deployment URL
+</process>
+```
+
+The workflow tells Antigravity WHEN to run the script. The script handles HOW the operation executes.
+</workflow_integration>
+
+<best_practices>
+**Do:**
+- Make scripts idempotent (safe to run multiple times)
+- Include clear usage comments
+- Validate inputs before executing
+- Provide meaningful error messages
+- Use `set -euo pipefail` in bash scripts
+
+**Don't:**
+- Hardcode secrets or credentials (use environment variables)
+- Create scripts for one-off operations
+- Skip error handling
+- Make scripts do too many unrelated things
+- Forget to make scripts executable (`chmod +x`)
+</best_practices>
+
+<security_considerations>
+- Never embed API keys, tokens, or secrets in scripts
+- Use environment variables for sensitive configuration
+- Validate and sanitize any user-provided inputs
+- Be cautious with scripts that delete or modify data
+- Consider adding `--dry-run` options for destructive operations
+</security_considerations>