feat(skills): per-skill agent targeting (agents/excludeAgents frontmatter)

[TimCrooker]

Why

Some skills should only be visible to one agent. The motivating case: a skill teaching Claude Code how to dispatch Codex subagents must not mirror into .agents/skills/, where Codex itself would discover it — recursive, confusing instructions for the wrong audience. Until now every skill fanned out to every manifest.skills.mirrors entry unconditionally.

What

• Frontmatter: agents: [claude] (whitelist) or excludeAgents: [claude] (blacklist), mutually exclusive. Agent IDs derive from each mirror path's first segment minus the leading dot: .claude/skills → claude, .agents/skills → agents, a future .cursor/skills → cursor. No manifest change needed.
• Validation: both fields set, empty whitelist, or non-string entries fail frontmatter parsing; an ID no manifest mirror produces fails the build with new AICTX_SKILL_AGENT_UNKNOWN.
• Plan-aware orphan detection: findOrphanedSkillMirrors accepts the planned mirror set (optional, back-compat), so adding a filter to an existing skill + build --remove-orphans deletes the now-excluded symlinks; doctor flags them with an updated message.
• CLI: skills create --agents <id> (repeatable); skills list shows [agents: …] and emits agents/excludeAgents in --json.
• Docs: skills-guide, cli-contract, and the meta-skill authoring reference.

Verification

• 221 tests pass (176 core / 22 templates / 23 cli), typecheck + lint + preflight:release clean.
• End-to-end smoke on a scratch repo: whitelist emits only .claude/skills, blacklist inverts, filter composes with scope:, doctor flags and --remove-orphans deletes stale mirrors, unknown ID errors cleanly, verify stays green.

Note: touched files were run through prettier (the repo's declared style), which accounts for the formatting-only hunks — main has pre-existing format drift in ~125 files.

🤖 Generated with Claude Code

Note

Add per-skill agent targeting via agents/excludeAgents frontmatter fields

• Skills can now declare agents (whitelist) or excludeAgents (blacklist) in their SKILL.md frontmatter to control which agent mirrors are produced; both fields cannot be set simultaneously and unknown agent IDs raise AICTX_SKILL_AGENT_UNKNOWN.
• planSkillMirrors in skills.ts derives known agent IDs from mirror paths, validates the filter fields, and trims the mirror plan accordingly.
• Orphan detection in findOrphanedSkillMirrors is now plan-aware: mirrors for still-active skills are treated as orphans when their exact paths are no longer in the current plan (e.g., excluded by agent filters).
• ai-context doctor flags mirrors excluded by scope or agent filters and suggests build --remove-orphans; the diff and verify commands also reflect plan-aware orphan state.
• The skills create CLI accepts a new repeatable --agents <id> flag written into the generated frontmatter, and skills list shows agent filters in text and JSON output.
• Behavioral Change: --remove-orphans now deletes mirrors excluded by agent filters for active skills, not only mirrors whose skill name is gone entirely.

^{Macroscope summarized 046a3ec.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[macroscopeapp]

Approvability

Verdict: Needs human review

Unable to check for correctness in 046a3ec. This PR introduces a new feature (per-skill agent targeting) that changes build pipeline behavior - skills can now filter which agent mirrors they emit to, and orphan detection is modified accordingly. New features with runtime behavior changes warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}