@fro.bot/systematic 1.14.0 → 1.16.0

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

@@ -1,372 +1,152 @@
-<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>
-```
+# Skill Structure Reference
 
-Always close tags:
-```xml
-<objective>
-Content here
-</objective>
-```
-</xml_nesting>
+Skills have three structural components: YAML frontmatter (metadata), standard markdown body (content), and progressive disclosure (file organization).
 
-<tag_naming_conventions>
-Use descriptive, semantic names:
-- `<workflow>` not `<steps>`
-- `<success_criteria>` not `<done>`
-- `<anti_patterns>` not `<dont_do>`
+## Body Format
 
-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>
+Use **standard markdown headings** for structure. Keep markdown formatting within content (bold, italic, lists, code blocks, links).
 
-<yaml_requirements>
-<required_fields>
-```yaml
+```markdown
 ---
-name: skill-name-here
-description: What it does and when to use it (third person, specific triggers)
+name: my-skill
+description: What it does and when to use it
 ---
-```
-</required_fields>
-
-<name_field>
-**Validation rules**:
-- Maximum 64 characters
-- Lowercase letters, numbers, hyphens only
-- No XML tags
-- No reserved words: "anthropic", "claude"
-- Must match directory name exactly
-
-**Examples**:
-- ✅ `process-pdfs`
-- ✅ `manage-facebook-ads`
-- ✅ `setup-stripe-payments`
-- ❌ `PDF_Processor` (uppercase)
-- ❌ `helper` (vague)
-- ❌ `claude-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.
-```
+# Skill Name
 
-```yaml
-description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
-```
+## Quick Start
+Immediate actionable guidance...
 
-```yaml
-description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
-```
+## Instructions
+Step-by-step procedures...
 
-**Avoid**:
-```yaml
-description: Helps with documents
-```
+## Examples
+Concrete usage examples...
 
-```yaml
-description: Processes data
+## Guidelines
+Rules and constraints...
 ```
-</description_field>
-</yaml_requirements>
 
-<naming_conventions>
-Use **verb-noun convention** for skill names:
+## Recommended Sections
 
-<pattern name="create">
-Building/authoring tools
+Every skill should have:
 
-Examples: `create-agent-skills`, `create-hooks`, `create-landing-pages`
-</pattern>
+- **Quick Start** - Immediate, actionable guidance (minimal working example)
+- **Instructions** - Core step-by-step guidance
+- **Success Criteria** - How to know it worked
 
-<pattern name="manage">
-Managing external services or resources
+Add based on complexity:
 
-Examples: `manage-facebook-ads`, `manage-zoom`, `manage-stripe`, `manage-supabase`
-</pattern>
+- **Context** - Background/situational information
+- **Workflow** - Multi-step procedures
+- **Examples** - Concrete input/output pairs
+- **Advanced Features** - Deep-dive topics (link to reference files)
+- **Anti-Patterns** - Common mistakes to avoid
+- **Guidelines** - Rules and constraints
 
-<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: `anthropic-helper`, `claude-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>
+## YAML Frontmatter
 
-<pattern name="high_level_guide">
-Quick start in SKILL.md, details in reference files:
+### Required/Recommended Fields
 
-```markdown
+```yaml
 ---
-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.
+name: skill-name-here
+description: What it does and when to use it (specific triggers included)
 ---
-
-<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>
 ```
 
-Claude loads forms.md or reference.md only when needed.
-</pattern>
+### Name Field
 
-<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)
-```
+**Validation rules:**
+- Maximum 64 characters
+- Lowercase letters, numbers, hyphens only
+- Must match directory name
+- No reserved words: "anthropic", "claude"
 
-When user asks about revenue, Claude reads only finance.md. Other files stay on filesystem consuming zero tokens.
-</pattern>
+**Examples:**
+- `triage-prs`
+- `deploy-production`
+- `review-code`
+- `setup-stripe-payments`
 
-<pattern name="conditional_details">
-Show basic content in SKILL.md, link to advanced in reference files:
+**Avoid:** `helper`, `utils`, `tools`, generic names
 
-```xml
-<objective>
-Process DOCX files with creation and editing capabilities.
-</objective>
+### Description Field
 
-<quick_start>
-<creating_documents>
-Use docx-js for new documents. See [docx-js.md](docx-js.md).
-</creating_documents>
+**Validation rules:**
+- Maximum 1024 characters
+- Include what it does AND when to use it
+- Third person voice
 
-<editing_documents>
-For simple edits, modify XML directly.
+**Good:**
+```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.
+```
 
-**For tracked changes**: See [redlining.md](redlining.md)
-**For OOXML details**: See [ooxml.md](ooxml.md)
-</editing_documents>
-</quick_start>
+**Bad:**
+```yaml
+description: Helps with documents
 ```
 
-Claude reads redlining.md or ooxml.md only when the user needs those features.
-</pattern>
+### Optional Fields
 
-<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 Claude may only partially read deeply nested files.
+| Field | Description |
+|-------|-------------|
+| `argument-hint` | Usage hints. Example: `[issue-number]` |
+| `disable-model-invocation` | `true` to prevent auto-loading. Use for side-effect workflows. |
+| `user-invocable` | `false` to hide from `/` menu. Use for background knowledge. |
+| `allowed-tools` | Tools without permission prompts. Example: `Read, Bash(git *)` |
+| `model` | `haiku`, `sonnet`, or `opus` |
+| `context` | `fork` for isolated subagent execution |
+| `agent` | Subagent type: `Explore`, `Plan`, `general-purpose`, or custom |
 
-**Add table of contents to long files**: For reference files over 100 lines, include a table of contents at the top.
+## Naming Conventions
 
-**Use pure XML in reference files**: Reference files should also use pure XML structure (no markdown headings in body).
-</critical_rules>
-</progressive_disclosure>
+Use descriptive names that indicate purpose:
 
-<file_organization>
-<filesystem_navigation>
-Claude navigates your skill directory using bash commands:
+| Pattern | Examples |
+|---------|----------|
+| Action-oriented | `triage-prs`, `deploy-production`, `review-code` |
+| Domain-specific | `setup-stripe-payments`, `manage-facebook-ads` |
+| Descriptive | `git-worktree`, `frontend-design`, `dhh-rails-style` |
 
-- 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>
+## Progressive Disclosure
 
-<directory_structure>
-Typical skill structure:
+Keep SKILL.md under 500 lines. Split into reference files:
 
 ```
-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...
+my-skill/
+├── SKILL.md           # Entry point (required, overview + navigation)
+├── reference.md       # Detailed docs (loaded when needed)
+├── examples.md        # Usage examples (loaded when needed)
+└── scripts/
+    └── helper.py      # Utility script (executed, not loaded)
 ```
 
-✅ 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. Claude 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>
+**Rules:**
+- Keep references one level deep from SKILL.md
+- Add table of contents to reference files over 100 lines
+- Use forward slashes in paths: `scripts/helper.py`
+- Name files descriptively: `form_validation_rules.md` not `doc2.md`
+
+## Validation Checklist
+
+Before finalizing:
+
+- [ ] YAML frontmatter valid (name matches directory, description specific)
+- [ ] Uses standard markdown headings (not XML tags)
+- [ ] Has Quick Start, Instructions, and Success Criteria sections
+- [ ] `disable-model-invocation: true` if skill has side effects
+- [ ] SKILL.md under 500 lines
+- [ ] Reference files linked properly from SKILL.md
+- [ ] File paths use forward slashes
+- [ ] Tested with real usage
+
+## Anti-Patterns
+
+- **XML tags in body** - Use standard markdown headings
+- **Vague descriptions** - Be specific with trigger keywords
+- **Deep nesting** - Keep references one level from SKILL.md
+- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
+- **Inconsistent naming** - Directory name must match `name` field
+- **Windows paths** - Always use forward slashes

package/skills/create-agent-skills/workflows/add-reference.md

@@ -10,7 +10,7 @@
 ## Step 1: Select the Skill
 
 ```bash
-ls ~/.claude/skills/
+ls ~/.config/opencode/skills/
 ```
 
 Present numbered list, ask: "Which skill needs a new reference?"
@@ -18,8 +18,8 @@ Present numbered list, ask: "Which skill needs a new reference?"
 ## Step 2: Analyze Current Structure
 
 ```bash
-cat ~/.claude/skills/{skill-name}/SKILL.md
-ls ~/.claude/skills/{skill-name}/references/ 2>/dev/null
+cat ~/.config/opencode/skills/{skill-name}/SKILL.md
+ls ~/.config/opencode/skills/{skill-name}/references/ 2>/dev/null
 ```
 
 Determine:

package/skills/create-agent-skills/workflows/add-script.md

@@ -24,7 +24,7 @@ If not a good fit, suggest alternatives (inline code in workflow, reference exam
 ## Step 3: Create Scripts Directory
 
 ```bash
-mkdir -p ~/.claude/skills/{skill-name}/scripts
+mkdir -p ~/.config/opencode/skills/{skill-name}/scripts
 ```
 
 ## Step 4: Design Script
@@ -58,7 +58,7 @@ set -euo pipefail
 ## Step 6: Make Executable (if bash)
 
 ```bash
-chmod +x ~/.claude/skills/{skill-name}/scripts/{script-name}.sh
+chmod +x ~/.config/opencode/skills/{skill-name}/scripts/{script-name}.sh
 ```
 
 ## Step 7: Update Workflow to Use Script

package/skills/create-agent-skills/workflows/add-template.md

@@ -24,7 +24,7 @@ If not a good fit, suggest alternatives (workflow guidance, reference examples).
 ## Step 3: Create Templates Directory
 
 ```bash
-mkdir -p ~/.claude/skills/{skill-name}/templates
+mkdir -p ~/.config/opencode/skills/{skill-name}/templates
 ```
 
 ## Step 4: Design Template Structure

package/skills/create-agent-skills/workflows/add-workflow.md

@@ -9,10 +9,10 @@
 <process>
 ## Step 1: Select the Skill
 
-**DO NOT use AskUserQuestion** - there may be many skills.
+**DO NOT use question tool** - there may be many skills.
 
 ```bash
-ls ~/.claude/skills/
+ls ~/.config/opencode/skills/
 ```
 
 Present numbered list, ask: "Which skill needs a new workflow?"
@@ -21,8 +21,8 @@ Present numbered list, ask: "Which skill needs a new workflow?"
 
 Read the skill:
 ```bash
-cat ~/.claude/skills/{skill-name}/SKILL.md
-ls ~/.claude/skills/{skill-name}/workflows/ 2>/dev/null
+cat ~/.config/opencode/skills/{skill-name}/SKILL.md
+ls ~/.config/opencode/skills/{skill-name}/workflows/ 2>/dev/null
 ```
 
 Determine:
@@ -34,7 +34,7 @@ Report current structure to user.
 
 ## Step 3: Gather Workflow Requirements
 
-Ask using AskUserQuestion or direct question:
+Ask using question tool or direct question:
 - What should this workflow do?
 - When would someone use it vs existing workflows?
 - What references would it need?

package/skills/create-agent-skills/workflows/audit-skill.md

@@ -10,11 +10,11 @@
 <process>
 ## Step 1: List Available Skills
 
-**DO NOT use AskUserQuestion** - there may be many skills.
+**DO NOT use question tool** - there may be many skills.
 
 Enumerate skills in chat as numbered list:
 ```bash
-ls ~/.claude/skills/
+ls ~/.config/opencode/skills/
 ```
 
 Present as:
@@ -33,12 +33,12 @@ Ask: "Which skill would you like to audit? (enter number or name)"
 After user selects, read the full skill structure:
 ```bash
 # Read main file
-cat ~/.claude/skills/{skill-name}/SKILL.md
+cat ~/.config/opencode/skills/{skill-name}/SKILL.md
 
 # Check for workflows and references
-ls ~/.claude/skills/{skill-name}/
-ls ~/.claude/skills/{skill-name}/workflows/ 2>/dev/null
-ls ~/.claude/skills/{skill-name}/references/ 2>/dev/null
+ls ~/.config/opencode/skills/{skill-name}/
+ls ~/.config/opencode/skills/{skill-name}/workflows/ 2>/dev/null
+ls ~/.config/opencode/skills/{skill-name}/references/ 2>/dev/null
 ```
 
 ## Step 3: Run Audit Checklist

package/skills/create-agent-skills/workflows/create-domain-expertise-skill.md

@@ -52,7 +52,7 @@ Get specific: "Python games" or "Python games with Pygame specifically"?
 
 Explain:
 ```
-Domain expertise skills go in: ~/.claude/skills/expertise/{domain-name}/
+Domain expertise skills go in: ~/.config/opencode/skills/expertise/{domain-name}/
 
 These are comprehensive BUILD skills that:
 - Execute tasks (build, debug, optimize, ship)
@@ -61,7 +61,7 @@ These are comprehensive BUILD skills that:
 - Can be loaded by other skills for domain knowledge
 
 Name suggestion: {suggested-name}
-Location: ~/.claude/skills/expertise/{suggested-name}/
+Location: ~/.config/opencode/skills/expertise/{suggested-name}/
 ```
 
 Confirm or adjust name.
@@ -499,21 +499,21 @@ Test both use cases:
 
 ```bash
 # Create structure
-mkdir -p ~/.claude/skills/expertise/{domain-name}
-mkdir -p ~/.claude/skills/expertise/{domain-name}/workflows
-mkdir -p ~/.claude/skills/expertise/{domain-name}/references
+mkdir -p ~/.config/opencode/skills/expertise/{domain-name}
+mkdir -p ~/.config/opencode/skills/expertise/{domain-name}/workflows
+mkdir -p ~/.config/opencode/skills/expertise/{domain-name}/references
 
 # Write SKILL.md
 # Write all workflow files
 # Write all reference files
 
 # Verify structure
-ls -R ~/.claude/skills/expertise/{domain-name}
+ls -R ~/.config/opencode/skills/expertise/{domain-name}
 ```
 
 ## Step 11: Document in create-plans
 
-Update `~/.claude/skills/create-plans/SKILL.md` to reference this new domain:
+Update `~/.config/opencode/skills/create-plans/SKILL.md` to reference this new domain:
 
 Add to the domain inference table:
 ```markdown
@@ -573,7 +573,7 @@ Domain expertise skill is complete when:
 - [ ] Anti-patterns documented throughout
 - [ ] Full lifecycle covered (build → debug → test → optimize → ship)
 - [ ] Platform-specific considerations included
-- [ ] Located in ~/.claude/skills/expertise/{domain-name}/
+- [ ] Located in ~/.config/opencode/skills/expertise/{domain-name}/
 - [ ] Referenced in create-plans domain inference table
 - [ ] Passes dual-purpose test: Can be invoked directly AND loaded for knowledge
 - [ ] User can build something professional from scratch through shipping