{
  "markdown": "# Fulcrum AI Toolkit\n\nPortable AI skills for building apps, data events, reports, integrations,\nmapping, queries, access models, and migrations on the\n[Fulcrum](https://www.fulcrumapp.com) platform.\n\nBuilt around the open [Agent Skills standard](https://agentskills.io/specification) — skills are portable Markdown workflows with structured metadata that compatible AI agents load on demand.\n\n## Install\n\nThis repository is a marketplace containing the distributable\n`plugins/fulcrum-ai-toolkit/` package.\n\nIn Claude Code, add the marketplace and install the plugin:\n\n```bash\n/plugin marketplace add https://github.com/fulcrumapp/fulcrum-ai-toolkit.git\n/plugin install fulcrum-ai-toolkit@fulcrum-ai-toolkit\n```\n\nIn Codex, add the repository marketplace, then install\n`fulcrum-ai-toolkit` from the Plugins directory:\n\n```bash\ncodex plugin marketplace add fulcrumapp/fulcrum-ai-toolkit\ncodex plugin install fulcrum-ai-toolkit@fulcrum-ai-toolkit\n```\n\nIn GitHub Copilot CLI, add the marketplace and install the plugin:\n\n```bash\ncopilot plugin marketplace add fulcrumapp/fulcrum-ai-toolkit\ncopilot plugin install fulcrum-ai-toolkit@fulcrum-ai-toolkit\n```\n\nFor a standalone skills loader, target the packaged skills directory:\n\n```bash\nnpx skills@latest add https://github.com/fulcrumapp/fulcrum-ai-toolkit/tree/main/plugins/fulcrum-ai-toolkit/skills\n```\n\nYou can also copy or symlink individual skill directories from\n`plugins/fulcrum-ai-toolkit/skills/` into a host's documented project skill\ndirectory. `.agents/` is reserved for repository-scoped agent assets and\nmarketplace metadata.\n\nThe toolkit installs guidance skills only. It does not include Fulcrum App MCP\nor Fulcrum credentials. When separately registered, App MCP is the toolkit's\ndefault control plane for supported app configuration and knowledge operations.\nWithout it, `fulcrum-app-builder` stops at an approved implementation handoff.\nApp MCP covers forms, schema builders and validation, choices, classifications,\nprojects, layer metadata, webhooks, Reference Files, memberships and roles,\nReport Templates, and report generation. Query API execution, record CRUD, and\nmedia CRUD require another authorized interface.\n\nLive installed App MCP schemas define the connector tool contract and take\nprecedence over toolkit prose.\n\n## Start here\n\n1. Run `fulcrum-discovery` for a new workflow.\n2. Define the goal and deliverable with `fulcrum-app-goal`.\n3. Use `fulcrum-app-builder` and `fulcrum-app-design` to propose and approve a schema.\n4. Route integration, mapping, Query API, access, and migration decisions to\n   their focused skills.\n5. Build through Fulcrum App MCP when available, or use the approved handoff.\n6. Test the workflow and document the result with `fulcrum-solution-document`.\n\n## Alpha install matrix\n\nThe distributable package uses the portable\n`plugins/fulcrum-ai-toolkit/skills/*/SKILL.md` layout. Host-specific manifests\nare adapters inside that package and either discover the standard `skills/`\ndirectory or explicitly point to it when the host contract supports that field.\n\n| Host | Install path | Skills | Live Fulcrum actions | Alpha status |\n| --- | --- | --- | --- | --- |\n| Generic skills loader | Add `plugins/fulcrum-ai-toolkit/skills/` | Yes | No, connector required | Target |\n| Claude Code | Add the Claude marketplace, then install the plugin | Yes | Connector-dependent | Target |\n| Cursor | Install `plugins/fulcrum-ai-toolkit/` as a plugin | Yes | Connector-dependent | Target |\n| Codex | Add the repository marketplace, then install the plugin | Yes | Connector-dependent | Target |\n| GitHub Copilot | Add this marketplace, then install the plugin | Yes | Connector-dependent | Target |\n| Gemini | Install `plugins/fulcrum-ai-toolkit/` as an extension | Verify | Connector-dependent | Verify |\n| Hermes | Install `plugins/fulcrum-ai-toolkit/` as a plugin | Yes | Connector-dependent | Verify |\n| Claude Desktop | Copy `plugins/fulcrum-ai-toolkit/skills/` to the consuming repo and configure MCP separately | Yes | MCP-dependent | Later |\n\nThe `Target` and `Verify` labels describe the toolkit's intended alpha support,\nnot a claim that every host has been tested in this repository yet.\n\n## Local validation\n\nRuby 3.2.11 is required; compatible version managers can provision it from\n`.ruby-version`. Run the Ruby checks from the repository root:\n\n```bash\nruby scripts/validate.rb\nruby test/app_mcp_contract_test.rb\nruby test/manifest_contract_test.rb\nruby test/product_knowledge_decomposition_test.rb\nruby test/external_examples_test.rb\nruby test/resource_contract_test.rb\nruby test/smoke_test.rb\n```\n\nStructural and read-only SQL validation for the externalized examples and assets\nlives in `tools/format-validator`, a small Node package whose parsers are pinned\nexactly in `package.json` and `package-lock.json`. Install once, then run it\ndirectly or let the external examples test invoke it:\n\n```bash\nnpm ci --prefix tools/format-validator\nnpm run --prefix tools/format-validator validate\n```\n\nThe Ruby checks are dependency-free and run without Node; only the parser-backed\npass needs the pinned package, and CI sets `REQUIRE_NODE=1` so it can never be\nskipped there.\n\nThe validator checks the exact 16-skill inventory, skill frontmatter,\ndirectory/name consistency, corporate absolute paths, possible credentials,\nJSON manifests, and README inventory.\nThe contract test prevents regressions in App MCP tool names, signatures, and\npreservation-safe form updates. The decomposition test checks focused skill\ndiscovery, sources, router/coverage links, and package boundaries. The external\nexamples test proves that no fenced code block remains in skill Markdown, that\nevery `examples/` and `assets/` file is indexed and reachable, that each one\nnames a public source URL, that no example, asset, or index carries credential\nor private material, and that the legacy and current example inventories match\n`test/data/example-block-inventory.json` exactly, identifier by identifier. It\nalso requires the format validator's own counts back, so the work it delegates\ncannot quietly become work that is skipped. The resource contract test validates\nall distributable local links, resource ownership, public-source precedence,\nprivacy boundaries, exact layer-4 inventory and report hashes, and the 100 KB\nskill-resource snapshot limit without network access.\n\nValidation never runs anything this repository authors. HTML is parsed, its\ninline scripts and styles are parsed, a report template is compiled to source by\nthe pinned official EJS parser and then parsed, and CSS, PostgreSQL, JSON, and\nJavaScript are parsed. No template is rendered, no example script is executed,\nand no query is issued, so validation needs no sandbox and claims none. Files\nthat are not whole documents are labeled `Fragment:` and validated as such.\nBeyond well-formedness the validator decides two contracts: read-only SQL, and\nwhat a `QUERY()` call and its interpolation may be.\n\nNothing here proves that arbitrary EJS escapes safely or that a template renders\nto valid HTML. No branch analysis is performed and none is claimed. What the\nreport templates must contain is stated instead as repository example checks\nover this repository's own fixed set of twelve templates.\n\nEvery SQL statement — in a `.sql` asset or in a report template's `QUERY()`\ncall — is held to allowlists applied to the parsed PostgreSQL tree: SELECT only,\none statement per `QUERY()` call, and an exact set of node forms, operators, cast\ntargets, and functions taken from what the examples actually use. So a write\nhidden after a semicolon, inside a CTE, behind a comment, or in a quoted function\nname is rejected, and `::application_side_effect_type`, `@@`, `SELECT ... INTO`,\nan unrecognized function, and a second statement riding along in one call all\nfail closed.\n\nEvery report template is turned into JavaScript, parsed, and walked to find its\n`QUERY()` calls, so a call written with a double-quoted string, an interposed\ncomment, or a newline cannot escape the check. The helper is also reachable\nthrough the locals bag `ejs` opens with `with`, so `locals.QUERY(...)` and\n`locals['QUERY'](...)` are read the same way, and everything that could hide a\ncall — a name referenced without being called, a computed property that is not a\nliteral, the locals bag used as a value, `eval`, `Function`, `arguments`,\n`constructor`, `prototype`, `globalThis`, `Reflect` — is refused rather than\nguessed at.\n\nReading a statement means replacing each `${...}` with a placeholder, and a\nplaceholder is only earned. A gap is accepted only when it is one of two\nrecognized encoders written in the gap itself and inside quotes —\n`('' + value).replace(/[^0-9-]/g, '')` for a date literal and\n`('' + value).replace(/[^A-Za-z0-9_-]/g, '')` for an identifier literal — and\neverything else is refused, including a value sanitized further up and a class\nthis list does not name. The examples convert with `('' + value)` rather than\n`String(value)` because `String` is an ordinary binding inside a template;\nrebinding or overwriting `String` or `RegExp` — through `const`, a parameter, a\n`catch` clause, an assignment, or a prototype — is refused in any case. Each\nrecognized class is measured on every run against the characters it actually\nkeeps, so it cannot be widened without the check that depends on it failing.\n\nThe report templates are a fixed, checked-in set. `test/data/example-block-inventory.json`\nlists each one by path, pins it by SHA-256, and declares whether it is a whole\ndocument or a fragment, so adding, renaming, or editing a template requires a\nvisible inventory update in the same change. Each template must also compile and\nparse, and must use neither a raw output tag nor an EJS output internal, both\nchecked as the literal text they are. The date-range example carries per-file\nassertions for the table wrapper that was reviewed by hand: its `<table>`,\n`<thead>`, and `<tbody>` open before its row branches and close after them, and\neach branch writes a complete row. These are checks on this repository's\nexamples; they generalize to nothing else. Bypass probes for the SQL and\n`QUERY()` contracts run on every invocation, on the same code paths the\nrepository's own files take. The smoke test exercises a small site-inspection\nworkflow through discovery, schema approval, offline review, and the no-MCP\nhandoff path.\n\n## Skills\n\n| Skill | Description | Type |\n| ------- | ------------- | ------ |\n| `fulcrum-product-knowledge` | Fulcrum platform capability router, constraints, plans, boundaries, and App MCP build reference | Model-invoked |\n| `fulcrum-integration-patterns` | Workflow and integration selection, webhooks, URL Actions, REST, middleware, and delivery safety | Model-invoked |\n| `fulcrum-gis-mapping` | GIS/layer selection, online/offline mapping, geometry, and import/export boundaries | Model-invoked |\n| `fulcrum-query-api` | Read-only Query API modeling, metadata discovery, safe SQL parameters, and spatial-query boundaries | Model-invoked |\n| `fulcrum-access-management` | Roles, resource access, memberships, SSO/SCIM, and least-privilege reasoning | Model-invoked |\n| `fulcrum-data-migration` | Supported migration assessment, mapping, dry runs, reconciliation, cutover, and rollback design | Model-invoked |\n| `fulcrum-app-builder` | Novice-friendly app discovery, schema approval, App MCP orchestration, and connector-independent handoff | Model-invoked |\n| `fulcrum-app-design` | App structure, field types, linked apps vs single app, repeatables | Model-invoked |\n| `fulcrum-app-goal` | Ensure every app has a clear goal and defined deliverable | Model-invoked |\n| `fulcrum-safety` | Flag missing safety steps in field workflows | Model-invoked |\n| `fulcrum-data-events` | Data event patterns, anti-patterns, and platform constraints | Model-invoked |\n| `fulcrum-workflow-decomposition` | Break monolithic apps into composable, maintainable pieces | Model-invoked |\n| `fulcrum-app-extensions` | App extension anatomy, FS bridge API, offline support, picker anti-pattern | Model-invoked |\n| `fulcrum-report-building` | Report template authoring — EJS tags, repeatables, parameters, debugging | Model-invoked |\n| `fulcrum-discovery` | Process discovery before building — interview the customer | User-invoked |\n| `fulcrum-solution-document` | Post-build documentation, privacy review, and destination-neutral sharing formats | User-invoked |\n\n## Usage\n\nSkills are **model-invoked** by default: the agent fires them automatically when building Fulcrum apps. The agent will:\n\n- Use the platform router for capability, plan, public AI, offline, and App MCP\n  boundary decisions (`fulcrum-product-knowledge`)\n- Select Workflows, webhooks, URL Actions, REST, and middleware safely\n  (`fulcrum-integration-patterns`)\n- Verify current GIS, layer, geometry, and online/offline mapping support\n  (`fulcrum-gis-mapping`)\n- Model read-only SQL from discovered Query API metadata\n  (`fulcrum-query-api`)\n- Design role plus resource access and SSO/SCIM lifecycle controls\n  (`fulcrum-access-management`)\n- Plan supported migrations with dry-run, reconciliation, and rollback evidence\n  (`fulcrum-data-migration`)\n- Guide app discovery, schema approval, and App MCP-dependent execution (`fulcrum-app-builder`)\n- Check that every app has a clear goal before building (`fulcrum-app-goal`)\n- Select appropriate field types and app structure (`fulcrum-app-design`)\n- Flag missing safety steps in field workflows (`fulcrum-safety`)\n- Apply data event best practices and avoid anti-patterns (`fulcrum-data-events`)\n- Recommend decomposition when apps grow too complex (`fulcrum-workflow-decomposition`)\n- Apply extension best practices and avoid the picker anti-pattern (`fulcrum-app-extensions`)\n- Guide report template authoring with correct EJS patterns and parameter handling (`fulcrum-report-building`)\n\nTwo skills are **user-invoked** — run them manually:\n\n- `fulcrum-discovery` — start a new project by interviewing the customer before building\n- `fulcrum-solution-document` — after building, document what was built, review it for privacy, and prepare it for a destination chosen by the user\n\n## Where this comes from\n\nThe toolkit combines public Fulcrum documentation with portable workflow\nguidance. Live App MCP schemas own connector names, arguments, and result\nshapes; public Fulcrum documentation owns product and runtime behavior.\n\nDistributable provenance uses `> Source:` notes with a public URL. The legacy\ncoverage manifest may instead use its neutral `Inventory fingerprint:` label.\nNamed people, customers, and non-public research attribution are not valid\npublic provenance. Validation enforces these structural cues across packaged\ntext, including dotfiles; it is not a general-purpose personal-data detector.\n\nThe five layer-3 product skills prohibit any triple-backtick or triple-tilde\ntoken anywhere in a packaged regular file. This intentionally simple rule is\nstricter than Markdown fence parsing; later layers own executable examples and\ntheir durable externalization policy.\n\n### Sources\n\n- [Fulcrum developer documentation](https://docs.fulcrumapp.com/) for public\n  platform behavior and runtime functions.\n- [Fulcrum public OpenAPI document](https://raw.githubusercontent.com/fulcrumapp/api/v2/reference/rest-api.json)\n  for REST resource shapes.\n- Live installed App MCP schemas for the connector control-plane contract used\n  by the current workflow guidance.\n\nThe [legacy product-knowledge migration coverage map](plugins/fulcrum-ai-toolkit/docs/legacy-product-knowledge-coverage.md)\ntracks every legacy domain, its canonical target, public sources, and material\nthat must remain private or be dropped.\n\n### Skill format\n\nSkills follow the [Agent Skills specification](https://agentskills.io/specification):\neach distributable skill under `plugins/fulcrum-ai-toolkit/skills/` is a\ndirectory containing a `SKILL.md` with YAML frontmatter (`name` and\n`description`) plus a Markdown body. The optional invocation fields are\nretained where supported by a host and ignored elsewhere.\n\n### Platform support\n\nPlugin configs are included for multiple AI platforms:\n\n| Platform | Config |\n| ---------- | -------- |\n| GitHub Copilot CLI | `.github/plugin/marketplace.json` and `plugins/fulcrum-ai-toolkit/plugin.json` |\n| Claude Code | `plugins/fulcrum-ai-toolkit/.claude-plugin/plugin.json` |\n| Cursor | `plugins/fulcrum-ai-toolkit/.cursor-plugin/plugin.json` |\n| Codex | `plugins/fulcrum-ai-toolkit/.codex-plugin/plugin.json` |\n| Hermes | `plugins/fulcrum-ai-toolkit/.hermes-plugin/` |\n| Gemini | `plugins/fulcrum-ai-toolkit/gemini-extension.json` |\n| MCP | `plugins/fulcrum-ai-toolkit/.mcp.json` |\n\nAll hosts discover or reference the package's shared `skills/` directory; they\ndo not maintain separate copies of skill content. GitHub Copilot marketplace\nmetadata is available at `.github/plugin/marketplace.json`; the same catalog is\nalso available at `.claude-plugin/marketplace.json` for Claude and Copilot's\nfallback lookup. The legacy root `marketplace.json` is kept for existing\ninstallers. Codex marketplace metadata is available at\n`.agents/plugins/marketplace.json` and points to the package under `plugins/`.\n\n## References\n\n- [Agent Skills specification](https://agentskills.io/specification)\n- [Claude Code plugins](https://code.claude.com/docs/en/plugins)\n- [Claude Code plugin manifest reference](https://code.claude.com/docs/en/plugins-reference#plugin-manifest-schema)\n- [OpenAI plugin skills](https://developers.openai.com/plugins/build/skills)\n- [OpenAI plugin packaging](https://developers.openai.com/plugins/build/plugins)\n- [GitHub Copilot agent skills](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills)\n- [Vercel skills CLI](https://github.com/vercel-labs/skills)\n- [Fulcrum developer documentation](https://docs.fulcrumapp.com/)\n\n## Contributing\n\nInternal contributors: PS, CS, and platform engineers. Open a PR with new skills or improvements.\n\nSkills should encode patterns you've seen work (or fail) across multiple customer engagements — not one-off configurations. If you've built the same kind of app three times, there's a skill in there.\n\n## License\n\nMIT\n",
  "bytes": 18253,
  "sha": "65a6842bd5e00e7ac25d8a0023d5afe467acd162b0d59c70df56478eb93336bc",
  "repo_slug": "fulcrumapp/fulcrum-ai-toolkit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_fulcrumapp_fulcrum_ai_toolkit_3b2e36ce/readme"
}