add-skill— agent skill

Structure

Skills — flat

• skills/<topic>/SKILL.md — thin wrapper: frontmatter + pointer(s) to knowledge file(s)
• One skill per topic, kebab-case: skills/vercel-ai-gateway/, skills/dexie/, skills/learn/

Knowledge — namespaced, shareable

• knowledge/<category>/<slug>.md — the actual content
• A knowledge file can be referenced by multiple skills

e.g. knowledge/rag/concepts.md read by both skills/rag/SKILL.md and skills/pinecone/SKILL.md

• A single session can produce multiple skills that share knowledge files — plan all files together before drafting

Steps

1. Read the prompt — if arguments were passed with the slash command (e.g. /add-skill I want to save the Stripe webhook pattern from this project), treat them as the user's description of what to add and proceed to step 1. If no arguments were given, ask: "What skill or knowledge do you want to add?" and wait for the answer before continuing.

1. Check existing knowledge — pull latest and scan all files in skills/ and knowledge/:

   gh repo clone phucbm/skills /tmp/phucbm-skills 2>/dev/null || git -C /tmp/phucbm-skills pull
   find /tmp/phucbm-skills/skills /tmp/phucbm-skills/knowledge -name "*.md" | sort

If a related entry exists, tell the user before proceeding:

"I found a related entry: knowledge/groq/streaming-integration.md — update that instead, or add a new file?"

1. Determine paths:

• Skill: skills/<topic>/SKILL.md — flat, one level only
• Knowledge: knowledge/<category>/<slug>.md — can be nested, shareable
• If adding related skills (e.g. rag + pinecone), plan all files together and note cross-references before drafting
• Use lowercase kebab-case. Ask if unclear.

1. Draft all files and show them to the user:

• SKILL.md: correct frontmatter (name, description, when_to_use, allowed-tools) + instructions to read knowledge file(s) using the ref format below
• knowledge/<category>/<slug>.md: full content — env vars, code patterns, gotchas, source reference. Generic patterns only; cite specific projects as examples, never hardcode project-specific data.

1. Wait for confirmation before writing anything.

1. Write all files, update README.md (add row to knowledge table for each new knowledge file, add row to skills table for each new skill), bump patch version in .claude-plugin/plugin.json, commit and push:

   git -C /tmp/phucbm-skills add .
   git -C /tmp/phucbm-skills commit -m "skill: add <topic>"
   git -C /tmp/phucbm-skills push

1. Confirm the push URL to the user.

Rules

• Follow Anthropic's official skill writing best practices:

https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md Key points: description is the primary trigger mechanism — be specific and slightly pushy to avoid undertriggering; keep SKILL.md under 500 lines; use bundled resources for large content.

• Never include real API keys or secrets — keep env blocks with empty values as templates
• Always show all files and wait for confirmation before pushing
• SKILL.md stays thin — frontmatter + a few lines, content belongs in knowledge/
• Always reference knowledge files as clickable markdown links using this format:
• Single ref (inline): Read [\@/knowledge/<category>/<slug>.md\](/knowledge/<category>/<slug>.md) and apply...
• Multiple refs (list):

    Read and apply:
    - [@/knowledge/<category>/<slug>.md](/knowledge/<category>/<slug>.md)
    - [@/knowledge/<category>/<slug>.md](/knowledge/<category>/<slug>.md)

• When a skill references shared knowledge, note it explicitly in the SKILL.md
• Knowledge files are generic — mention specific projects only as examples, never hardcode project-specific data