# Skill Manager v2.1 Upgrade Proposal

> Streamline skill creation, improve cross-platform support, and add research automation.

## Summary

This proposal addresses friction points discovered during skill creation:
1. Over-application of portability rules
2. Heavy template for simple skills
3. PowerShell-only tooling
4. Manual research for documentation-heavy skills
5. Redundant trigger syntax in descriptions

## Proposed Changes

### 1. Scoped Portability (SK011)

**Problem:** SK011 warns about hardcoded `references/` paths for all skills, but most skills don't need portability.

**Solution:** Add optional `portable: true` frontmatter field. Only enforce SK011 when set.

```yaml
---
name: skill-manager
portable: true  # This skill is used across projects
---
```

**Linter change:**
- SK011 becomes INFO level by default
- Elevated to WARN only when `portable: true` is set

---

### 2. Optional Template Sections

**Problem:** Template includes sections that don't apply to simple skills.

**Solution:** Mark optional sections in template with guidance comments.

```markdown
## Capabilities

1. **{Capability 1}** — {Brief description}

## Routing Logic
<!-- OPTIONAL: Include for multi-topic skills with reference files -->

| Request type | Load reference |
|--------------|----------------|

## Core Principles
<!-- OPTIONAL: Include for skills with non-obvious patterns -->

## Quick Reference
<!-- OPTIONAL: Include for skills with common commands/syntax -->

## Workflow
<!-- OPTIONAL: Include for multi-step processes -->

## Checklist
<!-- OPTIONAL: Include for skills with verification steps -->

## Environment Compatibility
<!-- OPTIONAL: Include only when using advanced frontmatter features -->

## When to Escalate
<!-- OPTIONAL: Include for skills involving judgment calls -->
```

**Minimum required sections:**
- Frontmatter (name, description, version)
- H1 title + one-line description
- Capabilities (at least one)

---

### 3. Triggers as Frontmatter

**Problem:** Triggers embedded in description are verbose and hard to parse.

**Current:**
```yaml
description: >
  Build reactive backends with Convex. Use when building real-time apps.
  Triggers: convex, reactive database, vector search.
```

**Proposed:**
```yaml
description: >
  Build reactive backends with Convex. Use when building real-time apps.
triggers:
  - convex
  - reactive database
  - vector search
  - convex auth
```

**Benefits:**
- Machine-parseable for routing
- Cleaner descriptions
- Easier to update
- Can be used for autocomplete/search

**Linter change:**
- SK006 checks for `triggers:` array OR inline "Triggers:" (backwards compatible)
- New SK017 INFO: Suggest migrating inline triggers to frontmatter

---

### 4. Cross-Platform Tooling

**Problem:** `skill-lint.ps1` requires PowerShell, limiting accessibility.

**Proposed:** Replace PowerShell with Node.js implementation.

```
skill-manager/
├── scripts/
│   └── skill-lint.mjs      # Cross-platform (replaces .ps1)
└── package.json            # npm scripts
```

**Usage:**
```bash
# Direct invocation
node scripts/skill-lint.mjs ../convex

# Via npm
npm run lint -- --path ../convex

# Later: via lush CLI
lush skill lint ../convex
```

**Implementation notes:**
- No external dependencies (uses built-in fs, path, readline)
- Same rule IDs and output format as current PowerShell version
- JSON output mode for CI integration (`--format json`)
- Deprecate and remove `skill-lint.ps1`

**Why not keep both?**
- Single codebase to maintain (no divergence risk)
- Node.js works on Windows, Mac, Linux
- Node.js already required in most dev workflows
- Easier to integrate into `lush` CLI later

---

### 5. Research Automation for Documentation Skills

**Problem:** Creating skills from external documentation (Convex, Stripe, etc.) requires significant manual research and synthesis.

**Proposed:** Add `skill-research` command that accelerates skill creation.

#### Workflow

```bash
# Step 1: Research and draft
lush skill research --url https://docs.convex.dev --name convex

# Outputs:
# - Fetches key pages from documentation
# - Extracts concepts, patterns, code examples
# - Generates draft SKILL.md with:
#   - Suggested capabilities
#   - Suggested triggers
#   - Core concepts extracted
#   - Code snippets
# - Generates draft reference file stubs
```

#### Implementation

```python
# src/lushbot/commands/skill_research.py

@click.command()
@click.option("--url", required=True, help="Documentation root URL")
@click.option("--name", required=True, help="Skill name")
@click.option("--focus", multiple=True, help="Focus areas (e.g., 'newer features')")
@click.option("--output", default=".claude/skills", help="Output directory")
def skill_research(url, name, focus, output):
    """Research documentation and draft a skill."""

    # 1. Crawl documentation (respect robots.txt)
    pages = crawl_docs(url, max_pages=50)

    # 2. Extract structured content
    content = extract_content(pages)

    # 3. Generate skill draft via LLM
    draft = generate_skill_draft(
        content=content,
        name=name,
        focus_areas=focus,
        template=load_template()
    )

    # 4. Write files
    write_skill(output / name, draft)

    # 5. Run linter
    lint_skill(output / name)
```

#### Research Modes

| Mode | Description | Use Case |
|------|-------------|----------|
| `--mode quick` | Top 10 pages, basic structure | Familiar technology |
| `--mode standard` | 30-50 pages, full references | New skill |
| `--mode thorough` | Deep crawl, changelogs, blog | Finding newer features |

#### Focus Flags

```bash
# Focus on recent changes (helpful for training data gaps)
lush skill research --url https://docs.convex.dev \
  --name convex \
  --focus "features released 2024-2025" \
  --focus "breaking changes" \
  --focus "best practices"
```

#### Output Structure

```
.claude/skills/convex/
├── SKILL.md              # Draft, needs review
├── references/
│   ├── functions.md      # Drafted
│   ├── database.md       # Drafted
│   └── ...
└── .research/
    ├── sources.json      # URLs used
    ├── raw_content.md    # Extracted text
    └── generation.log    # LLM prompts/responses
```

The `.research/` folder provides transparency and allows manual refinement.

---

## Migration Path

### Phase 1: Non-breaking (v2.1.0)
- Add `triggers:` frontmatter support (both styles work)
- Add `portable:` frontmatter field
- Mark template sections as optional
- SK011 becomes INFO by default

### Phase 2: Tooling (v2.2.0)
- Replace PowerShell linter with Node.js implementation
- Add `lush skill lint` command
- Add `lush skill research` command (experimental)
- Remove `skill-lint.ps1`

### Phase 3: Deprecation (v3.0.0)
- Deprecate inline "Triggers:" in description
- SK006 requires `triggers:` array

---

## Updated Template Preview

```markdown
---
name: {skill-name}
description: >
  {What this skill does}. {What content it covers}.
  Use when {scenarios}.
version: "1.0.0"
triggers:
  - {keyword1}
  - {keyword2}
  - {keyword3}
# portable: true  # Uncomment if skill is used across projects
---

# {Skill Title}

{One-line description of the skill's purpose.}

## Capabilities

1. **{Capability 1}** — {Brief description}
2. **{Capability 2}** — {Brief description}

<!-- OPTIONAL SECTIONS BELOW - delete if not applicable -->

## Routing Logic
<!-- Include for multi-topic skills with reference files -->

| Request type | Load reference |
|--------------|----------------|
| {Topic 1} | [references/{path}.md](references/{path}.md) |

## Core Principles
<!-- Include for skills with non-obvious patterns or philosophy -->

### 1. {Principle Name}

{Description of the principle and why it matters.}

## Quick Reference
<!-- Include for skills with common commands, syntax, or patterns -->

```{language}
// Example code or commands
```

## Workflow
<!-- Include for multi-step processes -->

1. **{Step 1}**: {What to do}
2. **{Step 2}**: {What to do}

## Checklist
<!-- Include for skills with verification steps -->

- [ ] {Check item 1}
- [ ] {Check item 2}

## When to Escalate
<!-- Include for skills involving judgment calls or edge cases -->

- {Situation requiring human review}
```

---

## Questions for Review

1. **Triggers format:** Array vs comma-separated string in frontmatter?
   ```yaml
   # Option A: Array
   triggers:
     - convex
     - vector search

   # Option B: String
   triggers: convex, vector search, convex auth
   ```

2. **Research command location:** Part of `lush` CLI or standalone `skill-research` script?

3. **Backwards compatibility:** How long to support inline "Triggers:" syntax?

---

## Acceptance Criteria

- [ ] `portable: true` field documented and linter updated
- [ ] Template sections marked as optional with guidance
- [ ] `triggers:` frontmatter field supported by linter
- [ ] Node.js linter replaces PowerShell version (same rules, cross-platform)
- [ ] `lush skill lint` command added to CLI
- [ ] `lush skill research` generates usable drafts (experimental flag OK)
- [ ] Migration guide for existing skills
- [ ] PowerShell linter deprecated and removed
