Agent-Skills.md

Agent Skills: Agent Folder Init

Initialize a comprehensive .agents/ folder structure for AI-first development. Use this skill when starting a new project that needs AI agent documentation, session tracking, task management, and coding standards. Generates full structure based on proven patterns from production projects.

UncategorizedID: shipshitdev/library/agent-folder-init

Repository

shipshitdev/library
shipshitdev
151

Install this agent skill to your local

pnpm dlx add-skill https://github.com/shipshitdev/library/tree/HEAD/bundles/session/skills/agent-folder-init

Skill Files

Browse the full folder contents for agent-folder-init.

Download Skill

Loading file tree…

bundles/session/skills/agent-folder-init/SKILL.md

Skill Metadata

Name
agent-folder-init
Description
Add or repair .agents/ project context for an existing repo. Use for AI agent documentation, session tracking, task management, and coding standards; do not use as the primary new-product scaffold.

Agent Folder Init

Contract

Inputs:

  • Existing project root
  • Project name and primary tech stack
  • Optional platform entry surfaces: Claude Code, Codex, and/or Cursor

Outputs:

  • Dry-run plan by default
  • .agents/ documentation structure and root AGENTS.md after explicit --write
  • Optional CLAUDE.md or .cursor/rules/agent-context.mdc only when that platform is explicitly selected; Codex uses AGENTS.md
  • Summary of planned, written, skipped, and unchanged files

Creates/Modifies:

  • .agents/, root AGENTS.md, optional CLAUDE.md, optional Cursor project rule, and .editorconfig
  • Does not create application source code

External Side Effects:

  • None in the default dry run; --write performs local file writes only

Confirmation Required:

  • Before any write: review the dry-run plan and explicitly rerun with --write
  • Before overwriting an existing entry file: add --force-entry-files; symlink and non-file targets are always refused
  • Before writing outside the current workspace

Delegates To:

  • project-init-orchestrator when starting a new product repo
  • fullstack-workspace-init / npx @shipshitdev/v0 when a new Shipshit.dev product should be scaffolded
  • agent-config-audit after generation to detect drift or stale config

Purpose

This skill plans, then scaffolds a lean AI agent documentation system including:

  • Session tracking (daily files in .agents/sessions/)
  • Durable project context in .agents/memory/ (one topic per file)
  • Supported platform entry surfaces without copying commands, rules, agents, user settings, or another project's configuration

When to Use

  • Adding AI coding-assistant context to an existing project
  • Setting up AI-first development workflows
  • Migrating an existing project to use structured AI documentation

For new Shipshit.dev product repos, prefer project-init-orchestrator, which routes to npx @shipshitdev/v0 and includes the standard .agents, .claude, and .codex setup.

Usage

Run the scaffold script:

python3 scripts/scaffold.py --help

# Basic usage
python3 scripts/scaffold.py \
  --root /path/to/project \
  --name "My Project"

# Review the plan, then write the shared files
python3 scripts/scaffold.py \
  --root /path/to/project \
  --name "My Project" \
  --write \
  --allow-outside

# Add only the documented Claude and Cursor entry surfaces
python3 scripts/scaffold.py \
  --root /path/to/project \
  --name "My Project" \
  --platform claude \
  --platform cursor \
  --write \
  --allow-outside

The default is always a dry run. --force-entry-files is the only flag that permits overwriting AGENTS.md, CLAUDE.md, or the generated Cursor entry rule. Other existing files are preserved.

Generated Structure

Documentation (.agents/)

.agents/
├── README.md                    # Navigation hub
├── memory/
│   └── README.md                # Source of truth for durable project facts
└── sessions/
    ├── README.md                # Session format guide
    └── TEMPLATE.md              # Session file template

Shared rules and coding standards go in the applicable AGENTS.md. Use AGENTS.override.md only for an intentional subtree override and CLAUDE.md only for Claude-specific additions. Durable supporting detail belongs in .agents/memory/.

Task tracking uses GitHub Issues (gh issue list, gh issue create) — not local task files.

Platform entry surfaces

AGENTS.md                         # shared instructions; native Codex entry
CLAUDE.md                         # only with --platform claude
.cursor/rules/agent-context.mdc   # only with --platform cursor

The scaffold never generates .codex/commands, copies user settings, or imports a library checkout. It copies only four .agents/ templates, .editorconfig, and the explicitly selected entry templates. Missing canonical assets are a hard failure before any write; there is no embedded or stale fallback.

Root Files

  • AGENTS.md - Shared project instructions and .agents/ navigation
  • CLAUDE.md - Optional Claude-specific additions that reference AGENTS.md
  • .editorconfig - Editor configuration

Key Patterns

memory/ Files

  • One topic per file: memory/architecture.md, memory/deployment.md, memory/entities.md, etc.
  • Every file carries a last_verified: YYYY-MM-DD front-matter field.
  • Transient or short-lived facts add status: temporary.

Session Files

  • One file per day: sessions/YYYY-MM-DD.md
  • Multiple sessions same day use Session 1, Session 2, etc. in the same file.

Customization

After scaffolding, customize:

  1. Root agent entry file - Add project-specific coding standards and "never do" rules
  2. .agents/memory/architecture.md - Document your architecture decisions
  3. .agents/memory/entities.md - Document your data entities
  4. .agents/memory/deployment.md - Document deployment steps and gotchas
  5. GitHub Issues - Create issues for tasks (gh issue create)
  6. Platform entry files - Add only harness-specific guidance that cannot live in shared AGENTS.md

Integration with Other Skills

This skill integrates with:

| Skill | How It Works Together | |-------|----------------------| | project-init-orchestrator | Routes new product requests to v0 before lower-level setup | | fullstack-workspace-init | Uses v0 for new Shipshit.dev product workspaces | | linter-formatter-init | Sets up quality tooling in the scaffolded project | | husky-test-coverage | Enforces test coverage in pre-commit hooks |