Scaffolding common patterns

The framework ships a small set of skills — markdown documents that scaffold recurring tasks. They're symlinked into both .claude/skills/ and .agents/skills/ at the project root by scripts/sync-agent-assets.php, and made discoverable by Claude Code (via /skill <name>) and any other agent that respects .agents/skills/.

Available skills

Skill	What it scaffolds	Source
new-module	A new flyokai module with bootstrap lifecycle	.agents/skills/new-module.md
new-endpoint	An HTTP route + controller + auth guard	.agents/skills/new-endpoint.md
new-dto	A DTO following data-mate conventions (Solid + Draft + GreyData)	.agents/skills/new-dto.md
new-cli-command	An async Symfony Console command with tuner/execution pipeline	.agents/skills/new-cli-command.md
new-request-handler	A data-service socket request handler (request DTO + response DTO + handler + DI registration)	.agents/skills/new-request-handler.md

Module-specific skills:

Module	Skill	Purpose
flyokai/db-schema	annotate-dto-schema	Tag an existing Solid DTO with #[Table] and friends to retire imperative DDL setup steps
flyokai/search-criteria	wire-searchable-repository	Add getList() / massUpdate() support to an existing repository

How to invoke them

From Claude Code

/skill flyokai-new-module

Skill names are vendor-prefixed when synced (e.g. flyokai-new-module.md instead of new-module.md) so they don't collide with skills from other vendors. The /skill command surfaces the markdown content for the current task.

From other agents

Any agent that respects .agents/skills/ will discover the synced files automatically. The same vendor prefix applies.

By hand

Each skill is a self-contained markdown document. Open it, follow the steps, copy the templates. Skills are intentionally not "automated" — they're worked-example docs that a human + agent can iterate on together.

Adding a new skill to a module

1. Create the markdown file under your module's .agents/skills/<skill-name>.md.
2. Run composer run sync-agent-assets (or just composer install / composer update).
3. The skill appears as <your-vendor>-<skill-name>.md in both .claude/skills/ and .agents/skills/ of every consuming project.

A skill should include:

• Prerequisites — what the agent needs to know before scaffolding (parameter names, target package, etc.).
• Step-by-step plan — file paths and what goes in each.
• Templates — copy-paste-friendly code blocks with <placeholder> markers.
• Conventions / gotchas — non-obvious things the agent might miss.
• Reference examples — pointers at existing modules that demonstrate the same pattern.

Adding a command

Commands (.agents/commands/<name>.md) are runnable single-purpose scripts that the agent invokes with a slash command. Two ship today:

Command	Module	Purpose
db-schema-status	flyokai/db-schema	Print a one-screen summary of the discovered schema (tables, aliases, FKs)
criteria-explain	flyokai/search-criteria	Compile a JSON criteria payload and print the resulting SQL + parameters

Add new commands the same way as skills, under .agents/commands/.

Sync details

scripts/sync-agent-assets.php is run by composer install and composer update via the post-install-cmd and post-update-cmd hooks. It:

1. Scans vendor/*/*/.agents/{commands,skills}/*.md.
2. For each file, creates a relative symlink at .claude/{commands,skills}/<vendor>-<name>.md and .agents/{commands,skills}/<vendor>-<name>.md.
3. Cleans up stale symlinks pointing at vendor files that no longer exist.

To re-run by hand: composer run sync-agent-assets.