fss-link 1.9.1 → 1.9.3

package/README.md

@@ -33,6 +33,16 @@ npm run bundle
 sudo npm install -g .
 ```
 
+### First run — bootstrap the database
+
+The database (`~/.fss-link/fss-link.db`) is created on the **first command that needs it**, not during `npm install`. If `fss-link` fails with "Database directory not found" or "Cannot save database", run:
+
+```bash
+fss-link --version
+```
+
+This is the quickest way to bootstrap everything — it creates the directory, initialises the schema, and inserts default model configs. After that, `fss-link` (interactive) and `fss-link -p "..."` will work normally.
+
 ## Usage
 
 ```bash

package/bundle/edit-link-skill/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: edit-link-skill
+description: >
+  Skills folder management guide — conventions, validation, authoring,
+  and the /skills slash command. Use when creating, editing, or managing
+  FSS Link skills.
+category: reference
+triggers: [skill management, skill authoring, skills folder, skill validation]
+version: 1
+---
+
+# Skills Folder — Management Guide
+
+**Use when:** Creating, editing, or managing FSS Link skills.
+
+## Directory Structure (New Format)
+
+```
+skill-name/
+├── SKILL.md              ← Entry point (~100-150 lines: decision table, core commands, safety, index)
+└── references/
+    ├── capabilities.md   ← Full command catalogue, flags, options, return formats
+    ├── workflows.md      ← Step-by-step procedures, common patterns, examples
+    └── troubleshooting.md ← Edge cases, known bugs, anti-patterns (if applicable)
+└── scripts/              ← Scripts referenced by the skill (if any)
+```
+
+The loader scans subdirectories for `SKILL.md` files. Flat `.md` files at the top level are **ignored** (old format, migration leftovers).
+
+## File Contract
+
+### Directory Name
+- Lowercase, hyphen-separated
+- The directory name **must equal** the `name` field in frontmatter
+- Example: `image-draw/` → `name: image-draw`
+
+### SKILL.md Frontmatter (YAML, required)
+
+```yaml
+---
+name: skill-name           # required, must match directory name
+description: One-line summary surfaced in the discovery list
+category: tooling            # required: tooling | workflow | reference | persona
+triggers: [keyword, hint]    # optional, string array
+external_cli: fss-img-gen    # optional, names the CLI this documents
+version: 1                   # optional, integer or semver string
+---
+```
+
+**Only those six fields are read by the loader.** Anything else is ignored.
+
+### Categories
+
+| Category | Use when | Examples |
+|----------|----------|----------|
+| `tooling` | External CLI or library — commands, flags, examples | `fss-parse-pdf`, `image-draw`, `chatterbox` |
+| `workflow` | Repeatable multi-step procedure or methodology | `deep-context-extraction`, `covert-ops` |
+| `reference` | Format, protocol, or data reference the agent looks up | `pdf-navigation-protocol`, `math-instruction` |
+| `persona` | Behavioural instructions for sub-agents or role contracts | `sub-agent`, `project-structure-specialist` |
+
+## /skills Slash Commands
+
+| Command | Effect |
+|---------|--------|
+| `/skills` or `/skills list` | Grouped listing of currently loaded skills |
+| `/skills reload` | Re-scan this directory and rebuild the registry |
+| `/skills show <name>` | Preview a skill locally without spending model context |
+| `/skills lint` | Show the load report — rejections with reasons, collisions |
+
+## Adding a New Skill
+
+1. Create the directory: `mkdir -p skill-name/references`
+2. Write `SKILL.md` with required frontmatter. Directory name must match `name`
+3. Write `references/capabilities.md` (full command catalogue, flags, options)
+4. Write `references/workflows.md` (step-by-step procedures) — only if the skill has multi-step procedures
+5. Write `references/troubleshooting.md` (edge cases, bugs) — only if applicable
+6. Write `scripts/` files (if the skill references scripts)
+7. Run `/skills reload`, then `/skills show <name>` to verify
+8. Optionally `/skills lint` to confirm zero rejections
+
+## Validation Rules (Rejection Reasons)
+
+The loader rejects any `SKILL.md` that:
+- Has no YAML frontmatter block
+- Has unparseable YAML
+- Is missing `name`, `description`, or `category`
+- Has a `category` outside the allowed set
+- Has `name` that does not match the directory name
+- Has `name` that collides with a built-in tool doc
+- Has `triggers` that is not an array of strings
+- Has `external_cli` that is not a string
+- Has `version` that is neither an integer nor a string
+- Is a duplicate of an already-loaded skill name (first-seen alphabetical wins)
+
+## Organisation Rules
+
+- **Subdirectories only.** The loader scans `*.md` at the top level — flat files are ignored.
+- **No `.md.backup` files.** They will be parsed and rejected as noise.
+- **Split, don't bloat.** If an ability grows past ~500 lines, split into focused siblings.
+- **Line targets:** SKILL.md ~100-150 lines, each reference file max 200 lines.
+
+## Pre-commit Checklist
+
+- [ ] Directory name equals `name` in frontmatter
+- [ ] `category` is one of `tooling | workflow | reference | persona`
+- [ ] `description` is a single useful line
+- [ ] No fictional frontmatter fields
+- [ ] CLI examples are real and runnable
+- [ ] No secrets in the body
+- [ ] `/skills reload` followed by `/skills lint` shows no rejections
+
+## Global Flags
+
+N/A — this is a workflow skill, not a CLI tool.
+
+---
+
+*This skill is part of the FSS Parsers collection.*
+
+**References:**
+- Full authoring guidance → `references/capabilities.md`