@lazyingart/agintiflow 0.13.0 → 0.14.0

package/README.md

@@ -83,6 +83,16 @@ For current docs, install errors, package/toolchain setup, and source discovery,
 
 For raster image work, AgInTiFlow has an optional `image_generation` skill backed by the `generate_image` tool and a local `GRSAI` key. The skill tells DeepSeek when image generation is appropriate; the tool calls GRS AI Nano Banana, saves manifests/images under `artifacts/images`, and sends the result to the canvas. See [docs/auxiliary-image-generation.md](docs/auxiliary-image-generation.md).
 
+AgInTiFlow now ships a Markdown skill library in `skills/<id>/SKILL.md`. Skills are prompt playbooks, while tools are deterministic actions such as `apply_patch`, `run_command`, `web_search`, `generate_image`, and `send_to_canvas`. Built-in skills cover code, websites/apps, LaTeX manuscripts, books, Word documents, image generation, GitHub, system maintenance, Android, R/Stan, Python, C/C++, shell, AAPS, and novel writing. See [docs/skills-and-tools.md](docs/skills-and-tools.md).
+
+```bash
+aginti skills
+aginti skills website
+aginti --list-skills latex
+# in chat:
+/skills github commit
+```
+
 Launch the local web UI from an installed package:
 
 ```bash

package/docs/skills-and-tools.md

@@ -0,0 +1,58 @@
+# Skills And Tools
+
+AgInTiFlow separates **skills** from **tools** so the agent can stay general while still improving on specialized work.
+
+## Definitions
+
+**Skill**: Markdown guidance stored at `skills/<id>/SKILL.md`. A skill describes when to use a workflow, what to inspect first, which outputs matter, and which tools are usually useful. Skills are prompt context, not executable code.
+
+**Tool**: A deterministic callable capability exposed to the model, such as `inspect_project`, `read_file`, `apply_patch`, `run_command`, `web_search`, `generate_image`, `preview_workspace`, or `send_to_canvas`.
+
+**Profile**: A broad runtime mode such as `auto`, `code`, `latex`, or `maintenance`. Profiles tune routing, max steps, and general behavior. Skills can combine across profiles.
+
+## Built-In Skills
+
+The package ships built-in skills for code engineering, website/app building, LaTeX manuscripts, books, Microsoft Word documents, image generation, GitHub maintenance, system maintenance, Android, R/Stan, Python, C/C++, shell scripting, AAPS, and novel writing.
+
+List them from a project:
+
+```bash
+aginti skills
+aginti skills website
+aginti --list-skills latex
+```
+
+Inside interactive chat:
+
+```text
+/skills
+/skills github commit
+```
+
+## Selection Flow
+
+For every run, AgInTiFlow scores the user goal and active profile against skill frontmatter:
+
+```yaml
+---
+id: latex-manuscript
+label: LaTeX Manuscript
+description: Write, compile, and package LaTeX papers, reports, figures, bibliographies, and PDFs.
+triggers:
+  - latex
+  - tex
+  - manuscript
+tools:
+  - write_file
+  - apply_patch
+  - run_command
+---
+```
+
+Selected skills are injected into the plan and execution prompts. The LLM still decides what to do; skills only provide domain playbooks and guardrails.
+
+## Adding A Skill
+
+Create `skills/<id>/SKILL.md` with valid YAML frontmatter and a short Markdown body. Keep descriptions strings, not YAML arrays, because loaders expect `id`, `label`, and `description` as scalar strings.
+
+Good skills are small, actionable, and tool-aware. They should say what to inspect, what to create or verify, and what to avoid. They should not hard-code one exact task.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "description": "AgInTiFlow is a resumable Playwright website-control agent with OpenAI-compatible tool calling.",
   "license": "Apache-2.0",
@@ -46,10 +46,12 @@
     "scripts/smoke-coding-tools.js",
     "scripts/smoke-capabilities.js",
     "scripts/smoke-inbox.js",
+    "scripts/smoke-skills.js",
     "scripts/smoke-toolchain-docker.js",
     "scripts/smoke-web-api.js",
     "src/",
     "run.js",
+    "skills/",
     "web.js"
   ],
   "bin": {
@@ -64,11 +66,12 @@
     "smoke:coding-tools": "node scripts/smoke-coding-tools.js",
     "smoke:auxiliary-tools": "node scripts/smoke-auxiliary-tools.js",
     "smoke:cli-chat": "node scripts/smoke-cli-chat.js",
+    "smoke:skills": "node scripts/smoke-skills.js",
     "smoke:toolchain-docker": "node scripts/smoke-toolchain-docker.js",
     "smoke:inbox": "node scripts/smoke-inbox.js",
     "smoke:web-api": "node scripts/smoke-web-api.js",
     "real:deepseek": "node scripts/real-deepseek-capabilities.js",
-    "test": "npm run check && npm run smoke:web-api && npm run smoke:coding-tools && npm run smoke:auxiliary-tools && npm run smoke:capabilities && npm run smoke:cli-chat && npm run smoke:inbox",
+    "test": "npm run check && npm run smoke:web-api && npm run smoke:coding-tools && npm run smoke:auxiliary-tools && npm run smoke:capabilities && npm run smoke:skills && npm run smoke:cli-chat && npm run smoke:inbox",
     "pack:dry-run": "npm pack --dry-run",
     "smoke:capabilities": "node scripts/smoke-capabilities.js"
   },

package/scripts/smoke-capabilities.js

@@ -81,6 +81,14 @@ try {
     capabilities.trustedDockerPolicy.some((check) => check.command.startsWith("chmod") && check.allowed),
     "trusted Docker policy did not allow chmod"
   );
+  assert(
+    capabilities.tools?.skills?.some((skill) => skill.id === "website-app"),
+    "capabilities did not report built-in website skill"
+  );
+  assert(
+    capabilities.tools?.skills?.some((skill) => skill.id === "latex-manuscript"),
+    "capabilities did not report built-in LaTeX skill"
+  );
 
   const doctor = JSON.parse(await runCli(["doctor", "--capabilities", "--json"]));
   assert(doctor.project.root === tempRoot, "doctor --capabilities used the wrong project root");
@@ -91,7 +99,7 @@ try {
       {
         ok: true,
         projectRoot: tempRoot,
-        checks: ["aginti-md-init", "capabilities-cli", "doctor-capabilities", "maintenance-policy", "trusted-docker-policy", "git-policy"],
+        checks: ["aginti-md-init", "capabilities-cli", "doctor-capabilities", "maintenance-policy", "trusted-docker-policy", "git-policy", "skills-capability"],
       },
       null,
       2

package/scripts/smoke-cli-chat.js

@@ -122,6 +122,10 @@ try {
   if (!instructionsResult.stdout.includes("AGINTI.md") || !instructionsResult.stdout.includes("Project instructions")) {
     throw new Error("interactive /instructions did not show AGINTI.md");
   }
+  const skillsResult = await runChat("/skills website\n/exit\n");
+  if (!skillsResult.stdout.includes("website-app") || !skillsResult.stdout.includes("Website And App Builder")) {
+    throw new Error("interactive /skills did not show matching built-in skills");
+  }
   await runChat("remember that this project prefers pytest smoke tests in AGINTI.md\n/exit\n");
   const updatedInstructions = await fs.readFile(path.join(tempRoot, "AGINTI.md"), "utf8");
   if (!updatedInstructions.includes("pytest smoke tests")) {
@@ -159,7 +163,7 @@ try {
       {
         ok: true,
         projectRoot: tempRoot,
-        checks: ["markdown-render", "markdown-table-no-duplicate", "patch-diff-render", "prompt-layout", "live-input-status-layout", "agent-response-gutter", "aginti-md", "instructions-command", "instructions-chat-edit", "interactive-chat", "mock-file-write", "run-status", "resume-latest", "resume-history-full"],
+        checks: ["markdown-render", "markdown-table-no-duplicate", "patch-diff-render", "prompt-layout", "live-input-status-layout", "agent-response-gutter", "aginti-md", "instructions-command", "skills-command", "instructions-chat-edit", "interactive-chat", "mock-file-write", "run-status", "resume-latest", "resume-history-full"],
       },
       null,
       2

package/scripts/smoke-skills.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import { formatSkillsForPrompt, listSkills, selectSkillsForGoal } from "../src/skill-library.js";
+
+const execFileAsync = promisify(execFile);
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function selectedIds(goal, taskProfile = "auto") {
+  return selectSkillsForGoal(goal, { taskProfile, limit: 8 }).map((skill) => skill.id);
+}
+
+const skills = listSkills({ includeBody: true });
+const ids = new Set(skills.map((skill) => skill.id));
+assert(skills.length >= 14, "expected built-in skills to load");
+for (const required of [
+  "aaps",
+  "code",
+  "github-maintenance",
+  "image-generation",
+  "latex-manuscript",
+  "system-maintenance",
+  "website-app",
+  "word-documents",
+]) {
+  assert(ids.has(required), `missing required skill ${required}`);
+}
+
+assert(selectedIds("write a beautiful React website and preview it").includes("website-app"), "website prompt did not select website-app");
+assert(selectedIds("write a LaTeX paper and compile a PDF").includes("latex-manuscript"), "latex prompt did not select latex-manuscript");
+assert(selectedIds("edit a Microsoft Word docx and preserve the original").includes("word-documents"), "docx prompt did not select word-documents");
+assert(selectedIds("generate a logo image with grsai nanobanana").includes("image-generation"), "image prompt did not select image-generation");
+assert(selectedIds("git status commit push with gh").includes("github-maintenance"), "git prompt did not select github-maintenance");
+assert(selectedIds("create an .aaps example for @lazyingart/aaps").includes("aaps"), "AAPS prompt did not select aaps");
+assert(selectedIds("debug a C++ CMake build").includes("c-cpp"), "C++ prompt did not select c-cpp");
+assert(selectedIds("set up Stan and CmdStanR reproducibly").includes("r-stan"), "Stan prompt did not select r-stan");
+
+const prompt = formatSkillsForPrompt(selectSkillsForGoal("write latex manuscript with figures", { taskProfile: "latex", limit: 3 }));
+assert(prompt.includes("A skill is Markdown guidance"), "skill prompt does not explain skill semantics");
+assert(prompt.includes("latex-manuscript"), "skill prompt omitted selected skill");
+assert(prompt.length < 5400, "skill prompt is too large for normal runs");
+
+const cli = await execFileAsync(process.execPath, [path.join(repoRoot, "bin/aginti-cli.js"), "skills", "website"], {
+  cwd: repoRoot,
+  timeout: 10000,
+  maxBuffer: 512 * 1024,
+  env: {
+    ...process.env,
+    AGINTIFLOW_RUNTIME_DIR: "",
+  },
+});
+assert(cli.stdout.includes("website-app"), "aginti skills website did not print website-app");
+
+console.log(
+  JSON.stringify(
+    {
+      ok: true,
+      skills: skills.length,
+      checks: ["load-built-ins", "select-by-goal", "prompt-format", "cli-skills"],
+    },
+    null,
+    2
+  )
+);

package/scripts/smoke-web-api.js

@@ -81,6 +81,9 @@ try {
   if (!Array.isArray(config.taskProfiles) || !config.taskProfiles.some((profile) => profile.id === "latex")) {
     throw new Error("task profiles are not advertised by /api/config");
   }
+  if (!Array.isArray(config.skills) || !config.skills.some((skill) => skill.id === "website-app")) {
+    throw new Error("built-in skills are not advertised by /api/config");
+  }
 
   const keyStatus = await fetchJson("/api/keys/status");
   if (typeof keyStatus.keyStatus?.deepseek !== "boolean") throw new Error("key status endpoint is invalid");

package/skills/aaps/SKILL.md

@@ -0,0 +1,21 @@
+---
+id: aaps
+label: AAPS Workflows
+description: Work with ../AAPS, .aaps files, @lazyingart/aaps, automation plans, and related project conventions.
+triggers:
+  - aaps
+  - .aaps
+  - @lazyingart/aaps
+  - automation plan
+tools:
+  - inspect_project
+  - read_file
+  - write_file
+  - run_command
+  - web_search
+---
+# AAPS Workflows
+
+Inspect nearby `.aaps` files, package docs, and project notes before generating workflows. Keep assumptions explicit and outputs project-local.
+
+Do not publish, upload, or expose credentials unless explicitly requested and safe.

package/skills/android/SKILL.md

@@ -0,0 +1,23 @@
+---
+id: android
+label: Android Development
+description: Build and debug Android, Gradle, Kotlin, Java, emulator, and mobile app projects.
+triggers:
+  - android
+  - gradle
+  - kotlin
+  - java
+  - apk
+  - emulator
+tools:
+  - inspect_project
+  - search_files
+  - apply_patch
+  - run_command
+  - web_search
+---
+# Android Development
+
+Inspect Gradle files, manifests, package names, modules, and existing build scripts before editing. Prefer narrow Gradle tasks and source-set-aware patches.
+
+If SDK/emulator tooling is missing, produce a setup report or project-local script rather than guessing.

package/skills/book-writing/SKILL.md

@@ -0,0 +1,23 @@
+---
+id: book-writing
+label: Book And Long-Form Writing
+description: Plan, draft, revise, and structure books, chapters, scripts, tutorials, and long documents.
+triggers:
+  - book
+  - chapter
+  - script
+  - tutorial
+  - long form
+  - outline
+  - manuscript
+tools:
+  - write_file
+  - read_file
+  - web_search
+  - send_to_canvas
+---
+# Book And Long-Form Writing
+
+Start with structure: audience, promise, outline, chapter flow, voice, and revision plan. Save durable drafts as Markdown unless the user requests another format.
+
+Use web search for current facts and keep source notes when claims matter. For long work, produce incremental chapters and revision notes instead of one huge brittle output.

package/skills/c-cpp/SKILL.md

@@ -0,0 +1,23 @@
+---
+id: c-cpp
+label: C And C++ Development
+description: Work with C, C++, CMake, Make, native builds, tests, and low-level debugging.
+triggers:
+  - c++
+  - cpp
+  - c language
+  - cmake
+  - makefile
+  - gcc
+  - clang
+tools:
+  - inspect_project
+  - search_files
+  - apply_patch
+  - run_command
+---
+# C And C++ Development
+
+Inspect build files before source edits. Keep patches narrow, respect formatting style, and run the smallest compile/test target available.
+
+If native dependencies are missing, prefer Docker/project-local setup notes and do not silently change host toolchains.

package/skills/code/SKILL.md

@@ -0,0 +1,25 @@
+---
+id: code
+label: Code Engineering
+description: Build, edit, debug, test, and maintain software projects across languages.
+triggers:
+  - code
+  - app
+  - bug
+  - test
+  - refactor
+  - package
+  - project
+tools:
+  - inspect_project
+  - search_files
+  - read_file
+  - apply_patch
+  - run_command
+  - web_search
+---
+# Code Engineering
+
+Orient before editing: inspect the project map, read instructions/manifests, search exact symbols or errors, then patch the smallest coherent set of files.
+
+Prefer deterministic `apply_patch` for source edits. Run focused checks first, repair failures, then broaden checks only when useful. Summarize changed files, commands run, and residual risk.

package/skills/github-maintenance/SKILL.md

@@ -0,0 +1,23 @@
+---
+id: github-maintenance
+label: GitHub And Release Maintenance
+description: Use git and gh safely for status, commits, pull requests, releases, and repository maintenance.
+triggers:
+  - git
+  - github
+  - gh
+  - commit
+  - push
+  - pull request
+  - release
+tools:
+  - run_command
+  - read_file
+  - apply_patch
+  - web_search
+---
+# GitHub And Release Maintenance
+
+Always inspect `git status --short` and relevant diffs before committing or pushing. Keep commits scoped and stop on conflicts, divergence, or unrelated dirty work.
+
+Use `gh` for PR/release/status workflows when authenticated. Fold long command output but preserve key errors, URLs, branch names, and commit hashes.

package/skills/image-generation/SKILL.md

@@ -0,0 +1,23 @@
+---
+id: image-generation
+label: Image Generation
+description: Generate or edit raster images, posters, covers, logos, illustrations, and visual assets.
+triggers:
+  - image
+  - logo
+  - poster
+  - cover
+  - illustration
+  - nanobanana
+  - grsai
+  - gpt image
+tools:
+  - generate_image
+  - write_file
+  - send_to_canvas
+---
+# Image Generation
+
+Use image generation when the user asks for a raster visual asset or prompt. Write a concise prompt with subject, style, composition, color, lighting, and output constraints.
+
+Prefer `generate_image` when a GRS AI key is available. Save selected outputs under artifacts and send the chosen image to canvas.

package/skills/latex-manuscript/SKILL.md

@@ -0,0 +1,25 @@
+---
+id: latex-manuscript
+label: LaTeX Manuscript
+description: Write, compile, and package LaTeX papers, reports, figures, bibliographies, and PDFs.
+triggers:
+  - latex
+  - tex
+  - manuscript
+  - paper
+  - pdf
+  - figure
+  - overleaf
+tools:
+  - write_file
+  - apply_patch
+  - run_command
+  - open_workspace_file
+  - send_to_canvas
+  - web_search
+---
+# LaTeX Manuscript
+
+Use a project subfolder with `main.tex`, figures, bibliography, and generated PDFs. Compile from the correct directory with `latexmk` or `pdflatex` when available.
+
+If TeX is missing, produce an honest setup note or Docker-local setup plan instead of faking success. Send the final PDF or source to canvas when useful.

package/skills/novel-writing/SKILL.md

@@ -0,0 +1,21 @@
+---
+id: novel-writing
+label: Novel Writing
+description: Plan, draft, revise, and manage novels, character arcs, scenes, chapters, and long fiction.
+triggers:
+  - novel
+  - fiction
+  - character
+  - scene
+  - plot
+  - chapter
+tools:
+  - write_file
+  - read_file
+  - send_to_canvas
+---
+# Novel Writing
+
+Track premise, characters, setting, conflict, tone, and continuity. Save outlines, chapter drafts, and revision notes as durable files.
+
+For long works, write in scenes or chapters and maintain a compact continuity bible instead of relying on chat history alone.

package/skills/python/SKILL.md

@@ -0,0 +1,24 @@
+---
+id: python
+label: Python Development
+description: Build Python packages, CLIs, scripts, tests, notebooks, plotting, and data workflows.
+triggers:
+  - python
+  - pytest
+  - pyproject
+  - pip
+  - uv
+  - matplotlib
+  - pandas
+tools:
+  - inspect_project
+  - search_files
+  - apply_patch
+  - run_command
+  - send_to_canvas
+---
+# Python Development
+
+Inspect `pyproject.toml`, requirements, package layout, and tests. Prefer stdlib tests when dependency installs are unnecessary; otherwise use project-local venv/conda/uv or Docker.
+
+For plots and artifacts, save files with clear names and send useful outputs to canvas.

package/skills/r-stan/SKILL.md

@@ -0,0 +1,24 @@
+---
+id: r-stan
+label: R And Stan
+description: Work with R, Stan, CmdStan, CmdStanR, PyStan, statistics, and reproducible analysis projects.
+triggers:
+  - r
+  - stan
+  - cmdstan
+  - cmdstanr
+  - pystan
+  - statistics
+  - bayesian
+tools:
+  - inspect_project
+  - write_file
+  - run_command
+  - web_search
+  - send_to_canvas
+---
+# R And Stan
+
+Keep analysis reproducible: scripts, data paths, package notes, seed handling, and output folders. Prefer Docker or project-local toolchains for installation.
+
+For Stan, validate model syntax and compile/run only when toolchains exist; otherwise write honest setup scripts and checks.

package/skills/shell/SKILL.md

@@ -0,0 +1,21 @@
+---
+id: shell
+label: Shell Scripting
+description: Write, audit, and run shell scripts for automation, setup, diagnostics, and maintenance.
+triggers:
+  - shell
+  - bash
+  - script
+  - terminal
+  - command
+  - cli
+tools:
+  - write_file
+  - run_command
+  - web_search
+---
+# Shell Scripting
+
+Prefer idempotent scripts with `set -euo pipefail` when appropriate, clear variables, dry-run or validation modes, and `bash -n` checks.
+
+Separate diagnosis from mutation. Keep dangerous host operations explicit and reversible.

package/skills/system-maintenance/SKILL.md

@@ -0,0 +1,24 @@
+---
+id: system-maintenance
+label: System Maintenance
+description: Diagnose and repair local system, shell, package, Docker, conda, Python, R, and toolchain problems.
+triggers:
+  - system
+  - install
+  - package
+  - docker
+  - conda
+  - environment
+  - fix computer
+  - error
+tools:
+  - run_command
+  - write_file
+  - web_search
+  - send_to_canvas
+---
+# System Maintenance
+
+Diagnose first with read-only commands. Prefer Docker/project-local scripts and `/aginti-env` for broad toolchain setup. Host-level sudo or destructive operations require explicit user approval outside normal automation.
+
+For complicated setup, write idempotent scripts, run syntax checks, and report exact next safe command.

package/skills/website-app/SKILL.md

@@ -0,0 +1,26 @@
+---
+id: website-app
+label: Website And App Builder
+description: Build polished websites, web apps, landing pages, dashboards, and local previews.
+triggers:
+  - website
+  - web app
+  - landing page
+  - frontend
+  - dashboard
+  - react
+  - html
+tools:
+  - inspect_project
+  - write_file
+  - apply_patch
+  - run_command
+  - preview_workspace
+  - open_workspace_file
+  - send_to_canvas
+---
+# Website And App Builder
+
+Create real files, not only advice. For new UI, choose a clear visual direction, responsive layout, purposeful typography, and meaningful content. For existing apps, preserve conventions.
+
+Use package scripts when available. Preview with `preview_workspace` or `open_workspace_file`; avoid transient Docker localhost loops.

package/skills/word-documents/SKILL.md

@@ -0,0 +1,22 @@
+---
+id: word-documents
+label: Microsoft Word Documents
+description: Edit, convert, inspect, or generate Word-style documents using available local tools.
+triggers:
+  - word
+  - docx
+  - microsoft word
+  - office
+  - pandoc
+  - libreoffice
+tools:
+  - read_file
+  - write_file
+  - run_command
+  - send_to_canvas
+---
+# Microsoft Word Documents
+
+Prefer safe conversions through available tools such as `pandoc`, `libreoffice`, or Python libraries when installed. Preserve originals; write converted or edited outputs to a new file unless overwrite is explicit.
+
+If binary `.docx` content cannot be inspected directly, explain the needed converter and create a project-local script or setup note.

package/src/agent-runner.js

@@ -22,6 +22,7 @@ import { engineeringGuidanceForTask } from "./engineering-guidance.js";
 import { searchWeb } from "./web-search.js";
 import { runParallelScouts, shouldRunParallelScouts } from "./parallel-scouts.js";
 import { readProjectInstructions } from "./project.js";
+import { formatSkillsForPrompt, selectSkillsForGoal } from "./skill-library.js";
 
 const exec = promisify(execCallback);
 const BROWSER_TOOLS = new Set(["open_url", "open_workspace_file", "preview_workspace", "click", "type", "scroll", "press", "back"]);
@@ -252,6 +253,8 @@ async function createInitialState(config, sessionId) {
   const now = new Date().toISOString();
   const taskProfile = getTaskProfile(config.taskProfile);
   const engineeringGuidance = engineeringGuidanceForTask(config.goal, config.taskProfile);
+  const selectedSkills = selectSkillsForGoal(config.goal, { taskProfile: config.taskProfile, limit: 6 });
+  const skillContext = formatSkillsForPrompt(selectedSkills);
   const projectInstructions = await readProjectInstructions(config.baseDir || config.commandCwd || process.cwd());
   const projectInstructionContext = formatProjectInstructions(projectInstructions);
   return {
@@ -272,6 +275,7 @@ async function createInitialState(config, sessionId) {
         truncated: projectInstructions.truncated,
         loadedAt: now,
       },
+      selectedSkills: selectedSkills.map((skill) => skill.id),
     },
     chat: [
       {
@@ -318,6 +322,7 @@ async function createInitialState(config, sessionId) {
             ? `Parallel DeepSeek scouts may run before complex execution. Scout count: ${config.parallelScoutCount}.`
             : "Parallel scouts are disabled.",
           `Task profile: ${taskProfile.label}. ${taskProfile.prompt}`,
+          skillContext,
           engineeringGuidance,
           "A frontend canvas/artifacts tunnel exists. Use send_to_canvas when important markdown, diffs, screenshots, images, or workspace files should be highlighted in the UI. It is optional and ordinary final text can still go directly to finish.",
           "For visual-output requests such as draw, plot, graph, chart, diagram, figure, image, or visualization, proactively publish a canvas artifact even when the user does not mention canvas. If workspace file tools are enabled, prefer creating a small SVG or markdown artifact and call send_to_canvas with selected=true.",
@@ -360,6 +365,7 @@ async function createInitialState(config, sessionId) {
           config.allowWebSearch ? "Web search tool: enabled." : "Web search tool: disabled.",
           config.allowParallelScouts ? `Parallel scouts: enabled count=${config.parallelScoutCount}.` : "Parallel scouts: disabled.",
           `Task profile: ${taskProfile.label}. ${taskProfile.prompt}`,
+          skillContext,
           engineeringGuidance,
           "Canvas/artifacts tunnel: available through send_to_canvas for optional frontend rendering.",
           "Visual-output requests should produce a canvas artifact without requiring the user to ask for canvas explicitly.",
@@ -451,6 +457,8 @@ async function applyContinuationPrompt(state, config, observers) {
 
   const taskProfile = getTaskProfile(config.taskProfile);
   const engineeringGuidance = engineeringGuidanceForTask(config.goal, config.taskProfile);
+  const selectedSkills = selectSkillsForGoal(config.goal, { taskProfile: config.taskProfile, limit: 6 });
+  const skillContext = formatSkillsForPrompt(selectedSkills);
   const projectInstructions = await readProjectInstructions(config.baseDir || config.commandCwd || process.cwd());
   state.meta = state.meta || {};
   state.meta.projectInstructions = {
@@ -459,6 +467,7 @@ async function applyContinuationPrompt(state, config, observers) {
     truncated: projectInstructions.truncated,
     loadedAt: new Date().toISOString(),
   };
+  state.meta.selectedSkills = selectedSkills.map((skill) => skill.id);
   ensureChatState(state);
   state.goal = config.goal;
   state.provider = config.provider;
@@ -485,6 +494,7 @@ async function applyContinuationPrompt(state, config, observers) {
         ? `Agent wrappers: selected=${normalizeWrapperName(config.preferredWrapper)}; ${wrapperStatusText()}`
         : "",
       `Task profile: ${taskProfile.label}. ${taskProfile.prompt}`,
+      skillContext,
       engineeringGuidance,
       formatProjectInstructions(projectInstructions),
       "AGINTI.md is editable project memory. If the user asks to remember a preference or update instructions, patch AGINTI.md rather than hiding that preference in session-only chat.",

package/src/capabilities.js

@@ -9,6 +9,7 @@ import { listTaskProfiles } from "./task-profiles.js";
 import { listAgentWrappers } from "./tool-wrappers.js";
 import { listAuxiliarySkills } from "./auxiliary-tools.js";
 import { readCodebaseMap } from "./codebase-map.js";
+import { listSkills } from "./skill-library.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -218,6 +219,13 @@ export async function buildCapabilityReport(projectRoot, packageVersion, config)
         label: profile.label,
         tools: profile.tools,
       })),
+      skills: listSkills().map((skill) => ({
+        id: skill.id,
+        label: skill.label,
+        description: skill.description,
+        triggers: skill.triggers,
+        tools: skill.tools,
+      })),
       auxiliarySkills: listAuxiliarySkills().map((skill) => ({
         id: skill.id,
         label: skill.label,

package/src/cli.js

@@ -17,6 +17,7 @@ import {
 import { listTaskProfiles } from "./task-profiles.js";
 import { recommendedMaxStepsForTask } from "./engineering-guidance.js";
 import { promptAndSaveDeepSeekKey, promptHidden, shouldPromptForDeepSeek } from "./auth-onboarding.js";
+import { listSkills, selectSkillsForGoal } from "./skill-library.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -64,6 +65,7 @@ export function parseArgs(argv) {
     port: "",
     host: "",
     listProfiles: false,
+    listSkills: false,
     latex: false,
     image: false,
   };
@@ -242,6 +244,10 @@ export function parseArgs(argv) {
       result.listProfiles = true;
       continue;
     }
+    if (arg === "--list-skills") {
+      result.listSkills = true;
+      continue;
+    }
     if (arg === "--sandbox-status") {
       result.sandboxStatus = true;
       continue;
@@ -261,7 +267,7 @@ export function parseArgs(argv) {
 
 function printUsage() {
   console.log(
-    'Usage: aginti [chat] OR aginti web [--port 3210] OR aginti login deepseek|openai|grsai OR aginti resume [latest|<session-id>] ["prompt"] OR aginti queue <session-id> "message" OR aginti [--image] [--latex] [--routing smart|fast|complex|manual] [--provider deepseek|openai|mock] [--sandbox-mode host|docker-readonly|docker-workspace] [--package-install-policy block|prompt|allow] [--approve-package-installs] [--allow-shell|--no-shell] [--allow-file-tools|--no-file-tools] [--web-search|--no-web-search] [--parallel-scouts|--no-parallel-scouts --scout-count 1..10] [--allow-auxiliary-tools|--no-auxiliary-tools] [--allow-wrappers --wrapper codex] [--sandbox-status|--sandbox-preflight] "your task"'
+    'Usage: aginti [chat] OR aginti web [--port 3210] OR aginti skills [query] OR aginti login deepseek|openai|grsai OR aginti resume [latest|<session-id>] ["prompt"] OR aginti queue <session-id> "message" OR aginti [--image] [--latex] [--routing smart|fast|complex|manual] [--provider deepseek|openai|mock] [--sandbox-mode host|docker-readonly|docker-workspace] [--package-install-policy block|prompt|allow] [--approve-package-installs] [--allow-shell|--no-shell] [--allow-file-tools|--no-file-tools] [--web-search|--no-web-search] [--parallel-scouts|--no-parallel-scouts --scout-count 1..10] [--allow-auxiliary-tools|--no-auxiliary-tools] [--allow-wrappers --wrapper codex] [--list-skills] [--sandbox-status|--sandbox-preflight] "your task"'
   );
 }
 
@@ -320,6 +326,17 @@ function printProfiles() {
   }
 }
 
+function printSkills(query = "") {
+  const skills = query
+    ? selectSkillsForGoal(query, { taskProfile: "auto", limit: 40, includeBody: false })
+    : listSkills({ includeBody: false });
+  for (const skill of skills) {
+    const triggers = skill.triggers?.length ? ` triggers=${skill.triggers.join(",")}` : "";
+    const tools = skill.tools?.length ? ` tools=${skill.tools.join(",")}` : "";
+    console.log(`${skill.id}: ${skill.label} - ${skill.description}${triggers}${tools}`);
+  }
+}
+
 function printInitResult(result) {
   console.log(`AgInTiFlow project initialized: ${result.projectRoot}`);
   console.log(`instructions=${result.instructionsPath}`);
@@ -534,6 +551,11 @@ export async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (argv[0] === "skills" || argv[0] === "skill") {
+    printSkills(argv.slice(1).join(" ").trim());
+    return;
+  }
+
   if (argv[0] === "queue") {
     await handleQueueCommand(argv.slice(1));
     return;
@@ -592,6 +614,11 @@ export async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (args.listSkills) {
+    printSkills(args.goal);
+    return;
+  }
+
   if (args.sandboxStatus || args.sandboxPreflight) {
     const config = loadConfig({ ...args, goal: args.goal || "sandbox preflight" }, { packageDir });
     const result = args.sandboxPreflight

package/src/interactive-cli.js

@@ -9,6 +9,7 @@ import { defaultMaxStepsForProfile, normalizeTaskProfile } from "./task-profiles
 import { recommendedMaxStepsForTask } from "./engineering-guidance.js";
 import { promptAndSaveDeepSeekKey, promptHidden, shouldPromptForDeepSeek } from "./auth-onboarding.js";
 import { SessionStore } from "./session-store.js";
+import { listSkills, selectSkillsForGoal } from "./skill-library.js";
 
 const useColor = Boolean(input.isTTY && output.isTTY && process.env.AGINTIFLOW_NO_COLOR !== "1");
 const ansi = {
@@ -44,6 +45,8 @@ const SLASH_COMMANDS = [
   "/new",
   "/resume",
   "/sessions",
+  "/skills",
+  "/skill",
   "/profile",
   "/web-search",
   "/scouts",
@@ -480,6 +483,7 @@ function printHelp() {
       "  /new                      Start a fresh session on the next message.",
       "  /resume <session-id>      Continue a saved session.",
       "  /sessions                 List recent sessions in this project.",
+      "  /skills [query]           List Markdown skills selected for a topic.",
       "  /profile <name>           Set task profile, e.g. code, website, latex, maintenance.",
       "  /web-search on|off        Enable or disable the web_search tool.",
       "  /scouts on|off|<1-10>     Enable parallel DeepSeek scouts and set scout count.",
@@ -1589,6 +1593,30 @@ async function handleCommand(line, state, packageDir) {
     }
     return true;
   }
+  if (command === "skills" || command === "skill") {
+    const skills = value
+      ? selectSkillsForGoal(value, { taskProfile: state.taskProfile, limit: 12, includeBody: false })
+      : listSkills({ includeBody: false });
+    if (skills.length === 0) {
+      printAgentMessage("No matching skills found.");
+      return true;
+    }
+    printAgentMessage(
+      skills
+        .map((skill) =>
+          [
+            `${skill.id}: ${skill.label}`,
+            `  ${skill.description}`,
+            skill.triggers?.length ? `  triggers: ${skill.triggers.join(", ")}` : "",
+            skill.tools?.length ? `  tools: ${skill.tools.join(", ")}` : "",
+          ]
+            .filter(Boolean)
+            .join("\n")
+        )
+        .join("\n\n")
+    );
+    return true;
+  }
   if (command === "profile") {
     state.taskProfile = normalizeTaskProfile(value || "auto");
     state.maxSteps = Math.max(state.maxSteps, defaultMaxStepsForProfile(state.taskProfile));

package/src/model-client.js

@@ -3,6 +3,7 @@ import { normalizeWrapperName, wrapperStatusText } from "./tool-wrappers.js";
 import { getTaskProfile } from "./task-profiles.js";
 import { listAuxiliarySkills } from "./auxiliary-tools.js";
 import { engineeringGuidanceForTask } from "./engineering-guidance.js";
+import { formatSkillsForPrompt, selectSkillsForGoal } from "./skill-library.js";
 
 export function createClient(config) {
   if (config.provider === "mock") {
@@ -193,6 +194,8 @@ function mockChatResponse(content, toolCalls = []) {
 export async function createPlan(client, config, state) {
   const taskProfile = getTaskProfile(config.taskProfile);
   const engineeringGuidance = engineeringGuidanceForTask(state.goal, config.taskProfile);
+  const selectedSkills = selectSkillsForGoal(state.goal, { taskProfile: config.taskProfile, limit: 5 });
+  const skillContext = formatSkillsForPrompt(selectedSkills);
   const projectInstructions = state.meta?.projectInstructions;
   if (client.mock) {
     return [
@@ -242,6 +245,7 @@ export async function createPlan(client, config, state) {
             ? `Parallel scout notes may be injected before execution for complex tasks. Scout count: ${config.parallelScoutCount}.`
             : "Parallel scouts are disabled.",
           `Task profile: ${taskProfile.label}. ${taskProfile.prompt}`,
+          skillContext,
           engineeringGuidance,
           "A canvas/artifacts tunnel is available through send_to_canvas. Use it when an output should be highlighted visually, such as screenshots, image files, important markdown, diffs, or generated artifact paths. It is optional for ordinary text answers.",
           "Work like a practical coding agent: inspect when useful, edit with file tools, run safe checks when they add confidence, and keep outputs inside the workspace.",

package/src/skill-library.js

@@ -0,0 +1,153 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_SKILLS_DIR = path.resolve(__dirname, "..", "skills");
+const DEFAULT_PROMPT_CHARS = 5200;
+
+function parseScalar(value = "") {
+  const trimmed = String(value || "").trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function parseFrontmatter(text, filePath) {
+  const match = String(text || "").match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) throw new Error(`${filePath}: missing YAML frontmatter`);
+  const meta = {};
+  const lines = match[1].split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const scalar = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!scalar) throw new Error(`${filePath}: invalid YAML line: ${line}`);
+    const key = scalar[1];
+    const value = scalar[2];
+    if (value.trim()) {
+      meta[key] = parseScalar(value);
+      continue;
+    }
+    const items = [];
+    while (index + 1 < lines.length && /^\s+-\s+/.test(lines[index + 1])) {
+      index += 1;
+      items.push(parseScalar(lines[index].replace(/^\s+-\s+/, "")));
+    }
+    meta[key] = items;
+  }
+  return {
+    meta,
+    body: String(text || "").slice(match[0].length).trim(),
+  };
+}
+
+function normalizeList(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item || "").trim()).filter(Boolean);
+  if (!value) return [];
+  return String(value)
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function loadSkillFile(filePath) {
+  const text = fs.readFileSync(filePath, "utf8");
+  const { meta, body } = parseFrontmatter(text, filePath);
+  for (const field of ["id", "label", "description"]) {
+    if (typeof meta[field] !== "string" || !meta[field].trim()) {
+      throw new Error(`${filePath}: ${field} must be a non-empty string`);
+    }
+  }
+  return {
+    id: meta.id.trim(),
+    label: meta.label.trim(),
+    description: meta.description.trim(),
+    triggers: normalizeList(meta.triggers),
+    tools: normalizeList(meta.tools),
+    body,
+    path: filePath,
+  };
+}
+
+export function listSkills({ includeBody = false, skillsDir = DEFAULT_SKILLS_DIR } = {}) {
+  let dirEntries = [];
+  try {
+    dirEntries = fs.readdirSync(skillsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const skills = [];
+  for (const entry of dirEntries) {
+    if (!entry.isDirectory()) continue;
+    const skillPath = path.join(skillsDir, entry.name, "SKILL.md");
+    try {
+      const skill = loadSkillFile(skillPath);
+      if (!includeBody) delete skill.body;
+      skills.push(skill);
+    } catch {
+      // Invalid local skill files are skipped so one bad skill does not break the agent.
+    }
+  }
+  return skills.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function scoreSkill(skill, text, taskProfile) {
+  let score = 0;
+  if (skill.id === taskProfile) score += 10;
+  if (skill.triggers.includes(taskProfile)) score += 6;
+  for (const trigger of skill.triggers) {
+    const needle = trigger.toLowerCase();
+    if (needle && text.includes(needle)) score += Math.max(2, Math.min(6, Math.ceil(needle.length / 6)));
+  }
+  for (const token of skill.description.toLowerCase().split(/[^a-z0-9+#.-]+/).filter((item) => item.length > 3)) {
+    if (text.includes(token)) score += 0.25;
+  }
+  return score;
+}
+
+export function selectSkillsForGoal(goal = "", { taskProfile = "auto", limit = 6, includeBody = true } = {}) {
+  const text = `${goal} ${taskProfile}`.toLowerCase();
+  const skills = listSkills({ includeBody });
+  const scored = skills
+    .map((skill) => ({ skill, score: scoreSkill(skill, text, taskProfile) }))
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score || a.skill.id.localeCompare(b.skill.id))
+    .map((item) => item.skill);
+  return scored.slice(0, Math.max(1, limit));
+}
+
+function compactBody(body = "", limit = 620) {
+  const text = String(body || "")
+    .replace(/^# .+$/gm, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+  if (text.length <= limit) return text;
+  return `${text.slice(0, limit - 20).trim()}\n...`;
+}
+
+export function formatSkillsForPrompt(skills = [], { maxChars = DEFAULT_PROMPT_CHARS } = {}) {
+  if (!Array.isArray(skills) || skills.length === 0) return "";
+  const chunks = [
+    "Selected AgInTiFlow skills. A skill is Markdown guidance for when and how to use tools; it is not itself a tool. Follow relevant skill guidance without becoming constrained by it.",
+  ];
+  for (const skill of skills) {
+    chunks.push(
+      [
+        `## ${skill.id}: ${skill.label}`,
+        `Description: ${skill.description}`,
+        skill.tools?.length ? `Preferred tools: ${skill.tools.join(", ")}` : "",
+        skill.body ? compactBody(skill.body) : "",
+      ]
+        .filter(Boolean)
+        .join("\n")
+    );
+  }
+  const output = chunks.join("\n\n");
+  if (output.length <= maxChars) return output;
+  return `${output.slice(0, Math.max(maxChars - 80, 1)).trim()}\n... [skills truncated]`;
+}

package/web.js

@@ -14,6 +14,7 @@ import { summarizeWorkspaceTools, WORKSPACE_TOOL_NAMES } from "./src/workspace-t
 import { listTaskProfiles, normalizeTaskProfile } from "./src/task-profiles.js";
 import { loadProjectEnv, projectPaths, providerKeyStatus, setProviderKey } from "./src/project.js";
 import { buildCapabilityReport } from "./src/capabilities.js";
+import { listSkills } from "./src/skill-library.js";
 import {
   buildArtifacts,
   countUnreadArtifacts,
@@ -574,6 +575,7 @@ app.get("/api/config", async (_req, res) => {
       maxSteps: 24,
     },
     taskProfiles: listTaskProfiles(),
+    skills: listSkills(),
     routing: {
       modes: ["smart", "fast", "complex", "manual"],
       presets: getModelPresets(),