---
slug: "social-value"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/sofer/social-value@main/README.md"
repo: "https://github.com/sofer/social-value"
source_file: "README.md"
branch: "main"
---
# Social value

Produce social value data from imported data for our social value report for Islington Council.

## Architecture

### Runtime Environment

This application runs within the AI coding interface:
- Application runs via natural language interaction with AI assistant
- AI assistant is the interface
- No API keys or separate deployment needed
- Skills provide capabilities
- Simple file-based storage (JSON, CSV, etc.)

### Technical Stack

- **Language**: Python
- **Documentation**: British English
- **Commits**: Conventional Commits specification

## Project Structure

```
project/
├── AGENTS.md            # Project conventions and session bootstrap
├── README.md            # This file
├── CLAUDE.md            # Claude Code auto-load redirect (optional)
├── skills/              # Reusable AI capabilities
│   ├── spec.md         # Creates project specifications
│   └── commit.md       # Formats commit messages
└── [project files]      # Your application code
```

## Getting Started

### Session Bootstrap

To start working with this project in any AI coding assistant:

**Codex CLI**: AGENTS.md loads automatically - just start working
**Claude Code**: Say anything (if CLAUDE.md is set up), or "Read AGENTS.md"
**Other tools**: Say "Read AGENTS.md"

### Available Skills

Current skills in `skills/` directory:
- **spec** - Create project specifications
- **commit** - Format commit messages following Conventional Commits
- **refactor** - Analyse Python code for refactoring opportunities and quality issues
- **social-value-report** - Generate the social value report from anonymised CSV data

Global skills in `~/.skills/` directory:
- **anonymise** - Strip PII from CSVs and timestamp outputs

### Configuration files

- `~/.skills/anonymise/config.txt` – column headers to remove during anonymisation (one per line, `#` for comments)
- `skills/social-value-report/config.json` – mapping from report fields to CSV column headers (defaults prefer aim 2, fall back to aim 1)

To add more skills, create `skills/skillname.md` with YAML frontmatter and instructions.

## Development Workflow

### Spec-First Development

1. Start with problem statement
2. Create specification (what the system does)
3. Define user stories (features from user perspective)
4. Implement iteratively, one story at a time
5. Use conventional commits for clean history

### Creating Skills

Skills are markdown files with YAML frontmatter:

```yaml
---
name: skill-name
description: When to use this skill. AI uses this to auto-activate.
---

# Skill instructions here
```

Simple skills go in `skills/skillname.md`. Complex skills with supporting files go in `skills/skillname/SKILL.md`.

## Platform Agnostic

This project works with:
- Claude Code
- Codex CLI (OpenAI)
- Gemini CLI (Google)
- Cursor
- Aider
- GitHub Copilot CLI
- Any future AI coding assistant

Skills and AGENTS.md are plain markdown - no vendor lock-in.

## References

- [Introducing Agent Skills | Anthropic](https://www.anthropic.com/news/skills)
- [Agent Skills Documentation | Claude](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
- [Conventional Commits](https://www.conventionalcommits.org/)

---

For detailed conventions, coding standards, and session bootstrap process, see AGENTS.md.