skill-contributor

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