meta/skills/skill-new/SKILL.md

name, description

name

description

skill-new

Create a new skill in the jsc skill set. Ask skill details via decision tree, generate the skill under the right jsc-{domain} per guidelines.md (create the domain from the template repo if missing), open a PR via jsc-git pr, then deploy the skill into the current session, verify it runs, and append the change report to wiki SKILLSET_{HASH}. Use when the user wants to add a skill; not for editing an existing one (use skill-update).

skill-new — create a skill

Single source of guidelines: ../../references/guidelines.md.

Flow

1. Ask for skill details via the jsc-ask:ask decision tree until no doubt remains:

   • Goal (single and not duplicating an existing skill; run tools/list-skills.sh first and show the similar skills for comparison — options must state the impact scope of "reuse existing" versus "create new")
   • Trigger (when to use, when not to, trigger keywords)
   • Input and output (can a standard input/output flow move down to tools/; does it need Gitea operations — if so, make the skill use jsc-gitea/tools/gitea.sh + token)
   • Owning domain (run tools/sync-domains.sh and offer its domain list — the domains registered in the canonical marketplace)

   Completion condition: goal, trigger, input/output and owning domain each have a recorded answer.

2. If the domain does not exist (tools/sync-domains.sh clones every domain registered in the marketplace, so a missing directory means the domain is unregistered — the repository itself may already exist on Gitea):

   1. Propose one short English word for the new domain (a single word preferred) and confirm it with the user. Completion condition: the user confirms the domain word.

   2. Check before creating: run jsc-gitea/tools/gitea.sh clone-url plugins/{domain}. A URL comes back when the repository already exists — clone it, skip creation, and go on to step 2.3 to fill in whatever content is missing. Only when no URL comes back create the repository through the tool, never by hand: gitea.sh api POST /orgs/plugins/repos when plugins is an organization, POST /user/repos when plugins is the token's own account (tea repo create does the same job). Only when the call is refused (403 — the token has write but not admin rights on the owner) ask the user to create plugins/{domain} by hand, then continue. Completion condition: gitea.sh clone-url plugins/{domain} prints a URL and cloning it succeeds.

   3. Build the content following the structure of https://gitea.jsc.idv.tw/plugins/template: three plugin manifests (plugin name jsc-{domain}, version starting at 0.0.1), skills/, README.md, AGENTS.md. Completion condition: the three manifests, skills/, README.md and AGENTS.md all exist in the new repo.

   4. Register the plugin: run tools/sync-marketplace.sh {domain} {repo-url} {description}. It needs python3 on PATH — it edits the marketplace JSON with the json module. It writes the entry into both canonical marketplace files in plugins/meta and copies both into every domain repo, so any repo works as the registration entry point. Route each exit code:

      • Exit 3 — written, but some domain repo is not present locally. Run tools/sync-domains.sh, then rerun this step.
      • Exit 2 — usage error. Fix the three arguments and rerun.
      • Exit 1 — missing python3, an unreadable canonical file, or a byte mismatch between copies. Read stderr, fix the named cause (install python3 for the first), then rerun.
      • Exit 0 — every copy holds identical bytes; the script verifies that itself.

      Completion condition: the script exits 0 and prints the touched paths.

3. Generate the skill per guidelines.md — this step MUST run as a sub agent:

   • skills/{name}/SKILL.md: entirely in English (description within either cap — ≤ 5 sentences or ≤ 5 steps — and stating when to use and when not to; body in STE100-style English)
   • Rules enforceable by hooks go to jsc-hooks (never scattered in this domain); standard input/output flows go to tools/

   Then run tools/sync-skill-manifest.sh {domain-path} directly (no sub agent needed) to sync the domain README's 「Skills 目錄」 section and bump the version in all three manifests. Completion condition: skills/{name}/SKILL.md exists, the README lists the skill, and all three manifests show the same new version.

4. Self-check every item of the guidelines.md audit checklist; fix anything that fails. Completion condition: every checklist item passes.

5. Call jsc-git:pr to open a Push Request. Completion condition: a PR URL comes back and is reported with the table format in references/pr-report.md.

6. Apply the new skill to the current working session, verify it works, then report:

   1. Force the change into the session — which of the two routes applies depends on where the change has reached, because the marketplace and version-guard.sh both read the repository's default branch (master), so jsc-cli:deploy cannot see anything that stopped at develop:
      • The PR is merged all the way to master: call jsc-cli:deploy in update mode so every installed CLI loads the new version, and restart the CLI when it asks (the deploy writes $JSC_HOME/restart-required; see guidelines.md「部署後重啟閘門」). When the deploy cannot update a CLI, record which CLIs did load the new version and carry on with one of those; when none did, stop and report the change as unverified. Completion condition: claude plugin list (or the equivalent command of another installed CLI) prints jsc-{domain} at the version the three manifests now carry.
      • The PR is still short of master (waiting on review, or merged only into develop): deploying is pointless and its completion condition is unreachable, so verify against the worktree instead — run step 6.2 against /root/plugins/{domain} rather than the installed copy, mark the report in 6.3 as 「工作樹驗證、尚未部署」, and say plainly which release PR still has to merge before the change reaches any CLI. Completion condition: step 6.2 passed against the worktree and the outstanding release PR is named in the report.
   2. Verify the function concretely: run tools/list-skills.sh and see the {domain}<TAB>{name} row for the new skill, then run every tool the skill added with real arguments and compare each exit code against its documented meaning. Invoke /jsc-{domain}:{name} once and confirm the CLI loads the SKILL.md body instead of reporting an unknown command. On any mismatch — a missing row, an exit code the tool's own documentation does not describe, an unknown command — fix the cause and rerun this step from 6.1. Completion condition: the row is printed, every added tool ran with an expected exit code, and the command loaded.
   3. Write the change report to wiki page SKILLSET_{HASH} — this part MUST run as a sub agent. Call jsc-gitea:wiki; {HASH} comes from the {owner}/{repo} of the domain repo that gained the skill, and the wiki repo resolves through JSC_WIKI_REPO_SKILLSET first, then JSC_WIKI_REPO. Append a section for this change — date, 「新增」, skill name, changed files, PR URL, the step 6.2 verification result per item — and keep every earlier section. Add the page to SKILLSET_CONTENTS when it is new. When the write fails — no {owner}/{repo} resolves, or jsc-gitea:wiki reports an API error — hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: the page holds the new section plus all earlier sections, and SKILLSET_CONTENTS links it.