docs(kyberforge): add agentskillsio, agentsmd research docs and skill-write examples

- Add agentskillsio/ reference docs (8 topic files, agentskills- prefix stripped)
- Add agentsmd/ reference docs (4 topic files)
- Add skill-write examples: skill-creator (Anthropic), writing-great-skills
  (mattpocock), writing-skills (obra/superpowers) with canonical sources.md files

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

plugins/kyberforge/docs/agentskillsio/specification.md

@@ -0,0 +1,124 @@
+---
+topic: agentskills-specification
+source_keys:
+  - agentskills-spec
+---
+
+## Frontmatter fields
+
+| Field           | Required | Constraints |
+|----------------|----------|-------------|
+| `name`         | Yes      | 1–64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. No consecutive hyphens (`--`). Must match the parent directory name. |
+| `description`  | Yes      | 1–1024 characters. Describes what the skill does and when to use it. |
+| `license`      | No       | License name or reference to a bundled license file. |
+| `compatibility`| No       | 1–500 characters. Environment requirements: intended product, required system packages, network access needs. Most skills don't need this. |
+| `metadata`     | No       | Arbitrary key-value map. Use for author, version, category, and any project extensions not defined by the spec. |
+| `allowed-tools`| No       | Space-separated string of pre-approved tools. Experimental — support varies by client. |
+
+## Minimal example
+
+```yaml
+---
+name: skill-name
+description: A description of what this skill does and when to use it.
+---
+```
+
+## Extended example
+
+```yaml
+---
+name: pdf-processing
+description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
+license: Apache-2.0
+metadata:
+  author: example-org
+  version: "1.0"
+  category: document
+allowed-tools: Bash(python3:*) Read Write
+---
+```
+
+## name field rules
+
+Valid: `pdf-processing`, `data-analysis`, `code-review`
+
+Invalid:
+- `PDF-Processing` — uppercase not allowed
+- `-pdf` — cannot start with hyphen
+- `pdf--processing` — consecutive hyphens not allowed
+
+The `name` value must exactly match the parent directory name. A skill at `.agents/skills/my-tool/SKILL.md` must have `name: my-tool`.
+
+## description field guidance
+
+The description carries the entire burden of triggering. Agents read only `name` and `description` at startup. Write it as a trigger — describe both what the skill does and when to use it.
+
+Good:
+```yaml
+description: >
+  Analyze CSV and tabular data files — compute summary statistics,
+  add derived columns, generate charts, and clean messy data. Use this
+  skill when the user has a CSV, TSV, or Excel file and wants to explore,
+  transform, or visualize the data, even if they don't explicitly mention
+  "CSV" or "analysis."
+```
+
+Poor:
+```yaml
+description: Helps with PDFs.
+```
+
+Hard limit: 1024 characters. Descriptions tend to grow during optimization — check length before committing.
+
+## Body content
+
+No format restrictions. Write whatever helps agents perform the task effectively.
+
+Recommended sections:
+- Step-by-step instructions
+- Examples of inputs and outputs
+- Common edge cases
+
+The agent loads the entire body once the skill is activated. Keep `SKILL.md` under 500 lines. Move detailed reference material to separate files in `references/` or similar directories.
+
+## Optional directories
+
+### `scripts/`
+
+Executable code agents can run. Scripts should be self-contained, include helpful error messages, and handle edge cases gracefully. See the scripts reference for design guidance.
+
+### `references/`
+
+Additional documentation agents can read when needed. Keep files focused — agents load them on demand, so smaller files mean less context use. Common files: `REFERENCE.md`, `FORMS.md`, domain-specific files (`finance.md`, `legal.md`).
+
+### `assets/`
+
+Static resources: templates, images, data files (lookup tables, schemas).
+
+## File references
+
+Use relative paths from the skill root when referencing other files:
+
+```markdown
+See [the reference guide](references/REFERENCE.md) for details.
+Run: scripts/extract.py
+```
+
+Keep references one level deep from `SKILL.md`. Avoid deeply nested reference chains.
+
+## Progressive disclosure levels
+
+1. **Metadata** (~100 tokens): `name` and `description` — loaded at startup for all skills
+2. **Instructions** (<5000 tokens recommended): full `SKILL.md` body — loaded on activation
+3. **Resources** (as needed): files in `scripts/`, `references/`, `assets/` — loaded only when required
+
+## Validation
+
+The `skills-ref` reference library validates `SKILL.md` frontmatter and naming conventions:
+
+```bash
+skills-ref validate ./my-skill
+```
+
+Source: `https://github.com/agentskills/agentskills/tree/main/skills-ref`