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/skill-authoring.md

@@ -0,0 +1,169 @@
+---
+topic: agentskills-skill-authoring
+source_keys:
+  - agentskills-best-practices
+---
+
+## Start from real expertise
+
+A common pitfall: asking an LLM to generate a skill without domain-specific context. The result is vague, generic procedures rather than the specific API patterns, edge cases, and project conventions that make a skill valuable.
+
+**Extract from a hands-on task.** Complete a real task in conversation with an agent, providing corrections and preferences along the way. Then extract the reusable pattern. Capture:
+- Steps that worked — the sequence that led to success
+- Corrections you made — "use library X not Y," "check for edge case Z"
+- Input/output formats — what data looked like going in and out
+- Context you provided — project-specific facts the agent didn't know
+
+**Synthesize from existing artifacts.** Feed project-specific material into an LLM and ask it to synthesize a skill. Good sources: internal runbooks, API specs, code review comments, version control history (especially patches — reveals patterns through what actually changed), real-world failure cases.
+
+## Refine with real execution
+
+Run the skill against real tasks. Feed results — all of them, not just failures — back into the creation process. Even a single execute-then-revise pass noticeably improves quality.
+
+Read agent execution traces, not just final outputs. Common causes of wasted work in traces:
+- Instructions too vague — agent tries multiple approaches
+- Instructions that don't apply to the current task — agent follows them anyway
+- Too many options without a clear default
+
+## Spending context wisely
+
+Once a skill activates, its full `SKILL.md` body loads alongside conversation history, system context, and other active skills. Every token competes for the agent's attention.
+
+**Add what the agent lacks, omit what it knows.** Focus on project-specific conventions, domain-specific procedures, non-obvious edge cases, and the particular tools to use. Don't explain what a PDF is or how HTTP works.
+
+```markdown
+<!-- Too verbose — the agent already knows what PDFs are -->
+PDF files contain text and images. To extract text, use pdfplumber...
+
+<!-- Better — jumps to what the agent wouldn't know on its own -->
+Use pdfplumber for text extraction. For scanned documents, fall back to
+pdf2image with pytesseract.
+```
+
+Ask about each piece of content: "Would the agent get this wrong without this instruction?" If no, cut it.
+
+**Design coherent units.** Skills scoped too narrowly force multiple skills to load for one task; skills scoped too broadly are hard to activate precisely. A skill for querying a database and formatting results is one coherent unit; a skill that also covers database administration is probably too broad.
+
+**Aim for moderate detail.** Overly comprehensive skills hurt — the agent struggles to extract what's relevant and may pursue unproductive paths. Concise, stepwise guidance with a working example outperforms exhaustive documentation.
+
+## Calibrating control
+
+**Give the agent freedom** when multiple approaches are valid. Explaining *why* is more effective than rigid directives — agents make better decisions when they understand the purpose.
+
+**Be prescriptive** when operations are fragile, consistency matters, or a specific sequence must be followed:
+
+```markdown
+## Database migration
+
+Run exactly this sequence:
+
+```bash
+python scripts/migrate.py --verify --backup
+```
+
+Do not modify the command or add additional flags.
+```
+
+**Provide defaults, not menus.** When multiple tools could work, pick one and mention alternatives briefly:
+
+```markdown
+<!-- Too many options -->
+You can use pypdf, pdfplumber, PyMuPDF, or pdf2image...
+
+<!-- Clear default with escape hatch -->
+Use pdfplumber for text extraction. For scanned PDFs requiring OCR,
+use pdf2image with pytesseract instead.
+```
+
+**Favor procedures over declarations.** Teach the agent *how to approach* a class of problems, not *what to produce* for a specific instance. The approach should generalize even when individual details are specific.
+
+## Effective instruction patterns
+
+### Gotchas sections
+
+The highest-value content in many skills is a list of gotchas — environment-specific facts that defy reasonable assumptions:
+
+```markdown
+## Gotchas
+
+- The `users` table uses soft deletes. Queries must include
+  `WHERE deleted_at IS NULL` or results will include deactivated accounts.
+- The user ID is `user_id` in the database, `uid` in the auth service,
+  and `accountId` in the billing API. All three refer to the same value.
+- The `/health` endpoint returns 200 even if the database is down.
+  Use `/ready` to check full service health.
+```
+
+Keep gotchas in `SKILL.md` where the agent reads them before encountering the situation. When an agent makes a mistake you correct, add the correction to the gotchas section.
+
+### Templates for output format
+
+Provide a template when the agent must produce a specific output format. Short templates live inline; longer ones go in `assets/` and are referenced conditionally.
+
+```markdown
+## Report structure
+
+Use this template:
+
+\`\`\`markdown
+# [Analysis Title]
+
+## Executive summary
+[One-paragraph overview]
+
+## Key findings
+- Finding 1 with supporting data
+
+## Recommendations
+1. Specific actionable recommendation
+\`\`\`
+```
+
+### Checklists for multi-step workflows
+
+```markdown
+## Workflow
+
+Progress:
+- [ ] Step 1: Analyze the form (run `scripts/analyze_form.py`)
+- [ ] Step 2: Create field mapping (edit `fields.json`)
+- [ ] Step 3: Validate mapping (run `scripts/validate_fields.py`)
+- [ ] Step 4: Fill the form (run `scripts/fill_form.py`)
+```
+
+### Validation loops
+
+```markdown
+## Editing workflow
+
+1. Make your edits
+2. Run validation: `python scripts/validate.py output/`
+3. If validation fails, fix and re-run
+4. Only proceed when validation passes
+```
+
+### Plan-validate-execute
+
+For batch or destructive operations: create an intermediate plan in a structured format, validate it against a source of truth, then execute:
+
+```markdown
+1. Extract form fields → `form_fields.json`
+2. Create `field_values.json` mapping each field to its intended value
+3. Validate: `python scripts/validate_fields.py form_fields.json field_values.json`
+4. If validation fails, revise and re-validate
+5. Fill the form: `python scripts/fill_form.py input.pdf field_values.json output.pdf`
+```
+
+### Bundling reusable scripts
+
+If execution traces show the agent independently reinventing the same logic across runs — building charts, parsing a format, validating output — write a tested script once and bundle it in `scripts/`. See the scripts reference.
+
+## Structure large skills with progressive disclosure
+
+Keep `SKILL.md` under 500 lines and 5,000 tokens — the core instructions the agent needs every run. When a skill needs more content, move detail to `references/` and tell the agent *when* to load each file:
+
+```markdown
+If the API returns a non-200 status code, read `references/api-errors.md`.
+```
+
+"Read `references/api-errors.md` if X" is more useful than a generic "see references/ for details." The agent loads context on demand rather than up front.