Setup Agent Config

Create the meta-layer that helps AI coding agents work effectively inside a project:

• AGENTS.md for project context.
• SKILL.md for reusable procedural knowledge.
• Optional adapter files for agents that need symlinks, copies, or agent-specific directories.

This skill writes configuration and documentation, not application code.

Source Files

Use this repository's files in this order:

Workflow

1. Research the Target Project

Gather only context that affects agent behavior:

• README and root manifests.
• Existing agent files such as AGENTS.md, CLAUDE.md, .cursor/, .github/, .pi/, .opencode/.
• Build, test, lint, format, typecheck, and CI commands.
• Representative source files showing architecture and conventions.
• Known gotchas from docs, issues, scripts, or config.

Do not invent commands. If a command cannot be verified from the project, mark it for user confirmation.

2. Choose the Starting Point

• Use scripts/scaffold-agent-config.sh <target> for a blank or lightly configured project.
• Use templates/ when manually composing files.
• Use the closest examples/ stack when filling architecture and command patterns.
• Update existing downstream files in place when the project already has agent configuration.

3. Fill AGENTS.md

Keep it under 200 lines and focus on what an agent would otherwise miss:

• Project summary.
• Exact commands.
• Architecture boundaries.
• Coding standards that affect edits.
• Verification workflow.
• Repo-specific gotchas.
• Agent-specific adapter notes when relevant.

Remove generic advice that applies to every repository.

4. Fill SKILL.md

Every skill needs valid frontmatter:

---
name: lowercase-hyphen-name
description: What the skill does. Use when specific trigger scenarios happen.
license: MIT
---

The description is the primary trigger mechanism. Make it explicit and trigger-rich. Include common user phrases and contexts, not only a short label.

Skill body expectations:

• Outcome.
• Inputs.
• Steps.
• Decision rules.
• Example input and output.
• References to scripts/, references/, or assets/ only when those resources exist.

5. Add Agent Adapters

Use adapters only when needed:

# Claude Code
ln -s AGENTS.md CLAUDE.md

# Pi.dev
mkdir -p .pi && cp AGENTS.md .pi/context.md

Place concrete skills in the target agent's skill directory:

6. Validate

For this repository, run:

python3 scripts/validate.py

For a downstream project, check:

• No unresolved placeholders unless intentionally left for the user.
• AGENTS.md is short, specific, and command-driven.
• SKILL.md has name and description.
• Skill description includes Use when or equivalent trigger language.
• Agent adapters exist only where required.

Placeholder Reference

Common placeholders:

Quality Checks

Before finishing, ask:

• Would the agent likely make a worse decision without this instruction?
• Are commands exact for the target repo?
• Does the skill trigger from frontmatter alone?
• Are examples concrete enough to imitate?
• Is compatibility described as native, adapter, or manual rather than overstated?