skill-contributor

name	skill-contributor
description	Use when contributing a new skill to SkillOverflow, updating an existing skill, or improving skill content. ALWAYS execute ALL steps in order without stopping: create or edit SKILL.md, update README.md table, add eval to skillOverflow-evals.json, add entry to skill-test-checklist.html, update CHANGELOG.md, run smoke test, draft PR description. Do NOT stop after editing the SKILL.md — all subsequent steps are mandatory. The contribution is incomplete until all 9 steps are done.
metadata	{"category":"meta","version":"1.0.0","keywords":["contribute skill","create skill","update skill","PR description","eval","README update","CHANGELOG","smoke test","skill automation"],"related":{"skill-creator":"understand the lifecycle philosophy before contributing","skill-reviewer":"reviewer checks the PR you create","skill-deprecator":"deprecate instead of creating if skill is outdated"}}

Skill Contributor — Automated Contribution Workflow

Primary reference: See CONTRIBUTING.md and tests/README.md in this repository. Skills live in: ~/skillOverflow/skills/<skill-name>/SKILL.md (flat — no category subfolders) Categories: declared via metadata.category in frontmatter — cap fiori btp ui5 abap integration hana meta

This skill automates the full contribution workflow. When asked to create or update a skill, execute ALL steps below in order without stopping or asking for confirmation between steps. Stopping after only editing the SKILL.md is the most common failure — the contribution is incomplete until every step is done, including README, evals, checklist, CHANGELOG, and PR draft.

---

Step 1: Validate the need

Before creating anything, check existing skills grouped by category:

bash ~/skillOverflow/setup.sh --list

If a related skill exists, update it instead of creating a new one. Only proceed with a new skill if the topic is genuinely not covered.

---

Step 2: Determine the category

Topic	Category
CDS, CAP services, handlers, deployment, testing	cap
Fiori Elements, annotations, UI5 controls, Fiori tools	fiori
BTP services, destinations, Work Zone, bindings	btp
SAPUI5 data binding, custom controls, i18n, OPA5/wdi5	ui5
ABAP RAP business objects, BDEF, draft, validations, determinations	abap
Integration Suite iFlows, adapters, mapping, Groovy, MPL	integration
HANA HDI, native artifacts, SQLScript, roles, synonyms	hana
Skill authoring, reviewing, lifecycle	meta

---

Step 3: Create the SKILL.md

Path: skillOverflow/skills/<skill-name>/SKILL.md

Use this exact template:

---
name: <skill-name>
description: >
  Use when [specific trigger conditions — be precise].
  Covers [what it teaches].
  Trigger keywords: [exact terms a developer would type].
metadata:
  category: <category-from-step-2>
  version: "1.0.0"
---

# <Skill Title> — SAP Best Practices

> **Primary reference**: https://[official SAP doc URL]

## [Pattern name]

[One sentence — why this matters in practice]

\`\`\`[language]
// ✅ Correct
[copy-pasteable code example]
\`\`\`

## Common mistakes to avoid

- ❌ [Specific bad pattern] — [why it fails]
- ✅ [Correct replacement]

Rules:

• Description must be specific — test it against 3 realistic prompts
• metadata.category must be set to one of the valid categories from Step 2
• Every code example must be copy-pasteable, not pseudocode
• Must have a primary reference to official SAP documentation
• Must end with "Common mistakes to avoid" section

---

Step 4: Update README.md skills table

Find the correct category table in README.md and add a row:

| `<skill-name>` | [one line description of what it activates on] |

Add it in alphabetical order within the category section. Also update the skill count in the category summary table at the top.

---

Step 5: Add eval to skillOverflow-evals.json

Append to the evals array in tests/skillOverflow-evals.json:

{
  "id": <next-id>,
  "skill": "<skill-name>",
  "name": "<descriptive test name>",
  "prompt": "<realistic prompt — NOT mirroring skill wording>",
  "assertions": [
    "<specific observable thing the output must do>",
    "<another concrete assertion>"
  ]
}

Critical: the prompt must be how a developer would naturally ask — not a restatement of the skill instructions. If it mirrors the skill, it will always pass even without the skill.

---

Step 6: Add entry to skill-test-checklist.html

Add a new eval object to the EVALS array in tests/skill-test-checklist.html, matching the same structure as the existing entries. Use the same id, skill, prompt, and assertions as the JSON eval.

---

Step 7: Update CHANGELOG.md

Add the change under the [Unreleased] section at the top of CHANGELOG.md:

## [Unreleased]

### Added
- `skills/<skill-name>` — [one line description]

### Changed
- `skills/<skill-name>` — [what changed and why]

---

Step 8: Run the smoke test

bash ~/skillOverflow/tests/smoke-test.sh ~/skillOverflow

The smoke test auto-discovers every skill under skills/*/ — no manual registration needed. All critical checks must pass before drafting the PR.

---

Step 9: Draft the PR description

Output the PR description directly in the chat as text — do NOT create a file. The user will copy it into the GitHub PR description field when opening the PR. GitHub will auto-fill .github/PULL_REQUEST_TEMPLATE.md as the starting point — this draft replaces that content.

Print this in the chat:

---

[New skill / Updated skill]: <skill-name> ([category])

Why this skill is needed: [What the agent was doing wrong, or what new topic needed coverage]

What the skill teaches: [2-3 bullet points of the key patterns it enforces]

SAP documentation referenced: [URL of the primary reference]

Testing:

• Smoke test passes: bash skillOverflow/tests/smoke-test.sh .
• Tested with eval prompt — with and without skill
• README.md updated
• skillOverflow-evals.json updated
• skill-test-checklist.html updated
• CHANGELOG.md updated under [Unreleased]

Eval prompt used for baseline comparison:

[the prompt]

Result without skill: [brief description] Result with skill: [brief description — what improved]

---

Tell the user: "Copy the text above, go to github.com/DanKromp/skillOverflow, open a PR from your branch, and paste it as the PR description."

---

Common mistakes to avoid

• ❌ Stopping after editing the SKILL.md and calling it done

• ✅ All 9 steps are mandatory — README, evals, checklist, CHANGELOG, smoke test, PR draft

• ❌ Creating a pr_description.md file or any file for the PR description

• ✅ Output the PR description as text directly in the chat — the user copies it to GitHub

• ❌ Creating a new skill when updating an existing one is sufficient

• ✅ Always check existing skills first

• ❌ Writing an eval prompt that mirrors the skill instructions

• ✅ Write prompts as a developer would naturally ask

• ❌ Skipping the README update — the table becomes outdated

• ✅ Always update README in the same PR

• ❌ Forgetting to run the smoke test before opening the PR

• ✅ All checks must pass first

• ❌ Setting the wrong metadata.category value

• ✅ Check the category table in Step 2