@michael-joseph-miller/ant-bot 0.1.0

package/skills/SPEC.md

@@ -0,0 +1,274 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://agentskills.io/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Specification
+
+> The complete format specification for Agent Skills.
+
+## Directory structure
+
+A skill is a directory containing, at minimum, a `SKILL.md` file:
+
+```
+skill-name/
+├── SKILL.md          # Required: metadata + instructions
+├── scripts/          # Optional: executable code
+├── references/       # Optional: documentation
+├── assets/           # Optional: templates, resources
+└── ...               # Any additional files or directories
+```
+
+## `SKILL.md` format
+
+The `SKILL.md` file must contain YAML frontmatter followed by Markdown content.
+
+### Frontmatter
+
+| Field           | Required | Constraints                                                                                                       |
+| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
+| `name`          | Yes      | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen.             |
+| `description`   | Yes      | Max 1024 characters. Non-empty. Describes what the skill does and when to use it.                                 |
+| `license`       | No       | License name or reference to a bundled license file.                                                              |
+| `compatibility` | No       | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). |
+| `metadata`      | No       | Arbitrary key-value mapping for additional metadata (a map from string keys to string values).                    |
+| `allowed-tools` | No       | Space-separated string of pre-approved tools the skill may use. (Experimental)                                    |
+
+<Card>
+  **Minimal example:**
+
+  ```markdown SKILL.md theme={null}
+  ---
+  name: skill-name
+  description: A description of what this skill does and when to use it.
+  ---
+  ```
+
+  **Example with optional fields:**
+
+  ```markdown SKILL.md theme={null}
+  ---
+  name: pdf-processing
+  description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
+  license: Apache-2.0
+  metadata:
+    author: example-org
+    version: "1.0"
+  ---
+  ```
+</Card>
+
+#### `name` field
+
+The required `name` field:
+
+* Must be 1-64 characters
+* May only contain unicode lowercase alphanumeric characters (`a-z`, `0-9`) and hyphens (`-`)
+* Must not start or end with a hyphen (`-`)
+* Must not contain consecutive hyphens (`--`)
+* Must match the parent directory name
+
+<Card>
+  **Valid examples:**
+
+  ```yaml theme={null}
+  name: pdf-processing
+  ```
+
+  ```yaml theme={null}
+  name: data-analysis
+  ```
+
+  ```yaml theme={null}
+  name: code-review
+  ```
+
+  **Invalid examples:**
+
+  ```yaml theme={null}
+  name: PDF-Processing  # uppercase not allowed
+  ```
+
+  ```yaml theme={null}
+  name: -pdf  # cannot start with hyphen
+  ```
+
+  ```yaml theme={null}
+  name: pdf--processing  # consecutive hyphens not allowed
+  ```
+</Card>
+
+#### `description` field
+
+The required `description` field:
+
+* Must be 1-1024 characters
+* Should describe both what the skill does and when to use it
+* Should include specific keywords that help agents identify relevant tasks
+
+<Card>
+  **Good example:**
+
+  ```yaml theme={null}
+  description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
+  ```
+
+  **Poor example:**
+
+  ```yaml theme={null}
+  description: Helps with PDFs.
+  ```
+</Card>
+
+#### `license` field
+
+The optional `license` field:
+
+* Specifies the license applied to the skill
+* We recommend keeping it short (either the name of a license or the name of a bundled license file)
+
+<Card>
+  **Example:**
+
+  ```yaml theme={null}
+  license: Proprietary. LICENSE.txt has complete terms
+  ```
+</Card>
+
+#### `compatibility` field
+
+The optional `compatibility` field:
+
+* Must be 1-500 characters if provided
+* Should only be included if your skill has specific environment requirements
+* Can indicate intended product, required system packages, network access needs, etc.
+
+<Card>
+  **Examples:**
+
+  ```yaml theme={null}
+  compatibility: Designed for Claude Code (or similar products)
+  ```
+
+  ```yaml theme={null}
+  compatibility: Requires git, docker, jq, and access to the internet
+  ```
+
+  ```yaml theme={null}
+  compatibility: Requires Python 3.14+ and uv
+  ```
+</Card>
+
+<Note>
+  Most skills do not need the `compatibility` field.
+</Note>
+
+#### `metadata` field
+
+The optional `metadata` field:
+
+* A map from string keys to string values
+* Clients can use this to store additional properties not defined by the Agent Skills spec
+* We recommend making your key names reasonably unique to avoid accidental conflicts
+
+<Card>
+  **Example:**
+
+  ```yaml theme={null}
+  metadata:
+    author: example-org
+    version: "1.0"
+  ```
+</Card>
+
+#### `allowed-tools` field
+
+The optional `allowed-tools` field:
+
+* A space-separated string of tools that are pre-approved to run
+* Experimental. Support for this field may vary between agent implementations
+
+<Card>
+  **Example:**
+
+  ```yaml theme={null}
+  allowed-tools: Bash(git:*) Bash(jq:*) Read
+  ```
+</Card>
+
+### Body content
+
+The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.
+
+Recommended sections:
+
+* Step-by-step instructions
+* Examples of inputs and outputs
+* Common edge cases
+
+Note that the agent will load this entire file once it's decided to activate a skill. Consider splitting longer `SKILL.md` content into referenced files.
+
+## Optional directories
+
+A skill directory may contain any files and directories beyond the required `SKILL.md`. The conventions below are recommendations for organizing common types of content.
+
+### `scripts/`
+
+Contains executable code that agents can run. Scripts should:
+
+* Be self-contained or clearly document dependencies
+* Include helpful error messages
+* Handle edge cases gracefully
+
+Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript.
+
+### `references/`
+
+Contains additional documentation that agents can read when needed:
+
+* `REFERENCE.md` - Detailed technical reference
+* `FORMS.md` - Form templates or structured data formats
+* Domain-specific files (`finance.md`, `legal.md`, etc.)
+
+Keep individual [reference files](#file-references) focused. Agents load these on demand, so smaller files mean less use of context.
+
+### `assets/`
+
+Contains static resources:
+
+* Templates (document templates, configuration templates)
+* Images (diagrams, examples)
+* Data files (lookup tables, schemas)
+
+## Progressive disclosure
+
+Agents load skills *progressively*, pulling in more detail only as a task calls for it. Skills should be structured to take advantage of this:
+
+1. **Metadata** (\~100 tokens): The `name` and `description` fields are loaded at startup for all skills
+2. **Instructions** (\< 5000 tokens recommended): The full `SKILL.md` body is loaded when the skill is activated
+3. **Resources** (as needed): Files (e.g. those in `scripts/`, `references/`, or `assets/`) are loaded only when required
+
+Keep your main `SKILL.md` under 500 lines. Move detailed reference material to separate files.
+
+## File references
+
+When referencing other files in your skill, use relative paths from the skill root:
+
+```markdown SKILL.md theme={null}
+See [the reference guide](references/REFERENCE.md) for details.
+
+Run the extraction script:
+scripts/extract.py
+```
+
+Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains.
+
+## Validation
+
+Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) reference library to validate your skills:
+
+```bash theme={null}
+skills-ref validate ./my-skill
+```
+
+This checks that your `SKILL.md` frontmatter is valid and follows all naming conventions.

package/skills/bug-repro/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: bug-repro
+description: "Turns a raw bug report into a reliable repro pack: exact steps, expected vs. actual, evidence, and a minimal test case, on a fresh test account in staging."
+---
+
+## When to use it
+
+Use this skill when handed a bug report (from a ticket, a message, or a user complaint) that
+needs to become something an engineer can act on immediately, without first having to reproduce
+it themselves. Not for triaging severity or deciding priority — just for turning "it's broken"
+into "here's exactly how, and here's proof."
+
+## Required inputs and access
+
+- The original bug report text, ticket link, or user message.
+- Access to a **staging** environment and a **fresh test account** — never a production account
+  or real customer data.
+- Browser and network-inspection tools for evidence capture.
+- If staging is unavailable or the bug depends on production-only data, stop and report that
+  instead of attempting the repro against production.
+
+## Sequence of work
+
+1. Read the report and write down what you believe is being claimed: expected vs. actual.
+2. Create or reuse a fresh test account in staging — never reuse a production/customer login.
+3. Attempt the exact steps described, in order, capturing a screenshot and the browser
+   console/network log at each meaningful step.
+4. If the first attempt doesn't reproduce it, vary one variable at a time (browser, account
+   state, timing) and note what changed.
+5. Once reproduced, strip the steps down to the smallest sequence that still triggers it.
+6. If it does not reproduce after reasonable attempts, say so plainly — do not force a result.
+
+## How to validate the result
+
+- The repro steps must be re-runnable by someone else from a fresh test account, using only what
+  is written down.
+- Expected vs. actual must be stated in one sentence each, unambiguously.
+- Every step must have supporting evidence (screenshot, console/network excerpt) attached.
+- If the bug turns out to be data-dependent on production, that is itself a finding — report it,
+  do not attempt to pull real production data to compensate.
+
+## What to return
+
+A repro pack containing: exact numbered steps, expected result, actual result, screenshots per
+step, relevant console/network excerpts, browser/OS versions used, the minimal test case, and (if
+reproduction failed) a clear statement of what was tried and what is still unknown.
+
+## What requires approval
+
+- Touching any production environment or any real customer account or data — always stay in
+  staging with a fresh test account.
+- Filing or closing the ticket on the reporter's behalf, unless explicitly asked to.
+- Sharing the repro pack anywhere outside the originating ticket/conversation.