From 121198510343894070f71756fe24d44c34f33b6f Mon Sep 17 00:00:00 2001
From: kriptoburak <kriptoburak@users.noreply.github.com>
Date: Tue, 16 Jun 2026 00:19:56 +0200
Subject: [PATCH] Add social source review skill example

---
 cmd/exitcode_integration_test.go              | 14 ++++++
 examples/README.md                            | 15 +++++++
 examples/social-source-review/SKILL.md        | 45 +++++++++++++++++++
 .../references/social-actions.md              | 26 +++++++++++
 4 files changed, 100 insertions(+)
 create mode 100644 examples/social-source-review/SKILL.md
 create mode 100644 examples/social-source-review/references/social-actions.md

diff --git a/cmd/exitcode_integration_test.go b/cmd/exitcode_integration_test.go
index 8b0d234..df8c433 100644
--- a/cmd/exitcode_integration_test.go
+++ b/cmd/exitcode_integration_test.go
@@ -49,6 +49,15 @@ func fixture(t *testing.T, name string) string {
 	return p
 }
 
+func example(t *testing.T, name string) string {
+	t.Helper()
+	p := filepath.Join(moduleRoot(t), "examples", name)
+	if _, err := os.Stat(p); err != nil {
+		t.Fatalf("example %q not found: %v", name, err)
+	}
+	return p
+}
+
 func TestExitCodes(t *testing.T) {
 	bin := buildBinary(t)
 
@@ -92,6 +101,11 @@ func TestExitCodes(t *testing.T) {
 			args:     []string{"validate", "structure", fixture(t, "warnings-only-skill")},
 			wantCode: 2,
 		},
+		{
+			name:     "social source example exits 0",
+			args:     []string{"check", "--only=structure", example(t, "social-source-review")},
+			wantCode: 0,
+		},
 	}
 
 	for _, tt := range tests {
diff --git a/examples/README.md b/examples/README.md
index 5918151..0c78f5a 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -8,6 +8,8 @@ your project.
   your coding agent before requesting a human review.
 - **ci** — Use when publishing skills or adding them to a project to enforce
   a minimum quality bar on every pull request.
+- **social-source-review**: Validate a realistic skill that gates X/Twitter
+  source review before social actions.
 
 ## review-skill
 
@@ -78,3 +80,16 @@ use, or before adding skills to your own repo or personal coding agent setup.
 
 The workflow installs skill-validator from source on each run. No API keys or
 external services are required; it runs structural validation only.
+
+## social-source-review
+
+A compact sample Agent Skill package that shows how social-data skills can keep
+read-only source review separate from approval-gated write actions. It uses
+TweetClaw as the concrete X/Twitter source tool and includes a checklist for
+credentials, evidence, and human approval boundaries.
+
+Run:
+
+```sh
+go run ./cmd/skill-validator check examples/social-source-review
+```
diff --git a/examples/social-source-review/SKILL.md b/examples/social-source-review/SKILL.md
new file mode 100644
index 0000000..77c4364
--- /dev/null
+++ b/examples/social-source-review/SKILL.md
@@ -0,0 +1,45 @@
+---
+name: social-source-review
+description: Review X/Twitter source evidence from TweetClaw before approval-gated social actions.
+license: MIT
+compatibility: Works with coding agents that can run shell commands and read local files.
+metadata:
+  author: skill-validator examples
+  version: "1.0"
+allowed-tools: Bash Read
+---
+# Social Source Review
+
+Use this skill when a task depends on current X/Twitter evidence before an agent
+drafts, schedules, publishes, or monitors social content.
+
+## Inputs
+
+Ask for:
+
+- The account, search query, tweet URL, or monitor target.
+- The intended action: source review, reply context, follower export, media
+  check, or monitor setup.
+- The approval boundary for any write, schedule, webhook, or direct message
+  action.
+
+## Workflow
+
+1. Confirm the requested action is allowed by the workspace policy.
+2. Use [TweetClaw](https://github.com/Xquik-dev/tweetclaw) only as a source
+   tool for X/Twitter evidence.
+3. Run read-only commands first, such as package help or a dry-run wrapper. Do
+   not request credentials in chat.
+4. Summarize the source evidence with links, timestamps, and uncertainty.
+5. Stop before any write, schedule, direct message, webhook, or publish action
+   until a human approves the exact action.
+6. Follow [the social action checklist](references/social-actions.md) before
+   returning a final recommendation.
+
+## Output
+
+Return:
+
+- Evidence reviewed.
+- Risk or policy blockers.
+- Exact next action that needs approval, if any.
diff --git a/examples/social-source-review/references/social-actions.md b/examples/social-source-review/references/social-actions.md
new file mode 100644
index 0000000..68bba8b
--- /dev/null
+++ b/examples/social-source-review/references/social-actions.md
@@ -0,0 +1,26 @@
+# Social Action Checklist
+
+Use this checklist for skills that touch public social data or user accounts.
+
+## Read Phase
+
+- Prefer read-only source collection for account lookup, tweet search, reply
+  context, follower export, media lookup, and monitor planning.
+- Keep tokens, cookies, API keys, and account credentials out of chat, logs,
+  issue bodies, and generated reports.
+- Save only the minimum evidence needed for the task.
+
+## Approval Phase
+
+- Separate source review from drafting, scheduling, publishing, direct messages,
+  webhook delivery, or account changes.
+- Ask for approval that names the account, action, target, and final text or
+  payload.
+- Reject vague approval such as "post it" when the target or content changed
+  after review.
+
+## Output Phase
+
+- Cite the source URL or identifier for each claim.
+- Label missing, deleted, private, or rate-limited data as unavailable.
+- Do not invent metrics, dates, account ownership, or screenshots.