tools/skills: create and modify skills behind a grant

skill_create writes a SKILL.md (name, description, body) plus whatever bundled
files the model lists, and skill_edit changes one file of an existing skill
either by literal replacement, by appending, or by rewriting it. Both resolve
every path inside the skill directory first, so a bad argument is answered
before anything is written and before the human is asked anything; a rewritten
SKILL.md is re-parsed so a skill that lost its description (or its frontmatter)
says so instead of failing quietly. The store is reloaded after a write, which
makes a new skill visible to the very next skill_list.

Writing is a host policy, not a directory-access grant: the denylist wins
first, then a session grant, then [skills].allow_write, then the host's confirm
hook — asked once per skill directory, so one answer covers its files. A host
without a hook denies, which keeps the library default safe; the confirm can
also answer 'session' to cover the rest of the chat.

src/plyngent/cli/display.py

@@ -754,6 +754,43 @@ def _skill_search_detail(_args_json: str, result: str) -> str:
     return _pretty_segments((f"({len(matches)} {match_unit} in {len(skills)} {skill_unit})", None))
 
 
+def _skill_create_prefix(args_json: str) -> str:
+    name = _json_str_arg(args_json, "name") or "?"
+    return _pretty_prefix(f"* Skill Create '{name}' ")
+
+
+def _skill_create_detail(_args_json: str, result: str) -> str:
+    """``skill_create`` outcome: created (with any notes), or the failure."""
+    if result.startswith("error:"):
+        return _pretty_segments((f"({result})", "red"))
+    detail = _pretty_segments(("(created)", "green"))
+    notes = result.partition("\nnotes: ")[2]
+    if notes:
+        detail += _pretty_segments((f" — {notes}", "yellow"))
+    return detail
+
+
+def _skill_edit_prefix(args_json: str) -> str:
+    name = _json_str_arg(args_json, "name") or "?"
+    file = _json_str_arg(args_json, "file") or ""
+    subject = f"'{name}'" if file in {"", _SKILL_MAIN_FILE} else f"'{name}' {file}"
+    return _pretty_prefix(f"* Skill Edit {subject} ")
+
+
+def _skill_edit_detail(_args_json: str, result: str) -> str:
+    """``skill_edit`` outcome: the change made, or the failure."""
+    if result.startswith("error:"):
+        return _pretty_segments((f"({result})", "red"))
+    first = result.splitlines()[0] if result else ""
+    match = re.search(r"\((.+)\)$", first)
+    text = match.group(1) if match is not None else "updated"
+    detail = _pretty_segments((f"({text})", "green"))
+    notes = result.partition("\nnotes: ")[2]
+    if notes:
+        detail += _pretty_segments((f" — {notes}", "yellow"))
+    return detail
+
+
 # Pretty tools: ``prefix`` prints as the call starts, ``detail`` when it lands.
 _PRETTY_LINES: dict[str, PrettyLine] = {
     "read_file": PrettyLine(prefix=_read_file_prefix, detail=_read_file_detail),
@@ -781,6 +818,8 @@ _PRETTY_LINES: dict[str, PrettyLine] = {
     "skill_list": PrettyLine(prefix=_skill_list_prefix, detail=_skill_list_detail),
     "skill_read": PrettyLine(prefix=_skill_read_prefix, detail=_skill_read_detail),
     "skill_search": PrettyLine(prefix=_skill_search_prefix, detail=_skill_search_detail),
+    "skill_create": PrettyLine(prefix=_skill_create_prefix, detail=_skill_create_detail),
+    "skill_edit": PrettyLine(prefix=_skill_edit_prefix, detail=_skill_edit_detail),
     "open_pty": PrettyLine(prefix=_open_pty_prefix, detail=_open_pty_detail),
     "read_pty": _pty_session_line("Read", _read_pty_detail),
     "write_pty": _pty_session_line("Write", _pty_write_detail),

src/plyngent/skills/__init__.py

@@ -5,6 +5,7 @@ from .discovery import Skill as Skill
 from .discovery import SkillRoot as SkillRoot
 from .discovery import SkillStore as SkillStore
 from .discovery import build_roots as build_roots
+from .discovery import resolve_inside as resolve_inside
 from .discovery import resolve_skill_file as resolve_skill_file
 from .discovery import validate_skill_name as validate_skill_name
 from .frontmatter import FrontmatterError as FrontmatterError
@@ -18,5 +19,7 @@ __all__ = [
     "SkillStore",
     "build_roots",
     "parse_frontmatter",
+    "resolve_inside",
+    "resolve_skill_file",
     "validate_skill_name",
 ]

src/plyngent/skills/discovery.py

@@ -136,26 +136,35 @@ def validate_skill_name(name: str) -> str | None:
     return None
 
 
-def resolve_skill_file(skill: Skill, relative: str) -> Path | None:
-    """Resolve *relative* inside *skill*; ``None`` when it escapes the directory.
+def resolve_inside(base: Path, relative: str) -> Path | None:
+    """Resolve *relative* under *base*; ``None`` when it is absolute or escapes.
 
-    The default (empty *relative*) is the skill's own ``SKILL.md``. Symlinks are
-    followed by the resolve, so a link pointing outside the skill is rejected
-    instead of becoming a way around the boundary.
+    Symlinks are followed by the resolve, so a link pointing outside *base* is
+    rejected instead of becoming a way around the boundary.
     """
-    token = relative.strip() or SKILL_FILE
+    token = relative.strip()
+    if not token:
+        return None
     candidate = Path(token)
     if candidate.is_absolute():
         return None
     try:
-        base = skill.path.resolve()
-        target = (base / candidate).resolve()
-        _ = target.relative_to(base)
+        root = base.resolve()
+        target = (root / candidate).resolve()
+        _ = target.relative_to(root)
     except OSError, ValueError:
         return None
     return target
 
 
+def resolve_skill_file(skill: Skill, relative: str) -> Path | None:
+    """Resolve *relative* inside *skill*; ``None`` when it escapes the directory.
+
+    The default (empty *relative*) is the skill's own ``SKILL.md``.
+    """
+    return resolve_inside(skill.path, relative.strip() or SKILL_FILE)
+
+
 class SkillStore:
     """Skills discovered under *roots*, highest-priority root first."""
 

src/plyngent/tools/context.py

@@ -86,6 +86,9 @@ class SessionState:
     # Directory-access grants for this session (resolved path → mode). Config /
     # process-scoped grants live on WorkspacePolicy; see plyngent.tools.access.
     access_grants: dict[Path, AccessMode] = field(default_factory=dict)
+    # Skill directories the human allowed this chat to write (resolved paths);
+    # the standing grant lives in [skills].allow_write (tools/skills.py).
+    skill_write_roots: set[Path] = field(default_factory=set)
 
     def has_grant(self, tool_name: str) -> bool:
         return bool(self.grants.get(tool_name))

src/plyngent/tools/skills.py

@@ -13,15 +13,35 @@ directory-access path of ``request_directory_access``.
 
 from __future__ import annotations
 
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
+
 from plyngent.agent import ToolTag, tool
 from plyngent.agent.budget import DEFAULT_TOOL_RESULT_MAX_CHARS
-from plyngent.skills import SKILL_FILE, Skill, SkillStore, resolve_skill_file
+from plyngent.skills import (
+    SKILL_FILE,
+    FrontmatterError,
+    Skill,
+    SkillStore,
+    parse_frontmatter,
+    resolve_inside,
+    resolve_skill_file,
+    validate_skill_name,
+)
 from plyngent.tools.file.grep_files import DEFAULT_MAX_MATCHES
 from plyngent.tools.file.grep_files import grep_files as _grep_files
 from plyngent.tools.file.read import read_file as _read_file
+from plyngent.tools.workspace import DEFAULT_POLICY_CONFIRM_TIMEOUT_SECONDS
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+    from plyngent.tools.context import InstanceState, SessionState
 
 # Keeps a listing readable when a third-party root holds a pile of skills.
 _MAX_LISTED_ISSUES = 8
+_SKILL_WRITE_POLICY_KEY = "skill_write_policy"
 
 
 def get_skill_store() -> SkillStore | None:
@@ -206,10 +226,339 @@ async def skill_search(
     return body
 
 
+# -- writing (needs a grant) -------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class SkillWriteDecision:
+    """A human's answer to a skill write prompt: allow, and for how long."""
+
+    allow: bool
+    # True keeps the grant for the rest of this chat session (the standing
+    # alternative is ``[skills].allow_write`` in the config).
+    session: bool = False
+
+
+type SkillWriteConfirmHook = Callable[[Path, str, str, float], SkillWriteDecision | bool | None]
+
+
+@dataclass(frozen=True, slots=True)
+class SkillWritePolicy:
+    """How this host authorizes writes to skill directories.
+
+    ``allow_all`` is the standing grant (``[skills].allow_write``). Otherwise the
+    host's ``confirm`` hook is asked per skill directory; a host that installs no
+    hook denies, which keeps the library default safe.
+    """
+
+    allow_all: bool = False
+    confirm: SkillWriteConfirmHook | None = None
+    timeout: float = DEFAULT_POLICY_CONFIRM_TIMEOUT_SECONDS
+
+
+def set_skill_write_policy(policy: SkillWritePolicy | None, *, instance: InstanceState | None = None) -> None:
+    """Install (or clear) the host's skill-write policy on the bound instance."""
+    from plyngent.tools.context import require_instance
+
+    inst = instance if instance is not None else require_instance()
+    if policy is None:
+        _ = inst.extras.pop(_SKILL_WRITE_POLICY_KEY, None)
+        return
+    inst.extras[_SKILL_WRITE_POLICY_KEY] = policy
+
+
+def get_skill_write_policy() -> SkillWritePolicy | None:
+    """The policy installed on the bound instance, if any."""
+    from plyngent.tools.context import get_instance
+
+    instance = get_instance()
+    return cast("SkillWritePolicy | None", instance.extras.get(_SKILL_WRITE_POLICY_KEY)) if instance else None
+
+
+def _denied_by_policy(*paths: Path) -> str | None:
+    """Hard path denylist for a write target (never skippable by a grant)."""
+    from plyngent.tools.workspace import denylist_match
+
+    for path in paths:
+        for candidate, directory in ((path, path.is_dir()), (path.parent, True)):
+            matched = denylist_match(candidate, directory=directory)
+            if matched is not None:
+                return f"error: path denied by policy (matched {matched!r}): {path}"
+    return None
+
+
+def _prompt_write(
+    skill_dir: Path,
+    *,
+    action: str,
+    detail: str,
+    policy: SkillWritePolicy,
+    session: SessionState | None,
+) -> str | None:
+    """Ask the host's hook and record a session grant when the human chose one."""
+    hook = policy.confirm
+    if hook is None:
+        return None
+    try:
+        decision = hook(skill_dir, action, detail, policy.timeout)
+    except Exception as exc:  # noqa: BLE001 — surface a failing prompt to the model
+        return f"error: skill write confirm failed: {exc}"
+    allowed = decision is True or (isinstance(decision, SkillWriteDecision) and decision.allow)
+    if not allowed:
+        return f"error: skill write to {skill_dir} denied (declined or timed out after {policy.timeout:g}s)"
+    if isinstance(decision, SkillWriteDecision) and decision.session and session is not None:
+        session.skill_write_roots.add(skill_dir)
+    return None
+
+
+def _authorize_write(skill_dir: Path, target: Path, *, action: str, detail: str) -> str | None:
+    """``None`` when a write to *target* inside *skill_dir* is authorized.
+
+    Grants are per **skill directory** — that is the unit the human is asked
+    about, and one answer covers every file of that skill. The denylist is
+    checked first and always wins; then a session grant, then
+    ``[skills].allow_write``, then the host's confirm hook. Without a hook the
+    write is denied rather than silently allowed.
+    """
+    denied = _denied_by_policy(target, skill_dir)
+    if denied is not None:
+        return denied
+    from plyngent.tools.context import get_session
+
+    session = get_session()
+    if session is not None and skill_dir in session.skill_write_roots:
+        return None
+    policy = get_skill_write_policy()
+    if policy is None or (policy.confirm is None and not policy.allow_all):
+        return (
+            "error: writing skills needs a grant (no confirm hook is installed; denied); "
+            "set [skills].allow_write = true to allow skill writes"
+        )
+    if policy.allow_all:
+        return None
+    return _prompt_write(skill_dir, action=action, detail=detail, policy=policy, session=session)
+
+
+def _frontmatter_scalar(text: str) -> str:
+    """One-line, quoted-if-needed frontmatter value for generated SKILL.md files."""
+    one_line = " ".join(text.split())
+    if not one_line:
+        return '""'
+    if any(char in one_line for char in ":#{}[]\"'"):
+        return '"' + one_line.replace('"', "'") + '"'
+    return one_line
+
+
+def _render_skill_md(name: str, description: str, body: str) -> str:
+    """Compose a minimal ``SKILL.md``: name, description, then the body."""
+    front = f"---\nname: {name}\ndescription: {_frontmatter_scalar(description)}\n---\n\n"
+    return front + body.strip() + "\n"
+
+
+def _skill_notes(skill_file: Path) -> str:
+    """Non-fatal notes after editing a ``SKILL.md`` (parse errors, missing fields)."""
+    try:
+        metadata, _body = parse_frontmatter(skill_file.read_text(encoding="utf-8", errors="replace"))
+    except (FrontmatterError, OSError) as exc:
+        return f"\nnotes: SKILL.md frontmatter not parsed ({exc}); it will use the directory name"
+    description = metadata.get("description")
+    if not isinstance(description, str) or not description.strip():
+        return "\nnotes: SKILL.md has no frontmatter description; the first paragraph will be used"
+    return ""
+
+
+def _write_file(target: Path, content: str) -> None:
+    """Write *content* under a skill, creating parent directories."""
+    target.parent.mkdir(parents=True, exist_ok=True)
+    _ = target.write_text(content, encoding="utf-8")
+
+
+def _create_target(store: SkillStore, name: str) -> tuple[Path, str] | str:
+    """Resolve the directory a new *name* goes into; error string when unusable."""
+    problem = validate_skill_name(name)
+    if problem is not None:
+        return f"error: {problem}"
+    root = store.default_write_root()
+    if root is None:
+        return "error: no skill root is configured; set [skills].paths or [skills].discover"
+    token = name.strip()
+    target = root.path / token
+    if (target / SKILL_FILE).is_file():
+        return f"error: skill {token!r} already exists at {target}; use skill_edit to change it"
+    if store.find(token) is not None:
+        return f"error: skill {token!r} is already visible from another root; edit it there instead"
+    return target, token
+
+
+def _bundled_targets(target: Path, files: dict[str, str], *, name: str) -> dict[Path, str] | str:
+    """Resolve every bundled file path before anything is written."""
+    resolved: dict[Path, str] = {}
+    for relative, content in files.items():
+        path = resolve_inside(target, relative)
+        if path is None:
+            return f"error: bundled file {relative!r} is outside skill {name!r}"
+        resolved[path] = content
+    return resolved
+
+
+@tool(tags=ToolTag.LOCAL | ToolTag.INSTANCE_STATE)
+async def skill_create(
+    name: str,
+    description: str,
+    body: str,
+    *,
+    files: dict[str, str] | None = None,
+) -> str:
+    """Create a new skill: a directory with a ``SKILL.md`` and optional files.
+
+    ``name`` is the skill name (lowercase letters, digits, hyphens); the skill
+    is written under the default write root (our own user skills directory
+    unless ``[skills].paths`` puts an explicit one first). ``body`` is the
+    instruction text, and ``files`` maps paths inside the skill to their content
+    (scripts, references, templates). Writing needs a grant: the human is asked
+    once per skill, or the whole feature is opened with ``[skills].allow_write``.
+    """
+    store = _store_or_error()
+    if isinstance(store, str):
+        return store
+    resolution = _create_target(store, name)
+    if isinstance(resolution, str):
+        return resolution
+    target, token = resolution
+    bundled = _bundled_targets(target, files or {}, name=token)
+    if isinstance(bundled, str):
+        return bundled
+
+    detail = f"create skill {token!r} at {target} (SKILL.md"
+    detail += f" + {len(bundled)} file(s)" if bundled else ""
+    detail += ")"
+    denial = _authorize_write(target, target, action="create", detail=detail)
+    if denial is not None:
+        return denial
+
+    try:
+        _write_file(target / SKILL_FILE, _render_skill_md(token, description, body))
+        for path, content in bundled.items():
+            _write_file(path, content)
+    except OSError as exc:
+        return f"error: failed to create skill {token!r}: {exc}"
+    store.reload()
+    return f"created skill {token!r} at {target}{_skill_notes(target / SKILL_FILE)}"
+
+
+def _edit_target(store: SkillStore, name: str, file: str) -> tuple[Skill, Path, str] | str:
+    """Look up the skill and the file to edit inside it."""
+    skill = store.find(name)
+    if skill is None:
+        return _unknown_skill(name)
+    target = resolve_skill_file(skill, file)
+    if target is None:
+        return f"error: file {file!r} is outside skill {skill.name!r}"
+    return skill, target, file.strip() or SKILL_FILE
+
+
+def _edit_mode_error(*, old_string: str, new_string: str, append: str) -> str | None:
+    """Reject an edit request that names no form, or two at once."""
+    if not (old_string or new_string or append):
+        return "error: nothing to write; pass old_string + new_string, append, or new_string alone"
+    if old_string and append:
+        return "error: use either old_string + new_string or append, not both"
+    return None
+
+
+def _apply_text_edit(
+    existing: str | None,
+    *,
+    relative: str,
+    skill_name: str,
+    old_string: str,
+    new_string: str,
+    append: str,
+    replace_all: bool,
+) -> tuple[str, str] | str:
+    """Compute the new file text; ``(text, detail)`` or an error string."""
+    mode_error = _edit_mode_error(old_string=old_string, new_string=new_string, append=append)
+    if mode_error is not None:
+        return mode_error
+    if old_string:
+        text = existing or ""
+        found = text.count(old_string)  # non-overlapping, like str.replace
+        if found == 0:
+            return f"error: old_string not found in {relative} of skill {skill_name!r}"
+        limit = found if replace_all else 1
+        detail = f"{relative}: replaced {limit} of {found} occurrence(s)"
+        return text.replace(old_string, new_string, limit), detail
+    if append:
+        if existing is None:
+            return f"error: no such file in skill {skill_name!r}: {relative}"
+        separator = "" if not existing or existing.endswith("\n") else "\n"
+        detail = f"{relative}: appended {len(append)} characters"
+        return f"{existing}{separator}{append}", detail
+    return new_string, f"{relative}: rewrote {len(new_string)} characters"
+
+
+@tool(tags=ToolTag.LOCAL | ToolTag.INSTANCE_STATE)
+async def skill_edit(
+    name: str,
+    *,
+    file: str = SKILL_FILE,
+    old_string: str = "",
+    new_string: str = "",
+    append: str = "",
+    replace_all: bool = False,
+) -> str:
+    """Change one file of an existing skill (``SKILL.md`` by default).
+
+    Three mutually exclusive forms:
+
+    - ``old_string`` + ``new_string``: literal replacement of the first match,
+      or of every match with ``replace_all``;
+    - ``append``: add text at the end of the file;
+    - ``new_string`` alone: rewrite the whole file (a missing file is created,
+      parent directories included).
+
+    Writing needs a grant for that skill (asked once, or standing via
+    ``[skills].allow_write``).
+    """
+    store = _store_or_error()
+    if isinstance(store, str):
+        return store
+    resolution = _edit_target(store, name, file)
+    if isinstance(resolution, str):
+        return resolution
+    skill, target, relative = resolution
+    existing = target.read_text(encoding="utf-8", errors="replace") if target.is_file() else None
+    outcome = _apply_text_edit(
+        existing,
+        relative=relative,
+        skill_name=skill.name,
+        old_string=old_string,
+        new_string=new_string,
+        append=append,
+        replace_all=replace_all,
+    )
+    if isinstance(outcome, str):
+        return outcome
+    updated, detail = outcome
+
+    denial = _authorize_write(skill.path, target, action="update", detail=f"{skill.name}: {detail}")
+    if denial is not None:
+        return denial
+    try:
+        _write_file(target, updated)
+    except OSError as exc:
+        return f"error: failed to write {relative} of skill {skill.name!r}: {exc}"
+    store.reload()
+    notes = _skill_notes(target) if target.name == SKILL_FILE else ""
+    return f"updated skill {skill.name!r} ({detail}){notes}"
+
+
 SKILL_TOOLS = [
     skill_list,
     skill_read,
     skill_search,
+    skill_create,
+    skill_edit,
 ]
 
 # Fed to the catalog selection filter: ``[skills].enabled = false`` drops these