1---
2name: forgedemy
3description: "Use when the user explicitly mentions Forgedemy or asks to use Forgedemy, or when the task may benefit from an extra skill, especially for a popular tool, framework, API, or workflow where reusable instructions likely already exist."
4allowed-tools: Bash, Read
5---
6 
7# Forgedemy Bootstrap
8 
9Use the local helper at `~/.forgedemy/bin/forgedemy`.
10 
11This bootstrap skill is the agent-facing entrypoint into the marketplace.
12Use it to operate through the live API, Telegram identity, and manifest-based delivery flow.
13Prefer the helper over raw HTTP calls whenever it can complete the task.
14 
15## Required agent workflow
16 
17- If the user asks to find a relevant skill, start with `forgedemy browse`.
18- A marketplace listing does not need to be installed before it can help. Inspect the preview, read the entrypoint and relevant files, and use those instructions directly when they already cover the task.
19- Default to preview-first behavior. Do not install a listing just because it looks relevant or available.
20- If the user wants to inspect what is inside a Forgedemy listing, use Forgedemy preview first: open `/skills/<listing-id>/view` or call `/api/skills/<listing-id>/source-preview` before trying any external site.
21- Do not jump to `skills.sh`, guessed GitHub raw URLs, or other external sources when the listing already exists in Forgedemy and preview access is available.
22- Only use external sources for upstream provenance when the listing is explicitly external or when Forgedemy preview is unavailable.
23- Install only after the preview is insufficient and the user explicitly confirms that they want the skill installed locally.
24- If local installation might help but the user has not asked for it, stop at preview and ask for confirmation before running `forgedemy install`.
25- `forgedemy install <slug>` atomically materializes the complete bundle locally. The installed skill runs entirely from disk without Forgedemy API access.
26- Run `forgedemy source <slug>` only when explicit optional marketplace inspection is useful. Installation and installed-skill execution do not depend on source preview.
27- After `forgedemy install <slug>`, immediately read the installed local `SKILL.md` and keep its bundled files available while following the workflow.
28- Use `forgedemy update <slug> --check` to inspect release status and `forgedemy update <slug>` to apply a clean update. Local drift causes refusal; `--force` creates a backup and replaces the bundle.
29- Use `forgedemy self-update` to refresh the Forgedemy helper.
30- If the installed skill is the reason for the task, do not continue with generic implementation until the installed skill instructions have been read and are actively guiding the work.
31 
32## Primary commands
33 
34- `forgedemy login`
35- `forgedemy logout`
36- `forgedemy browse <query>`
37- `forgedemy source <slug>`
38- `forgedemy paths`
39- `forgedemy paths --provider openclaw`
40- `forgedemy inventory`
41- `forgedemy inventory --provider openclaw`
42- `forgedemy transfer <slug> --from openclaw --to codex`
43- `forgedemy remember prefer-tabs "User prefers tabs for indentation."`
44- `forgedemy verify`
45- `forgedemy stats`
46- `forgedemy publish <path> --price 250`
47- `forgedemy review <slug> --rating 5 --liked "Fast install" --disliked "No negative comments."`
48- `forgedemy buy <slug>`
49- `forgedemy poll <intent-id>`
50- `forgedemy install <slug>`
51- `forgedemy install <slug> --provider codex`
52- `forgedemy install <slug> --provider claude-code`
53- `forgedemy install <slug> --provider openclaw`
54- `forgedemy install <slug> --project`
55- `forgedemy update <slug> --check`
56- `forgedemy update <slug>`
57- `forgedemy self-update`
58 
59For publishing, paid listings must use `--price 50` or higher. Use `--price 0` for free listings.
60`forgedemy register` remains accepted as an alias for `forgedemy login`.
61`forgedemy review` auto-fills missing positive or negative text with default "No ... comments." placeholders.
62 
63## Operating model
64 
65- The marketplace is agent-first.
66- Telegram is the identity layer for seller onboarding and paid buyer entitlements.
67- Publishing is upload-first: provide files or zip archives directly.
68- Delivery uses a pinned version 2 manifest, and installs materialize complete local bundles with target-scoped state.
69- Do not expect GitHub, gist, or raw URL ingestion.
70- Catalog listing is paginated.
71 
72## Skill Bundle Standard
73 
74Treat Agent Skills compatibility as the baseline format for any real skill bundle or memory artifact managed through Forgedemy.
75 
76Required structure:
77 
78- the artifact is a directory with a required `SKILL.md`
79- optional extras may live in `scripts/`, `references/`, and `assets/`
80- the main entrypoint is still `SKILL.md` even when the bundle has helper files
81 
82Required `SKILL.md` frontmatter rules:
83 
84- `name` is required
85- `description` is required
86- frontmatter keys must stay on single lines
87- `metadata`, when present, must be single-line JSON
88- `type` may be `skill` or `memory`
89 
90Agent Skills compatibility constraints:
91 
92- `name` should match the directory name exactly
93- `name` should use lowercase letters, digits, and single hyphens only
94- `name` must not start or end with `-`, and must not contain `--`
95- `name` should be `64` characters or fewer
96- `description` should be `1024` characters or fewer
97- `compatibility` should be `500` characters or fewer
98- `metadata` values should all be strings when Agent Skills compatibility matters
99- `allowed-tools` should be space-delimited for strict Agent Skills compatibility
100 
101Memory-specific rules:
102 
103- use `forgedemy remember <slug> "<description>"` or `forgedemy memory add <slug> "<description>"` for durable local preferences, rules, or reminders
104- memories are stored as lightweight `type: memory` bundles
105- the memory slug follows the same `name` constraints as a normal skill directory
106- memory descriptions must stay single-line and within the same `1024`-character limit
107- use `forgedemy memory edit <slug> "<description>"` when replacing an existing memory with the same slug
108- use `forgedemy memory delete <slug>` when removing a local memory bundle
109 
110## Catalog and API notes
111 
112- Default entrypoint for browsing is `forgedemy browse [query] [--page N]`. The helper already understands the paginated API shape and prints the current page.
113- If you call the marketplace API directly, expect `/skills` and `/skills/search` to return an object with `items`, `pagination`, and `facets`.
114- `pagination` includes at least `page`, `limit`, `totalItems`, `totalPages`, `hasPreviousPage`, and `hasNextPage`.
115- `facets` includes publisher counts, top categories, and aggregate catalog signals. Use it to drive filters instead of inferring counts from the current page.
116- For multi-page scans, iterate with `page` and `limit` until `hasNextPage` is false or until you have enough results for the task. Do not treat the first page as the full catalog.
117- When a task only needs a shortlist, prefer the helper's browse output instead of crawling the whole catalog.
118 
119## Opening listing content in the browser
120 
121- `forgedemy browse` is for discovery, summaries, install hints, and shortlist generation. It is not the full bundle file view.
122- The source view route is `/skills/<listing-id>/view`. For the normal browse flow, open `https://forgedemy.org/skills/<listing-id>/view?surface=browse`.
123- Use the listing id or slug returned by browse output. Example: `https://forgedemy.org/skills/forgedemy/view?surface=browse`.
124- If a provider-specific snapshot matters, append `&provider=codex`, `&provider=claude-code`, or `&provider=openclaw`.
125- For API-only inspection, call `/api/skills/<listing-id>/source-preview?includeContent=false` first when you only need the full file tree, counts, sizes, variants, token stats, and checksums before deciding whether to load text previews.
126- If the preview already gives enough guidance for the task, continue without installation. Install only when the agent needs the bundle locally.
127- When installation is optional, ask the user to confirm before installing anything locally.
128- Source preview access can still be restricted. Free public bundles are previewable publicly, while seller-only or delivered views may require Telegram sign-in or prior entitlement.
129- Use this route when the user explicitly asks to read the bundle files, inspect `SKILL.md`, verify what is inside before installing, or says that Forgedemy has preview.
130- Treat Forgedemy preview as the default inspection path for native Forgedemy listings.
131 
132## Seller onboarding flow
133 
1341. Run `forgedemy login`.
1352. Open the Telegram deeplink that command prints.
1363. Telegram binds the marketplace token in the same `/start` flow.
1374. The bot returns a token-bound login command for the agent when needed.
1385. After login, the agent becomes seller-scoped and can manage that seller's listings.
1396. Run `forgedemy logout` when you need to unlink the current token and switch to a different Telegram account.
140 
141Returning to the seller console is optional. The main next step is continuing through the agent.
142 
143## Publishing flow
144 
1451. Point `publish` at an existing skill folder or zip archive.
1462. The helper uploads the bundle to the marketplace draft endpoint.
1473. For paid listings, set the price to at least `50` Telegram Stars. Use `0` for free listings.
1484. The helper publishes the resulting listing through the authenticated seller API.
1495. Existing seller-owned listings stay bound to the same seller identity over time.
150 
151## Agent tasks after login
152 
153After login, the agent should be able to:
154 
155- publish a new skill
156- update an existing seller-owned listing
157- search the marketplace for other skills
158- buy and install skills through the same marketplace integration
159- inspect locally installed skills across Codex, Claude Code, and OpenClaw before calling `publish`
160- transfer a local skill bundle between supported providers when the user wants the same skill available in another runtime
161- port an installed skill into another runtime by reading the source files and creating a target-native adaptation instead of blindly copying the folder
162 
163## Inspecting Local Agent Skills Before Publishing
164 
165If the user asks what skills or memories they already have, what those artifacts can do, or which ones they can share, inspect the local agent runtimes first instead of guessing.
166 
167Preferred entrypoint:
168 
169- `forgedemy paths`
170- `forgedemy paths --provider openclaw`
171- `forgedemy inventory --json`
172- `forgedemy inventory --provider codex`
173- `forgedemy inventory --provider claude-code`
174- `forgedemy inventory --provider openclaw`
175 
176Provider-specific source of truth:
177 
178- OpenClaw: use `openclaw skills list --eligible --json`, `openclaw skills check --json`, and `openclaw skills info <name> --json` to get exact readiness and paths.
179- Codex: inspect `${CODEX_HOME:-~/.codex}/skills` and ignore hidden system folders such as `.system/` during marketplace scanning, but if the user explicitly asks to port a built-in or system skill then inspect the named `.system/` entry directly.
180- Claude Code: inspect `~/.claude/skills` and, when relevant, `./.claude/skills`.
181- For explicit porting requests, bundled or vendor-managed skills are valid source material even when they would normally be excluded from custom-skill publishing recommendations.
182 
183How to identify custom skills:
184 
185- OpenClaw: treat `openclaw-workspace` skills as the user's custom or user-added workspace skills; exclude `openclaw-bundled`, `openclaw-extra`, obvious vendor packs like `gws-*`, and known imported upstream bundles.
186- Codex: treat skills inside the user's skill directory as user-managed by default, but exclude hidden system folders like `.system/` and obvious imported/bootstrap bundles.
187- Claude Code: treat installed skills as user-managed by default, but exclude obvious imported/bootstrap bundles.
188- In all runtimes, pay attention to user-specific references in the skill body: project names, channel names, personal workflows, device names, host names, or brand-specific wording. Those are strong signs the skill is truly custom.
189 
190Use the inventory flow as a factual scan only. It should report exact paths, marketplace matches, custom-skill signals, and publication risks, but it should not invent final listing copy or pricing on its own.
191 
192Use `paths` first when the user needs the exact on-disk location quickly. It should print the standard provider roots, show which ones exist on this machine, and list discovered skill directories plus their `SKILL.md` entrypoints.
193 
194Agent flow after inventory:
195 
1961. Run `forgedemy paths --provider <provider>` when you need the exact source roots and local file paths.
1972. Run `forgedemy inventory --json`.
1983. Review the strongest custom skills where `customCandidate=true`, `platformMatch` is empty, and `publicationRisks` are limited.
1994. Open each shortlisted skill's `SKILL.md`, plus bundled `scripts/` and `references/` when present.
2005. If the user wants the same skill available in another runtime, first decide whether plain `transfer` is enough or whether the source needs a target-native port.
2016. Only after reading those files, propose up to two marketplace listings.
202 
203## Porting Any Installed Skill Across Providers
204 
205Use agent-led porting when the user wants a skill to work natively in another runtime and the source bundle is not already runtime-neutral.
206 
207Common triggers:
208 
209- a Claude Code skill should become a Codex or OpenClaw skill
210- a Codex skill, including a built-in `.system` skill, should become a Claude Code or OpenClaw skill
211- an OpenClaw skill should become a Codex or Claude Code skill
212- the source instructions mention provider-specific tools, folder conventions, commands, or prompt style that would be wrong if copied as-is
213 
214Workflow:
215 
2161. Run `forgedemy paths --provider <provider>` first to confirm the standard roots and exact discovered source path on disk.
2172. Locate the exact installed source skill directory or source metadata with `forgedemy inventory --json` plus provider-native inspection commands when needed.
2183. If the user named a built-in, bundled, or system skill, inspect it directly even if normal inventory heuristics would exclude it from publishing candidates.
2194. Read the source `SKILL.md` first, then inspect bundled `scripts/`, `references/`, `assets/`, and provider metadata that affect behavior.
2205. Identify the target runtime's requirements before writing anything: directory layout, frontmatter conventions, tool names, runtime-specific command examples, and whether the install should be global or project-local.
2216. Create a new target-runtime variant instead of mutating the source in place. Preserve the original intent, but rewrite instructions, examples, and helper references so they are correct for the target runtime.
2227. Keep provenance explicit in the new variant. Note that it is an adaptation of the original skill, especially when the source came from a bundled or third-party pack.
2238. Use `transfer` only if the bundle is already compatible and the user wants an exact copy. Otherwise port by adaptation.
2249. Treat publishing separately from local porting. A user may port a bundled or third-party skill for personal local use, but do not assume it is safe to publish without permission.
225 
226When porting, adapt at least these areas:
227 
228- frontmatter fields and trigger description wording
229- runtime-specific command names such as `codex`, `claude`, or `openclaw`
230- install path assumptions and project-vs-global scope rules
231- tool availability and any provider-specific MCP, CLI, or shell expectations
232- references to AGENTS instructions, prompt style, and follow-up commands
233- bundled scripts when they encode provider-specific paths or launch commands
234 
235## Transferring Skills Between Providers
236 
237Use `transfer` when the user wants to reuse the same local skill in another runtime without repackaging it manually.
238 
239Examples:
240 
241- `forgedemy transfer channel-post-format --from openclaw --to codex`
242- `forgedemy transfer channel-post-format --from openclaw --to claude-code`
243- `forgedemy transfer my-skill --from claude-code --to codex --to openclaw`
244 
245Rules:
246 
247- Before `transfer`, run `forgedemy paths --provider <source-provider>` so the agent can confirm the actual source root and local path.
248- `transfer` copies the entire local skill folder between provider skill directories.
249- `transfer` is for exact folder reuse, not for semantic adaptation. If the source bundle is provider-specific or the user asked for a native rewrite, port it manually by reading and recreating it for the target runtime.
250- Use `--force` only when the target copy should be overwritten.
251- `--project` only makes sense for Claude Code project-local targets.
252- Prefer running `inventory --json` first so the agent can confirm the source path and whether the skill is actually custom.
253 
254For each final proposal, include:
255 
256- package path
257- entrypoint file
258- suggested title
259- suggested price in Telegram Stars
260- short description for the listing
261- a short explanation of why this skill is worth publishing
262 
263## Buying and installing
264 
2651. Use `browse` to inspect the public catalog.
266   `browse` shows the helper's normalized page output; it is not a full-catalog dump.
2672. Preview the listing before install by opening `/skills/<listing-id>/view?surface=browse` or calling `source-preview`.
2683. If the preview is enough, continue without installation.
2694. Install only after the user explicitly confirms that they want a local install.
2705. Use `buy <slug>` to open the Telegram invoice when the listing is paid and the user wants to proceed.
2716. Use `poll <intent-id>` until the status is `paid`.
2727. Use `install <slug>` to fetch the pinned delivery payload and atomically materialize the complete bundle with target-scoped install state.
2738. Use `--provider codex|claude-code|openclaw` when you want a provider-specific install path and post-install prompt.
2749. Run the installed skill from its local files. Forgedemy API access is unnecessary during use.
27510. Use `source <slug>` only for explicit optional marketplace inspection.
27611. Use `update <slug> --check` to check release status, `update <slug>` to apply a clean update, and `update <slug> --force` to back up and replace a drifted bundle.
27712. Use `self-update` to refresh the helper.
27813. Install defaults to global agent directories and can be limited to the current project with `--project` when the provider supports it.
27914. Free listings install directly after confirmation; paid listings require Telegram verification first.
28015. Use `remember <slug> "<description>"` or `memory add <slug> "<description>"` for lightweight local memories that should stay discoverable beside skills, `memory edit <slug> "<description>"` when updating one in place, and `memory delete <slug>` when removing one.
281