Ecosystem architecture
Skribly is a local-first workbench for people and coding agents. It gives them one tracker, one look and one honest record of the work, with no account needed to start and nothing leaving your machine unless you send it. Status as of 8 November 2026.
What makes it different
Section titled “What makes it different”- Local first, no account. Skribly Agent runs on your machine with no account and no telemetry.
- Every agent. It works with the coding agents you already use, on your own logins, through open standards.
- The task lives in your repository. An issue from Jira, Redmine, GitHub, GitLab, Linear or Skribly Tracker becomes
TASK.mdandSTATE.mdin the repository, so any tool can read it. - A tracker built for agents. Skribly Tracker’s REST API maps one call to one action of an agent’s tracker client.
- Your style, your history. Commits follow the repository’s own style and never get AI co-author trailers.
Products
Section titled “Products”| Product | What it is | Status |
|---|---|---|
| Skribly Agent | Desktop app that runs many coding agents side by side, turns issues into task files, and shows which agent is working, waiting for you or done | Available, v1.0.37 |
| agent-skills | A library of 29 skills and a small installer for seven coding agents, in the shared Agent Skills format | Available to the team, v0.2.11 |
| Skribly Tracker | Issue tracker with a REST API and signed webhooks, designed for people and agents together | First release, 0.1 |
@skribly/core |
Shared contracts, API client, webhook signing, the event envelope, identity and scopes, app manifests, the project profile, errors, config, translations | v0.2.0 |
@skribly/ui |
Design tokens, plain CSS classes and React components for one look everywhere | First version |
| skribly.pl | The product site | Live |
| docs.skribly.pl | This documentation | Live |
The workflow
Section titled “The workflow”Skribly Tracker Skribly Agent Coding agents(or Jira, Redmine, task branch or worktree, runs Claude Code, Codex, GitHub, GitLab, ──────▶ TASK.md and STATE.md, ──────▶ Cursor Agent, Gemini CLI Linear) an agent session and nine more ▲ │ │ comment, status, time rules │ changes │ agent-skills ─────────▶│ │ tests, reviews, ▼ └──────────────────────────────────── audits, commits You review the diff and the audit results- Plan. A task starts in Skribly Tracker or arrives from Jira, Redmine, GitHub, GitLab or Linear.
- Start. One action in Skribly Agent creates the branch, saves the task to
.skribly/tasks/<KEY>/TASK.mdand starts an agent with a ready prompt. - Agents work. Each one can run in its own Git worktree, and the app shows who is working, waiting or done.
- Rules apply. Tests, reviews, audits and commit style come from one skill library, agent-skills.
- Review. You read the changes and the security, WCAG and SEO audit results.
- Close. You accept the commit and add the comment and logged time to the task.
agent-skills needs nothing else to work: it is a standalone library for any repository and any of the seven agents it supports. Skribly Agent works with trackers other than Skribly Tracker, and Skribly Tracker’s API works with any HTTP client.
How the apps connect today
Section titled “How the apps connect today”| From | To | How |
|---|---|---|
| Skribly Agent | Skribly Tracker, Jira, Redmine, GitHub, GitLab, Linear | Each tracker’s REST API with a token stored in the system keychain. See Tasks and trackers. |
| Skribly Agent | agent-skills | Clones the skills repository, reads skills.json and installs skills per project and per agent through the agent-skills CLI. |
| Skribly Agent | coding agents | Starts each agent’s own CLI in a terminal or in headless mode, and passes SKRIBLY_TRACKER_URL and SKRIBLY_TRACKER_TOKEN to the session. |
| agent-skills | Skribly Tracker and five other trackers | agent-skills tasks fetch reads issues with a personal token. See Trackers. |
| agent-skills | @skribly/core |
.skribly/project.json follows the project profile schema of @skribly/core, copied into agent-skills so it keeps no runtime dependencies. agent-skills tasks event prints the skills.task.completed event in the core format; it sends nothing. |
| Skribly Tracker | any service | Signed webhooks for issue.created, issue.updated, issue.deleted and comment.created. |
| Every Node app | @skribly/core, @skribly/ui |
Shared packages for contracts, the Tracker client, webhook signing and the look. See How apps connect. |
Apps never import each other. They talk over HTTP, and the shapes of what they send are defined once in @skribly/core.
Shared packages
Section titled “Shared packages”@skribly/coreconnects everything. It holds the contracts the apps speak: the Tracker API v1 schemas, the Tracker client, webhook signing and verification, RFC 9457 problem errors, environment config, logging and translations. Since 0.2.0 it also defines the shared building blocks below as schemas and helpers: identity and scopes, the CloudEvents envelope, app manifests, notifications, the audit log and the project profile. The apps do not use most of them yet.@skribly/uigives one look. Three layers: design tokens, plain CSS classes for any page, and React components built on React Aria for keyboard and screen reader behaviour. A later framework change replaces only the top layer. This site uses the tokens and the plain classes.
Planned building blocks
Section titled “Planned building blocks”These are designs, not features you can use in the apps today. Where @skribly/core 0.2.0 already defines the shapes, the status says so; a schema in the shared package is not yet a feature of an app.
| Block | Design | Status |
|---|---|---|
| Identity | One account per person, organisations with the roles admin, member and viewer. Apps sign in through OAuth 2.1. Integrations belong to the organisation, not to whoever installed them. |
Planned; users, organisations and memberships are defined in @skribly/core |
| Tokens | Personal tokens for people writing scripts. Apps and agents get short-lived tokens limited to chosen projects and actions, and act as a visible bot. | Planned; personal tokens exist in Skribly Tracker today, and @skribly/core defines scopes such as tracker.issues:write |
| Events | One envelope in the CloudEvents 1.0.2 format, with dot-delimited types such as issue.updated, the actor (person, agent or app) and what changed. The same stream feeds webhooks, the inbox, activity feeds, the audit log and search. |
The envelope and the event catalogue are in @skribly/core; no app sends them yet. See Events |
| Webhooks | Signed the Standard Webhooks way: an id, a timestamp and a signature over both, secret rotation without downtime, and retries over about a day. | Planned; HMAC-SHA256 signing exists today |
| App manifests | Each app describes itself in one file: name, address, navigation, commands, widgets, events and permissions. | Planned; a first manifest schema and registry are in @skribly/core |
| Command palette | Cmd/Ctrl+K in every app, on by default. | In Skribly Agent today; planned elsewhere |
| Inbox | One list of what needs you, with a reason on each item. “An agent is waiting for you” comes first. | Planned |
| Agent sessions | An agent works on an issue as a delegate and reports what it is doing. A person stays accountable. | Planned |
| MCP | Skribly Tracker will offer a Model Context Protocol server with OAuth, a read-only mode and per-project scope. | Planned; Skribly Agent already has an MCP server for driving its own sessions |
| Feature flags | One switch turns off every AI feature, and each AI feature says what it sends to a model. | Planned |
Open standards
Section titled “Open standards”| Standard | Used for |
|---|---|
| Model Context Protocol | Tools for agents |
| Agent Client Protocol | Talking to local agents in a structured way |
| Agent Skills | The format of agent-skills |
| AGENTS.md | Project instructions for agents |
| llms.txt | Docs that agents can read; this site publishes /llms.txt |
| Standard Webhooks | Signing webhooks (planned) |
| CloudEvents 1.0.2 | The event envelope in @skribly/core |
| OpenAPI 3.1 | The REST API reference |
| Design Tokens (DTCG) | Token files of @skribly/ui |
| WCAG 2.2 AA | The accessibility target |
The shared stack planned for every app, checked on 8 November 2026:
| Layer | Choice |
|---|---|
| Runtime | Node.js 26 LTS, TypeScript 7 |
| Web | React 19, React Router 8, Vite 8, Tailwind CSS 4, React Aria Components |
| Server | Hono 4 |
| Data | PostgreSQL 18, Drizzle ORM, Zod 4, pg-boss for queues |
| Desktop | Electron 45 |
| Docs | Astro 7 with Starlight, Pagefind search |
| Quality | Vitest, Playwright, oxlint, axe |
Skribly Agent already runs on Electron, React and Vite. @skribly/core, @skribly/ui and this site run on Node.js 26. The released Skribly Tracker 0.1 runs on PHP and Laravel; moving it to this stack is planned and would keep the same API.
Principles
Section titled “Principles”- Local first; an account is a reason to share, never a gate.
- Open standards over closed plugin systems.
- A person stays accountable. Agents are always shown as agents, stop when told, and never log time or push code silently.
- Time from the work, never from watching people.
- The task lives in the repository.
- One look across every app.
- Your data can leave in open formats.
- Public claims are checked and dated.
Privacy and accessibility
Section titled “Privacy and accessibility”- Skribly Agent sends no telemetry. When an app sends anything, it says what and where. See Security.
- Skribly will not offer screenshots, keystroke counts or productivity scores of people.
- The target is WCAG 2.2 AA, and AAA wherever possible. Automated tools cannot prove full conformance, so each statement says what was tested by hand. A statement is not a declaration of conformity. See Accessibility.