feat: add output profile support for generate and update commands

Author: airscripts

README.md

@@ -245,13 +245,15 @@ agentskill generate <repo>
 agentskill generate <repo> --out AGENTS.md
 agentskill generate <repo> --reference ../ref-a --reference ../ref-b
 agentskill generate <repo> --interactive
+agentskill generate <repo> --profile comprehensive
 
 # Update or create AGENTS.md in place
 agentskill update <repo>
 agentskill update <repo> --section testing
 agentskill update <repo> --exclude-section git
 agentskill update <repo> --force
 agentskill update <repo> --out updated-AGENTS.md
+agentskill update <repo> --profile concise
 
 # Retained wrapper entrypoints for operator/skill workflows
 python scripts/analyze.py <repo> --pretty

agentskill/lib/generate_runner.py

@@ -13,6 +13,7 @@
     interactive_section_notes,
 )
 from agentskill.lib.output import validate_out_path
+from agentskill.lib.output_profiles import validate_output_profile
 from agentskill.lib.reference_flow import load_reference_documents
 from agentskill.lib.reference_initialization import (
     initialize_from_references,
@@ -46,7 +47,15 @@ def render_agents_markdown(
     references: list[str] | None = None,
     interactive: bool = False,
     prompt_io: PromptIO | None = None,
+    profile: str = "concise",
 ) -> str:
+    profile = validate_output_profile(profile)
+
+    if profile == "split":
+        raise NotImplementedError(
+            "generate with profile 'split' is not implemented yet"
+        )
+
     documents = load_reference_documents(references)
     analysis = run_all(str(repo))
     feedback = load_feedback(repo)
@@ -83,6 +92,7 @@ def generate_agents(
     references: list[str] | None = None,
     interactive: bool = False,
     prompt_io: PromptIO | None = None,
+    profile: str = "concise",
 ) -> int:
     try:
         repo_path = validate_repo(repo)
@@ -91,6 +101,7 @@ def generate_agents(
             references=references,
             interactive=interactive,
             prompt_io=prompt_io,
+            profile=profile,
         )
 
         if out is not None:

agentskill/lib/output_profiles.py

@@ -0,0 +1,20 @@
+"""Shared output profile contract for generate and update flows."""
+
+SUPPORTED_OUTPUT_PROFILES = ("concise", "comprehensive", "split")
+DEFAULT_OUTPUT_PROFILE = "concise"
+
+
+def validate_output_profile(value: str) -> str:
+    """Normalize and validate an output profile name.
+
+    Returns the normalized profile string on success.
+
+    Raises ValueError for unsupported values.
+    """
+    normalized = value.strip().lower()
+
+    if normalized not in SUPPORTED_OUTPUT_PROFILES:
+        allowed = ", ".join(SUPPORTED_OUTPUT_PROFILES)
+        raise ValueError(f"unsupported output profile: {value!r} (allowed: {allowed})")
+
+    return normalized

agentskill/lib/update_runner.py

@@ -17,6 +17,7 @@
     normalize_section_name,
 )
 from agentskill.lib.output import validate_out_path
+from agentskill.lib.output_profiles import validate_output_profile
 from agentskill.lib.runner import run_all
 from agentskill.lib.update_feedback import (
     SectionFeedback,
@@ -1030,9 +1031,17 @@ def update_agents(
     exclude_sections: list[str] | None = None,
     force: bool = False,
     out: str | None = None,
+    profile: str = "concise",
 ) -> int:
     """Update or create AGENTS.md for a repository."""
     try:
+        profile = validate_output_profile(profile)
+
+        if profile == "split":
+            raise NotImplementedError(
+                "update with profile 'split' is not implemented yet"
+            )
+
         repo_path = validate_repo(repo)
         analysis = run_all(str(repo_path))
         feedback = load_feedback(repo_path)

agentskill/main.py

@@ -6,6 +6,10 @@
 from agentskill.lib.generate_runner import generate_agents
 from agentskill.lib.logging_utils import configure_logging
 from agentskill.lib.output import run_and_output, write_output
+from agentskill.lib.output_profiles import (
+    DEFAULT_OUTPUT_PROFILE,
+    validate_output_profile,
+)
 from agentskill.lib.runner import COMMANDS, run_many
 from agentskill.lib.update_runner import update_agents
 
@@ -53,12 +57,21 @@ def cmd_update(args: argparse.Namespace) -> int:
         print("update does not support --pretty", file=sys.stderr)
         return 1
 
+    try:
+        profile = validate_output_profile(
+            getattr(args, "profile", DEFAULT_OUTPUT_PROFILE)
+        )
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
     return update_agents(
         args.repo,
         include_sections=getattr(args, "section", None),
         exclude_sections=getattr(args, "exclude_section", None),
         force=args.force,
         out=getattr(args, "out", None),
+        profile=profile,
     )
 
 
@@ -67,11 +80,20 @@ def cmd_generate(args: argparse.Namespace) -> int:
         print("generate does not support --pretty", file=sys.stderr)
         return 1
 
+    try:
+        profile = validate_output_profile(
+            getattr(args, "profile", DEFAULT_OUTPUT_PROFILE)
+        )
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
     return generate_agents(
         args.repo,
         out=getattr(args, "out", None),
         references=getattr(args, "reference", None),
         interactive=getattr(args, "interactive", False),
+        profile=profile,
     )
 
 
@@ -96,9 +118,11 @@ def main(argv: list[str] | None = None) -> int:
     p_analyze.add_argument(
         "repos", nargs="+", metavar="repo", help="Path(s) to repository"
     )
+
     p_analyze.add_argument(
         "--lang", help="Filter to a single language where applicable"
     )
+
     p_analyze.add_argument(
         "--reference",
         action="append",
@@ -126,48 +150,66 @@ def main(argv: list[str] | None = None) -> int:
     p_symbols = sub.add_parser(
         "symbols", help="Symbol name extraction and pattern clustering"
     )
+
     p_symbols.add_argument("repo", help="Path to repository")
     p_symbols.add_argument("--lang", help="Filter to a single language")
 
     p_tests = sub.add_parser(
         "tests", help="Test-to-source mapping and framework detection"
     )
-    p_tests.add_argument("repo", help="Path to repository")
 
+    p_tests.add_argument("repo", help="Path to repository")
     p_update = sub.add_parser("update", help="Update or create AGENTS.md")
     p_update.add_argument("repo", help="Path to repository")
+
     p_update.add_argument(
         "--section",
         action="append",
         help="Regenerate only the named section; may be repeated",
     )
+
     p_update.add_argument(
         "--exclude-section",
         action="append",
         help="Skip regenerating the named section; may be repeated",
     )
+
     p_update.add_argument(
         "--force",
         action="store_true",
         help="Rebuild AGENTS.md from regenerated sections only",
     )
+
     p_update.add_argument("--out", metavar="FILE", help="Write markdown to file")
+    p_update.add_argument(
+        "--profile",
+        default=DEFAULT_OUTPUT_PROFILE,
+        help=f"Output profile (default: {DEFAULT_OUTPUT_PROFILE})",
+    )
 
     p_generate = sub.add_parser(
         "generate", help="Generate AGENTS.md markdown from repository analysis"
     )
+
     p_generate.add_argument("repo", help="Path to repository")
     p_generate.add_argument(
         "--reference",
         action="append",
         help="Reference repository path or URL; may be repeated",
     )
+
     p_generate.add_argument(
         "--interactive",
         action="store_true",
         help="Prompt for missing or ambiguous generation inputs",
     )
+
     p_generate.add_argument("--out", metavar="FILE", help="Write markdown to file")
+    p_generate.add_argument(
+        "--profile",
+        default=DEFAULT_OUTPUT_PROFILE,
+        help=f"Output profile (default: {DEFAULT_OUTPUT_PROFILE})",
+    )
 
     for p in [
         p_scan,

docs/reference/cli.md

@@ -39,6 +39,7 @@ generation, and update workflows.
 - `--out` writes JSON or markdown to a file instead of stdout.
 - `--reference` is supported by `analyze` and `generate`.
 - `--interactive` is supported by `generate` only.
+- `--profile` is supported by `generate` and `update`. Accepted values are `concise` (default), `comprehensive`, and `split`. The `split` profile is accepted at the CLI level but raises a not-implemented error until multi-file emission is ready.
 - `--section`, `--exclude-section`, and `--force` are supported by `update`.
 
 Release-grade CLI contract tests live in `tests/test_cli_contract.py`.