feat: add compact output format

The default text output prints every passing check, the token tables, and the analysis sections for each skill. Validating a directory of skills produces hundreds of lines in which the few findings that need attention are buried.

Add -o compact, which renders each skill as a single line naming it and its outcome, with any warnings and errors listed beneath it. Passing and informational findings, token counts, and the content and contamination analysis sections are omitted. Only the rendering changes: finding counts, the overall summary, and exit codes are still computed from the full report, and the other output formats are untouched.

Author: choplin

README.md

@@ -24,6 +24,7 @@ Spec compliance is table stakes. `skill-validator` goes further: it checks that
   - [score evaluate](#score-evaluate)
   - [score report](#score-report)
 - [Output Formats](#output-formats)
+  - [Compact output](#compact-output)
   - [JSON output](#json-output)
   - [Markdown output](#markdown-output)
   - [GitHub Actions annotations](#github-actions-annotations)
@@ -435,7 +436,33 @@ The `--compare` flag is useful for understanding how different models perceive y
 
 ## Output Formats
 
-All commands accept `-o text` (default), `-o json`, or `-o markdown` for output format. Use `--emit-annotations` with any format to emit GitHub Actions workflow annotations alongside normal output.
+All commands accept `-o text` (default), `-o compact`, `-o json`, or `-o markdown` for output format. Use `--emit-annotations` with any format to emit GitHub Actions workflow annotations alongside normal output.
+
+### Compact output
+
+The default text output prints every passing check, token counts, and the
+analysis sections for each skill, which is a lot to read when you only want to
+know what needs fixing. Use `-o compact` to reduce each skill to a single line,
+with its warnings and errors listed beneath it:
+
+```
+skill-validator check -o compact <path>
+```
+
+```
+⚠ skills/llm-wiki-base: 1 warning
+    ⚠ SKILL.md body is 5233 tokens (spec recommends < 5000)
+✓ skills/llm-wiki-capture: passed
+✓ skills/llm-wiki-distill: passed
+✓ skills/llm-wiki-retrieve: passed
+
+4 skills validated: all passed
+Total: 1 warning
+```
+
+Passing checks, informational findings, token counts, and the content and
+contamination analysis sections are omitted. Only the display changes: error and
+warning counts, the summary, and exit codes are identical to the full report.
 
 ### JSON output
 

cmd/compact_integration_test.go

@@ -0,0 +1,69 @@
+package cmd_test
+
+import (
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+func TestCompactOutput(t *testing.T) {
+	bin := buildBinary(t)
+
+	t.Run("passing skill is a single line", func(t *testing.T) {
+		cmd := exec.Command(bin, "check", "-o", "compact", fixture(t, "valid-skill"))
+		out, _ := cmd.CombinedOutput()
+		s := string(out)
+
+		if got := cmd.ProcessState.ExitCode(); got != 0 {
+			t.Errorf("exit code = %d, want 0\noutput: %s", got, s)
+		}
+		if got := strings.Count(strings.TrimRight(s, "\n"), "\n"); got != 0 {
+			t.Errorf("expected a single line, got:\n%s", s)
+		}
+		if !strings.Contains(s, ": passed") {
+			t.Errorf("expected a passed summary, got:\n%s", s)
+		}
+	})
+
+	t.Run("warnings are listed under the summary", func(t *testing.T) {
+		cmd := exec.Command(bin, "check", "-o", "compact", fixture(t, "warnings-only-skill"))
+		out, _ := cmd.CombinedOutput()
+		s := string(out)
+
+		if got := cmd.ProcessState.ExitCode(); got != 2 {
+			t.Errorf("exit code = %d, want 2\noutput: %s", got, s)
+		}
+		if !strings.Contains(s, "1 warning") {
+			t.Errorf("expected the warning count on the summary line:\n%s", s)
+		}
+		if !strings.Contains(s, "    ") || !strings.Contains(s, "unknown directory") {
+			t.Errorf("expected the warning indented beneath the summary:\n%s", s)
+		}
+		if strings.Contains(s, "Validating skill") || strings.Contains(s, "Tokens") {
+			t.Errorf("compact output should omit the full report sections:\n%s", s)
+		}
+	})
+
+	t.Run("errors are listed under the summary", func(t *testing.T) {
+		cmd := exec.Command(bin, "check", "-o", "compact", fixture(t, "invalid-skill"))
+		out, _ := cmd.CombinedOutput()
+		s := string(out)
+
+		if got := cmd.ProcessState.ExitCode(); got != 1 {
+			t.Errorf("exit code = %d, want 1\noutput: %s", got, s)
+		}
+		if !strings.Contains(s, "error") {
+			t.Errorf("expected the error count on the summary line:\n%s", s)
+		}
+	})
+
+	t.Run("text output is unchanged", func(t *testing.T) {
+		cmd := exec.Command(bin, "check", fixture(t, "warnings-only-skill"))
+		out, _ := cmd.CombinedOutput()
+		s := string(out)
+
+		if !strings.Contains(s, "Validating skill") || !strings.Contains(s, "Tokens") {
+			t.Errorf("default text output should still be the full report:\n%s", s)
+		}
+	})
+}

cmd/root.go

@@ -31,7 +31,7 @@ var rootCmd = &cobra.Command{
 
 func init() {
 	rootCmd.Version = version
-	rootCmd.PersistentFlags().StringVarP(&outputFormat, "output", "o", "text", "output format: text, json, or markdown")
+	rootCmd.PersistentFlags().StringVarP(&outputFormat, "output", "o", "text", "output format: text, compact, json, or markdown")
 	rootCmd.PersistentFlags().BoolVar(&emitAnnotations, "emit-annotations", false, "emit GitHub Actions workflow command annotations (::error/::warning) alongside normal output")
 }
 

cmd/validate.go

@@ -38,6 +38,8 @@ func outputReportWithExitOpts(r *types.Report, perFile bool, opts exitOpts) erro
 		if err := report.PrintMarkdown(os.Stdout, r, perFile); err != nil {
 			return fmt.Errorf("writing markdown: %w", err)
 		}
+	case "compact":
+		report.PrintCompact(os.Stdout, r)
 	default:
 		report.Print(os.Stdout, r, perFile)
 	}
@@ -69,6 +71,8 @@ func outputMultiReportWithExitOpts(mr *types.MultiReport, perFile bool, opts exi
 		if err := report.PrintMultiMarkdown(os.Stdout, mr, perFile); err != nil {
 			return fmt.Errorf("writing markdown: %w", err)
 		}
+	case "compact":
+		report.PrintMultiCompact(os.Stdout, mr)
 	default:
 		report.PrintMulti(os.Stdout, mr, perFile)
 	}

report/compact.go

@@ -0,0 +1,67 @@
+package report
+
+import (
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/agent-ecosystem/skill-validator/types"
+	"github.com/agent-ecosystem/skill-validator/util"
+)
+
+// PrintCompact writes a one-line outcome for the skill. Warnings and errors are
+// listed underneath it; passing checks, token counts, and analysis sections are
+// omitted.
+func PrintCompact(w io.Writer, r *types.Report) {
+	printCompactSkill(w, r)
+}
+
+// PrintMultiCompact writes one compact entry per skill, followed by the overall
+// summary.
+func PrintMultiCompact(w io.Writer, mr *types.MultiReport) {
+	for _, r := range mr.Skills {
+		printCompactSkill(w, r)
+	}
+	printMultiSummary(w, mr)
+}
+
+func printCompactSkill(w io.Writer, r *types.Report) {
+	icon, color := compactLevel(r)
+	_, _ = fmt.Fprintf(w, "%s%s %s: %s%s\n", color, icon, r.SkillDir, compactOutcome(r), colorReset)
+
+	for _, res := range r.Results {
+		if res.Level < types.Warning {
+			continue
+		}
+		resIcon, resColor := formatLevel(res.Level)
+		_, _ = fmt.Fprintf(w, "    %s%s %s%s\n", resColor, resIcon, res.Message, colorReset)
+	}
+}
+
+// compactLevel returns the icon and color representing the report's worst outcome.
+func compactLevel(r *types.Report) (string, string) {
+	switch {
+	case r.Errors > 0:
+		return "✗", colorRed
+	case r.Warnings > 0:
+		return "⚠", colorYellow
+	default:
+		return "✓", colorGreen
+	}
+}
+
+// compactOutcome summarizes the report as "passed" or as its finding counts.
+func compactOutcome(r *types.Report) string {
+	if r.Errors == 0 && r.Warnings == 0 {
+		return "passed"
+	}
+
+	parts := []string{}
+	if r.Errors > 0 {
+		parts = append(parts, fmt.Sprintf("%d error%s", r.Errors, util.PluralS(r.Errors)))
+	}
+	if r.Warnings > 0 {
+		parts = append(parts, fmt.Sprintf("%d warning%s", r.Warnings, util.PluralS(r.Warnings)))
+	}
+	return strings.Join(parts, ", ")
+}

report/compact_test.go

@@ -0,0 +1,140 @@
+package report
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/agent-ecosystem/skill-validator/types"
+)
+
+func compactFixture(dir string, results ...types.Result) *types.Report {
+	r := &types.Report{
+		SkillDir:            dir,
+		Results:             results,
+		TokenCounts:         []types.TokenCount{{File: "SKILL.md", Tokens: 100}},
+		ContentReport:       &types.ContentReport{WordCount: 10},
+		ContaminationReport: &types.ContaminationReport{ContaminationLevel: "low"},
+	}
+	r.Tally()
+	return r
+}
+
+func TestPrintCompact_Passed(t *testing.T) {
+	r := compactFixture("my-skill",
+		types.Result{Level: types.Pass, Category: "Structure", Message: "SKILL.md found"},
+		types.Result{Level: types.Info, Category: "Structure", Message: "fyi"},
+	)
+
+	var buf strings.Builder
+	PrintCompact(&buf, r)
+	out := buf.String()
+
+	if !strings.Contains(out, "✓ my-skill: passed") {
+		t.Errorf("expected one-line passed summary, got:\n%s", out)
+	}
+	if got := strings.Count(out, "\n"); got != 1 {
+		t.Errorf("a passing skill should occupy one line, got %d:\n%s", got, out)
+	}
+	if strings.Contains(out, "SKILL.md found") || strings.Contains(out, "fyi") {
+		t.Errorf("pass and info findings should be omitted:\n%s", out)
+	}
+}
+
+func TestPrintCompact_ListsWarningsAndErrors(t *testing.T) {
+	r := compactFixture("my-skill",
+		types.Result{Level: types.Pass, Category: "Structure", Message: "SKILL.md found"},
+		types.Result{Level: types.Error, Category: "Links", Message: "broken link: ./gone.md"},
+		types.Result{Level: types.Warning, Category: "Structure", Message: "unknown directory: extras/"},
+	)
+
+	var buf strings.Builder
+	PrintCompact(&buf, r)
+	lines := strings.Split(strings.TrimRight(buf.String(), "\n"), "\n")
+
+	if len(lines) != 3 {
+		t.Fatalf("expected a summary line plus two findings, got %d lines:\n%s", len(lines), buf.String())
+	}
+	if !strings.Contains(lines[0], "✗ my-skill: ") ||
+		!strings.Contains(lines[0], "1 error") || !strings.Contains(lines[0], "1 warning") {
+		t.Errorf("summary line should carry both counts, got: %s", lines[0])
+	}
+	for _, line := range lines[1:] {
+		if !strings.HasPrefix(line, "    ") {
+			t.Errorf("findings should be indented under the summary, got: %q", line)
+		}
+	}
+	if !strings.Contains(lines[1], "broken link: ./gone.md") {
+		t.Errorf("expected the error message, got: %s", lines[1])
+	}
+	if !strings.Contains(lines[2], "unknown directory: extras/") {
+		t.Errorf("expected the warning message, got: %s", lines[2])
+	}
+	if strings.Contains(buf.String(), "SKILL.md found") {
+		t.Errorf("pass findings should be omitted:\n%s", buf.String())
+	}
+}
+
+func TestPrintCompact_OmitsAnalysisSections(t *testing.T) {
+	r := compactFixture("my-skill",
+		types.Result{Level: types.Warning, Category: "Structure", Message: "meh"},
+	)
+	r.OtherTokenCounts = []types.TokenCount{{File: "extra.md", Tokens: 50}}
+
+	var buf strings.Builder
+	PrintCompact(&buf, r)
+	out := buf.String()
+
+	for _, unwanted := range []string{"Tokens", "Content Analysis", "Contamination Analysis", "Validating skill"} {
+		if strings.Contains(out, unwanted) {
+			t.Errorf("compact output should omit %q:\n%s", unwanted, out)
+		}
+	}
+}
+
+func TestPrintCompact_WarningOnlyUsesWarningIcon(t *testing.T) {
+	r := compactFixture("my-skill",
+		types.Result{Level: types.Warning, Category: "Structure", Message: "meh"},
+	)
+
+	var buf strings.Builder
+	PrintCompact(&buf, r)
+	out := buf.String()
+
+	if !strings.Contains(out, "⚠ my-skill: 1 warning") {
+		t.Errorf("expected warning icon and count, got:\n%s", out)
+	}
+	if strings.Contains(out, "✗") {
+		t.Errorf("a warning-only report should not use the error icon:\n%s", out)
+	}
+}
+
+func TestPrintMultiCompact(t *testing.T) {
+	mr := &types.MultiReport{
+		Skills: []*types.Report{
+			compactFixture("a"),
+			compactFixture("b", types.Result{Level: types.Warning, Category: "Structure", Message: "meh"}),
+			compactFixture("c"),
+		},
+	}
+	for _, r := range mr.Skills {
+		mr.Errors += r.Errors
+		mr.Warnings += r.Warnings
+	}
+
+	var buf strings.Builder
+	PrintMultiCompact(&buf, mr)
+	out := buf.String()
+
+	if !strings.Contains(out, "✓ a: passed") || !strings.Contains(out, "✓ c: passed") {
+		t.Errorf("expected one-line summaries for passing skills, got:\n%s", out)
+	}
+	if !strings.Contains(out, "⚠ b: 1 warning") || !strings.Contains(out, "    ") {
+		t.Errorf("expected the failing skill's finding indented, got:\n%s", out)
+	}
+	if strings.Contains(out, strings.Repeat("━", 60)) {
+		t.Errorf("compact output should not draw separators:\n%s", out)
+	}
+	if !strings.Contains(out, "3 skills validated") || !strings.Contains(out, "Total: ") {
+		t.Errorf("expected the overall summary, got:\n%s", out)
+	}
+}

report/report.go

@@ -168,6 +168,13 @@ func PrintMulti(w io.Writer, mr *types.MultiReport, perFile bool) {
 		Print(w, r, perFile)
 	}
 
+	_, _ = fmt.Fprintf(w, "%s\n", strings.Repeat("━", 60))
+	printMultiSummary(w, mr)
+}
+
+// printMultiSummary writes the trailing per-skill tally and total counts shared
+// by the full and compact multi-skill renderers.
+func printMultiSummary(w io.Writer, mr *types.MultiReport) {
 	passed := 0
 	failed := 0
 	for _, r := range mr.Skills {
@@ -178,7 +185,6 @@ func PrintMulti(w io.Writer, mr *types.MultiReport, perFile bool) {
 		}
 	}
 
-	_, _ = fmt.Fprintf(w, "%s\n", strings.Repeat("━", 60))
 	_, _ = fmt.Fprintf(w, "\n%s%d skill%s validated: ", colorBold, len(mr.Skills), util.PluralS(len(mr.Skills)))
 	if failed == 0 {
 		_, _ = fmt.Fprintf(w, "%sall passed%s\n", colorGreen, colorReset)