ag-cortex 0.1.0

package/.agent/skills/create-agent-skills/references/core-principles.md

@@ -0,0 +1,437 @@
+<overview>
+Core principles guide skill authoring decisions. These principles ensure skills are efficient, effective, and maintainable across different models and use cases.
+</overview>
+
+<xml_structure_principle>
+<description>
+Skills use pure XML structure for consistent parsing, efficient token usage, and improved Antigravity performance.
+</description>
+
+<why_xml>
+<consistency>
+XML enforces consistent structure across all skills. All skills use the same tag names for the same purposes:
+- `<objective>` always defines what the skill does
+- `<quick_start>` always provides immediate guidance
+- `<success_criteria>` always defines completion
+
+This consistency makes skills predictable and easier to maintain.
+</consistency>
+
+<parseability>
+XML provides unambiguous boundaries and semantic meaning. Antigravity can reliably:
+- Identify section boundaries (where content starts and ends)
+- Understand content purpose (what role each section plays)
+- Skip irrelevant sections (progressive disclosure)
+- Parse programmatically (validation tools can check structure)
+
+Markdown headings are just visual formatting. Antigravity must infer meaning from heading text, which is less reliable.
+</parseability>
+
+<token_efficiency>
+XML tags are more efficient than markdown headings:
+
+**Markdown headings**:
+```markdown
+## Quick start
+## Workflow
+## Advanced features
+## Success criteria
+```
+Total: ~20 tokens, no semantic meaning to Antigravity
+
+**XML tags**:
+```xml
+<quick_start>
+<workflow>
+<advanced_features>
+<success_criteria>
+```
+Total: ~15 tokens, semantic meaning built-in
+
+Savings compound across all skills in the ecosystem.
+</token_efficiency>
+
+<antigravity_performance>
+Antigravity performs better with pure XML because:
+- Unambiguous section boundaries reduce parsing errors
+- Semantic tags convey intent directly (no inference needed)
+- Nested tags create clear hierarchies
+- Consistent structure across skills reduces cognitive load
+- Progressive disclosure works more reliably
+
+Pure XML structure is not just a style preference—it's a performance optimization.
+</antigravity_performance>
+</why_xml>
+
+<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:
+- `<objective>` - What the skill does and why it matters
+- `<quick_start>` - Immediate, actionable guidance
+- `<success_criteria>` or `<when_successful>` - How to know it worked
+
+See [use-xml-tags.md](use-xml-tags.md) for conditional tags and intelligence rules.
+</required_tags>
+</xml_structure_principle>
+
+<conciseness_principle>
+<description>
+The context window is shared. Your skill shares it with the system prompt, conversation history, other skills' metadata, and the actual request.
+</description>
+
+<guidance>
+Only add context Antigravity doesn't already have. Challenge each piece of information:
+- "Does Antigravity really need this explanation?"
+- "Can I assume Antigravity knows this?"
+- "Does this paragraph justify its token cost?"
+
+Assume Antigravity is smart. Don't explain obvious concepts.
+</guidance>
+
+<concise_example>
+**Concise** (~50 tokens):
+```xml
+<quick_start>
+Extract PDF text with pdfplumber:
+
+```python
+import pdfplumber
+
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+</quick_start>
+```
+
+**Verbose** (~150 tokens):
+```xml
+<quick_start>
+PDF files are a common file format used for documents. To extract text from them, we'll use a Python library called pdfplumber. First, you'll need to import the library, then open the PDF file using the open method, and finally extract the text from each page. Here's how to do it:
+
+```python
+import pdfplumber
+
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+
+This code opens the PDF and extracts text from the first page.
+</quick_start>
+```
+
+The concise version assumes Antigravity knows what PDFs are, understands Python imports, and can read code. All those assumptions are correct.
+</concise_example>
+
+<when_to_elaborate>
+Add explanation when:
+- Concept is domain-specific (not general programming knowledge)
+- Pattern is non-obvious or counterintuitive
+- Context affects behavior in subtle ways
+- Trade-offs require judgment
+
+Don't add explanation for:
+- Common programming concepts (loops, functions, imports)
+- Standard library usage (reading files, making HTTP requests)
+- Well-known tools (git, npm, pip)
+- Obvious next steps
+</when_to_elaborate>
+</conciseness_principle>
+
+<degrees_of_freedom_principle>
+<description>
+Match the level of specificity to the task's fragility and variability. Give Antigravity more freedom for creative tasks, less freedom for fragile operations.
+</description>
+
+<high_freedom>
+<when>
+- Multiple approaches are valid
+- Decisions depend on context
+- Heuristics guide the approach
+- Creative solutions welcome
+</when>
+
+<example>
+```xml
+<objective>
+Review code for quality, bugs, and maintainability.
+</objective>
+
+<workflow>
+1. Analyze the code structure and organization
+2. Check for potential bugs or edge cases
+3. Suggest improvements for readability and maintainability
+4. Verify adherence to project conventions
+</workflow>
+
+<success_criteria>
+- All major issues identified
+- Suggestions are actionable and specific
+- Review balances praise and criticism
+</success_criteria>
+```
+
+Antigravity has freedom to adapt the review based on what the code needs.
+</example>
+</high_freedom>
+
+<medium_freedom>
+<when>
+- A preferred pattern exists
+- Some variation is acceptable
+- Configuration affects behavior
+- Template can be adapted
+</when>
+
+<example>
+```xml
+<objective>
+Generate reports with customizable format and sections.
+</objective>
+
+<report_template>
+Use this template and customize as needed:
+
+```python
+def generate_report(data, format="markdown", include_charts=True):
+    # Process data
+    # Generate output in specified format
+    # Optionally include visualizations
+```
+</report_template>
+
+<success_criteria>
+- Report includes all required sections
+- Format matches user preference
+- Data accurately represented
+</success_criteria>
+```
+
+Antigravity can customize the template based on requirements.
+</example>
+</medium_freedom>
+
+<low_freedom>
+<when>
+- Operations are fragile and error-prone
+- Consistency is critical
+- A specific sequence must be followed
+- Deviation causes failures
+</when>
+
+<example>
+```xml
+<objective>
+Run database migration with exact sequence to prevent data loss.
+</objective>
+
+<workflow>
+Run exactly this script:
+
+```bash
+python scripts/migrate.py --verify --backup
+```
+
+**Do not modify the command or add additional flags.**
+</workflow>
+
+<success_criteria>
+- Migration completes without errors
+- Backup created before migration
+- Verification confirms data integrity
+</success_criteria>
+```
+
+Antigravity must follow the exact command with no variation.
+</example>
+</low_freedom>
+
+<matching_specificity>
+The key is matching specificity to fragility:
+
+- **Fragile operations** (database migrations, payment processing, security): Low freedom, exact instructions
+- **Standard operations** (API calls, file processing, data transformation): Medium freedom, preferred pattern with flexibility
+- **Creative operations** (code review, content generation, analysis): High freedom, heuristics and principles
+
+Mismatched specificity causes problems:
+- Too much freedom on fragile tasks → errors and failures
+- Too little freedom on creative tasks → rigid, suboptimal outputs
+</matching_specificity>
+</degrees_of_freedom_principle>
+
+<model_testing_principle>
+<description>
+Skills act as additions to models, so effectiveness depends on the underlying model. What works for Opus might need more detail for Haiku.
+</description>
+
+<testing_across_models>
+Test your skill with all models you plan to use:
+
+<haiku_testing>
+**Antigravity Haiku** (fast, economical)
+
+Questions to ask:
+- Does the skill provide enough guidance?
+- Are examples clear and complete?
+- Do implicit assumptions become explicit?
+- Does Haiku need more structure?
+
+Haiku benefits from:
+- More explicit instructions
+- Complete examples (no partial code)
+- Clear success criteria
+- Step-by-step workflows
+</haiku_testing>
+
+<sonnet_testing>
+**Antigravity Sonnet** (balanced)
+
+Questions to ask:
+- Is the skill clear and efficient?
+- Does it avoid over-explanation?
+- Are workflows well-structured?
+- Does progressive disclosure work?
+
+Sonnet benefits from:
+- Balanced detail level
+- XML structure for clarity
+- Progressive disclosure
+- Concise but complete guidance
+</sonnet_testing>
+
+<opus_testing>
+**Antigravity Opus** (powerful reasoning)
+
+Questions to ask:
+- Does the skill avoid over-explaining?
+- Can Opus infer obvious steps?
+- Are constraints clear?
+- Is context minimal but sufficient?
+
+Opus benefits from:
+- Concise instructions
+- Principles over procedures
+- High degrees of freedom
+- Trust in reasoning capabilities
+</opus_testing>
+</testing_across_models>
+
+<balancing_across_models>
+Aim for instructions that work well across all target models:
+
+**Good balance**:
+```xml
+<quick_start>
+Use pdfplumber for text extraction:
+
+```python
+import pdfplumber
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+
+For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.
+</quick_start>
+```
+
+This works for all models:
+- Haiku gets complete working example
+- Sonnet gets clear default with escape hatch
+- Opus gets enough context without over-explanation
+
+**Too minimal for Haiku**:
+```xml
+<quick_start>
+Use pdfplumber for text extraction.
+</quick_start>
+```
+
+**Too verbose for Opus**:
+```xml
+<quick_start>
+PDF files are documents that contain text. To extract that text, we use a library called pdfplumber. First, import the library at the top of your Python file. Then, open the PDF file using the pdfplumber.open() method. This returns a PDF object. Access the pages attribute to get a list of pages. Each page has an extract_text() method that returns the text content...
+</quick_start>
+```
+</balancing_across_models>
+
+<iterative_improvement>
+1. Start with medium detail level
+2. Test with target models
+3. Observe where models struggle or succeed
+4. Adjust based on actual performance
+5. Re-test and iterate
+
+Don't optimize for one model. Find the balance that works across your target models.
+</iterative_improvement>
+</model_testing_principle>
+
+<progressive_disclosure_principle>
+<description>
+SKILL.md serves as an overview. Reference files contain details. Antigravity loads reference files only when needed.
+</description>
+
+<token_efficiency>
+Progressive disclosure keeps token usage proportional to task complexity:
+
+- Simple task: Load SKILL.md only (~500 tokens)
+- Medium task: Load SKILL.md + one reference (~1000 tokens)
+- Complex task: Load SKILL.md + multiple references (~2000 tokens)
+
+Without progressive disclosure, every task loads all content regardless of need.
+</token_efficiency>
+
+<implementation>
+- Keep SKILL.md under 500 lines
+- Split detailed content into reference files
+- Keep references one level deep from SKILL.md
+- Link to references from relevant sections
+- Use descriptive reference file names
+
+See [skill-structure.md](skill-structure.md) for progressive disclosure patterns.
+</implementation>
+</progressive_disclosure_principle>
+
+<validation_principle>
+<description>
+Validation scripts are force multipliers. They catch errors that Antigravity might miss and provide actionable feedback.
+</description>
+
+<characteristics>
+Good validation scripts:
+- Provide verbose, specific error messages
+- Show available valid options when something is invalid
+- Pinpoint exact location of problems
+- Suggest actionable fixes
+- Are deterministic and reliable
+
+See [workflows-and-validation.md](workflows-and-validation.md) for validation patterns.
+</characteristics>
+</validation_principle>
+
+<principle_summary>
+<xml_structure>
+Use pure XML structure for consistency, parseability, and Antigravity performance. Required tags: objective, quick_start, success_criteria.
+</xml_structure>
+
+<conciseness>
+Only add context Antigravity doesn't have. Assume Antigravity is smart. Challenge every piece of content.
+</conciseness>
+
+<degrees_of_freedom>
+Match specificity to fragility. High freedom for creative tasks, low freedom for fragile operations, medium for standard work.
+</degrees_of_freedom>
+
+<model_testing>
+Test with all target models. Balance detail level to work across Haiku, Sonnet, and Opus.
+</model_testing>
+
+<progressive_disclosure>
+Keep SKILL.md concise. Split details into reference files. Load reference files only when needed.
+</progressive_disclosure>
+
+<validation>
+Make validation scripts verbose and specific. Catch errors early with actionable feedback.
+</validation>
+</principle_summary>

package/.agent/skills/create-agent-skills/references/executable-code.md

@@ -0,0 +1,175 @@
+<when_to_use_scripts>
+Even if Antigravity could write a script, pre-made scripts offer advantages:
+- More reliable than generated code
+- Save tokens (no need to include code in context)
+- Save time (no code generation required)
+- Ensure consistency across uses
+
+<execution_vs_reference>
+Make clear whether Antigravity should:
+- **Execute the script** (most common): "Run `analyze_form.py` to extract fields"
+- **Read it as reference** (for complex logic): "See `analyze_form.py` for the extraction algorithm"
+
+For most utility scripts, execution is preferred.
+</execution_vs_reference>
+
+<how_scripts_work>
+When Antigravity executes a script via bash:
+1. Script code never enters context window
+2. Only script output consumes tokens
+3. Far more efficient than having Antigravity generate equivalent code
+</how_scripts_work>
+</when_to_use_scripts>
+
+<file_organization>
+<scripts_directory>
+**Best practice**: Place all executable scripts in a `scripts/` subdirectory within the skill folder.
+
+```
+skill-name/
+├── SKILL.md
+├── scripts/
+│   ├── main_utility.py
+│   ├── helper_script.py
+│   └── validator.py
+└── references/
+    └── api-docs.md
+```
+
+**Benefits**:
+- Keeps skill root clean and organized
+- Clear separation between documentation and executable code
+- Consistent pattern across all skills
+- Easy to reference: `python scripts/script_name.py`
+
+**Reference pattern**: In SKILL.md, reference scripts using the `scripts/` path:
+
+```bash
+python ~/.antigravity/skills/skill-name/scripts/analyze.py input.har
+```
+</scripts_directory>
+</file_organization>
+
+<utility_scripts_pattern>
+<example>
+## Utility scripts
+
+**analyze_form.py**: Extract all form fields from PDF
+
+```bash
+python scripts/analyze_form.py input.pdf > fields.json
+```
+
+Output format:
+```json
+{
+  "field_name": { "type": "text", "x": 100, "y": 200 },
+  "signature": { "type": "sig", "x": 150, "y": 500 }
+}
+```
+
+**validate_boxes.py**: Check for overlapping bounding boxes
+
+```bash
+python scripts/validate_boxes.py fields.json
+# Returns: "OK" or lists conflicts
+```
+
+**fill_form.py**: Apply field values to PDF
+
+```bash
+python scripts/fill_form.py input.pdf fields.json output.pdf
+```
+</example>
+</utility_scripts_pattern>
+
+<solve_dont_punt>
+Handle error conditions rather than punting to Antigravity.
+
+<example type="good">
+```python
+def process_file(path):
+    """Process a file, creating it if it doesn't exist."""
+    try:
+        with open(path) as f:
+            return f.read()
+    except FileNotFoundError:
+        print(f"File {path} not found, creating default")
+        with open(path, 'w') as f:
+            f.write('')
+        return ''
+    except PermissionError:
+        print(f"Cannot access {path}, using default")
+        return ''
+```
+</example>
+
+<example type="bad">
+```python
+def process_file(path):
+    # Just fail and let Antigravity figure it out
+    return open(path).read()
+```
+</example>
+
+<configuration_values>
+Document configuration parameters to avoid "voodoo constants":
+
+<example type="good">
+```python
+# HTTP requests typically complete within 30 seconds
+REQUEST_TIMEOUT = 30
+
+# Three retries balances reliability vs speed
+MAX_RETRIES = 3
+```
+</example>
+
+<example type="bad">
+```python
+TIMEOUT = 47  # Why 47?
+RETRIES = 5   # Why 5?
+```
+</example>
+</configuration_values>
+</solve_dont_punt>
+
+<package_dependencies>
+<runtime_constraints>
+Skills run in code execution environment with platform-specific limitations:
+- **agent.ai**: Can install packages from npm and PyPI
+- **Antigravity API**: No network access and no runtime package installation
+</runtime_constraints>
+
+<guidance>
+List required packages in your SKILL.md and verify they're available.
+
+<example type="good">
+Install required package: `pip install pypdf`
+
+Then use it:
+
+```python
+from pypdf import PdfReader
+reader = PdfReader("file.pdf")
+```
+</example>
+
+<example type="bad">
+"Use the pdf library to process the file."
+</example>
+</guidance>
+</package_dependencies>
+
+<mcp_tool_references>
+If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names.
+
+<format>ServerName:tool_name</format>
+
+<examples>
+- Use the BigQuery:bigquery_schema tool to retrieve table schemas.
+- Use the GitHub:create_issue tool to create issues.
+</examples>
+
+Without the server prefix, Antigravity may fail to locate the tool, especially when multiple MCP servers are available.
+</mcp_tool_references>