Skip to content

EliasOulkadi/shokunin / .pack/skills/init

Use when the user asks to initialize a repo, create AGENTS.md, generate contributor guidelines, or set up agent-oriented documentation for a codebase.

AGENTS.md Generator

Analyze a codebase and generate a concise, accurate AGENTS.md contributor guide.

Target: the current working directory, unless user provided another folder as input.


Gather Information

Collect facts about the repository. Only record what is actually found — never invent information.

These probes are independent — run them in parallel (e.g., dispatch subagents) when the tooling supports it.

Repository structure

Map the repo structure (3 levels deep, excluding .git, node_modules, dist, build, pycache, .venv and other autogenerated folders). This is analysis input — the output AGENTS.md should describe non-obvious architecture, not list directories. Focus on the "big picture" that requires reading multiple files to understand.

Build & dev commands

Extract actual command definitions from the project's build system: package.json scripts, Makefile targets, pyproject.toml scripts, Cargo.toml bins/workspace members, go.mod module path, docker-compose.yml services, etc.

Coding conventions

Check for and record key settings of:

  • Linter configs
  • Formatter configs
  • Type checking (note strict mode if applicable)
  • Agent rules: .cursorrules, .cursor/rules/, .github/copilot-instructions.md
  • Pre-commit hooks

If agent rules files exist, read and extract the important parts — focus on conventions that matter for code generation, not verbatim content.

Git history

Review the last 20 commits to identify commit message conventions and patterns. If this fails (not a git repo or shallow clone), note the limitation and skip.

Existing documentation

  • If README.md exists, read it for context about the repo's purpose and setup.
  • If AGENTS.md already exists, read it — you'll be improving it rather than starting fresh.
  • If CLAUDE.md exists, read it for additional context.

Generate AGENTS.md

Document requirements

  • Title: # Repository Guidelines
  • 200-400 words (exceed only if complexity genuinely demands it)
  • Direct, instructional tone
  • No repetition across sections

Sections to include (omit any that lack evidence)

## Project Structure & Module Organization Architecture that requires reading multiple files to understand. Omit anything obvious from opening a single file.

## Build, Test, and Development Commands Actual commands from the build system. Include how to run a single test.

## Coding Style & Naming Conventions Enforced rules from linter/formatter configs. Include tool names.

## Testing Guidelines Test framework, how to run tests, coverage requirements if any.

## Commit & Pull Request Guidelines Commit conventions derived from actual git history. Note any PR templates.

Add other sections only if facts strongly support them (e.g., Architecture Overview, Agent Instructions).

What to never include

Do not include generic development practices such as:

  • "Write unit tests for all new utilities"
  • "Use meaningful variable names"

Do not invent sections like "Common Development Tasks" or "Tips for Development" unless the repo's own documentation expressly contains them. Do not list every file — only document what is non-obvious.

New vs existing

  • Existing AGENTS.md: Fix inaccuracies, fill gaps, remove generic advice, ensure commands are current. Preserve correct, specific content. Present the diff and ask to confirm before overwriting.
  • New AGENTS.md: Write directly to the repository root. No confirmation needed.

Validate

Before finalizing, verify:

  • Every command mentioned actually exists in the build system
  • Every file path mentioned exists in the repo
  • No generic advice slipped in
  • No repeated information across sections
  • The document stays within the target word count
  • Agent rules are incorporated (woven into relevant sections, not dumped verbatim)

Principles

  • Never fabricate — if a section has no evidence, omit it entirely
  • Prefer commands over prose — npm test over "run the test suite"
  • Big picture only — architecture that spans multiple files, skip the obvious
  • Incorporate agent rules — weave important parts of .cursorrules or copilot instructions into relevant sections
  • Respect existing work — in improvement mode, preserve correct specific content
  • Conciseness is quality — every sentence must earn its place

Workflow

  1. Probe repository structure — map 3 levels deep, exclude generated dirs. Identify build system, language, and framework.
  2. Extract commands — read package.json scripts, Makefile targets, pyproject.toml, Cargo.toml, docker-compose.yml.
  3. Collect conventions — linter configs (.eslintrc, .prettierrc, pyproject.toml), formatter settings, type checking mode, agent rules files (.cursorrules, .cursor/rules/).
  4. Review git history — last 20 commits for commit convention patterns (conventional commits, custom formats). Skip if not a git repo.
  5. Read existing documentation — README.md for context. Existing AGENTS.md or CLAUDE.md for improvement baseline.
  6. Draft AGENTS.md — 200-400 words, direct tone. Include project structure, build commands, coding style, testing, commit conventions. Omit generic advice.
  7. Validate output — every command mentioned exists in build system. Every path exists in repo. No fabricated content. No repetition.

Error Handling

CauseFix
Not a git repositorySkip git history section. Note limitation explicitly in output.
Shallow clone with limited commit historyUse available commits. Note "limited history available."
No build system detectedSkip build commands section. Document that no formal build system was found.
Existing AGENTS.md has inaccuraciesFix errors, fill gaps, remove generic advice. Show diff before overwriting.
Agent rules files not foundSkip agent rules integration. Never invent conventions.
Mixed or ambiguous conventions across filesNote the inconsistency. Default to the dominant convention in the majority of files.
Empty repository with no source filesGenerate minimal AGENTS.md with project name only. Add "populate as project grows."

Anti-Patterns

PatternProblemFix
Including generic advice ("write unit tests")Not actionable, not project-specificOnly include conventions actually enforced in the codebase
Listing every directory in the repoAdds noise, not architecture insightDocument only non-obvious structure that spans multiple files
Copying agent rules verbatim into AGENTS.mdRedundant and bloatedWeave important rules into relevant sections only
Inventing commands not in the build systemBuild breaks when user tries themExtract commands only from actual build system files
Missing sections where evidence existsIncomplete onboarding guideInclude all sections that have supporting evidence
Overwriting correct, specific existing contentLoses institutional knowledgePreserve correct content. Fix only inaccuracies and gaps.
Exceeding 400 words with filler proseToo long to scan; loses utilityCut every sentence that doesn't convey a specific convention

Checklist

  • Project type identified (lib, app, monorepo, etc.)
  • AGENTS.md created with profile, behavior, and tools sections
  • .gitignore includes platform-relevant entries (node_modules, .env, etc.)
  • License file created matching project requirements
  • CI/CD scaffolding included if project will be deployed

Sources

  • GitHub Docs — "About READMEs" (docs.github.com)
  • Keep a Changelog — keepachangelog.com
  • Conventional Commits — conventionalcommits.org
  • Google Open Source — "README.md guidelines" (opensource.google)
  • Daniele Procida — "Diátaxis documentation framework" (diataxis.fr)
  • Write the Docs Guide — writethedocs.org
  • Eric Holscher — "Documentation Principles" (ericholscher.com)
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 197kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 197kUpdated Claude CodeCodexVerifiedInstall