docs: enhance agent plugin tutorial with detailed usage instructions and custom skill definitions

Co-authored-by: Copilot <copilot@github.com>

Author: ivictbor

adminforth/documentation/docs/tutorial/08-Plugins/01-agent.md

@@ -279,22 +279,197 @@ plugins: [
 ]
 ```
 
-When using OpenAI-compatible providers for agent modes, you can force Chat Completions API mode with `useComplitionApi: true`:
+Each item in `modes` defines a user-selectable preset in the chat UI. The selected mode is sent to the backend and the plugin uses that mode's `completionAdapter` for the response.
+
+The plugin adds a chat surface to the admin UI, keeps session history per admin user, and shows a mode picker when `modes` are configured.
+
+# Using with self-hosted models
+
+`CompletionAdapterOpenAIResponses` when works with agent plugin, under the hood uses the LangChain internal proxy called `OpenAIChat` (in LangChain they call it "provider"). This proxy is capable with a fresh versions of OpenAI-compatible Responses APIs, for example [self-hosted latest versions of vLLM installations](https://devforth.io/insights/self-hosted-gpt-real-response-time-token-throughput-and-cost-on-l4-l40s-and-h100-for-gpt-oss-20b/)
+To use them, just point the adapter to your local vLLM server:
+
+
+```ts
+completionAdapter: new CompletionAdapterOpenAIResponses({
+  openAiApiKey: process.env.MY_API_KEY as string, // if you use authorization
+  baseUrl: 'http://my_local_vllm_server:8000/v1',  
+  model: 'gpt-oss-120b',
+})
+```
+
+However some of 3rd party providers might serve outdated vLLM and still don't fully support the Responses API needed for langchain internal implmentation, for example [OVH AI Endpoints](https://www.ovhcloud.com/en/public-cloud/ai-endpoints/) in Responses mode still don't play well with langchain proxy (25 Apr 2026)
+
+In that case you can try to use the OpenAI Complition API mode of the plugin, which is less efficient but more compatible with older APIs, you can force Chat Completions API mode with `useComplitionApi: true`:
 
 ```ts
 completionAdapter: new CompletionAdapterOpenAIResponses({
   openAiApiKey: process.env.OVH_AI_ENDPOINTS_ACCESS_TOKEN as string,
   baseUrl: 'https://oai.endpoints.kepler.ai.cloud.ovh.net/v1',
-  model: 'gpt-oss-20b',
+  model: 'gpt-oss-120b',
   useComplitionApi: true,
 })
 ```
 
 OVH AI Endpoints still does not fully support the OpenAI `responses` API, so `useComplitionApi: false` may work unstably there.
 
-Each item in `modes` defines a user-selectable preset in the chat UI. The selected mode is sent to the backend and the plugin uses that mode's `completionAdapter` for the response.
 
-The plugin adds a chat surface to the admin UI, keeps session history per admin user, and shows a mode picker when `modes` are configured.
+
+
+## Writing own skills
+
+You can write own skills by following [SKILL.md Agennt Skills](https://agentskills.io/)
+
+For example we will write a skill which can summarizes backoffice data stats like record counts by resources and send it to user email.
+
+It may handle prompts like
+
+```
+Please send record counts for all resources to my email
+```
+
+Or:
+
+```
+Please send record counts to all admin users
+```
+
+### Writing custom tools
+
+To define a custom tool you should simply define an express API route in your app using `admin.express.withSchema` wrapper which makes the route available for the agent (clear and predictable schema is a crucial part of making the tool work well).
+
+If you are using `admin.express.authorize` wrapper for authorization, adminuser will be injected atomatically from user which sits on the surface and controls the agent. In other words all permissions and access rights of the agent are defined by the admin user which is controlling this agent. At the same time all actions done by agent are automatically attributed in the audit log to the admin user which is controlling the agent.
+
+This example uses the same email adapter pattern shown in the Email Invite and Email Password Reset plugins. The transport below uses Mailgun only to keep the snippet short; you can replace it with SES or any other adapter from [List of adapters](/docs/tutorial/ListOfAdapters/).
+
+```ts title="./api.ts"
+import type { Express, Response } from 'express';
+import { Filters, type IAdminForth, type IAdminUserExpressRequest } from 'adminforth';
+import * as z from 'zod';
+import EmailAdapterMailgun from '@adminforth/email-adapter-mailgun';
+
+const agentEmailAdapter = new EmailAdapterMailgun({
+  apiKey: process.env.MAILGUN_API_KEY as string,
+  domain: process.env.MAILGUN_DOMAIN as string,
+  baseUrl: process.env.MAILGUN_REGION_URL || 'api.mailgun.net',
+});
+const agentSendFrom = process.env.AGENT_SEND_FROM_EMAIL as string;
+
+function escapeHtml(value: string) {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function renderEmailHtml(body: string) {
+  return `<html><body><pre style="font-family: sans-serif; white-space: pre-wrap;">${escapeHtml(body)}</pre></body></html>`;
+}
+
+export function initApi(app: Express, admin: IAdminForth) {
+  app.post('/send_email_to_user',
+    admin.express.withSchema(
+      {
+        description: 'Send an email to one AdminForth user by id. Use this after the user row is resolved.',
+        request: z.object({
+          userId: z.string(),
+          subject: z.string().min(1),
+          body: z.string().min(1),
+        }),
+        response: z.object({
+          ok: z.boolean(),
+          email: z.string().email().optional(),
+          error: z.string().optional(),
+        }),
+      },
+      admin.express.authorize(
+        async (req: IAdminUserExpressRequest, res: Response) => {
+          const { userId, subject, body } = req.body as {
+            userId: string;
+            subject: string;
+            body: string;
+          };
+
+          await agentEmailAdapter.validate();
+
+          const user = await admin.resource('adminuser').get(
+            Filters.EQ('id', userId),
+          );
+
+          if (!user || typeof user.email !== 'string' || !user.email) {
+            res.status(404).json({ ok: false, error: 'User not found' });
+            return;
+          }
+
+          const result = await agentEmailAdapter.sendEmail(
+            agentSendFrom,
+            user.email,
+            body,
+            renderEmailHtml(body),
+            subject,
+          );
+
+          if (!result.ok) {
+            res.status(500).json({ ok: false, error: result.error ?? 'Failed to send email' });
+            return;
+          }
+
+          res.json({ ok: true, email: user.email });
+        }
+      )
+    )
+  );
+}
+```
+
+## Define skills instructions
+
+Custom skills live in your app's custom directory. The agent loads project skills from:
+
+- `custom/skills/<skill_name>/SKILL.md`
+
+Also it can load skills from plugins, it allows other plugins to expose their own skills and tools:
+
+- `custom/plugins/adminforth-agent/skills/<skill_name>/SKILL.md`
+
+Each skill needs YAML frontmatter with `name` and `description`. The `description` is the discovery surface, so include the phrases the admin is likely to type in chat. Skills are not loaded automcatically, agent loads them 
+on demand once understands that `description` of the skill matches the user intent, so keep the description clear and concise.
+
+Tools are also not loaded automatically, the agent loads them only if they are mentioned in the skill instructions. Then agent calls `fetch_tool_schema` meta tool to load actual schema of your custom tool.
+
+Tool names are derived from route paths. If you want the tool name to be exactly `send_email_to_user`, register the route as `/send_email_to_user`.
+
+The example below creates a minimal user skill which:
+
+- resolves a user row
+- reads the `total` count for each resource with `get_resource_data`
+- sends the final report by email with `send_email_to_user`
+
+Create the skill in your app custom folder:
+
+```md title="./custom/skills/email_resource_counts/SKILL.md"
+---
+name: email_resource_counts
+description: Email record counts for each AdminForth resource to a user. Use when the user asks to send resource counts or all-record statistics by email.
+---
+
+# Involved tools
+
+Use `send_email_to_user` to send the final report after you have one exact target user row.
+
+# Instructions
+
+- For each resource in system use fetch data default skill to collect total count of records in each resource.
+- Create html report in format `Resource Label (resourceId): count` for each resource on a new line, sort resources by count in descending order. 
+- Use modern, stylish but compatible html formatting in the email.
+- Call `send_email_to_user` with the resolved user primary key, the final subject, and the final plain text body.
+- After the tool succeeds, tell the user the email was sent and include a short summary in chat.
+```
+
+This way allows to extend your agent with literally any custom instructions and tools and make it do complex tasks related to your backoffice data and operations.
+
+
+## Standard skills
+
 
 ## Persistent checkpointer
 
@@ -559,17 +734,3 @@ services:
 ![alt text](image-6.png)
 
 
-## Custom skills and tools
-
-
-Place you skills in `custom/skills/<skill_name>/SKILL.md` file. The plugin will pick them up automatically and make available in agent's toolbox.
-
-
-To define custom tools, create api endpoints, prefer `admin.express.withSchema(...)` from [Custom Pages / API docs](/docs/tutorial/Customization/customPages/). That exposes machine-readable request and response schemas the agent can use.
-
-In skills markdown file, merge which tool exactlu agent should load.
-
-
-Skill example:
-
-// TODO