Proposal: New skill for intelligent agent onboarding and intent capture

# Summary

I'd like to propose a new skill focused on the "cold start" problem for AI agents. Currently, when an agent enters a complex repository, it often lacks context on architectural intent, leading to "vibe coding" rather than structured engineering. This skill would interactively generate and maintain optimized project-level instructions (CLAUDE.md or AGENTS.md) tailored to the the specific tech stack and the the developer's unique intent.

# The problem with existing solutions

While native commands like claude `/init` provide a baseline, they are fundamentally passive and descriptive.

- they perform surface-level scans of file names but fail to capture philosophical "Why" behind the architecture.
- They struggle with negative constraints; for example, if a developer intentionally avoid certain UI libraries to maintain creative control of follows specific security patterns for infrastructure, a passive scan will miss these rules.

# Proposed workflow

The skill would function through a three-step process:

1. **Discovery.** Scan core configuration files (e.g. package.json, build.gradle.kts, README.md) to identify the tech stack
2. **Interview.** Actively prompt the developer 3-5 targeted questions to capture intent that isn't in the code (e.g. "I noticed no UI framework; are we building from scratch?").
3. **Synthesis.** Generate a context-aware instruction file optimized for the current environment (CLAUDE.md for Claude or AGENTS.md for general frameworks).

# Suggested skill names

- project-blueprint
- intent-capture
- agent-briefing
- agent-onboarding

# Call for thoughts

This is a raw proposal, and I'd love to hear if this sparks any thoughts from the maintainers and contributors. There are a few areas I haven't fully specified yet and would value your intput:

1. What are the best 3-5 questions an agent should ask to get the most alignment whit the developer?
2. Should this skill only be for a starting new files, or should it also be able to update existing files as well?
3. How can we make sure the agent is actually verify the rules it just wrote down?

I'm curious to hear if the community things this fits the current direction of the library!