@asm-agent/coding-agent 0.8.4 → 0.8.6

package/dist/skills/solid-source-modularity/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: solid-source-modularity
+always-apply: true
+description: Enforce SOLID design, cohesive source modules, staged refactoring, and source-file size limits. MUST be used whenever the agent creates, modifies, reviews, or refactors authored source code in any project.
+---
+
+# SOLID Source Modularity
+
+Apply this policy to all authored source-code work.
+
+## Required policy
+
+- Follow SOLID and give each module one cohesive responsibility.
+- Separate orchestration, domain logic, I/O, rendering, and platform adapters.
+- Prefer small contracts and explicit dependencies. Avoid generic catch-all modules.
+- Target at most 300 physical lines per authored source file.
+- Allow 301–500 lines only as a documented exception when splitting would reduce
+  cohesion or create artificial coupling.
+- More than 500 lines is always a violation and requires modularization.
+- Generated files and lockfiles are exempt.
+
+## Required refactoring sequence
+
+1. Inventory files and responsibilities.
+2. Define boundaries, contracts, and dependency direction.
+3. Create all destination modules before replacing the original implementation.
+4. Validate new modules in isolation when possible.
+5. Replace the original code with imports, delegation, and orchestration only
+   after the destination modules exist.
+6. Organize tests by responsibility and run the project's required checks.
+7. Run the source audit and document each 301–500-line exception.
+
+Keep structural refactoring separate from new behavior. Preserve behavior during
+structural changes. Never create a commit without explicit user authorization.
+
+## Audit
+
+Call the prepared Python skill from the repository root:
+
+```python
+report = await solid_source_modularity(
+    root=".",
+    extensions=[".ts", ".tsx", ".py"],
+)
+```
+
+`report` separates `compliant`, `exceptions`, `violations`, and `skipped` files.
+Do not raise `target_lines` above 300 or `hard_limit` above 500.

package/dist/skills/solid-source-modularity/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "solid-source-modularity"
+version = "0.1.0"
+description = "Audit authored source files against ASM Agent modularity limits."
+requires-python = ">=3.10"
+dependencies = []
+
+[project.scripts]
+solid_source_modularity = "rlm.skill:cli"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/solid_source_modularity"]

package/dist/skills/solid-source-modularity/src/solid_source_modularity/__init__.py

@@ -0,0 +1,154 @@
+"""Audit authored source files against ASM Agent modularity limits."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Iterable
+
+_DEFAULT_EXTENSIONS = (
+    ".c",
+    ".cpp",
+    ".cs",
+    ".go",
+    ".h",
+    ".hpp",
+    ".java",
+    ".js",
+    ".jsx",
+    ".py",
+    ".rs",
+    ".ts",
+    ".tsx",
+)
+_DEFAULT_EXCLUDED_NAMES = (
+    "Cargo.lock",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+)
+_EXCLUDED_DIRECTORIES = frozenset(
+    {
+        ".git",
+        ".mypy_cache",
+        ".next",
+        ".pytest_cache",
+        ".tox",
+        ".venv",
+        "build",
+        "coverage",
+        "dist",
+        "node_modules",
+        "target",
+        "vendor",
+    }
+)
+_GENERATED_NAME_MARKERS = (".generated.", ".gen.")
+
+
+def _normalize_extensions(extensions: Iterable[str]) -> frozenset[str]:
+    normalized = set()
+    for extension in extensions:
+        if not isinstance(extension, str) or not extension.strip():
+            raise TypeError("extensions must contain non-empty strings")
+        value = extension.strip().lower()
+        normalized.add(value if value.startswith(".") else f".{value}")
+    if not normalized:
+        raise ValueError("extensions must not be empty")
+    return frozenset(normalized)
+
+
+def _validate_limits(target_lines: int, hard_limit: int) -> None:
+    if not isinstance(target_lines, int) or isinstance(target_lines, bool):
+        raise TypeError("target_lines must be an integer")
+    if not isinstance(hard_limit, int) or isinstance(hard_limit, bool):
+        raise TypeError("hard_limit must be an integer")
+    if target_lines <= 0 or target_lines > 300:
+        raise ValueError("target_lines must be between 1 and 300")
+    if hard_limit <= target_lines or hard_limit > 500:
+        raise ValueError("hard_limit must be greater than target_lines and at most 500")
+
+
+def _is_generated_name(name: str) -> bool:
+    lowered = name.lower()
+    return any(marker in lowered for marker in _GENERATED_NAME_MARKERS)
+
+
+def _entry(path: Path, root: Path, lines: int) -> dict[str, object]:
+    return {"path": path.relative_to(root).as_posix(), "lines": lines}
+
+
+async def audit_source_files(
+    root: str,
+    extensions: list[str] | None = None,
+    target_lines: int = 300,
+    hard_limit: int = 500,
+    excluded_names: list[str] | None = None,
+) -> dict[str, object]:
+    """Audit authored source files and classify their physical line counts."""
+    _validate_limits(target_lines, hard_limit)
+    root_path = Path(root).expanduser().resolve()
+    if not root_path.is_dir():
+        raise NotADirectoryError(f"{root} is not an existing directory")
+
+    included_extensions = _normalize_extensions(extensions or list(_DEFAULT_EXTENSIONS))
+    excluded = set(excluded_names or list(_DEFAULT_EXCLUDED_NAMES))
+    compliant: list[dict[str, object]] = []
+    exceptions: list[dict[str, object]] = []
+    violations: list[dict[str, object]] = []
+    skipped: list[dict[str, str]] = []
+
+    for current_root, directories, filenames in os.walk(root_path):
+        directories[:] = sorted(name for name in directories if name not in _EXCLUDED_DIRECTORIES)
+        current_path = Path(current_root)
+        for filename in sorted(filenames):
+            path = current_path / filename
+            if path.suffix.lower() not in included_extensions:
+                continue
+            relative = path.relative_to(root_path).as_posix()
+            if filename in excluded or _is_generated_name(filename):
+                skipped.append({"path": relative, "reason": "excluded or generated"})
+                continue
+            try:
+                line_count = len(path.read_text(encoding="utf-8").splitlines())
+            except (OSError, UnicodeError) as error:
+                skipped.append({"path": relative, "reason": str(error)})
+                continue
+            entry = _entry(path, root_path, line_count)
+            if line_count <= target_lines:
+                compliant.append(entry)
+            elif line_count <= hard_limit:
+                exceptions.append(entry)
+            else:
+                violations.append(entry)
+
+    return {
+        "root": str(root_path),
+        "target_lines": target_lines,
+        "hard_limit": hard_limit,
+        "scanned_files": len(compliant) + len(exceptions) + len(violations),
+        "compliant": compliant,
+        "exceptions": exceptions,
+        "violations": violations,
+        "skipped": skipped,
+    }
+
+
+async def run(
+    root: str,
+    extensions: list[str] | None = None,
+    target_lines: int = 300,
+    hard_limit: int = 500,
+    excluded_names: list[str] | None = None,
+) -> dict[str, object]:
+    """Audit source files under ``root`` against the 300/500-line policy."""
+    return await audit_source_files(
+        root,
+        extensions=extensions,
+        target_lines=target_lines,
+        hard_limit=hard_limit,
+        excluded_names=excluded_names,
+    )
+
+
+__all__ = ["audit_source_files", "run"]

package/docs/skills.md

@@ -50,6 +50,9 @@ ASM Agent ships with built-in skills that load by default:
 
 - `prime-intellect` - Prime Intellect products and workflows via the prime CLI: verifiers environments and the Environments Hub, evaluations (local and hosted), Hosted Training and prime-rl, sandboxes, tunnels, Prime Inference, GPU compute, and storage. Reference docs for each area load on demand from the skill's `references/` directory.
 - `skill-creator` - teaches the agent to create new skills: markdown skill layout, frontmatter rules, placement and precedence, and the full Python-backed skill contract (package layout, `run()` convention, optional CLI, kernel venv behavior) with a working template in `references/python-skills.md`.
+- `solid-source-modularity` - an always-applied SOLID and source modularity policy with a Python source-size auditor.
+- `final-response-summary` - an always-applied root-agent completion and final-summary policy.
+- `request-report` - an always-applied report policy with a Python writer for `docs/report/<number>_<feature>_<date>.md`.
 - `websearch` - a Python-backed Google search skill using the [Serper](https://serper.dev) API.
 
 Built-in skills behave like any other skill but have the lowest precedence: a user, project, package, or `--skill` skill with the same name overrides the built-in one.
@@ -132,9 +135,10 @@ For project-level Claude Code skills, add to `.asm-agent/settings.json`:
 1. At startup, ASM Agent scans skill locations and extracts names, descriptions, type, and file locations
 2. The system prompt includes visible skills in XML format per the [specification](https://agentskills.io/integrate-skills)
 3. When a task matches, the agent uses `ipython` to load the full `SKILL.md` (models don't always do this; use prompting or `/skill:name` to force it)
-4. The agent follows the instructions, using relative paths to reference scripts and assets
+4. Skills with `always-apply: true` have their full instructions injected into the system prompt without an explicit invocation
+5. The agent follows the instructions, using relative paths to reference scripts and assets
 
-This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.
+This normally uses progressive disclosure: descriptions are always in context and full instructions load on demand. Reserve `always-apply` for concise universal policies because their bodies consume context in every session.
 
 Skills with `disable-model-invocation: true` are hidden from the startup skill list. They can still be invoked explicitly with `/skill:name`.
 
@@ -306,6 +310,7 @@ Per the [Agent Skills specification](https://agentskills.io/specification#frontm
 | `compatibility` | No | Max 500 chars. Environment requirements. |
 | `metadata` | No | Arbitrary key-value mapping. |
 | `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental). |
+| `always-apply` | No | ASM Agent extension. When `true`, injects the full skill instructions into every system prompt. |
 | `disable-model-invocation` | No | When `true`, skill is hidden from system prompt. Users must use `/skill:name`. |
 
 ### Name Rules
@@ -342,7 +347,7 @@ ASM Agent validates skills against the Agent Skills standard. Most issues produc
 - Name starts/ends with hyphen or has consecutive hyphens
 - Description exceeds 1024 characters
 
-Unknown frontmatter fields are ignored.
+Unknown frontmatter fields are ignored. `always-apply` is an ASM Agent extension to the standard.
 
 **Exception:** Skills with missing description are not loaded.
 

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.0.4",
+  "version": "0.8.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.0.4",
+      "version": "0.8.6",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "0.0.4",
+  "version": "0.8.6",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "0.0.4",
+  "version": "0.8.6",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "1.4.3",
+	"version": "0.8.6",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "1.4.3",
+			"version": "0.8.6",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "^0.0.55"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-sandbox",
 	"private": true,
-	"version": "1.4.3",
+	"version": "0.8.6",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-with-deps",
-  "version": "0.0.4",
+  "version": "0.8.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "0.0.4",
+      "version": "0.8.6",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-with-deps",
   "private": true,
-  "version": "0.0.4",
+  "version": "0.8.6",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@asm-agent/coding-agent",
-	"version": "0.8.4",
+	"version": "0.8.6",
 	"description": "Coding agent CLI with a persistent Python REPL kernel and session management",
 	"type": "module",
 	"asmAgentConfig": {
@@ -48,10 +48,10 @@
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "^1.3.0",
-		"@asm-agent/agent": "^0.8.4",
-		"@asm-agent/ai": "^0.8.4",
-		"@asm-agent/postgres": "^0.8.4",
-		"@asm-agent/tui": "^0.8.4",
+		"@asm-agent/agent": "^0.8.6",
+		"@asm-agent/ai": "^0.8.6",
+		"@asm-agent/postgres": "^0.8.6",
+		"@asm-agent/tui": "^0.8.6",
 		"@silvia-odwyer/photon-node": "^0.3.4",
 		"chalk": "^5.5.0",
 		"cli-highlight": "^2.1.11",

package/skills/final-response-summary/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: final-response-summary
+always-apply: true
+description: Ensure the root ASM Agent sends one concise final response that summarizes the complete user request after all delegated agents, agent follow-ups, validations, and other work have settled. MUST be used for every root user request that reaches completion.
+---
+
+# Final Response Summary
+
+Apply this workflow only to the root, user-facing agent. Child agents must report
+their results to their parent instead of producing the user's final summary.
+
+## Completion gate
+
+Before sending a final answer:
+
+1. Re-read the user's original request and all later user changes.
+2. Collect every required reply from delegated agents and their follow-ups.
+3. Confirm no relevant child is still running, queued, or expected to reply.
+4. Complete required edits, checks, tests, and the request report.
+5. Separate verified results from blockers or unverified claims.
+
+If relevant delegated work is still active, send only a short progress update and
+end the turn. Do not present that update as the final result. Resume when replies
+arrive.
+
+## Final response
+
+Send one concise response that covers:
+
+- what the user requested;
+- what was completed;
+- important files or behavior changed;
+- checks and tests run;
+- blockers, remaining work, or next steps, when applicable;
+- the generated `docs/report/...` path when the request-report skill applies.
+
+Do not repeat the full transcript. Do not invent completion, test results, or
+agent findings. Keep simple requests short and use sections only when they make
+the result clearer.

package/skills/request-report/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: request-report
+always-apply: true
+description: Create one numbered Markdown report at docs/report/<number_mil>_<feature>_<date>.md for the latest user request. MUST be used by the root ASM Agent for every completed project task or user request in a writable workspace, after all work and validation finish and before the final response.
+---
+
+# Request Report
+
+The root, user-facing agent must create exactly one report for each completed
+user request in a writable project workspace. Child agents must send findings
+to their parent and must not create request reports.
+
+Create the report after edits and validation finish, but before the final user
+response. Call the prepared Python skill:
+
+```python
+path = await request_report(
+    root=".",
+    feature="short feature name",
+    request="The user's complete request, including later changes.",
+    summary="What was completed and the resulting behavior.",
+    modified_files=["packages/example/src/file.ts", "docs/example.md"],
+    changes=["Changed ...", "Added ..."],
+    validation=["npm run check — passed"],
+    status="completed",
+)
+```
+
+The skill:
+
+- creates `docs/report/` when needed;
+- allocates sequential numbers with at least four digits (`0001`, `0002`, ...);
+- converts `feature` to a safe kebab-case slug;
+- uses an ISO date (`YYYY-MM-DD`);
+- requires `modified_files` and renders every path as a relative Markdown link;
+- always links the generated report itself in the modified-files list;
+- rejects modified-file paths outside the project root;
+- creates the file atomically without overwriting an existing report;
+- returns the created path.
+
+Pass every created, modified, or deleted project file in `modified_files`. Use
+paths relative to `root` when possible. Use `status="partial"` or
+`status="blocked"` when appropriate. Record only checks
+that actually ran. If the workspace is read-only or the request does not have a
+project filesystem, state that limitation in the final response instead of
+claiming a report was created.

package/skills/request-report/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "request-report"
+version = "0.1.0"
+description = "Create numbered Markdown reports for completed ASM Agent requests."
+requires-python = ">=3.10"
+dependencies = []
+
+[project.scripts]
+request_report = "rlm.skill:cli"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/request_report"]

package/skills/request-report/src/request_report/__init__.py

@@ -0,0 +1,160 @@
+"""Create numbered Markdown reports for completed user requests."""
+
+from __future__ import annotations
+
+import os
+import re
+import unicodedata
+from datetime import date as date_type
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterable
+from urllib.parse import quote
+
+_REPORT_NUMBER_WIDTH = 4
+_REPORT_NAME_PATTERN = re.compile(r"^(\d{4,})_.*\.md$")
+_VALID_STATUSES = frozenset({"blocked", "completed", "partial"})
+
+
+def _slugify(value: str) -> str:
+    normalized = unicodedata.normalize("NFKD", value)
+    ascii_value = normalized.encode("ascii", "ignore").decode("ascii").lower()
+    slug = re.sub(r"[^a-z0-9]+", "-", ascii_value).strip("-")
+    return (slug or "request")[:60].rstrip("-")
+
+
+def _validate_date(value: str | None) -> str:
+    if value is None:
+        return datetime.now(timezone.utc).date().isoformat()
+    try:
+        return date_type.fromisoformat(value).isoformat()
+    except ValueError as error:
+        raise ValueError("date must use YYYY-MM-DD format") from error
+
+
+def _next_number(report_dir: Path) -> int:
+    highest = 0
+    for path in report_dir.glob("*.md"):
+        match = _REPORT_NAME_PATTERN.match(path.name)
+        if match:
+            highest = max(highest, int(match.group(1)))
+    return highest + 1
+
+
+def _section(title: str, content: str) -> list[str]:
+    return [f"## {title}", "", content.strip() or "Not provided.", ""]
+
+
+def _bullet_section(title: str, values: Iterable[str] | None) -> list[str]:
+    items = [value.strip() for value in (values or []) if value.strip()]
+    content = "\n".join(f"- {item}" for item in items) or "- None recorded."
+    return _section(title, content)
+
+
+def _normalize_modified_files(root: Path, values: list[str]) -> list[str]:
+    if not isinstance(values, list):
+        raise TypeError("modified_files must be a list of project file paths")
+    normalized: list[str] = []
+    for value in values:
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError("modified_files must contain non-empty strings")
+        candidate = Path(value).expanduser()
+        resolved = candidate.resolve() if candidate.is_absolute() else (root / candidate).resolve()
+        try:
+            relative = resolved.relative_to(root).as_posix()
+        except ValueError as error:
+            raise ValueError(f"modified file path is outside the project root: {value}") from error
+        if relative not in normalized:
+            normalized.append(relative)
+    return normalized
+
+
+def _escape_link_label(value: str) -> str:
+    return value.replace("\\", "\\\\").replace("[", "\\[").replace("]", "\\]")
+
+
+def _modified_files_section(root: Path, report_path: Path, modified_files: list[str]) -> list[str]:
+    report_relative = report_path.relative_to(root).as_posix()
+    paths = [*modified_files]
+    if report_relative not in paths:
+        paths.append(report_relative)
+    links = []
+    for path in paths:
+        target = Path(os.path.relpath(root / path, report_path.parent)).as_posix()
+        links.append(f"- [{_escape_link_label(path)}]({quote(target, safe='/-._')})")
+    return _section("Modified files", "\n".join(links))
+
+
+def _render_report(
+    root: Path,
+    report_path: Path,
+    request: str,
+    summary: str,
+    modified_files: list[str],
+    changes: list[str] | None,
+    validation: list[str] | None,
+    status: str,
+    generated_date: str,
+) -> str:
+    lines = ["# Request Report", "", f"- Status: {status}", f"- Date: {generated_date}", ""]
+    lines.extend(_section("User request", request))
+    lines.extend(_section("Summary", summary))
+    lines.extend(_modified_files_section(root, report_path, modified_files))
+    lines.extend(_bullet_section("Changes", changes))
+    lines.extend(_bullet_section("Validation", validation))
+    return "\n".join(lines).rstrip() + "\n"
+
+
+async def run(
+    root: str,
+    feature: str,
+    request: str,
+    summary: str,
+    modified_files: list[str],
+    changes: list[str] | None = None,
+    validation: list[str] | None = None,
+    status: str = "completed",
+    date: str | None = None,
+) -> str:
+    """Create and return one atomic numbered report for a completed request."""
+    root_path = Path(root).expanduser().resolve()
+    if not root_path.is_dir():
+        raise NotADirectoryError(f"{root} is not an existing directory")
+    if not isinstance(feature, str) or not feature.strip():
+        raise ValueError("feature must be a non-empty string")
+    if not isinstance(request, str) or not request.strip():
+        raise ValueError("request must be a non-empty string")
+    if not isinstance(summary, str) or not summary.strip():
+        raise ValueError("summary must be a non-empty string")
+    if status not in _VALID_STATUSES:
+        raise ValueError(f"status must be one of: {', '.join(sorted(_VALID_STATUSES))}")
+
+    generated_date = _validate_date(date)
+    normalized_modified_files = _normalize_modified_files(root_path, modified_files)
+    report_dir = root_path / "docs" / "report"
+    report_dir.mkdir(parents=True, exist_ok=True)
+    slug = _slugify(feature)
+    number = _next_number(report_dir)
+
+    while True:
+        report_path = report_dir / f"{number:0{_REPORT_NUMBER_WIDTH}d}_{slug}_{generated_date}.md"
+        content = _render_report(
+            root_path,
+            report_path,
+            request,
+            summary,
+            normalized_modified_files,
+            changes,
+            validation,
+            status,
+            generated_date,
+        )
+        try:
+            with report_path.open("x", encoding="utf-8") as report_file:
+                report_file.write(content)
+            return str(report_path)
+        except FileExistsError:
+            number += 1
+
+
+__all__ = ["run"]

package/skills/skill-creator/SKILL.md

@@ -5,7 +5,7 @@ description: Create, validate, and install ASM Agent skills - both markdown skil
 
 # Skill Creator
 
-A skill is a directory with a `SKILL.md` file (YAML frontmatter + markdown instructions). At startup ASM Agent reads only each skill's name and description into the system prompt; the full file loads on demand when a task matches. ASM Agent follows the [Agent Skills standard](https://agentskills.io/specification) and extends it with Python-backed skills.
+A skill is a directory with a `SKILL.md` file (YAML frontmatter + markdown instructions). At startup ASM Agent reads each skill's name and description into the system prompt. The full file normally loads on demand when a task matches. Skills marked `always-apply: true` are an ASM Agent extension whose full instructions are injected at startup. ASM Agent follows the [Agent Skills standard](https://agentskills.io/specification) and extends it with Python-backed and always-applied skills.
 
 | Kind | What it is | When to use |
 |---|---|---|
@@ -51,6 +51,7 @@ description: What this skill does and when to use it. Be specific.
 |---|---|---|
 | `name` | Yes | Max 64 chars. Lowercase a-z, 0-9, hyphens. No leading/trailing/consecutive hyphens. Must match the parent directory name. |
 | `description` | Yes | Max 1024 chars. A skill with a missing or empty description is **silently not loaded**. |
+| `always-apply` | No | `true` injects the full skill instructions into every system prompt. Reserve this for small, universal policies. |
 | `disable-model-invocation` | No | `true` hides the skill from the system prompt; only explicit `/skill:<name>` invokes it. |
 | `license` | No | License name or reference to a bundled file. |
 | `compatibility` | No | Max 500 chars. Environment requirements. |