diff --git a/src/state.ts b/src/state.ts
index 03597b6..89d7bb0 100644
--- a/src/state.ts
+++ b/src/state.ts
@@ -86,3 +86,34 @@ export function createRuntimeFlags(): RuntimeFlags {
 		autoCompactIntegration: "auto",
 	};
 }
+
+export interface TrackSkillInput {
+	name: string;
+	filePath: string;
+	baseDir: string;
+	source: SkillSource;
+	seenAt?: number;
+}
+
+/** Upsert by name, merge sources, preserve insertion order (SPEC §6.1). */
+export function trackSkill(state: ExtensionState, input: TrackSkillInput): void {
+	const seenAt = input.seenAt ?? Date.now();
+	const existing = state.skills.find((skill) => skill.name === input.name);
+	if (existing) {
+		existing.filePath = input.filePath;
+		existing.baseDir = input.baseDir;
+		existing.lastSeenAt = seenAt;
+		if (!existing.sources.includes(input.source)) {
+			existing.sources.push(input.source);
+		}
+		return;
+	}
+	state.skills.push({
+		name: input.name,
+		filePath: input.filePath,
+		baseDir: input.baseDir,
+		firstSeenAt: seenAt,
+		lastSeenAt: seenAt,
+		sources: [input.source],
+	});
+}