@modootoday/pmcp 0.17.4 → 0.18.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/plugins/marketplace.json +1 -1
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +60 -0
- package/README.md +29 -24
- package/dist/apply-4IGTXOCQ.js +242 -0
- package/dist/{attachment-tU5FZrgZ.d.ts → attachment-D84OGI6n.d.ts} +1 -1
- package/dist/available-DBSIVVJ6.js +73 -0
- package/dist/broadcast-3RY3OZGY.js +18 -0
- package/dist/chunk-25GHX674.js +1246 -0
- package/dist/chunk-2P4Z2NUX.js +28 -0
- package/dist/chunk-34DECPVC.js +22 -0
- package/dist/chunk-3NYG4SGU.js +45 -0
- package/dist/chunk-3PW4FI7U.js +32 -0
- package/dist/chunk-3Y3HDMHA.js +108 -0
- package/dist/chunk-47O3X4VS.js +113 -0
- package/dist/chunk-4NDEP7HU.js +26 -0
- package/dist/chunk-4VCC2NXE.js +104 -0
- package/dist/chunk-5OMOPUE6.js +39 -0
- package/dist/chunk-5QQWS4US.js +53 -0
- package/dist/chunk-5ZABTVSW.js +48 -0
- package/dist/chunk-65ZHM5RH.js +4985 -0
- package/dist/chunk-665TA55Z.js +419 -0
- package/dist/chunk-6STKGOCW.js +27 -0
- package/dist/chunk-6WXMJOMI.js +9 -0
- package/dist/chunk-73AKO4UL.js +24 -0
- package/dist/chunk-7BLPN3W6.js +31 -0
- package/dist/chunk-7DLZC73N.js +29 -0
- package/dist/chunk-7GBYECSK.js +72 -0
- package/dist/chunk-7TD53M7L.js +13 -0
- package/dist/chunk-A4PKLESO.js +112 -0
- package/dist/chunk-ABTJQ4QV.js +74 -0
- package/dist/chunk-BBTBJCFA.js +380 -0
- package/dist/chunk-BU65MNVU.js +13 -0
- package/dist/chunk-BVCTKPT3.js +83 -0
- package/dist/chunk-C4NHQGHL.js +142 -0
- package/dist/chunk-CJTKR6K6.js +1213 -0
- package/dist/chunk-DCU2EXQV.js +78 -0
- package/dist/chunk-DZ2MRTYT.js +135 -0
- package/dist/chunk-E2YOZ2FF.js +207 -0
- package/dist/chunk-E3DQB5LS.js +48 -0
- package/dist/chunk-E7OOHLQR.js +7 -0
- package/dist/chunk-EATCUWGG.js +66 -0
- package/dist/chunk-EIDIVIAD.js +33 -0
- package/dist/chunk-EJBZGIDK.js +1934 -0
- package/dist/chunk-ELAGZ635.js +252 -0
- package/dist/chunk-GZHHEHKY.js +44 -0
- package/dist/chunk-HDMBVLCZ.js +53 -0
- package/dist/chunk-HQOB7OQS.js +81 -0
- package/dist/chunk-IGYRMM62.js +28 -0
- package/dist/chunk-IJBSOWHK.js +86 -0
- package/dist/chunk-INT7QLEU.js +114 -0
- package/dist/chunk-J6QLLQVL.js +1025 -0
- package/dist/chunk-J7UYNJCR.js +9 -0
- package/dist/chunk-JEL35P7S.js +53 -0
- package/dist/chunk-JGJ4INEN.js +32 -0
- package/dist/chunk-JS5RTH4I.js +84 -0
- package/dist/chunk-JUXNIXN4.js +42 -0
- package/dist/chunk-JWRZDYB5.js +59 -0
- package/dist/chunk-KMXRRSKT.js +660 -0
- package/dist/chunk-LAZQBMAU.js +67 -0
- package/dist/chunk-LLBPVZXM.js +67 -0
- package/dist/chunk-LLT5FQBE.js +57 -0
- package/dist/chunk-LMT3PPXJ.js +17 -0
- package/dist/chunk-MM2Y43LC.js +87 -0
- package/dist/chunk-MPSQXSC6.js +346 -0
- package/dist/chunk-MVFH26QT.js +97 -0
- package/dist/chunk-MWFOUBFC.js +39 -0
- package/dist/chunk-N5AQ3PP7.js +211 -0
- package/dist/chunk-NQPURJT5.js +44 -0
- package/dist/chunk-NRBQK6UX.js +105 -0
- package/dist/chunk-NZS5CD72.js +333 -0
- package/dist/chunk-OEH47H6A.js +48 -0
- package/dist/chunk-OG7QR2DP.js +75 -0
- package/dist/chunk-OPYFEHKG.js +52 -0
- package/dist/chunk-P4N7DBD5.js +83 -0
- package/dist/chunk-PAX3QXX2.js +140 -0
- package/dist/chunk-PLX3BOOS.js +396 -0
- package/dist/chunk-PMJG2CXF.js +122 -0
- package/dist/chunk-PWSJJXLQ.js +643 -0
- package/dist/chunk-Q5H3L6Y4.js +23 -0
- package/dist/chunk-Q65R3XKX.js +155 -0
- package/dist/chunk-QEW4J3IZ.js +74 -0
- package/dist/chunk-QPL7E2HW.js +464 -0
- package/dist/chunk-R2GPCZUX.js +22 -0
- package/dist/chunk-R4L6LJJ2.js +778 -0
- package/dist/chunk-R5MT42JS.js +284 -0
- package/dist/chunk-RK4PYD7L.js +73 -0
- package/dist/chunk-RMATE45Z.js +197 -0
- package/dist/chunk-S3PIAMXV.js +230 -0
- package/dist/chunk-SG5TPMKH.js +93 -0
- package/dist/chunk-T3LKX23M.js +168 -0
- package/dist/chunk-T6GOWHK6.js +30 -0
- package/dist/chunk-TIA4SPU2.js +10 -0
- package/dist/chunk-TNCZ6444.js +57 -0
- package/dist/chunk-TVL5RTE6.js +269 -0
- package/dist/chunk-UOCLRM7P.js +151 -0
- package/dist/chunk-UPQTAHUK.js +189 -0
- package/dist/chunk-V4NPDK6X.js +14 -0
- package/dist/chunk-VJFEN6DJ.js +38 -0
- package/dist/chunk-WIW772I3.js +25 -0
- package/dist/chunk-XELAZAIM.js +136 -0
- package/dist/chunk-XNML2KIC.js +23 -0
- package/dist/chunk-XP2U3LO3.js +30 -0
- package/dist/chunk-YGOWIJPE.js +51 -0
- package/dist/chunk-YIXDHQYE.js +11 -0
- package/dist/chunk-YMHUM7AV.js +22 -0
- package/dist/chunk-YSAWTGNA.js +117 -0
- package/dist/chunk-Z4HRRXRF.js +478 -0
- package/dist/chunk-ZH6R642Z.js +102 -0
- package/dist/claude-U2JC2DNQ.js +77 -0
- package/dist/cli-VYCQJZ5X.js +41 -0
- package/dist/cli-ZTCBSDW4.js +46 -0
- package/dist/cli.js +144 -16197
- package/dist/completion-E7RRG3ZT.js +142 -0
- package/dist/config-DnpLL2kT.d.ts +46 -0
- package/dist/{service-qpCsOXkQ.d.ts → core-C1LPjxK6.d.ts} +2 -6
- package/dist/diagnostics-XXH4FLUG.js +93 -0
- package/dist/doctor-ZIOESU3N.js +538 -0
- package/dist/entry-ZNFCTDVE.js +305 -0
- package/dist/exec-mcp-X6372BLE.js +365 -0
- package/dist/harness-F2XFDYXF.js +177 -0
- package/dist/harness-egress-bridge.js +4 -4
- package/dist/harness-launch-gate.js +47 -940
- package/dist/harness-pane-runner.js +13 -80
- package/dist/harness-worker.js +21 -2703
- package/dist/hook-body.js +5221 -0
- package/dist/hook-spec-C5fWTSCH.d.ts +100 -0
- package/dist/hook.js +26 -0
- package/dist/hooks-FYE2L5RW.js +21 -0
- package/dist/host-GRY3VAHH.js +22 -0
- package/dist/host-X6BR6X4O.js +200 -0
- package/dist/host-run-GCA6H6SR.js +307 -0
- package/dist/http.d.ts +5 -42
- package/dist/http.js +21 -2234
- package/dist/import-mcp-2TTBPVLY.js +400 -0
- package/dist/index.d.ts +146 -168
- package/dist/index.js +133 -4948
- package/dist/init-627KFXTG.js +14 -0
- package/dist/install-GG7HHZK2.js +796 -0
- package/dist/invoke-LW22Z6ET.js +23 -0
- package/dist/list-MCP2FXUF.js +68 -0
- package/dist/list-NGMSQ5SH.js +65 -0
- package/dist/load-BEUBABtB.d.ts +21 -0
- package/dist/logout-6CSHUWWE.js +44 -0
- package/dist/logs-SPB6AANY.js +107 -0
- package/dist/mailbox/index.d.ts +10 -5
- package/dist/mailbox/index.js +53 -1572
- package/dist/mailbox-7BV54Q4R.js +285 -0
- package/dist/mailbox-GDJ7BWQN.js +189 -0
- package/dist/mainline-JQTTYJMI.js +639 -0
- package/dist/marketplace-G4VQET5W.js +191 -0
- package/dist/mcp-2DKVU3SW.js +15 -0
- package/dist/mcp-V23HC3LB.js +193 -0
- package/dist/models-ISU4DCMA.js +32 -0
- package/dist/opencode-CN7JLQYO.js +60 -0
- package/dist/pause-FFAYRBWI.js +18 -0
- package/dist/preview-DT7DWG5F.js +91 -0
- package/dist/project/hook-adapter.d.ts +5 -2
- package/dist/project/hook-adapter.js +41 -27
- package/dist/project-FY62G55N.js +70 -0
- package/dist/pty-XTJ4MIWK.js +94 -0
- package/dist/recovery-U6QB3PMT.js +100 -0
- package/dist/reindex-Y27QJFDB.js +22 -0
- package/dist/resume-UU4HZIUP.js +18 -0
- package/dist/run-HALGEJNJ.js +19 -0
- package/dist/run-OGA3P7FC.js +126 -0
- package/dist/serve-NBKT5BKY.js +104 -0
- package/dist/session-XM2CR425.js +159 -0
- package/dist/setup-DTKZLZUT.js +18 -0
- package/dist/start-login-UIQYQBMC.js +416 -0
- package/dist/status-A2OUTNGK.js +9 -0
- package/dist/status-H2VAHIDV.js +10 -0
- package/dist/status-NOOHW5WA.js +43 -0
- package/dist/status-VHODZPXB.js +55 -0
- package/dist/status-XQANBVXW.js +286 -0
- package/dist/stdio.d.ts +3 -13
- package/dist/stdio.js +16 -3186
- package/dist/sweep-64JDCGK6.js +18 -0
- package/dist/test-MKAXFJOL.js +561 -0
- package/dist/tools-gpHNq9Dh.d.ts +328 -0
- package/dist/tui-MWKAXE4K.js +153 -0
- package/dist/unbroadcast-KPUEFLZD.js +18 -0
- package/dist/validate-5GZ5YWNA.js +46 -0
- package/dist/worker-RQ575EJL.js +80 -0
- package/dist/worktree-create-PZSRB7PH.js +89 -0
- package/dist/worktree-list-JYB6VXLW.js +51 -0
- package/dist/worktree-sync-UF5CXPWV.js +30 -0
- package/docs/hooks/capabilities/antigravity.json +199 -0
- package/docs/hooks/capabilities/claude.json +179 -0
- package/docs/hooks/capabilities/codex.json +179 -0
- package/docs/hooks/capabilities/gemini.json +196 -0
- package/docs/hooks/capabilities/grok.json +192 -0
- package/docs/hooks/capabilities/opencode.json +184 -0
- package/docs/project-configuration.md +821 -4
- package/docs/terminal-harness.md +71 -28
- package/docs/terminal-workspace.md +91 -170
- package/gemini-extension.json +1 -1
- package/package.json +13 -1
- package/plugin.json +1 -1
- package/plugins/pmcp/.claude-plugin/plugin.json +4 -2
- package/plugins/pmcp/gemini-extension.json +1 -1
- package/plugins/pmcp/mod/commands.ts +72 -0
- package/plugins/pmcp/mod/contract.d.ts +39 -0
- package/plugins/pmcp/mod/draw.tsx +216 -0
- package/plugins/pmcp/mod/guard.ts +42 -0
- package/plugins/pmcp/mod/hooks.json +4 -0
- package/plugins/pmcp/mod/host.ts +46 -0
- package/plugins/pmcp/mod/model.ts +144 -0
- package/plugins/pmcp/mod/reader/index.ts +18 -0
- package/plugins/pmcp/mod/reader/read.ts +76 -0
- package/plugins/pmcp/mod/reader/settings.ts +54 -0
- package/plugins/pmcp/mod/reader/types.ts +38 -0
- package/plugins/pmcp/mod/register.tsx +73 -0
- package/plugins/pmcp/mod/sessions/format.ts +91 -0
- package/plugins/pmcp/mod/sessions/types.ts +162 -0
- package/plugins/pmcp/mod/snapshot.ts +75 -0
- package/plugins/pmcp/mod/spinner.tsx +30 -0
- package/plugins/pmcp/mod/state.ts +28 -0
- package/plugins/pmcp/plugin.json +1 -1
- package/plugins/pmcp/skills/agent-assets-migrate/SKILL.md +96 -0
- package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +100 -0
- package/plugins/pmcp/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
- package/plugins/pmcp/skills/package-skill-catalog/SKILL.md +51 -11
- package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +145 -0
- package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +104 -0
- package/plugins/pmcp/skills/skill-package-scaffold/SKILL.md +88 -0
- package/schema/catalog-v1.json +158 -0
- package/schema/library.json +164 -0
- package/schema/marketplace-manifest.json +130 -0
- package/schema/plugin-manifest.json +55 -0
- package/schema/skill-frontmatter.json +144 -0
- package/schema/skill-metadata-core.json +110 -0
- package/skills/agent-assets-migrate/SKILL.md +96 -0
- package/skills/headless-agents-ci-scaffold/SKILL.md +100 -0
- package/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
- package/skills/package-skill-catalog/SKILL.md +51 -11
- package/skills/pmcp-project-init/SKILL.md +145 -0
- package/skills/pmcp-sessions-and-git/SKILL.md +104 -0
- package/skills/skill-package-scaffold/SKILL.md +88 -0
- package/dist/config-BkSpjUG6.d.ts +0 -50
- package/dist/embed-DRROSD3F.d.ts +0 -53
- package/dist/hook-spec-CSJJySsH.d.ts +0 -11
- package/dist/server-VWSY3Shw.d.ts +0 -543
- package/dist/tui-worker.js +0 -6549
- /package/dist/{tui-worker.d.ts → hook.d.ts} +0 -0
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: headless-agents-ci-scaffold
|
|
3
|
+
description: Write a CI job that runs Claude Code, Gemini CLI, Codex, Grok Build and Antigravity headless against a project MCP server, giving each the permission setting it actually honours, asserting on the tool call rather than the exit code, and gating with pmcp project --check and pmcp doctor. Use when adding agent CLIs to CI, when a headless agent run skips an MCP tool call, or when a permission flag seems to do nothing. Not for interactive sessions or for writing the MCP server itself.
|
|
4
|
+
metadata:
|
|
5
|
+
tier: open
|
|
6
|
+
level: L3
|
|
7
|
+
domain: agent-workflow
|
|
8
|
+
install: optional
|
|
9
|
+
keywords: "headless agent, CI, allowedTools, permission flags, MCP permissions, Codex sandbox, Grok, Antigravity, pmcp doctor"
|
|
10
|
+
requires-bin: "pmcp"
|
|
11
|
+
verified-runtimes: "claude-code"
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# Headless agent CLIs in CI
|
|
15
|
+
|
|
16
|
+
Every agent CLI blocks an MCP tool call it was not told to allow, and each spells the
|
|
17
|
+
allowance differently. Several fail quietly: the model announces the call and the run ends
|
|
18
|
+
with exit 0. So a CI job needs the right setting per tool and an assertion that the call
|
|
19
|
+
happened.
|
|
20
|
+
|
|
21
|
+
The settings below were measured with one headless MCP call per tool (Claude Code 2.1.289,
|
|
22
|
+
Gemini CLI 0.38.2, Codex 0.131.0, Grok Build 1.0.46, Antigravity 1.2.16). Re-check after an
|
|
23
|
+
upgrade; these flags move.
|
|
24
|
+
|
|
25
|
+
## Permission per tool
|
|
26
|
+
|
|
27
|
+
`<server>` is the MCP alias (the `[mcp.<alias>]` name), `<tool>` the tool name.
|
|
28
|
+
|
|
29
|
+
| Tool | Command | What lets the call through |
|
|
30
|
+
| --- | --- | --- |
|
|
31
|
+
| Claude Code | `claude -p "<prompt>" --permission-mode default --allowedTools mcp__<server>__<tool>` | the `--allowedTools` rule; without it the call is blocked under `default` |
|
|
32
|
+
| Gemini CLI | `gemini -p "<prompt>" --allowed-mcp-server-names <server> --allowed-tools mcp_<server>_<tool>` | one `--allowed-tools` flag per tool (a bare tool name does not match; the array form swallowed the prompt); the folder must be trusted; the flag is deprecated in favour of the Policy Engine |
|
|
33
|
+
| Codex | `codex exec "<prompt>"` | nothing; `exec` allowed the call without a flag |
|
|
34
|
+
| Grok Build | `grok -p "<prompt>" --permission-mode default --allow <server>__<tool>` | `--allow <server>__<tool>`; the Claude-style `mcp__<server>__<tool>` matches nothing |
|
|
35
|
+
| Antigravity | `agy -p "<prompt>"` | a `permissions.allow` entry `mcp(<server>/<tool>)` in `~/.gemini/antigravity-cli/settings.json`; `mcp(<server>)` alone does not match, and an unlisted tool is auto-denied |
|
|
36
|
+
|
|
37
|
+
### Grok precedence traps
|
|
38
|
+
|
|
39
|
+
- Grok reads Claude Code's `~/.claude/settings.json`. A `defaultMode: auto` there approves
|
|
40
|
+
MCP calls over Grok's own `--permission-mode default` and `--disallowed-tools`. Run Grok on
|
|
41
|
+
a runner whose home has no such setting.
|
|
42
|
+
- `--permission-mode default` on the command line beats a config `permission_mode =
|
|
43
|
+
"always-approve"`, but `--disallowed-tools` does not. Do not rely on a deny rule to keep a
|
|
44
|
+
tool from running; pin the mode by flag and allow only what the job needs.
|
|
45
|
+
- A blocked call in `-p` is silent: no error line, exit 0.
|
|
46
|
+
|
|
47
|
+
### Codex sandbox
|
|
48
|
+
|
|
49
|
+
Under `--sandbox workspace-write`, `.agents/` is protected like `.git`: a patch touching it
|
|
50
|
+
is refused whole, including its other files. If the job edits `.agents/`, list it under
|
|
51
|
+
`[sandbox_workspace_write] writable_roots` in `.codex/config.toml`, or per run:
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
codex exec -s workspace-write \
|
|
55
|
+
-c 'sandbox_workspace_write.writable_roots=["<absolute repo path>/.agents"]' "<prompt>"
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Trust on the runner
|
|
59
|
+
|
|
60
|
+
Codex, Gemini and Grok skip project assets (skills, MCP servers, agents) in an untrusted
|
|
61
|
+
folder, without an error. On a fresh runner, record the checkout as trusted for each tool
|
|
62
|
+
before the run (Codex: `[projects."<absolute path>"] trust_level = "trusted"` in
|
|
63
|
+
`~/.codex/config.toml`; Gemini: `~/.gemini/trustedFolders.json`; Grok:
|
|
64
|
+
`~/.grok/trusted_folders.toml`; Antigravity: `trustedWorkspaces` in its settings file).
|
|
65
|
+
|
|
66
|
+
## Assert the call, not the exit code
|
|
67
|
+
|
|
68
|
+
Exit 0 proves nothing here. Either put a logging proxy in front of the MCP server and
|
|
69
|
+
assert it logged a `tools/call` for the tool, or have the prompt return a value only the
|
|
70
|
+
tool can supply and grep for it.
|
|
71
|
+
|
|
72
|
+
## Projection gate
|
|
73
|
+
|
|
74
|
+
```sh
|
|
75
|
+
pmcp project --check # exit 2: generated files drifted, went stale or are undeclared
|
|
76
|
+
pmcp doctor # exit 1 on any failed check
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`pmcp doctor` skips a CLI that is not installed, except the Codex trust check, which reads
|
|
80
|
+
`~/.codex/config.toml` whenever `codex` is in `[targets]`. On a runner without Codex, either
|
|
81
|
+
write the trust entry or pass `--tool` for the tools present (`pmcp doctor --tool claude
|
|
82
|
+
--tool gemini`).
|
|
83
|
+
|
|
84
|
+
## Job skeleton
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
set -eu
|
|
88
|
+
pmcp project --check
|
|
89
|
+
pmcp doctor --tool claude --tool gemini --tool grok
|
|
90
|
+
out=$(claude -p "Call <tool> on <server> and print the first result name." \
|
|
91
|
+
--permission-mode default --allowedTools mcp__<server>__<tool>)
|
|
92
|
+
printf '%s\n' "$out" | grep -q '<expected value>'
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Repeat the last two lines per tool with its own setting from the table.
|
|
96
|
+
|
|
97
|
+
## Report
|
|
98
|
+
|
|
99
|
+
The job file, the per-tool settings used with the version each was checked on, how each run
|
|
100
|
+
asserts the call, and any tool left out and why.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: marketplace-plugin-scaffold
|
|
3
|
+
description: Package skills, commands, subagents, hooks and MCP servers as a plugin in a plugin marketplace laid out the way pmcp's catalog reads it - marketplace.json with a tier, plugin.json, skills/, commands/, agents/, hooks/hooks.json and .mcp.json - and confirm every asset is listed with pmcp list and pmcp validate. Use when turning a folder of skills into a marketplace plugin, when a plugin's assets do not show up in a skill catalog, or when setting the tier of a marketplace. Not for writing a single skill's content or for hosting the catalog over HTTP.
|
|
4
|
+
metadata:
|
|
5
|
+
tier: open
|
|
6
|
+
level: L2
|
|
7
|
+
domain: agent-workflow
|
|
8
|
+
install: optional
|
|
9
|
+
keywords: "plugin marketplace, marketplace.json, plugin.json, skill plugin, pmcp catalog, tier, commands, hooks, mcp.json"
|
|
10
|
+
requires-bin: "pmcp"
|
|
11
|
+
verified-runtimes: "claude-code"
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# Scaffolding a marketplace plugin pmcp can read
|
|
15
|
+
|
|
16
|
+
pmcp reads a marketplace by its files, with no package.json involved. Anything outside the
|
|
17
|
+
places below is invisible to it, and an asset without a description is dropped with a
|
|
18
|
+
reason, not served.
|
|
19
|
+
|
|
20
|
+
## Layout
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
<marketplace>/
|
|
24
|
+
.claude-plugin/marketplace.json
|
|
25
|
+
plugins/<plugin>/
|
|
26
|
+
.claude-plugin/plugin.json
|
|
27
|
+
skills/<name>/SKILL.md
|
|
28
|
+
commands/<name>.md
|
|
29
|
+
agents/<name>.md or agents/<name>/agent.md
|
|
30
|
+
hooks/hooks.json
|
|
31
|
+
.mcp.json
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## marketplace.json
|
|
35
|
+
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"name": "acme",
|
|
39
|
+
"metadata": { "tier": "open" },
|
|
40
|
+
"plugins": [{ "name": "billing-skills", "source": "./plugins/billing-skills" }]
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
- A plugin entry without `name` or `source`, or whose `source` directory does not exist, is
|
|
45
|
+
skipped without a message. Check the count in `pmcp list`.
|
|
46
|
+
- The tier lives here, for the whole marketplace. There is no plugin-level tier.
|
|
47
|
+
- A skill, command or agent may repeat it as `metadata.tier` in its frontmatter. If that
|
|
48
|
+
disagrees with the marketplace tier the asset is rejected, because a mislabelled tier is
|
|
49
|
+
how a private asset leaks. Keep one tier per marketplace and split marketplaces by tier.
|
|
50
|
+
|
|
51
|
+
## plugin.json
|
|
52
|
+
|
|
53
|
+
`description` is what a hook entry and each MCP server entry are described with. `hooks` may
|
|
54
|
+
name a different hooks file (a string path); otherwise `hooks/hooks.json` is read.
|
|
55
|
+
|
|
56
|
+
## What each place becomes
|
|
57
|
+
|
|
58
|
+
| Place | Catalog entry | Name in the catalog |
|
|
59
|
+
| --- | --- | --- |
|
|
60
|
+
| `skills/<name>/SKILL.md` | a skill; its folder is what describe and read may open | `<marketplace>/<plugin>/<name>` |
|
|
61
|
+
| `commands/<name>.md` | a one-file skill; only that file is readable | `<marketplace>/<plugin>/<name>` |
|
|
62
|
+
| `agents/<name>.md`, `agents/<name>/agent.md` | kind `agent` | `<marketplace>/<plugin>/agents/<name>` |
|
|
63
|
+
| `hooks/hooks.json` | one kind `hook` entry for the plugin; needs a `description` in the file or in plugin.json | `<marketplace>/<plugin>/hooks` |
|
|
64
|
+
| `.mcp.json` | one kind `mcp` entry per key of `mcpServers` | `<marketplace>/<plugin>/mcp/<server>` |
|
|
65
|
+
|
|
66
|
+
Skills and commands appear in `skill_catalog` and `skill_find`. Agents, hooks and MCP
|
|
67
|
+
servers are left out unless the caller asks for that `kind` (`agent`, `hook`, `mcp` or
|
|
68
|
+
`any`). A command is listed like any skill; nothing marks it as started by the user only.
|
|
69
|
+
The frontmatter `name` sets the slug; without one the file or folder name is used. Keep
|
|
70
|
+
them equal: the Agent Skills specification requires a skill's name to match its directory.
|
|
71
|
+
|
|
72
|
+
## Check
|
|
73
|
+
|
|
74
|
+
```sh
|
|
75
|
+
pmcp list --marketplace <marketplace> --no-config # every entry, with its tier
|
|
76
|
+
pmcp validate --marketplace <marketplace> --no-config # rejections and specification errors
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`validate` prints why each asset was left out (`no description`, `metadata.tier ... in a
|
|
80
|
+
... marketplace`, `.mcp.json has no mcpServers object`, `hooks.json is not a JSON object`).
|
|
81
|
+
Compare the `list` count with the files you created; a missing plugin is usually a wrong
|
|
82
|
+
`source`.
|
|
83
|
+
|
|
84
|
+
## Report
|
|
85
|
+
|
|
86
|
+
The tree, marketplace.json and plugin.json, the `pmcp list` count per kind against the files
|
|
87
|
+
created, and the `pmcp validate` output.
|
|
@@ -1,20 +1,42 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: package-skill-catalog
|
|
3
|
-
description: Find
|
|
3
|
+
description: Find, check and load the right skill from a PMCP skill catalog instead of guessing, including version-appropriate instructions for installed public libraries, and install selected PMCP marketplace skills through a native runtime. Use when a task might have a dedicated skill, when the PMCP tools (skill_find, skill_catalog, skill_describe, skill_call, skill_read, skill_bundle) are available, or when a search for a skill came back empty.
|
|
4
|
+
metadata:
|
|
5
|
+
tier: open
|
|
6
|
+
level: L1
|
|
7
|
+
domain: agent-workflow
|
|
8
|
+
install: default
|
|
9
|
+
keywords: skill search, skill catalog, skill router, library instructions
|
|
10
|
+
verified-runtimes: claude-code
|
|
4
11
|
---
|
|
5
12
|
|
|
6
13
|
# Package skill catalog
|
|
7
14
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
15
|
+
A catalog server keeps hundreds of skills out of the session until one is
|
|
16
|
+
needed. Its value depends on the order you use it in: search before you read,
|
|
17
|
+
check before you load, and never invent a name. Prefer the project's installed
|
|
18
|
+
library version and preserve its package manager, configuration, build scripts
|
|
19
|
+
and native runtime permissions.
|
|
11
20
|
|
|
12
|
-
##
|
|
21
|
+
## The loop
|
|
13
22
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
23
|
+
1. **Search with the problem, not a keyword.** Call skill_find with one full
|
|
24
|
+
English sentence that says what you are trying to do and for whom. Add
|
|
25
|
+
filters only for facts you already know (for example tier or medium).
|
|
26
|
+
2. **On an empty result, look before concluding.** Call skill_catalog (paged)
|
|
27
|
+
and scan the group names. An empty search means the wording missed, not that
|
|
28
|
+
no skill exists. Rephrase once with the vocabulary you saw there.
|
|
29
|
+
3. **Check the top one to three candidates.** Call skill_describe for each and
|
|
30
|
+
compare metadata.level, the requirements, compatibility, the output licence
|
|
31
|
+
and whether approval is needed. Prefer the narrowest skill that covers the task.
|
|
32
|
+
4. **Load one.** Call skill_call with the exact name the server returned. The
|
|
33
|
+
body is the instruction; follow it on your own host.
|
|
34
|
+
5. **Read extra files only when the body points at them.** Use skill_read with
|
|
35
|
+
the path the body names, or skill_bundle when the complete selected skill is
|
|
36
|
+
needed. Treat scripts as text to review, not to run, unless the body asks and
|
|
37
|
+
the user agreed.
|
|
38
|
+
|
|
39
|
+
## Library instructions
|
|
18
40
|
|
|
19
41
|
Check the target major and verified version before following version-sensitive
|
|
20
42
|
API examples. Catalog availability is not proof that a particular version was
|
|
@@ -24,6 +46,21 @@ Without MCP, use pmcp list to inspect local catalogs and pmcp available to match
|
|
|
24
46
|
the public catalog against installed npm dependencies. Public library instructions
|
|
25
47
|
remain free and do not require a PMCP account.
|
|
26
48
|
|
|
49
|
+
## Rules
|
|
50
|
+
|
|
51
|
+
- Use only names a tool returned. A guessed name wastes a call and can load the
|
|
52
|
+
wrong skill.
|
|
53
|
+
- Load at most two skills for one task. If neither fits, say so and work
|
|
54
|
+
without one rather than stacking partial matches.
|
|
55
|
+
- Say which skill you used and why, in one line, so the user can check the
|
|
56
|
+
choice.
|
|
57
|
+
- A skill tagged paid runs on a remote service and may cost the user. Show the
|
|
58
|
+
estimate it asks for and wait for confirmation before submitting work.
|
|
59
|
+
- Never paste secrets into a skill's inputs. Skills name the environment
|
|
60
|
+
variables they need; the values stay in the user's environment.
|
|
61
|
+
- When native skills and MCP both expose the same instructions, use one source
|
|
62
|
+
for the task rather than loading duplicate bodies.
|
|
63
|
+
|
|
27
64
|
## Install deliberately
|
|
28
65
|
|
|
29
66
|
PMCP 0.14.0 includes the marketplace export command and public default provider.
|
|
@@ -39,8 +76,11 @@ Use pmcp install --dry-run before applying public npm skill installation with
|
|
|
39
76
|
provider OAuth credentials into plugin manifests or PMCP configuration.
|
|
40
77
|
|
|
41
78
|
Avoid activating competing major versions under the same unnamespaced skill name.
|
|
42
|
-
|
|
43
|
-
|
|
79
|
+
|
|
80
|
+
## When to stop using the catalog
|
|
81
|
+
|
|
82
|
+
If the task is a one-line answer, or the user named the exact procedure, skip
|
|
83
|
+
the search. The catalog is for tasks where a tested procedure beats improvising.
|
|
44
84
|
|
|
45
85
|
## Boundaries and sources
|
|
46
86
|
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pmcp-project-init
|
|
3
|
+
description: Set up a repository so every coding agent reads the same instructions, skills, subagents, rules and MCP servers - one AGENTS.md with CLAUDE.md and GEMINI.md linked to it, sources under .agents/, a pmcp.toml with [targets] and [mcp.*] entries, then the optional layers chosen from what the repository is (hook guards, sessions, the git workflow when it is a git checkout, logging, shared MCP authentication, marketplaces), then pmcp project and pmcp doctor, plus the one-time trust step each agent CLI needs. Use when starting a new repository the pmcp way, adding pmcp to a repository that has no agent assets yet, enabling hooks, sessions or the git workflow, or when asked to write a pmcp.toml. Not for moving existing scattered agent files (migrate them instead) or for hosting a skills server.
|
|
4
|
+
metadata:
|
|
5
|
+
tier: open
|
|
6
|
+
level: L2
|
|
7
|
+
domain: agent-workflow
|
|
8
|
+
install: optional
|
|
9
|
+
keywords: "pmcp, pmcp.toml, AGENTS.md, .agents, agent assets, project setup, MCP config, hooks, sessions, git worktrees, multi-agent repository"
|
|
10
|
+
requires-bin: "pmcp"
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Starting a repository the pmcp way
|
|
14
|
+
|
|
15
|
+
pmcp has no `init` command. You write the sources by hand; `pmcp project` writes every
|
|
16
|
+
tool's native files from them, and `pmcp doctor` asks each installed tool what it loads.
|
|
17
|
+
Never write the generated files yourself: pmcp refuses to overwrite a file it did not write.
|
|
18
|
+
|
|
19
|
+
Install the pmcp package as a dev dependency under the scoped name its documentation gives.
|
|
20
|
+
Never run the bare unscoped name through npx: that name is not the package, and whoever
|
|
21
|
+
publishes it later would run in your repository.
|
|
22
|
+
|
|
23
|
+
## 1. Instructions: one file, two links
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
printf '# <project>\n\n' > AGENTS.md
|
|
27
|
+
ln -s AGENTS.md CLAUDE.md
|
|
28
|
+
ln -s AGENTS.md GEMINI.md
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
`AGENTS.md` is the real file. Claude Code reads `CLAUDE.md` and Gemini CLI `GEMINI.md`, so
|
|
32
|
+
the links make them read the same text. pmcp does not create these links. Keep them
|
|
33
|
+
file-to-file links; a directory symlink at the repository root (for example `.agents`
|
|
34
|
+
pointing at another folder) is rejected by the Codex sandbox.
|
|
35
|
+
|
|
36
|
+
## 2. Sources under .agents/
|
|
37
|
+
|
|
38
|
+
| Path | Holds | Frontmatter |
|
|
39
|
+
| -------------------------------- | ----------------------------------------------------------- | --------------------------------------------- |
|
|
40
|
+
| `.agents/skills/<name>/SKILL.md` | a skill; `<name>` equals the frontmatter `name` | `name`, `description` |
|
|
41
|
+
| `.agents/agents/<name>/agent.md` | a subagent (directory form; a flat `<name>.md` is not read) | `name`, `description` only |
|
|
42
|
+
| `.agents/rules/<topic>.md` | a path-scoped rule | `trigger: glob`, `description`, `globs:` list |
|
|
43
|
+
|
|
44
|
+
Keep `tools`, `model` and other tool-specific fields out of `agent.md`: Antigravity drops
|
|
45
|
+
an agent whose `tools` names another tool's tools. Those fields go in `pmcp.toml`.
|
|
46
|
+
|
|
47
|
+
## 3. The base pmcp.toml
|
|
48
|
+
|
|
49
|
+
```toml
|
|
50
|
+
[targets]
|
|
51
|
+
tools = ["claude", "codex", "gemini", "grok", "antigravity"]
|
|
52
|
+
|
|
53
|
+
[mcp.skills]
|
|
54
|
+
command = "node"
|
|
55
|
+
args = ["${PROJECT_ROOT}/node_modules/<pmcp package>/dist/cli.js", "serve"]
|
|
56
|
+
|
|
57
|
+
[skills.release]
|
|
58
|
+
invocation = "user"
|
|
59
|
+
|
|
60
|
+
[agents.reviewer.claude]
|
|
61
|
+
tools = "Read, Grep"
|
|
62
|
+
model = "inherit"
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
- `[targets] tools` - any of `claude`, `codex`, `gemini`, `grok`, `antigravity`, `opencode`.
|
|
66
|
+
An unknown name is an error. A tool not listed gets no files.
|
|
67
|
+
- `[mcp.<alias>]` - exactly one of `command` (stdio: `args`, `env`, `env_vars`, `cwd`) or
|
|
68
|
+
`url` (Streamable HTTP: `headers`, `header_env`, `bearer_token_env_var`); `targets`
|
|
69
|
+
narrows the tools, `tools` filters the server's tools. A value naming `${PROJECT_ROOT}`
|
|
70
|
+
is launched through `sh`, so committed files carry no machine path.
|
|
71
|
+
- `[skills.<name>] invocation` - `"any"` (default) or `"user"`: the person starts it and the
|
|
72
|
+
model is not offered it.
|
|
73
|
+
- `[agents.<name>.<tool>]` - fields merged into that tool's copy. Claude keeps `name`,
|
|
74
|
+
`description`, `tools`, `model`, `effort`; Gemini keeps `name` and `description`.
|
|
75
|
+
- `[catalog]` - optional search roots; an unknown key is an error.
|
|
76
|
+
|
|
77
|
+
The project configuration guide lists every table with its keys and defaults.
|
|
78
|
+
|
|
79
|
+
## 4. Choose the optional layers from what the repository is
|
|
80
|
+
|
|
81
|
+
Every layer is a table; a missing table is off. Look before adding:
|
|
82
|
+
|
|
83
|
+
```sh
|
|
84
|
+
git rev-parse --git-common-dir # a git checkout? then the git layer applies
|
|
85
|
+
git worktree list # more than one line: desks already exist
|
|
86
|
+
git remote -v # the remote deliveries push to
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
| The repository | Add | Why |
|
|
90
|
+
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
91
|
+
| Agents run shell commands (always for Claude or Codex) | `[hooks]` with `targets`, and the `[hooks.guards.shell.*]` and `[hooks.guards.git.*]` you want | Refuses heredocs, in-place `sed -i`, `git add -A`, `push --no-verify`, credential exfiltration. Each declared table is one guard. |
|
|
92
|
+
| A validator script per skill or package | `[hooks.checks.after_edit]` with `validator_glob` and a `command` containing `{validator}` | Reports a failing validator as context right after the edit. |
|
|
93
|
+
| Committed generated files | `[hooks.checks.on_stop]` | Reports projection drift at the end of a turn that edited. |
|
|
94
|
+
| More than one agent at a time | `[sessions.registry]`, `[sessions.pause]`, `[sessions.broadcast]` | The operator can see, pause and message every session. |
|
|
95
|
+
| A lockfile or other file two sessions must not change at once | `[sessions.leases.<name>]` with `path` and the `blocks` command prefixes | A delivery touching that file holds the lease; the listed commands wait. |
|
|
96
|
+
| A git checkout | nothing: `[git] enabled` is `"auto"`, and `[git.shared_checkout]` warns once the hooks exist | A session in the main checkout is warned while desks exist. |
|
|
97
|
+
| Parallel agents in worktrees | `[git.worktrees]`, `[git.worktrees.sync]` | `pmcp git worktree create <alias>`; desks follow the mainline when that loses nothing. |
|
|
98
|
+
| A protected mainline with a test gate | `[git.mainline]` with `branch`, `[git.mainline.gate]` with `command`, `[git.mainline.deliver]`, `[git.mainline.sync]` | `pmcp git deliver` replays, gates and pushes one delivery at a time; direct `git push` is refused. |
|
|
99
|
+
| Submodules | `[git.submodules]` | Sync follows clean submodule pins. |
|
|
100
|
+
| You will debug hooks | `[logging]` with `level` | `pmcp logs` reads the JSONL; redaction is on by default. |
|
|
101
|
+
| A remote MCP server both Claude and Codex use | `auth = "pmcp"` on that `[mcp.<alias>]`, then `pmcp mcp login <alias>` | One login shared by both tools; tokens never enter the project. |
|
|
102
|
+
| A team plugin marketplace | `[marketplaces.<name>]` with `source` and `plugins` | Claude and Codex both enable the same plugins. |
|
|
103
|
+
| Claude Code with several sessions | `[ui.claude]` (needs `[sessions.registry]`) | Session panes and a hold before editing another session's file. |
|
|
104
|
+
| Claude should ask before reading secrets or running risky git | `[permissions.claude]` with `allow`, `ask`, `deny` lists of native rules such as `Read(.env)` or `Bash(git push:*)` | pmcp owns only the entries it adds to `.claude/settings.json`; rules already there stay. Claude only. |
|
|
105
|
+
|
|
106
|
+
Keep Codex's limits in mind: Codex has no ask, so an ask becomes `[hooks] ask_fallback`
|
|
107
|
+
(`deny` by default); roles cannot apply there (no agent type); Stop notices arrive at the
|
|
108
|
+
next prompt; SessionEnd hooks get at most 3 seconds.
|
|
109
|
+
|
|
110
|
+
## 5. Project and check
|
|
111
|
+
|
|
112
|
+
```sh
|
|
113
|
+
pmcp project # write; exits 1 if it would overwrite a file it did not write
|
|
114
|
+
pmcp project --check # write nothing; exit 2 on drift, stale, undeclared or dead-glob outputs
|
|
115
|
+
pmcp doctor # exit 1 on any failed check; prints the feature x runtime table
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
`pmcp project` writes the tools' native files, `.agents/pmcp-hooks/` when any hook layer is
|
|
119
|
+
declared, and `pmcp.lock`. Commit the lock with the outputs: `--check` reports a removed
|
|
120
|
+
source's outputs as stale only from the lock, and the hook refuses a `policy.json` whose hash
|
|
121
|
+
differs from it.
|
|
122
|
+
|
|
123
|
+
Only Claude gets the rules. For the other tools, add one pointer row per rule to
|
|
124
|
+
`AGENTS.md` (path and when to read it).
|
|
125
|
+
|
|
126
|
+
## 6. Trust the folder in each tool
|
|
127
|
+
|
|
128
|
+
Codex, Gemini CLI and Grok Build skip project assets silently until the folder is trusted;
|
|
129
|
+
skills, MCP servers, agents and hooks just do not appear. Each developer does this once per
|
|
130
|
+
tool, and again in Codex `/hooks` after a projection changes a hook entry:
|
|
131
|
+
|
|
132
|
+
| Tool | Where trust is recorded |
|
|
133
|
+
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
134
|
+
| Codex | `~/.codex/config.toml`: `[projects."<absolute path>"]` with `trust_level = "trusted"`; hooks are reviewed in `/hooks` |
|
|
135
|
+
| Gemini CLI | `~/.gemini/trustedFolders.json` |
|
|
136
|
+
| Grok Build | `~/.grok/trusted_folders.toml` |
|
|
137
|
+
| Antigravity | `trustedWorkspaces` in `~/.gemini/antigravity-cli/settings.json` |
|
|
138
|
+
|
|
139
|
+
`pmcp doctor` reports Codex and Grok trust directly. Run it after trusting, not before, or
|
|
140
|
+
its failures only restate the missing trust.
|
|
141
|
+
|
|
142
|
+
## Report
|
|
143
|
+
|
|
144
|
+
The files written, the layers chosen and why, the `pmcp project --check` exit code, the
|
|
145
|
+
`pmcp doctor` feature table, and which tools still need the trust or hook review step.
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pmcp-sessions-and-git
|
|
3
|
+
description: Work alongside other agent sessions in a pmcp repository - read who is working and what is held with pmcp sessions status, pause, resume and broadcast as the operator, wait out a lease, work in a desk (a linked worktree) instead of the shared main checkout, deliver commits through pmcp git deliver rather than git push, sync the main checkout and desks, and read pmcp logs to explain a hook refusal. Use when a pmcp hook refused or warned, when several agents share one repository, when asked to land or deliver work, or when a session reports a pause, lease or leftover edits. Not for writing pmcp.toml (set the project up first) or for repositories without pmcp hooks.
|
|
4
|
+
metadata:
|
|
5
|
+
tier: open
|
|
6
|
+
level: L2
|
|
7
|
+
domain: agent-workflow
|
|
8
|
+
install: optional
|
|
9
|
+
keywords: "pmcp, sessions, pause, broadcast, lease, worktree, desk, deliver, mainline, git sync, pmcp logs, hook refusal"
|
|
10
|
+
requires-bin: "pmcp"
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Working with other sessions under pmcp
|
|
14
|
+
|
|
15
|
+
pmcp hooks see every session in the repository and its worktrees. They refuse or warn with
|
|
16
|
+
a reason that names what to do instead. Do what the reason says; never work around a
|
|
17
|
+
refusal with another spelling of the same command.
|
|
18
|
+
|
|
19
|
+
## Read the room first
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
pmcp sessions status
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
It prints each live session (its id, runtime, checkout and current tool), the pause, current
|
|
26
|
+
broadcasts, held leases, and files edited but not landed in a shared checkout. Read it
|
|
27
|
+
before landing anything, and whenever a hook mentions another session.
|
|
28
|
+
|
|
29
|
+
## Pause and broadcast (operator)
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
pmcp sessions pause "release freeze" --by operator
|
|
33
|
+
pmcp sessions resume
|
|
34
|
+
pmcp sessions broadcast "main moved; sync your desk before delivering"
|
|
35
|
+
pmcp sessions unbroadcast
|
|
36
|
+
pmcp sessions sweep # drop records whose process is gone
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
While paused, every other session's edits and mutating commands are refused; reading and
|
|
40
|
+
planning continue. A broadcast reaches each session once, as context. An agent does not
|
|
41
|
+
pause, resume or broadcast on its own initiative; it reports the need to the operator.
|
|
42
|
+
|
|
43
|
+
## Leases
|
|
44
|
+
|
|
45
|
+
A lease protects a file two sessions must not change at once, such as a lockfile. While a
|
|
46
|
+
delivery that touches it is landing, the commands listed for that lease are refused with
|
|
47
|
+
`... is landing ... retry when it has landed`. Wait and retry; do not run the command another
|
|
48
|
+
way.
|
|
49
|
+
|
|
50
|
+
## Desks, not the shared checkout
|
|
51
|
+
|
|
52
|
+
When the repository has worktrees, the main checkout is shared: an edit left there blocks
|
|
53
|
+
syncing the mainline for every session, and the hook says so. Work in a desk:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
pmcp git worktree create <alias> # prints the desk path; work there
|
|
57
|
+
pmcp git worktree list # alias, branch, behind/ahead, path
|
|
58
|
+
pmcp git worktree sync # move this desk onto the mainline when nothing is lost
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
If you already edited the main checkout, land those files within the task or move them to a
|
|
62
|
+
desk. `pmcp sessions status` lists them under the shared checkout.
|
|
63
|
+
|
|
64
|
+
## Deliver, do not push
|
|
65
|
+
|
|
66
|
+
With `[git.mainline.deliver]`, a direct `git push` from any checkout of the repository is
|
|
67
|
+
refused. Commit in the desk, then:
|
|
68
|
+
|
|
69
|
+
```sh
|
|
70
|
+
pmcp git deliver # every commit the upstream lacks
|
|
71
|
+
pmcp git deliver <commit>... # only these
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
It fetches, replays the commits onto the mainline, runs the gate in its own tree under a
|
|
75
|
+
lock, and pushes, replaying again if the mainline moved. Exit 0 delivered or nothing to
|
|
76
|
+
deliver; 1 refused (pause, lease, gate failure, attempts exhausted) with the reason on
|
|
77
|
+
stderr; 2 the fetch failed. Fix what the gate reports; never bypass it with
|
|
78
|
+
`--no-verify` or a gate-bypass variable, which the guards refuse.
|
|
79
|
+
|
|
80
|
+
`pmcp git sync` moves the main checkout to the mainline afterwards; it refuses (exit 2)
|
|
81
|
+
while unlanded edits sit there.
|
|
82
|
+
|
|
83
|
+
## Explain a refusal with pmcp logs
|
|
84
|
+
|
|
85
|
+
```sh
|
|
86
|
+
pmcp logs --since 15m --level warn --pretty
|
|
87
|
+
pmcp logs --session <id-prefix> --pretty
|
|
88
|
+
pmcp logs --trace <trace-id>
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Each hook call has a trace id; one trace shows every policy that ran, its verdict and
|
|
92
|
+
duration. Secret values, prompt text and environment values are redacted.
|
|
93
|
+
|
|
94
|
+
## Runtime differences
|
|
95
|
+
|
|
96
|
+
- Codex has no ask: a guard that would ask denies there.
|
|
97
|
+
- Codex sends no agent type, so roles apply only in Claude Code.
|
|
98
|
+
- Claude hears end-of-turn notices in the same turn; Codex at the next prompt.
|
|
99
|
+
|
|
100
|
+
## Report
|
|
101
|
+
|
|
102
|
+
What `pmcp sessions status` showed, which refusal or warning occurred and what it asked
|
|
103
|
+
for, the commands run instead (delivery or sync and their exit codes), and anything left for
|
|
104
|
+
the operator (a pause to lift, a lease still held, leftovers in the shared checkout).
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: skill-package-scaffold
|
|
3
|
+
description: Lay out one new skill folder that passes the Agent Skills specification - SKILL.md frontmatter within the limits pmcp validate enforces, references/, scripts/ and assets/ only where needed, and evals/ with a normal, an exception and a missing-information case - then gate it with pmcp validate. Use when creating the folder for a new skill, when pmcp validate rejects a skill, or when a skill needs its first eval cases. Not for deciding what the skill should teach or for packaging several skills as a plugin.
|
|
4
|
+
metadata:
|
|
5
|
+
tier: open
|
|
6
|
+
level: L2
|
|
7
|
+
domain: agent-workflow
|
|
8
|
+
install: optional
|
|
9
|
+
keywords: "SKILL.md, skill scaffold, Agent Skills specification, pmcp validate, skill frontmatter, skill evals"
|
|
10
|
+
requires-bin: "pmcp"
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Scaffolding one skill folder
|
|
14
|
+
|
|
15
|
+
This is the shape, not the content. What the body should say, and how to word a description
|
|
16
|
+
that triggers, is skill authoring (domain-skill-authoring covers it). Here the job is a
|
|
17
|
+
folder that every loader accepts and that carries its own test cases.
|
|
18
|
+
|
|
19
|
+
## Layout
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
<name>/
|
|
23
|
+
SKILL.md
|
|
24
|
+
references/ only files the body names, read on demand
|
|
25
|
+
scripts/ only code the body tells the agent to run
|
|
26
|
+
assets/ templates or files the output is built from
|
|
27
|
+
evals/
|
|
28
|
+
normal/prompt.md
|
|
29
|
+
exception/prompt.md
|
|
30
|
+
missing-info/prompt.md
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Create a directory only when something goes in it. An empty `scripts/` makes reviewers look
|
|
34
|
+
for code that is not there.
|
|
35
|
+
|
|
36
|
+
## Frontmatter limits
|
|
37
|
+
|
|
38
|
+
These are the checks `pmcp validate` runs (pmcp 0.8):
|
|
39
|
+
|
|
40
|
+
| Field | Rule |
|
|
41
|
+
| --- | --- |
|
|
42
|
+
| `name` | required; at most 64 characters; lowercase letters, digits and single hyphens, not starting or ending with one; equal to the directory name |
|
|
43
|
+
| `description` | required, non-blank; at most 1024 characters |
|
|
44
|
+
| `compatibility` | optional string; at most 500 characters |
|
|
45
|
+
| `license` | optional string |
|
|
46
|
+
| `allowed-tools` | optional; one space-separated string, not a list |
|
|
47
|
+
| `metadata` | optional map |
|
|
48
|
+
|
|
49
|
+
A marketplace may add its own rules on top (a metadata schema, tiers, ASCII-only text).
|
|
50
|
+
Check those separately; `pmcp validate` does not know them.
|
|
51
|
+
|
|
52
|
+
```markdown
|
|
53
|
+
---
|
|
54
|
+
name: invoice-dispute-reply
|
|
55
|
+
description: Draft a reply to a customer disputing an invoice ... Use when ... Not for ...
|
|
56
|
+
---
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Evals: three cases, each self-contained
|
|
60
|
+
|
|
61
|
+
| Case | Tests |
|
|
62
|
+
| --- | --- |
|
|
63
|
+
| normal | the common request, with every input present |
|
|
64
|
+
| exception | the input that should change the answer: a rule's exception, an edge value, a refusal |
|
|
65
|
+
| missing-info | a request lacking something essential; the skill must ask or state the assumption, not invent |
|
|
66
|
+
|
|
67
|
+
Each `prompt.md` must carry everything the case needs. The grader's sandbox starts empty, so
|
|
68
|
+
paste file contents into the prompt instead of naming a path. Write what PASS means next to
|
|
69
|
+
the prompt, as checkable statements, before writing the body.
|
|
70
|
+
|
|
71
|
+
## Gate
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
pmcp validate path/to/<name> # one folder; exit 1 on any error
|
|
75
|
+
pmcp validate --marketplace <dir> # every skill a marketplace reaches
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`pmcp validate` checks frontmatter and naming only. It does not run the eval cases; run
|
|
79
|
+
those with your eval harness, with and without the skill.
|
|
80
|
+
|
|
81
|
+
Size matters when the skill is served over MCP: the Skills extension lists a skill only if
|
|
82
|
+
it stays within 512 files and 16 MiB. Larger skills stay reachable through the tools.
|
|
83
|
+
Scripts are returned as text by catalog servers, never run by them.
|
|
84
|
+
|
|
85
|
+
## Report
|
|
86
|
+
|
|
87
|
+
The tree created, the `pmcp validate` output, and the three eval prompts with their PASS
|
|
88
|
+
statements.
|