/auto-skill

name: auto-skill
description: "Claude Skills meta-skill: extract domain material (docs/APIs/code/specs) into a reusable Skill (SKILL.md + references/scripts/assets), and refactor existing Skills for clarity, activation reliability, and quality gates."

Auto Skill

Turn scattered domain material into a Skill that is reusable, maintainable, and reliably activatable:

• `SKILL.md` as the entrypoint (triggers, constraints, patterns, examples)
• `references/` for long-form evidence and navigation
• optional `scripts/` and `assets/` for scaffolding and templates

When to Use This Skill

Trigger this meta-skill when you need to:

• Create a new Skill from scratch from docs/specs/repos
• Refactor an existing Skill (too long, unclear, inconsistent, misfires)
• Design reliable activation (frontmatter + triggers + boundaries)
• Extract a clean Quick Reference from large material
• Split long content into navigable `references/`
• Add a quality gate and a validator

Not For / Boundaries

This meta-skill is NOT:

• A domain Skill by itself (it builds domain Skills)
• A license to invent external facts (if the material does not prove it, say so and add a verification path)
• A substitute for required inputs (if inputs are missing, ask 1-3 questions before proceeding)

Quick Reference

Deliverables (What You Must Produce)

Your output MUST include: 1. A concrete directory layout (typically `skills/<skill-name>/`) 2. An actionable `SKILL.md` with decidable triggers, boundaries, and reproducible examples 3. Long-form docs moved to `references/` with a `references/index.md` 4. A pre-delivery checklist (Quality Gate)

Built-in Tool (Mandatory): Skill Seekers (Linked)

This meta-skill exposes the `tools/external/Skill_Seekers-development` submodule through a relative symlink so you can generate a first-draft Skill from:

• Documentation websites
• GitHub repositories
• PDFs

Bootstrap dependencies (once):

./skills/auto-skill/scripts/skill-seekers-bootstrap.sh

Run Skill Seekers (from linked source):

./skills/auto-skill/scripts/skill-seekers.sh -- --version
./skills/auto-skill/scripts/skill-seekers.sh -- scrape --config ./skills/auto-skill/scripts/Skill_Seekers-development/configs/react.json
./skills/auto-skill/scripts/skill-seekers.sh -- github --repo facebook/react --name react

Import the generated skill into this repo's canonical `skills/` tree:

./skills/auto-skill/scripts/skill-seekers-import.sh react
./skills/auto-skill/scripts/skill-seekers-import.sh react --force

Update the linked source by moving the `tools/external/Skill_Seekers-development` submodule pointer directly. The update helper is guarded to avoid overwriting the linked repository.

./skills/auto-skill/scripts/skill-seekers-update.sh --dry-run

Recommended Layout (Minimal -> Full)

skill-name/
|-- SKILL.md              # Required: entrypoint with YAML frontmatter
|-- references/           # Optional: long-form docs/evidence/index
|   `-- index.md          # Recommended: navigation index
|-- scripts/              # Optional: helpers/automation
`-- assets/               # Optional: templates/configs/static assets

The truly minimal version is just `SKILL.md` (you can add `references/` later).

YAML Frontmatter (Required)

---
name: skill-name
description: "What it does + when to use (activation triggers)."
---

Frontmatter rules:

• `name` MUST match `^[a-z][a-z0-9-]*$` and SHOULD match the directory name
• `description` MUST be decidable (not "helps with X") and include concrete trigger keywords

Minimal `SKILL.md` Skeleton (Copy/Paste)

---
name: my-skill
description: "[Domain] capability: includes [capability 1], [capability 2]. Use when [decidable triggers]."
---

# my-skill Skill

One sentence that states the boundary and the deliverable.

## When to Use This Skill

Trigger when any of these applies:
- [Trigger 1: concrete task/keyword]
- [Trigger 2]
- [Trigger 3]

## Not For / Boundaries

- What this skill will not do (prevents misfires and over-promising)
- Required inputs; ask 1-3 questions if missing

## Quick Reference

### Common Patterns

**Pattern 1:** one-line explanation
```text
[command/snippet you can paste and run]

Examples

Example 1

• Input:
• Steps:
• Expected output / acceptance:

Example 2

Example 3

References

• `references/index.md`: navigation
• `references/...`: long-form docs split by topic

Maintenance

• Sources: docs/repos/specs (do not invent)
• Last updated: YYYY-MM-DD
• Known limits: what is explicitly out of scope

### Authoring Rules (Non-negotiable)

1. Quick Reference is for short, directly usable patterns
   - Keep it <= 20 patterns when possible.
   - Anything that needs paragraphs of explanation goes to `references/`.
2. Activation must be decidable
   - Frontmatter `description` should say "what + when" with concrete keywords.
   - "When to Use" must list specific tasks/inputs/goals, not vague help text.
   - "Not For / Boundaries" is mandatory for reliability.
3. No bluffing on external details
   - If the material does not prove it, say so and include a verification path.

### Workflow (Material -> Skill)

Do not skip steps:
0. If your source material is a docs site / GitHub repo / PDF: generate a first draft with the linked Skill Seekers tool, then import into `skills/<skill-name>/`
1. Scope: write MUST/SHOULD/NEVER (three sentences total is fine)
2. Extract patterns: pick 10-20 high-frequency patterns (commands/snippets/flows)
3. Add examples: >= 3 end-to-end examples (input -> steps -> acceptance)
4. Define boundaries: what is out-of-scope + required inputs
5. Split references: move long text into `references/` + write `references/index.md`
6. Apply the gate: run the checklist and the validator

### Quality Gate (Pre-delivery Checklist)

Minimum checks (see `references/quality-checklist.md` for the full version):
1. `name` matches `^[a-z][a-z0-9-]*