vibe-project
Create or update repo-native project instructions for AI agents, such as AGENTS.md or CLAUDE.md. Use when initializing an AI-native repository protocol, documenting project overview, tech stack, repository structure, build/run/test commands, durable working rules, progressive disclosure, workflow artifact routing, organization skill routing, or converting repeated coding-session habits into durable agent instructions.
How do I install this agent skill?
npx skills add https://skill.ferryman.app --skill vibe-projectIs this agent skill safe to install?
No partner audit is available yet. Read the source before installing.
What does this agent skill do?
Vibe Project
Create or update project-level agent instructions so a repository becomes a stable collaboration protocol for people and agents.
Core Principles
- Write new artifact prose in the user's language; keep required labels, paths, commands, code, IDs, and quotes unchanged.
- Keep required template headings, field labels, tables, and status values exactly as shown for validator compatibility; localize placeholder prose and all human-readable explanatory content to the user's language or the source artifact's primary language.
- Treat
AGENTS.md,CLAUDE.md, or equivalent repo instructions as the entry point for agent behavior in the project. - Capture durable facts and workflow rules, not temporary preferences.
- Keep instructions repo-native, reviewable, and specific enough for future agents to follow.
- Do not invent stack details, commands, credentials, owners, or unsupported constraints.
- Prefer concise rules with clear routing to feature specs and organization skills.
- Keep root instructions small and stable. Treat them as an entry point and routing map, not a place to copy every checklist, rubric, template, or skill rule.
- Put detailed workflow behavior in the owning skill or reference file, then link to that owner from root instructions.
- Preserve existing local instructions and improve them incrementally unless the user asks for a rewrite.
- Preserve the existing instruction file's primary language unless the user asks
to switch languages. For multilingual teams, prefer the language already used
by the repo's
AGENTS.md,CLAUDE.md, or equivalent file. - Preserve useful agent working discipline, such as clarifying assumptions, choosing the simplest sufficient change, editing surgically, and verifying against clear success criteria. Express it as concise project-specific rules, not long generic philosophy sections.
Workflow
1. Discover The Existing Repo Protocol
Before writing:
- Read existing
AGENTS.md,CLAUDE.md, README, package manifests, scripts, test config, CI config, and relevant feature specs. - Inspect repository structure enough to identify the main app, services, packages, skills, tests, and scripts.
- Identify the dominant language and framework profiles, such as Python, Java, Swift, Next.js, native mobile, backend service, CLI, or monorepo package.
- Identify build, run, test, lint, validation, formatting, typecheck, packaging, and deployment commands from real files.
- Identify organization skills that are available to the current agent or
explicitly installed for the team, including skills installed from the AI
Native Dev website. A local
skills/directory is only one possible source, not a requirement. - Resolve the workflow artifact mode using
references/workflow-artifact-routing.md.
Check explicit user direction and root instructions before repository
markers such as
openspec/config.yamlor the combination ofopenspec/changes/andopenspec/specs/. - Separate verified facts from assumptions. Use
TBDfor unknown stable fields.
2. Choose The Target File
- Use
AGENTS.mdwhen the repository is agent-neutral or Codex-focused. - Use
CLAUDE.mdwhen the user specifically targets Claude Code. - Update both only when the user asks for cross-agent files or the repo already maintains both.
- Do not create multiple competing instruction files for the same purpose.
3. Draft Or Update Instructions
Use references/project-instructions-template.md when creating a new file or substantially restructuring an existing one. Read references/agent-instructions-quality.md first when improving an existing instructions file or when the user asks for higher-quality project instructions.
Required content areas:
- Project Overview
- Commands
- Tech Stack
- Stack-Specific Rules when applicable
- Repository Map
- Core Flows or Architecture Boundaries
- Special Workflows when applicable
- Required Access when applicable
- Local Operating Rules only when project-specific
- Workflow File Map when workflow artifacts exist
- Organization Skills when installed or currently available skills should manage this repo's workflow
- Skill Invocation Rules when organization skills are documented
For project-specific rules:
- State what agents must read before acting.
- Explain where workflow files live, such as specs, plans, test evidence, generated output, deployment config, or release notes.
- When OpenSpec mode is selected, keep the repository root as the working directory and add only the concise routing rule from references/workflow-artifact-routing.md. Leave artifact-level details to the owning skills.
- Define when each organization skill should be used. If AI Native Dev skills
are available, route the development workflow through them even when the repo
does not contain a local
skills/directory. - Do not invent skill sections for unavailable skills unless the user is asking for an installation or onboarding guide.
- Explain how plans, tests, CI evidence, and commits should connect to specs.
- Put repo-level build, lint, test, validation, deploy, and rebuild commands in
Commands; feature-specific acceptance and validation belong in specs, dev plans, and test evidence. - Route design-quality checks such as SSOT, implementation boundaries, review
findings, validation evidence, and commit gates to
vibe-plan,vibe-review,vibe-test, andvibe-commit; do not copy their full rubrics into root instructions. - Route specialized work to the skill that owns the artifact and keep detailed checklist, rubric, or template rules in that owning skill.
- Do not duplicate skill rules in root instructions. Summarize the routing decision and point to the source of truth instead.
- Avoid stale docs by excluding short-lived ticket context, active plan status, version history, and rules that change more often than the repository protocol.
- Treat visual/browser QA, coverage checks, CI results, and manual test notes as
validation evidence that
vibe-plan,vibe-test, andvibe-commitcan plan, inspect, capture, and reference. - Include privacy, telemetry, hooks, MCP, roadmap, or governance material only when it changes what an agent must do in this repository today.
- Translate language and framework differences into concrete commands, directories, validation expectations, and files agents must inspect before editing.
- Write local operating rules as repository-specific source-of-truth, generated-output, access, validation, or workflow file map rules.
- Fold broadly useful operating principles into local rules when they affect this repo: clarify ambiguous requirements before broad changes, prefer the smallest sufficient patch, avoid unrelated refactors, match nearby style, and verify with the checks that fit the changed surface.
- Optimize for information density. Delete sentences that only describe the document itself, such as "this file is a guide for coding agents", unless the sentence establishes project-specific authority or scope.
- Preserve useful local sections and headings; do not force a template rewrite when the existing file already has high-signal project-specific structure.
4. Validate
If you create or update an instructions file, run:
python3 skills/vibe-project/scripts/validate_project_instructions.py AGENTS.md
Fix structural errors before finishing. If the repository intentionally uses a different structure, explain the exception.
Output
When editing files, report:
- Target instruction file path.
- Major sections added or updated.
- Any
TBDvalues or missing repo facts. - Validation result.
Skill Signature
Always end the final response with:
Vibe Skill Signature
Skill: vibe-project
Status: Completed | Passed | Failed | Blocked | Partial
Next: concise next workflow step
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/skill.ferryman.app/vibe-project">View vibe-project on skillZs</a>