unifai 2.0.1

package/skills/skill-writer-skills/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: skill-writer
+description: Universal guide for creating well-structured Agent Skills for any technology or domain. Use when creating, writing, authoring, or designing a new Skill. Triggers on requests involving SKILL.md files, skill structure, frontmatter, bundled resources (scripts/references/assets), skill validation, skill packaging, or when user wants to convert workflows into reusable Skills.
+---
+
+# Skill Writer
+
+Create high-quality Agent Skills for any technology, language, or domain.
+
+## What Skills Are
+
+Skills are modular packages that extend AI capabilities by providing:
+- **Specialized workflows** - Multi-step procedures for specific domains
+- **Tool integrations** - Instructions for working with file formats or APIs
+- **Domain expertise** - Schemas, business logic, conventions
+- **Bundled resources** - Scripts, references, assets for complex tasks
+
+Skills are **orchestrators**, not tools themselves. They guide AI on HOW to use tools.
+
+## Core Principles
+
+1. **Concise is Key** - Challenge each token; prefer examples over explanations
+2. **Degrees of Freedom** - Match specificity to task fragility
+3. **Progressive Disclosure** - Load details only when needed
+
+See [references/core-principles.md](references/core-principles.md) for detailed guidance.
+
+## Skill Anatomy
+
+```
+skill-name/
+├── SKILL.md (REQUIRED)
+│   ├── YAML frontmatter (name, description)
+│   └── Markdown instructions
+└── Bundled Resources (OPTIONAL)
+    ├── scripts/      - Executable code (deterministic tasks)
+    ├── references/   - Documentation (loaded as needed)
+    └── assets/       - Output files (not loaded into context)
+```
+
+See [references/skill-anatomy.md](references/skill-anatomy.md) for when to use each resource type.
+
+## 6-Step Creation Process
+
+1. **Understand** - Gather concrete usage examples
+2. **Plan** - Identify reusable resources (scripts/references/assets)
+3. **Initialize** - Create directory structure
+4. **Edit** - Implement resources + write SKILL.md
+5. **Package** - Validate and create distributable
+6. **Iterate** - Improve based on real usage
+
+See [references/creation-process.md](references/creation-process.md) for step-by-step guidance.
+
+## Writing SKILL.md
+
+### Frontmatter (Critical)
+
+```yaml
+---
+name: lowercase-hyphenated-name
+description: WHAT it does + WHEN to use it. Include trigger words and contexts.
+---
+```
+
+The description is the **primary triggering mechanism**. Include ALL trigger information here—the body only loads AFTER triggering.
+
+### Body (Concise)
+
+- Keep under 500 lines
+- Use imperative form
+- Reference bundled resources clearly
+- For multi-step processes, give overview early
+
+See [references/design-patterns.md](references/design-patterns.md) for workflow and output patterns.
+
+## Common Pitfalls
+
+| Pitfall | Solution |
+|---------|----------|
+| Verbose SKILL.md | Challenge each sentence—does AI need this? |
+| "When to use" in body | Put ALL triggers in description field |
+| Untested scripts | Always test before packaging |
+| Unnecessary files | No README.md, CHANGELOG.md in skills |
+| Duplicated info | Pick SKILL.md OR references, not both |
+
+See [references/common-pitfalls.md](references/common-pitfalls.md) for complete list.
+
+## Validation
+
+Before packaging, verify:
+- [ ] Frontmatter: name + description present
+- [ ] Description: includes WHAT + WHEN
+- [ ] SKILL.md: under 500 lines, only essentials
+- [ ] Scripts: tested and working
+- [ ] No duplication between SKILL.md and references
+
+See [references/validation-checklist.md](references/validation-checklist.md) for full checklist.

package/skills/skill-writer-skills/metadata.json

@@ -0,0 +1,17 @@
+{
+  "version": "1.0.0",
+  "author": "Agent Skills Community",
+  "date": "January 2026",
+  "abstract": "Universal guide for AI agents to create high-quality, well-structured Skills for any technology, language, or domain. Based on Claude's official skill-writing principles: conciseness, appropriate degrees of freedom, and progressive disclosure. Covers the complete 6-step creation process from understanding use cases to packaging and iteration.",
+  "references": [
+    "https://claude.ai/docs/skills",
+    "https://github.com/vercel-labs/agent-skills",
+    "https://docs.anthropic.com"
+  ],
+  "compatibility": [
+    "Claude Code",
+    "OpenCode",
+    "Cursor",
+    "Other MCP-compatible agents"
+  ]
+}

package/skills/skill-writer-skills/references/common-pitfalls.md

@@ -0,0 +1,291 @@
+# Common Pitfalls and How to Avoid Them
+
+Learn from common mistakes in skill creation.
+
+---
+
+## Pitfall 1: Verbose SKILL.md Files
+
+### Problem
+Including information Claude already knows, wasting context tokens.
+
+### Bad Example
+```markdown
+## Introduction to Data Validation
+
+Data validation is a crucial process in software development that ensures 
+the integrity and quality of data. When data enters a system, it must be 
+checked for correctness, completeness, and conformance to defined rules. 
+Without proper validation, applications may behave unexpectedly or produce 
+incorrect results. This skill helps with data validation tasks.
+
+### What is JSON Schema?
+
+JSON Schema is a vocabulary that allows you to annotate and validate JSON 
+documents. It provides a way to describe the structure of JSON data for 
+documentation, validation, and interaction control...
+```
+
+### Good Example
+```markdown
+## Quick Start
+
+Validate JSON against schema:
+```bash
+python scripts/validate.py input.json --schema schema.json
+```
+
+For custom validation rules, see [references/rules.md](references/rules.md).
+```
+
+### Solution
+Challenge each sentence: "Does Claude really need this?" Claude already knows what JSON Schema is.
+
+---
+
+## Pitfall 2: "When to Use" in Body
+
+### Problem
+Putting trigger information in the SKILL.md body, which only loads AFTER triggering.
+
+### Bad Example
+```yaml
+---
+name: report-generator
+description: Generates reports
+---
+
+# Report Generator
+
+## When to Use This Skill
+
+Use this skill when:
+- Creating quarterly reports
+- Generating financial summaries
+- Building dashboards
+```
+
+### Good Example
+```yaml
+---
+name: report-generator
+description: Generate professional reports including quarterly reports, 
+  financial summaries, and dashboards. Use when creating any business report, 
+  data visualization, or executive summary. Triggers on requests for Q1/Q2/Q3/Q4 
+  reports, metrics dashboards, or financial documentation.
+---
+
+# Report Generator
+
+## Quick Start
+[Immediately useful content]
+```
+
+### Solution
+Put ALL trigger information in the description field. The body only loads after the skill is already triggered.
+
+---
+
+## Pitfall 3: Untested Scripts
+
+### Problem
+Scripts fail when Claude tries to use them.
+
+### Bad Example
+Creating `scripts/process.py` without testing:
+```python
+def process(file):
+    # Untested code with potential bugs
+    data = load(file)  # NameError: load is undefined
+    return transform(data)
+```
+
+### Good Example
+Test every script before including:
+```bash
+# Run the script with test data
+python scripts/process.py test_input.json
+
+# Verify output
+cat output.json
+```
+
+### Solution
+- Always test scripts by actually running them
+- Include error handling
+- Test edge cases
+
+---
+
+## Pitfall 4: Unnecessary Documentation Files
+
+### Problem
+Including files that clutter the skill but don't help Claude.
+
+### Bad Structure
+```
+my-skill/
+├── SKILL.md
+├── README.md              ❌ Not needed
+├── INSTALLATION.md        ❌ Not needed
+├── CHANGELOG.md           ❌ Not needed
+├── CONTRIBUTING.md        ❌ Not needed
+├── .gitignore             ❌ Not needed
+└── scripts/
+```
+
+### Good Structure
+```
+my-skill/
+├── SKILL.md
+├── scripts/
+│   └── process.py
+└── references/
+    └── schema.md
+```
+
+### Solution
+Only include files that Claude needs to do the job. No README, CHANGELOG, or other developer documentation.
+
+---
+
+## Pitfall 5: Duplicated Information
+
+### Problem
+Same information in both SKILL.md and references, causing confusion.
+
+### Bad Example
+
+**In SKILL.md:**
+```markdown
+## API Endpoints
+
+- GET /users - List all users
+- POST /users - Create a user
+- GET /users/{id} - Get specific user
+...
+```
+
+**In references/api.md:**
+```markdown
+## API Endpoints
+
+- GET /users - List all users
+- POST /users - Create a user
+- GET /users/{id} - Get specific user
+...
+```
+
+### Good Example
+
+**In SKILL.md:**
+```markdown
+## API Reference
+
+For complete endpoint documentation, see [references/api.md](references/api.md).
+
+Quick examples:
+- List users: `GET /users`
+- Create user: `POST /users`
+```
+
+**In references/api.md:**
+```markdown
+[Complete, detailed API documentation]
+```
+
+### Solution
+Information lives in EITHER SKILL.md OR references, not both. Use SKILL.md for overview, references for details.
+
+---
+
+## Pitfall 6: Over-Specifying When Flexibility is Better
+
+### Problem
+Giving rigid instructions when multiple approaches are valid.
+
+### Bad Example
+```markdown
+## Writing Blog Posts
+
+You MUST follow this EXACT process:
+1. Write exactly 5 outline points
+2. Each paragraph must be 100-150 words
+3. Use exactly 3 subheadings
+4. Include exactly 2 quotes
+5. End with exactly 3 bullet points
+```
+
+### Good Example
+```markdown
+## Writing Blog Posts
+
+Create engaging content following these guidelines:
+- Start with a compelling hook
+- Use subheadings to organize content
+- Include relevant examples or quotes
+- End with clear takeaways
+
+Adjust structure based on topic and audience needs.
+```
+
+### Solution
+Match specificity to task fragility. Creative tasks need high freedom; fragile operations need low freedom.
+
+---
+
+## Pitfall 7: No Progressive Disclosure
+
+### Problem
+SKILL.md becomes too long, consuming too many tokens.
+
+### Bad Example
+```markdown
+# PDF Processing
+
+## Text Extraction
+[500 lines of detailed documentation]
+
+## Form Filling
+[500 lines of detailed documentation]
+
+## Table Extraction
+[500 lines of detailed documentation]
+
+## Merge and Split
+[500 lines of detailed documentation]
+
+Total: 2000+ lines loaded every time skill triggers
+```
+
+### Good Example
+```markdown
+# PDF Processing
+
+## Quick Start
+[50 lines covering basic usage]
+
+## Features
+- Text extraction: See [references/text.md](references/text.md)
+- Form filling: See [references/forms.md](references/forms.md)
+- Tables: See [references/tables.md](references/tables.md)
+
+Total: ~100 lines in SKILL.md, details loaded only when needed
+```
+
+### Solution
+Keep SKILL.md under 500 lines. Move variant-specific details into reference files.
+
+---
+
+## Quick Reference: Pitfall Checklist
+
+| Check | Question |
+|-------|----------|
+| ✓ | Is every sentence in SKILL.md necessary? |
+| ✓ | Is ALL trigger info in the description field? |
+| ✓ | Have all scripts been tested? |
+| ✓ | Are there any unnecessary files (README, etc.)? |
+| ✓ | Is information duplicated between files? |
+| ✓ | Is the freedom level appropriate for each task? |
+| ✓ | Is SKILL.md under 500 lines? |

package/skills/skill-writer-skills/references/core-principles.md

@@ -0,0 +1,147 @@
+# Core Principles for Skill Design
+
+These three principles guide all skill creation decisions.
+
+---
+
+## Principle 1: Concise is Key
+
+**The context window is a public good.** Skills share context with:
+- System prompt
+- Conversation history
+- Other skills' metadata
+- The actual user request
+
+### Default Assumption
+Claude is already very smart. Only add context Claude doesn't already have.
+
+### Challenge Each Piece
+Ask yourself:
+- "Does Claude really need this explanation?"
+- "Does this paragraph justify its token cost?"
+- "Can I show this with an example instead of explaining it?"
+
+### Prefer Examples Over Explanations
+
+**Verbose (avoid):**
+```markdown
+When processing user data, you should validate each field 
+according to the schema. The validation process involves 
+checking that required fields are present, that data types 
+match the expected types, and that values fall within 
+acceptable ranges as defined in the schema documentation.
+```
+
+**Concise (prefer):**
+```markdown
+Validate fields against schema:
+- Required fields present
+- Types match
+- Values in range
+```
+
+---
+
+## Principle 2: Degrees of Freedom
+
+Match the level of specificity to the task's fragility and variability.
+
+### High Freedom (text-based instructions)
+
+**Use when:**
+- Multiple approaches are valid
+- Decisions depend on context
+- Heuristics guide the approach
+
+**Example:**
+```markdown
+Analyze the data and choose the most appropriate visualization 
+based on data type and user needs.
+```
+
+### Medium Freedom (pseudocode or scripts with parameters)
+
+**Use when:**
+- A preferred pattern exists
+- Some variation is acceptable
+- Configuration affects behavior
+
+**Example:**
+```markdown
+Generate report using:
+1. Query data with provided filters
+2. Apply template from references/templates.md
+3. Format output as [PDF|HTML|Markdown] based on user preference
+```
+
+### Low Freedom (specific scripts, few parameters)
+
+**Use when:**
+- Operations are fragile and error-prone
+- Consistency is critical
+- A specific sequence must be followed
+
+**Example:**
+```markdown
+Execute exactly:
+1. Run `python scripts/validate.py input.json`
+2. Run `python scripts/transform.py --config config.yaml`
+3. Run `python scripts/output.py --format pdf`
+```
+
+### Mental Model
+
+Think of Claude as exploring a path:
+- **Narrow bridge with cliffs** → Specific guardrails (low freedom)
+- **Open field** → Many valid routes (high freedom)
+
+---
+
+## Principle 3: Progressive Disclosure
+
+Skills use a three-level loading system to manage context efficiently.
+
+### Level 1: Metadata (Always in Context)
+
+- **Content:** name + description (~100 words)
+- **Loaded:** Always, for all skills
+- **Purpose:** Determines when skill triggers
+
+### Level 2: SKILL.md Body (When Triggered)
+
+- **Content:** Instructions and guidance (<5k words, ideally <500 lines)
+- **Loaded:** Only after skill triggers
+- **Purpose:** Core workflow and navigation to resources
+
+### Level 3: Bundled Resources (As Needed)
+
+- **Content:** Scripts, references, assets (unlimited)
+- **Loaded:** When Claude determines they're needed
+- **Purpose:** Detailed information and executable code
+
+### Practical Guidelines
+
+| If SKILL.md is... | Action |
+|-------------------|--------|
+| Under 200 lines | Good, keep as is |
+| 200-500 lines | Consider splitting some content to references |
+| Over 500 lines | Must split into references |
+
+### Example: Progressive Structure
+
+**In SKILL.md (loaded when triggered):**
+```markdown
+## Quick Start
+Extract text with pdfplumber:
+[brief code example]
+
+## Advanced Features
+- Form filling: See [references/forms.md](references/forms.md)
+- API reference: See [references/api.md](references/api.md)
+```
+
+**In references/forms.md (loaded only when needed):**
+```markdown
+# Complete Form Filling Guide
+[Detailed multi-page documentation]
+```