home / skills / bizshuk / llm_plugin / project-metadata

project-metadata skill

safe

This skill initializes project structure for golang or profile types and generates or updates README documentation to accelerate setup and onboarding.

npx playbooks add skill bizshuk/llm_plugin --skill project-metadata

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

4.5 KB

---
name: project-metadata
description: Project structure initialization and metadata generation. This skill should be used when creating a new project, initializing project structure based on type (golang or social profile), or generating/updating README documentation.
---

# Project Metadata

## Overview

This skill provides project initialization and metadata (README.md) generation based on project type. It supports structured initialization for golang and social profile projects.

## When to Use

Use this skill when:

- Creating a new project and need to initialize its structure
- Generating or updating README documentation for golang projects
- Setting up a social profile workspace

## Supported Project Types

| Type      | Structure Reference          | Metadata Reference             |
| --------- | ---------------------------- | ------------------------------ |
| `default` | N/A (analyzes existing)      | `references/default.readme.md` |
| `golang`  | `rules/go-structure.md`      | `references/golang.readme.md`  |
| `profile` | `rules/profile-structure.md` | `references/profile.readme.md` |

**Note:** If no project type is specified, the `default` type is used, which analyzes the existing project structure and generates a comprehensive README.md with folder descriptions.

---

## Project Initialization

### Golang Projects

To initialize a golang project structure, follow the guidelines in `rules/go-structure.md`:

```
<project-name>/
├── cmd/        # CLI entry points (spf13/cobra)
├── config/     # Configuration and client initialization
├── model/      # Database CRUD operations
├── svc/        # Single domain business logic
├── handler/    # E2E feature orchestration
└── utils/      # Common helper functions
```

### Social Profile Projects

To initialize a social profile project structure, follow the guidelines in `rules/profile-structure.md`:

```
<project-name>/
├── archetype/   # Prototype models for the profile
├── background/  # Profile information and details
├── post/        # Generated posts (YYYYMMDD-<story> naming)
└── assets/      # Non-defined files
```

---

## Metadata Generation

### Default README (Any Project Type)

To generate README documentation for any project, use the workflow defined in `references/default.readme.md`.

This is the **default workflow** when no specific project type is provided. It works for any codebase by:

1. **Identifying Project Type** - Detects language and framework from files
2. **Traversing Domain Folders** - Analyzes top-level folders (excluding infrastructure)
3. **Analyzing Configuration** - Extracts info from package files and configs
4. **Finding Entry Points** - Discovers how to run, build, and test
5. **Understanding Purpose** - Infers project goals from structure and docs
6. **Generating README** - Creates comprehensive documentation

The workflow provides detailed descriptions for each domain folder, helping newcomers understand the project structure quickly.

Read the full reference for detailed steps:

```
references/default.readme.md
```

### Golang README

To generate README documentation for a golang project, use the workflow defined in `references/golang.readme.md`.

The workflow analyzes:

1. **Folder Structure** - Documents key directories and their purposes
2. **Handler List** - HTTP/RPC endpoints with methods and descriptions
3. **External Services** - RPC, Database, Cache, MQ dependencies
4. **Run/Test Instructions** - Build, run, and testing commands

Read the full reference for detailed steps:

```
references/golang.readme.md
```

### Social Profile Metadata

To generate README documentation for a social profile project, use the workflow defined in `references/profile.readme.md`.

The workflow analyzes:

1. **Profile Overview** - Name, type, and description
2. **Directory Structure** - Standard profile directories
3. **Background Information** - Biography, personality, voice from `background/`
4. **Archetype References** - Prototype models from `archetype/`
5. **Post List** - All posts from `post/` with dates and content types

Read the full reference for detailed steps:

```
references/profile.readme.md
```

---

## Resources

### references/

| File                | Description                            |
| ------------------- | -------------------------------------- |
| `default.readme.md` | Workflow for default README generation |
| `golang.readme.md`  | Workflow for golang README generation  |
| `profile.readme.md` | Workflow for profile README generation |

Overview

This skill initializes project structure and generates project metadata and documentation based on the chosen project type. It supports structured scaffolding for Go services and social-profile workspaces, plus a default analysis mode that builds documentation from an existing codebase. Use it to jumpstart new projects or keep documentation in sync with code and folders.

How this skill works

The skill inspects the codebase to detect project language and framework, then applies a type-specific structure or analysis workflow. For golang it sets up canonical directories (cmd, config, model, svc, handler, utils) and extracts handlers, dependencies, and run/test commands. For social profiles it scaffolds archetype, background, post, and assets and extracts profile metadata and posts. In default mode it traverses top-level folders, reads config files, finds entry points, infers purpose, and generates structured project documentation.

When to use it

Creating a new Go service and needing standard project layout
Setting up a social profile workspace with content folders and archetypes
Generating or updating project documentation from an existing codebase
Onboarding new contributors who need clear folder-level explanations
Automating documentation updates as structure or configs change

Best practices

Choose the project type (golang, profile, or default) before scaffolding to get the right layout
Keep configuration files (module, package, or manifest) at project root for accurate metadata extraction
Populate handler and background folders with brief comments to improve generated documentation clarity
Run the analyzer after structural changes to keep documentation up to date
Treat generated documentation as editable: refine language and add examples after generation

Example use cases

Initialize a Go microservice with recommended directories and a clear run/test section for CI pipelines
Create a personal social profile workspace that tracks archetypes, background info, and dated posts
Analyze an existing codebase to produce domain-level documentation and entry point instructions for new hires
Regenerate project metadata after adding external services (DB, cache, MQ) to capture new dependencies
Produce a profile overview and post index for static-site generation or content import

FAQ

What project types are supported?

golang, profile (social profile), and default analysis mode for any existing codebase.

Can I customize the generated documentation?

Yes. The tool produces editable documentation that you should review and refine to include examples and project-specific notes.

How does the default analysis identify entry points?

It scans top-level folders and common config files to find build/run/test scripts, main packages, and service entry points.