Refactor skills CLI to plain agent with SessionStart hook

- Rename `plain skills` to `plain agent` with subcommands:
  - `plain agent install` - Install skills and set up hooks
  - `plain agent skills` - List available skills
  - `plain agent context` - Output framework context
- Add SessionStart hook that runs `plain agent context` at session start
- Remove plain-principles skill (content now in context output)
- Add --no-headers and --no-body flags to plain request
- Improve plain-request description for better skill activation
- Move code style guidelines to plain-fix skill
- Mark plain-tailwind and plain-models as not user-invocable
- Update plain dev to call `plain agent install`

Author: davegaeddert

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run plain agent context 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
+  }
+}

example/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run plain agent context 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
+  }
+}

plain-code/plain/code/skills/plain-fix/SKILL.md

@@ -11,6 +11,11 @@ uv run plain fix [path]
 
 Automatically fixes formatting and linting issues using ruff and biome.
 
+## Code Style
+
+- Add `from __future__ import annotations` at the top of Python files
+- Keep imports at the top of the file unless avoiding circular imports
+
 Options:
 
 - `--unsafe-fixes` - Apply ruff unsafe fixes

plain-dev/plain/dev/core.py

@@ -142,7 +142,7 @@ def run(self, *, reinstall_ssl: bool = False) -> int:
         )
 
         self.symlink_plain_src()
-        self.install_skills()
+        self.install_agent()
         self.modify_hosts_file()
 
         print_event("Running preflight checks...", newline=False)
@@ -229,24 +229,24 @@ def symlink_plain_src(self) -> None:
         if plain_path.exists() and not symlink_path.exists():
             symlink_path.symlink_to(plain_path)
 
-    def install_skills(self) -> None:
-        """Install skills from Plain packages to .claude/agents/."""
+    def install_agent(self) -> None:
+        """Install AI agent skills and hooks."""
         try:
             result = subprocess.run(
-                [sys.executable, "-m", "plain", "skills", "--install"],
+                [sys.executable, "-m", "plain", "agent", "install"],
                 check=False,
                 capture_output=True,
                 text=True,
             )
             if result.returncode != 0 and result.stderr:
                 click.secho(
-                    f"Warning: Failed to install skills: {result.stderr}",
+                    f"Warning: Failed to install agent: {result.stderr}",
                     fg="yellow",
                     err=True,
                 )
         except Exception as e:
             click.secho(
-                f"Warning: Failed to install skills: {e}",
+                f"Warning: Failed to install agent: {e}",
                 fg="yellow",
                 err=True,
             )

plain-dev/plain/dev/skills/plain-dev/SKILL.md

@@ -11,6 +11,8 @@ Run `uv run plain dev` to start the development server.
 
 The server URL will be displayed (typically `https://<project>.localhost:8443`).
 
+This also runs `plain agent install` to set up AI agent skills and hooks.
+
 ## Logs
 
 - `uv run plain dev logs` - Show log output for running processes

plain-models/plain/models/skills/plain-models/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plain-models
 description: Manages database migrations and model changes. Use when creating migrations, running migrations, or modifying models.
+user-invocable: false
 ---
 
 # Database Migrations

plain-tailwind/plain/tailwind/skills/plain-tailwind/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plain-tailwind
 description: Provides Tailwind CSS patterns for Plain templates. Use when styling templates or working with conditional CSS classes.
+user-invocable: false
 ---
 
 # Tailwind CSS Patterns

plain/plain/cli/skills.py plain/plain/cli/agent.pyplain/plain/cli/skills.py renamed to plain/plain/cli/agent.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import importlib.util
+import json
 import pkgutil
 import shutil
 from pathlib import Path
@@ -127,29 +128,63 @@ def _install_skills_to(
     return installed_count, removed_count
 
 
-@click.command()
-@click.option(
-    "--install/--no-install",
-    is_flag=True,
-    help="Install skills to agent directories",
-)
-def skills(install: bool) -> None:
-    """Install skills from Plain packages"""
+def _setup_session_hook(dest_dir: Path) -> None:
+    """Create or update settings.json with SessionStart hook."""
+    settings_file = dest_dir / "settings.json"
 
+    # Load existing settings or start fresh
+    if settings_file.exists():
+        settings = json.loads(settings_file.read_text())
+    else:
+        settings = {}
+
+    # Ensure hooks structure exists
+    if "hooks" not in settings:
+        settings["hooks"] = {}
+
+    # Define the Plain hook - calls the agent context command directly
+    plain_hook = {
+        "matcher": "startup|resume",
+        "hooks": [
+            {
+                "type": "command",
+                "command": "uv run plain agent context 2>/dev/null || true",
+            }
+        ],
+    }
+
+    # Get existing SessionStart hooks, remove any existing plain hook
+    session_hooks = settings["hooks"].get("SessionStart", [])
+    session_hooks = [h for h in session_hooks if "plain agent" not in str(h)]
+    # Also remove old plain-context.md hooks for migration
+    session_hooks = [h for h in session_hooks if "plain-context.md" not in str(h)]
+    session_hooks.append(plain_hook)
+    settings["hooks"]["SessionStart"] = session_hooks
+
+    settings_file.write_text(json.dumps(settings, indent=2) + "\n")
+
+
+@click.group()
+def agent() -> None:
+    """AI agent integration for Plain projects"""
+    pass
+
+
+@agent.command()
+def context() -> None:
+    """Output Plain framework context for AI agents"""
+    click.echo("This is a Plain project. Use the /plain-* skills for common tasks.")
+
+
+@agent.command()
+def install() -> None:
+    """Install skills and hooks to agent directories"""
     skills_by_package = _get_packages_with_skills()
 
     if not skills_by_package:
         click.echo("No skills found in installed packages.")
         return
 
-    if not install:
-        # Just list available skills
-        click.echo("Available skills:")
-        for pkg_name in sorted(skills_by_package.keys()):
-            for skill_dir in skills_by_package[pkg_name]:
-                click.echo(f"  - {skill_dir.name} (from {pkg_name})")
-        return
-
     # Find destinations based on what agent directories exist
     destinations = _get_skill_destinations()
 
@@ -163,10 +198,30 @@ def skills(install: bool) -> None:
     # Install to each destination
     for dest in destinations:
         installed_count, removed_count = _install_skills_to(dest, skills_by_package)
-        if installed_count > 0 or removed_count > 0:
-            parts = []
-            if installed_count > 0:
-                parts.append(f"installed {installed_count}")
-            if removed_count > 0:
-                parts.append(f"removed {removed_count}")
-            click.echo(f"Skills: {', '.join(parts)} in {dest}/")
+
+        # Setup hook in parent directory
+        parent_dir = dest.parent  # .claude/ or .codex/
+        _setup_session_hook(parent_dir)
+
+        parts = []
+        if installed_count > 0:
+            parts.append(f"installed {installed_count} skills")
+        if removed_count > 0:
+            parts.append(f"removed {removed_count} skills")
+        parts.append("updated hooks")
+        click.echo(f"Agent: {', '.join(parts)} in {parent_dir}/")
+
+
+@agent.command()
+def skills() -> None:
+    """List available skills from installed packages"""
+    skills_by_package = _get_packages_with_skills()
+
+    if not skills_by_package:
+        click.echo("No skills found in installed packages.")
+        return
+
+    click.echo("Available skills:")
+    for pkg_name in sorted(skills_by_package.keys()):
+        for skill_dir in skills_by_package[pkg_name]:
+            click.echo(f"  - {skill_dir.name} (from {pkg_name})")

plain/plain/cli/core.py

@@ -9,6 +9,7 @@
 import plain.runtime
 from plain.exceptions import ImproperlyConfigured
 
+from .agent import agent
 from .build import build
 from .changelog import changelog
 from .chores import chores
@@ -22,7 +23,6 @@
 from .server import server
 from .settings import settings
 from .shell import run, shell
-from .skills import skills
 from .upgrade import upgrade
 from .urls import urls
 from .utils import utils
@@ -35,7 +35,7 @@ def plain_cli() -> None:
 
 plain_cli.add_command(docs)
 plain_cli.add_command(request)
-plain_cli.add_command(skills)
+plain_cli.add_command(agent)
 plain_cli.add_command(preflight_cli)
 plain_cli.add_command(create)
 plain_cli.add_command(chores)

plain/plain/cli/request.py

@@ -40,6 +40,16 @@
     multiple=True,
     help="Additional headers (format: 'Name: Value')",
 )
+@click.option(
+    "--no-headers",
+    is_flag=True,
+    help="Hide response headers from output",
+)
+@click.option(
+    "--no-body",
+    is_flag=True,
+    help="Hide response body from output",
+)
 def request(
     path: str,
     method: str,
@@ -48,6 +58,8 @@ def request(
     follow: bool,
     content_type: str | None,
     headers: tuple[str, ...],
+    no_headers: bool,
+    no_body: bool,
 ) -> None:
     """Make HTTP requests against the dev database"""
 
@@ -155,14 +167,14 @@ def request(
         click.echo()
 
         # Show headers
-        if response.headers:
+        if response.headers and not no_headers:
             click.secho("Response Headers:", fg="yellow", bold=True)
             for key, value in response.headers.items():
                 click.echo(f"  {key}: {value}")
             click.echo()
 
         # Show response content last
-        if response.content:
+        if response.content and not no_body:
             content_type = response.headers.get("Content-Type", "")
 
             if "json" in content_type.lower():
@@ -187,7 +199,7 @@ def request(
                 click.secho("Response Body:", fg="yellow", bold=True)
                 content = response.content.decode("utf-8", errors="replace")
                 click.echo(content)
-        else:
+        elif not no_body:
             click.secho("(No response body)", fg="yellow", dim=True)
 
     except Exception as e: