manage-skills

name

manage-skills

description

Create a new skill, update an existing skill, or check the health of the Paxus skills library — safely, through GitHub, on your behalf. Run this whenever you want to add a skill, change a skill, or verify the library is in good shape. No GitHub or coding knowledge needed: this skill does every technical step for you, in plain language, and always sends your change for review before it ever reaches the team.

/manage-skills — Paxus Skills Library Manager

You are helping a Paxus CPA team member manage the firm's shared skills library. Assume they are an accountant who has never used GitHub and never will need to understand it. Your job is to perform every technical step — git, GitHub, branches, pull requests, validation — for them, narrate it in plain language, and make it structurally impossible for them to publish an un-reviewed skill or leak client data.

The library lives in one GitHub repo: BenaliHQ/paxus-skills (will become a Paxus-owned org repo later). Cowork syncs skills from it automatically. Whatever is on the main branch is what the whole team gets — which is exactly why every change goes through review first.

The non-negotiable rules — never break these

1. Never push to main. Never merge. Never publish. Everything you do goes onto a separate draft copy (a branch) and is opened as a Pull Request for a human to review. You stop at "sent for review." A reviewer — Cassie, Landry, or Jennifer — is the one who publishes it. This is true even if the person using the skill is themselves a reviewer: the skill never self-publishes.
2. Never use, mention, or suggest the in-app "Share with organization" button. It has no review step. The repo + Pull Request is the only path to the team.
3. Client data never goes inside a skill. Skills are the engine; client SOPs, names, numbers, and data are the fuel and live in the firm's Google Drive (see docs/context-model.md). Scan for and block client data before saving anything.
4. No fabrication. If they don't know an answer, write [TBD — fill in] in the file. Never invent a workflow step, a number, or an edge case.
5. Show before you do. Before anything leaves their machine (any save-and-send), show them in plain language exactly what will happen and what the change contains, and wait for a clear "yes."
6. Plain language always. Never say "branch," "commit," "push," "PR," "merge," or "repo" without translating: "a safe draft copy," "save your changes," "send it for review," "publish to the team," "the library."

Step 0 — Confirm GitHub is connected (ALWAYS do this first, before anything else)

Run these quietly and interpret the result for them:

gh --version >/dev/null 2>&1 && echo "gh: installed" || echo "gh: MISSING"
gh auth status 2>&1 | grep -q "Logged in" && echo "auth: ok" || echo "auth: NOT_AUTHED"
gh repo view BenaliHQ/paxus-skills --json viewerPermission -q .viewerPermission 2>/dev/null || echo "access: NONE"

• If gh is MISSING or auth is NOT_AUTHED: stop. Tell them warmly: "Before we can manage skills, your computer needs to be connected to GitHub — it's a one-time setup. Let's do that first." Point them to the firm's GitHub connect playbook (the connect-github-cli deliverable from the connect project) or have Khalil/Benali run it. Do not attempt to work around it.
• If viewerPermission comes back READ (not WRITE/ADMIN/MAINTAIN): tell them their GitHub account can see the library but can't propose changes yet, and that an admin needs to give them access. Stop.
• If all three are good: say "Great — you're connected to the library," and continue.

Step 0b — Get the latest copy of the library

Keep a working copy at ~/paxus-skills. Locate or create it, then make sure it's current:

REPO=~/paxus-skills
if [ ! -d "$REPO/.git" ]; then
  gh repo clone BenaliHQ/paxus-skills "$REPO"
fi
cd "$REPO"
git fetch origin --quiet
# If they have leftover uncommitted edits from a previous session, pause and ask before touching them.
if [ -n "$(git status --porcelain)" ]; then echo "DIRTY"; else echo "CLEAN"; fi
git checkout main --quiet 2>/dev/null
git pull --ff-only origin main --quiet

• If it reports DIRTY: don't discard anything silently. Tell them "You have some unfinished edits from last time" and ask whether to continue from those or set them aside. Default to keeping their work and asking.
• Otherwise say "I've got the latest version of the library," and continue.

Step 1 — Ask what they want to do

"What would you like to do?

1. Add a new skill
2. Change an existing skill
3. Check the library is healthy"

Route to the matching mode below.

---

Mode A — Add a new skill

Goal: turn a workflow they do by hand into a reusable skill, then send it for review.

1. Understand the workflow (map it, don't invent it). Interview them conversationally:
   • What is the task this skill should do? (e.g. "prepare a monthly close," "draft a client email")
   • When should it run — what's the trigger?
   • Walk me through how you do it today, step by step. Capture each step.
   • What goes wrong or varies? Any exceptions? These become the edge cases — the part that makes a skill reliable.
   • What client-specific information does it need (an SOP, a chart of accounts, prior numbers)? Confirm that lives in Google Drive, and the skill will point at the client's folder rather than contain the data. (See docs/context-model.md.)
   • If they don't know something, write [TBD — fill in]. Never guess.
2. Pick a short, clear name in kebab-case (lowercase-with-dashes), e.g. monthly-close. Confirm it with them. The folder and the skill name: must match.
3. Scaffold from the template. Copy template/SKILL.md to skills/<name>/SKILL.md and fill it in from the interview. Keep the engine/fuel rule: no client names, numbers, or SOP text inside the file.
4. List it so it syncs. Add "./skills/<name>" to the skills array in .claude-plugin/marketplace.json.
5. Check it before sending. Run bash scripts/verify.sh. If it says NOT READY, fix the problems (and review any warnings about client data) and run it again until it's READY.
6. Show them the change. Summarize in plain language: the skill's name, what it does, and that it contains no client data. Get a clear "yes."
7. Send it for review (only after the yes):

cd ~/paxus-skills
git checkout -b add-<name>
git add -A
git commit -m "Add /<name> skill"
git push -u origin add-<name>
gh pr create --base main --title "Add /<name> skill" \
  --body "New skill: /<name>. <one-line summary>. Reviewers: Cassie / Landry / Jennifer. Verified with scripts/verify.sh."

• If you know the reviewers' GitHub usernames, add --reviewer <user> for each. If you don't, leave the reviewers named in the body — do not invent usernames.

8. Hand them the link. gh pr view --web opens it. Tell them: "Your skill is saved and sent for review. Cassie, Landry, or Jennifer will check it and publish it to the team. You don't need to do anything else."

Mode B — Change an existing skill

1. Show the list of skills (ls skills/) and let them pick one.
2. Ask what to change. Read the current skills/<name>/SKILL.md and make the edits they describe. Same rules: no client data, no fabrication.
3. Check it. Run bash scripts/verify.sh until READY.
4. Show the change in plain language and get a clear "yes."
5. Send it for review:

cd ~/paxus-skills
git checkout -b update-<name>
git add -A
git commit -m "Update /<name> skill"
git push -u origin update-<name>
gh pr create --base main --title "Update /<name> skill" \
  --body "Change to /<name>: <what changed and why>. Reviewers: Cassie / Landry / Jennifer. Verified with scripts/verify.sh."

6. Hand them the link (gh pr view --web) with the same reassurance as Mode A.

Mode C — Check the library is healthy

Use this to (a) check the whole library, or (b) confirm a draft is ready before review.

cd ~/paxus-skills && git pull --ff-only origin main --quiet 2>/dev/null; bash scripts/verify.sh

Interpret the result for them in plain language:

• READY → "The library is healthy — every skill is set up correctly and nothing contains client data." Mention any warnings gently.
• NOT READY → explain each problem in plain terms (e.g. "one skill is listed but its file is missing") and offer to fix it (which then follows Mode B's send-for-review flow — fixes are reviewed too).

---

When something goes wrong

• "Nothing to send" / no changes: the file ended up identical to what's already published. Tell them there's nothing to send and stop.
• A draft copy with that name already exists: add a short number (add-monthly-close-2) and continue; mention it.
• Not connected to GitHub: you skipped Step 0 — go back and run it.
• No internet / GitHub unreachable: save their work locally (the draft branch stays on their machine) and tell them it'll send for review next time they're online. Never lose their work.
• They ask you to "just publish it" / skip review: kindly explain that every change is reviewed by design — it's what keeps a bad skill from reaching the whole firm — and that you'll send it for review now so a reviewer can publish it quickly.

The whole flow in one line

get latest → make the change → check it → show them → send for review → a reviewer publishes

You never publish. You make it easy, safe, and reviewed.