chore: migrate repository to standard knowledge base layout

2026-08-23 15:58:05 +00:00 · 2026-05-02 03:29:06 +08:00
parent 40a721c24d
commit 628a3bc832
565 changed files with 687 additions and 711 deletions
@@ -0,0 +1,111 @@
+# Skill Spec (This Repo)
+
+This document defines what a "production-grade Skill" means in this repository. Use it as the source of truth when creating or refactoring anything under `skills/`.
+
+Keywords: MUST / SHOULD / MAY / MUST NOT / SHOULD NOT are normative.
+
+## 1. Directory & Naming
+
+- A Skill MUST be a directory under `skills/` named after its `name` field.
+- The directory name MUST match `^[a-z][a-z0-9-]*$`.
+- The Skill entrypoint MUST be `SKILL.md` at the root of the skill directory.
+
+## 2. Frontmatter (Required)
+
+`SKILL.md` MUST start with YAML frontmatter:
+
+```yaml
+---
+name: skill-name
+description: "What it does + when to use (activation triggers)."
+---
+```
+
+Rules:
+- `name` MUST match `^[a-z][a-z0-9-]*$`.
+- `name` SHOULD equal the directory name.
+- `description` MUST be decidable and operational:
+  - Good: "X development and debugging. Use when doing A/B/C."
+  - Bad: "Helps with X."
+
+## 3. SKILL.md Structure
+
+### 3.1 Required Sections
+
+`SKILL.md` SHOULD follow this section order, and in strict mode it MUST:
+
+1. `## When to Use This Skill`
+2. `## Not For / Boundaries`
+3. `## Quick Reference`
+4. `## Examples`
+5. `## References`
+6. `## Maintenance`
+
+Rationale:
+- Activation reliability depends on explicit triggers and boundaries.
+- Usability depends on short patterns and reproducible examples.
+- Maintainability depends on sources and navigable references.
+
+### 3.2 Quick Reference Rules
+
+- Quick Reference MUST contain short, directly usable patterns.
+- Quick Reference MUST NOT become a documentation dump.
+- Long explanations SHOULD go to `references/`.
+- A good target is <= 20 patterns, but large domains may justify more.
+
+### 3.3 Example Rules
+
+- The Examples section MUST contain reproducible examples.
+- Each example SHOULD specify:
+  - input(s)
+  - steps
+  - expected output / acceptance criteria
+- Pseudo-code MAY be used only if the platform is unavailable, and MUST be clearly labeled.
+
+### 3.4 Boundaries Rules
+
+- "Not For / Boundaries" MUST list:
+  - explicit out-of-scope items (to prevent misfires)
+  - required inputs and what to ask when missing (1-3 questions)
+
+## 4. references/ (Long-form Docs)
+
+- `references/` SHOULD exist when the domain has:
+  - long docs
+  - many edge cases
+  - extensive APIs/CLIs/config surfaces
+- If `references/` exists, it SHOULD include:
+  - `references/index.md` as a navigation entrypoint
+
+Guideline:
+- `references/` is for evidence, depth, and navigation.
+- `SKILL.md` is for execution: short patterns + examples + constraints.
+
+## 5. scripts/ and assets/
+
+- `scripts/` MAY contain helper automation (generators, validators, setup).
+  - Scripts MUST be non-interactive by default.
+  - Scripts MUST NOT require network access unless explicitly stated.
+- `assets/` MAY contain templates, configs, or static resources.
+
+## 6. Safety & Integrity
+
+- Skills MUST NOT include secrets (API keys, tokens, credentials).
+- Skills MUST NOT invent external facts.
+  - If uncertain, they MUST include a verification path (where/how to check).
+- Potentially destructive commands MUST be explicitly labeled and gated.
+
+## 7. Maintenance Metadata
+
+Each Skill SHOULD include a `## Maintenance` section with:
+- sources (docs/repos/specs)
+- last-updated date
+- known limits / non-goals
+
+## 8. Quality Gate
+
+Before shipping, run the checklist in `quality-checklist.md` and (if available) the validator:
+
+```bash
+./skills/auto-skill/scripts/validate-skill.sh skills/<skill-name> --strict
+```