skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
factorialco/factorial-code-skills346 installs

fcode-ama

Factorial Code platform user journey and support — from requesting access through app creation, OAuth setup, demo companies and the Test marketplace to releases and marketplace publication. Use when answering "how do I…" questions about using the platform, guiding a user through any journey stage, or acting as a Factorial Code support agent.

How do I install this agent skill?

npx skills add https://github.com/factorialco/factorial-code-skills --skill fcode-ama
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill is a documentation guide for the Factorial Code platform. It provides legitimate instructions for app development, testing, and deployment. No malicious patterns or security risks were identified.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

What does this agent skill do?

Factorial Code — platform guide (AMA)

Factorial Code (fcode) is Factorial's platform for building apps and automations against the Factorial Public API. This skill covers using the platform — the journey from requesting access to a published marketplace app — and how to behave when supporting users through it. For building the app itself (processes, modules, CLI, forms), route to the owning skills (see the routing table below).

The full stage-by-stage walkthrough is in references/journey.md; common problems and fixes are in references/troubleshooting.md.

Who you're helping

Four user roles use the platform. Establish which one you're talking to early — several flows diverge by role:

RoleWhoKey differences
Factorial internalDevelopers at FactorialCreate demo companies directly (using the Demo generator); Slack #factorial-code-users available
PartnerExternal companies building apps/integrations with FactorialDemo companies by request
Factorial CustomerA company that uses Factorial, building an app or automation for its own Factorial account — even when one person (say, an HR admin) does it aloneSame as Partner; usually wants a private installation in its own company rather than a marketplace listing (see "Private app installed for a specific company" under Escalation)
Individual ContributorAnyone else building outside a partner or a company that uses Factorial — e.g. someone doing a security auditSame as Partner

To tell the last two apart: building for the company that uses Factorial → Factorial Customer; otherwise → Individual Contributor.

"Factorial Customer" is a builder's team type. Everywhere else in this skill, customers are the companies that install an App. Never call a builder an "end customer".

OAuth credentials are created automatically for every role (stage 4 in references/journey.md).

All roles talk to Factorial through the Public API, and all belong to a development team: every app a team creates is shared by all its members. When someone requests access and an administrator sees their organization already has a team on the platform, they are added to that existing team.

Support-agent behavior rules

  • Answer only from documented flows — this skill, its references, the other fcode-* skills, and the public docs. Never invent UI elements, URLs, commands, or policies. If it isn't covered, say so and escalate.
  • Identify the user's role first when the answer differs by role.
  • Describe flows by page and section name (e.g. "the Getting started checklist on the App detail page"), not by exact button pixels — labels change; flows are stable.
  • Admin actions: outcome only. When a step is performed by an administrator (access approval, demo provisioning, release review), tell the user what they will observe and what to do next. Never describe admin-side mechanics or how credentials are delivered.
  • Answer in the user's language.
  • Fetch before deep-diving. When you have web access, read the linked docs page before answering a detailed question; the live docs win over this skill on details. Without web access, answer from this skill and say which docs page has more.
  • Escalate when needed — an admin action, a stuck request, or an uncovered question. Escalation paths are in the last section.

Platform map

Everything lives under https://code.factorialhr.com, split across three surfaces users often conflate:

  • Docs (/docs/...) — public documentation, plus the landing page with the request-access form.
  • App console (/dashboard/...) — apps, teams, demo companies, marketplaces, installations. Where the journey below happens.
  • Workspace console (/platform/...) — inside a workspace: processes, executions, schedules, variables, versions, API credentials. The app console links into it — every such jump is labelled "Open on platform"; for a deploy- (installation) workspace it lands on the executions page.

App console areas (the sidebar groups them into Build, Operate, and Admin sections):

AreaWhat it's for
AppsThe team's apps; where a new app is created
App detail pagePer-app home: the Getting started checklist and the Development / Production / Publication / README tabs
App settingsConfiguration (marketplace visibility, lifecycle) and OAuth (requested scopes plus the development and production credentials)
Demo companiesDemo Factorial companies for testing installs
Test marketplaceSimulation of the production marketplace, run against demo companies

Plus the self-describing Marketplace, Team, and Installations areas.

The journey at a glance

#StageWhereWhat happens
1Request accessLanding page → request-access formAn administrator reviews it and you're notified; joins an existing development team when one matches
2Create an AppApps → createName and purpose; language (JavaScript or Python); OAuth scopes; the integrations framework opt-in (decision rule in references/journey.md)
3Getting startedApp detail page checklistOrdered setup steps: build locally, link the Factorial integration (framework apps only), configure OAuth (when scopes were requested), publish a release, add marketplace metadata
4Configure OAuthApp settings → OAuth tabPer-environment client credentials for the OAuth flow (per-role setup in references/journey.md)
5Build locallyYour machineInstall the CLI, fcode clone the dev workspace (or fcode team:clone for every App of your team at once), code with your own agent + the fcode-* skills, test locally, fcode push
6Demo companyDemo companies pageInternal: create directly. Everyone else: request one; you're notified by email
7Test installsTest marketplaceRun the real OAuth flow with the demo company's credentials, install, exercise the install / settings / uninstall forms and any UI trigger buttons inside the demo company's Factorial
8ReleaseApp detail → Production tab, or fcode app:releases:requestRequest a release (semver + notes); the dashboard copies dev into the prod workspace, then a Factorial admin of the owning team or an operator marks it deployed (references/journey.md §8)
9Publish listingApp detail → Publication tab; workspace Settings › Factorial tabMarketplace listing metadata: a linked DatoCMS record and/or the fallback fields; the agent description One reads to pick the App (set on the prod workspace)
10ProductionMarketplaceVisible and installable; each install gets its own isolated workspace

Per-stage detail, per-role callouts, and lifecycle states: references/journey.md.

Workspaces behind the journey

Naming caution: a Factorial Code workspace is also called a "team" in the workspace console, in the platform API, and in a few CLI surfaces ("team variables", the parentTeams field) — that sense is unrelated to the development team of humans described above. The CLI's fcode team:* commands mean the development team: they operate on every App it owns (see fcode-cli).

Each app maps to workspaces (slugs carry an encoded token, not the raw id):

  • dev-{appId} — the development workspace you clone and push to.
  • prod-{appId} — production copy, created when the first release is requested. Treat its code as read-only — changes belong in dev and reach it through the release flow; only operators and the app's Factorial team admins can write to it at all. Its variables are live — shared defaults and credentials for all installations are managed there.
  • deploy-{installationId} — one per company installation, inheriting from the app workspace: it holds only that company's variables and executions, fully isolated from other companies. A change in the parent workspace is automatically available in every installation workspace.
  • base-app / base-integration-app (language-matched variants, -js/-py) — shared bases every app inherits: API clients, webhook/schedule/email/form helpers, and (for framework apps) the integration templates.

Released versions are pinned tags and the stable alias points at the current one (model in fcode-core-concepts). For a marketplace app, ship through the release flow (stage 8) — don't publish versions or move stable by hand.

Buttons inside Factorial — UI triggers

Besides forms and webhooks, an installed app can put its own buttons on Factorial's pages. Factorial teams declare locations in the product (a page header, an actions dropdown — e.g. calendar.header.admin); an app process that declares a uiTrigger for that location shows up there as a button, with the app's label and icon, for every company that installed the app. Clicking it runs the process with the page's context (the record on screen, the company), or opens the process's form when it has one — so a "Sync to Acme" action can live next to Factorial's native actions without Factorial shipping any integration-specific UI.

What to tell users:

  • It works only for installed marketplace apps — the buttons are read from the company's deploy- workspace, so a trigger reaches customers through the release flow (stage 8) like any other change; in development, the demo company shows the dev workspace's triggers (stage 7).
  • The location id comes from Factorial: there is no catalogue in the platform. A developer who wants a button on a page that has no location yet needs the owning Factorial team to add one — escalate as a product request.
  • Some locations admit one app at a time; installing a second app that claims such a location fails with a message naming the first.
  • Configuration lives on the process page (Trigger from Factorial, the section of a Factorial Action that also covers forms and, in later phases, Factorial One tools and backend jobs — fcode-factorial-actions) or in metadata.json; the developer-facing rules for the button are in fcode-ui-triggers.

Routing — where deep questions live

Question is aboutRoute to
Platform model: processes, modules, variables & inheritance, datastore/storage, versioning & stablefcode-core-concepts
CLI commands, metadata.json / settings.json fields, webhook auth, FACTORIAL_TOKENfcode-cli — docs: /docs/cli/
Writing process/module codefcode-javascript / fcode-python — docs: /docs/processes/
Input-parameter schemas (forms definition)fcode-json-schema
Embedding forms on webpages, themes, pre-fillfcode-forms — docs: /docs/forms/
Exposing a process to Factorial (factorial block, Factorial One tool contract, lifecycle slugs)fcode-factorial-actions — docs: /docs/factorial-actions/
Buttons inside Factorial (factorial.uiTrigger, locations, result envelope)fcode-ui-triggers
Recommended agent working method, MCP toolsfcode-agent — docs: /docs/mcp-server/
Worked examples (integration, inbound import, install/uninstall lifecycle)fcode-examples
Executions, schedules, webhooks at runtimedocs: /docs/executions/
Integrations framework (outbound)docs: /docs/building-apps/integrations-framework/
Inbound imports tracked as a sync run (InboundRecordSync)fcode-examples references/integration-inbound.md — docs: /docs/building-apps/inbound-sync/
OAuth & API tokensdocs: /docs/building-apps/oauth/
Workspace hierarchydocs: /docs/building-apps/workspaces/
Roles & permissions: who can read/write/promote per workspacereferences/journey.md §8 — docs: /docs/building-apps/permissions/
The end-to-end journey (public version)docs: /docs/building-apps/developer-journey/

Doc paths are relative to https://code.factorialhr.com.

Escalation & admin actions

NeedWhat to do
Access request pendingIt's under review; you'll be notified of the outcome
OAuth credentials missingCreated automatically: development when the App is created, production with its first release. If one hasn't appeared by then, escalate
Demo company (not Factorial internal)"Request a demo company" on the Demo companies page; you're emailed when it's ready
Release review outcomeThe release either deploys or you're notified of required changes; fix and request again (the same version, once the release is marked failed)
Promote a release to productionRequest it (Production tab or fcode app:releases:request, fcode-release): the copy into prod is automatic; a Factorial admin of the owning team or an operator marks it deployed — references/journey.md §8
Private app installed for a specific companyA production installation created from the App detail page — by an administrator or by a developer who provides the Factorial company ID (e.g. how Factorial's Forward Deployed Engineers roll out private apps)
Need a higher limit (execution time, concurrency, datastore, rate, …)Every workspace is on the same fixed plan — there is no self-service upgrade. Ask us: internal Factorial users in Slack #factorial-code-users, others through their Factorial contact. Current values: fcode-core-concepts › Plans & limits
Anything not coveredInternal Factorial users: Slack #factorial-code-users. Others: the in-platform request flows above

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/factorialco/factorial-code-skills/fcode-ama">View fcode-ama on skillZs</a>